When Dify workspace keys should live in Azure Key Vault
If your team deploys self-hosted Dify in Azure and must control where credential encryption keys are held, the decision is not a default you can leave for later. The Dify environment variable reference says workspace encryption keys can be stored locally or in Azure Key Vault. Choosing between those two options determines where the key material that protects each workspace's stored credentials lives, who can reach it, and how it is audited.
A workspace encryption key protects the credentials a workspace stores, such as the API keys you enter for model providers and tools. Those credentials are what Dify must decrypt to call external services, so the key's location shapes your exposure if the Dify database or its host is compromised. Treat this as a platform configuration decision that the platform team owns jointly with security and compliance, not as a checkbox. The owner should be the person who answers for key custody in your control framework, and that person should sign off on the setting before any workspace is created.
Confirm three things with your security lead and with Dify's documentation before you choose: whether the key store must sit in your Azure subscription and region, whether your policy requires keys to be held outside the application host, and whether the team can operate a vault alongside the Dify stack. Record the decision in your architecture file, because changing the key store after workspaces hold credentials is a migration project in its own right, not a setting you flip.
Local storage or Azure Key Vault for workspace keys
This table compares storing Dify workspace encryption keys on local disk with storing them in Azure Key Vault across custody, ownership, Azure dependency, audit evidence and the work each option leaves to your team. Read it as a checklist of what you must build for each choice, because the key location is set before the first workspace exists.
| Factor | Local storage | Azure Key Vault |
|---|---|---|
| Key custody | Keys sit on the Dify host or its volumes, so anyone with host or volume access can read them alongside the data they protect | Keys are held in the vault, and Dify reads them at runtime, so custody depends on vault access policies and who can administer the vault |
| Operational ownership | Your team owns key backup, host hardening and any key recovery procedure | Your team owns the vault, its access model, networking and lifecycle, and the identity Dify uses to reach it |
| Dependency on Azure connectivity | No Azure dependency for key retrieval, so an Azure outage or network path change does not block Dify | Dify must reach the vault from its network, so vault availability, DNS and firewall rules become part of the Dify runtime path |
| Audit evidence | Evidence is host logs and your own change records, which you must design to show who touched key material | Vault audit logs can show key access events, which you must confirm are enabled, retained and exported to your logging system |
| Authentication to the store | Filesystem permissions on the host, which you must set and test | Confirm with the Dify environment reference and Azure documentation how Dify authenticates to Key Vault, including whether managed identity is supported |
| Key rotation | Rotation is a manual procedure you design, test and document | Confirm with Azure documentation which rotation features apply to the keys Dify stores and how Dify picks up a rotated key |
| Migration after first use | Moving keys later requires re-encrypting or re-keying stored workspace credentials, so plan a window and test restore | Moving to the vault later has the same re-keying concern, so confirm with Dify docs whether a supported path exists before go-live |
| What to build around it | Host hardening, encrypted backups of key material, restore tests and access reviews | Vault RBAC or access policies, private networking, audit log export, a break-glass process and monitoring of vault access failures |
Why the storage choice must be made before the first workspace
The choice of where workspace encryption keys live should be fixed before any workspace holds real credentials. Dify's environment reference says workspace encryption keys can be stored locally or in Azure Key Vault. Those keys protect the credentials that model providers, tools and data sources store inside each workspace. Once a workspace has saved provider credentials under one storage choice, moving that workspace to the other choice is a change to live encrypted data, not a configuration tweak. Before you create the first workspace, record the decision, the reason for it and the person who approved it in your deployment design, so the choice is not made by default during setup.
Ask Dify in writing whether an existing workspace's keys can be moved from local storage to Azure Key Vault, or back, and what the supported procedure is. The supplied facts do not describe a migration path, so treat any answer as something to confirm with Dify and to test in your own non-production environment before you rely on it. A later change would touch the environment configuration that selects the key store, the Key Vault resource and its access policy, the stored credentials in every affected workspace, and your backup and restore runbook, since a restore must be able to decrypt what it restores. Name the approvers now: typically the platform owner, the security lead who signs off on key custody, and the application owners whose model credentials would be re-entered or re-encrypted if the procedure requires it.
Document the current state so a later review can check it. Record the key store in use, the vault name and region, the identity that reads from it, who holds administrative rights on the vault, and the rotation expectations you have agreed with the security team. Keep the same record for the .env settings that select the key store, stored in your configuration management system rather than a shared file. Then test a restore from backup into a clean environment with the same key configuration, because that test is the only way to show that the stored credentials can still be decrypted.
Decisions to settle before the first workspace exists
Each card below is a decision that is hard to reverse once the first workspace holds encrypted credentials. Settle them with your Azure team and your Dify vendor before the first workspace is created, so the key store, identity and recovery path are built in from the start.
Choose the key store
Decide whether workspace encryption keys live locally on the Dify host or in Azure Key Vault. The Dify environment reference lists both options, so the choice is a configuration setting, but moving keys later means planning a re-encryption of stored credentials. Ask the vendor whether a switch after the first workspace is supported and what it involves.
Assign the subscription and vault
Decide which Azure subscription and which vault will own the keys, and whether they sit with the same team that runs the Dify host. Separate ownership from the application team where your policy requires it. Ask the Azure team which subscription and resource group are approved for production key material and how vault names are standardized across environments.
Name the vault administrators
Define who can create, read, rotate and delete keys and who can change vault access policies. Keep administrative rights separate from the identity the Dify host uses at runtime. Ask the Azure team how privileged roles are granted, reviewed and logged, and who approves a change to key permissions.
Give the host a managed identity
Decide how the Dify host authenticates to Key Vault, preferably with a managed identity assigned to the virtual machine or container runtime rather than a stored client secret. Scope that identity to only the key operations Dify needs. Ask the Azure team whether a managed identity is available in your hosting model and how its permissions are reviewed.
Plan the network path
Decide whether Dify reaches Key Vault over the public endpoint with firewall rules or over a private endpoint inside your virtual network. Confirm that DNS resolves the vault name to the chosen endpoint from every Dify container host. Ask the network team which egress path is allowed and whether the SSRF proxy settings affect calls to the vault.
Set backup and recovery
Decide how key material is protected if the vault is deleted or a region fails. Confirm that soft delete and purge protection are enabled on the vault and that deletion needs a documented approval. Ask the Azure team what recovery steps exist for a deleted key and rehearse a restore of a Dify workspace against a test vault before go-live.
Setting up Key Vault for a new Dify deployment
This sequence takes a new self-hosted Dify instance from an empty Azure tenant to a verified state in which the first workspace stores its encryption key in Azure Key Vault. Each step closes with a check, so the team knows the key store works before any real data arrives.
Confirm the key storage option and vault requirements
Before touching Azure, the platform owner reads the workspace encryption key settings in the Dify environment variable reference and the current release notes for the target version. Confirm the exact variable names, the accepted values for selecting Azure Key Vault, the vault URL format, and the minimum permissions the vault's access model requires. Record the target Dify version next to these answers, since the docs and release notes are the authority for names and permissions. Done when the team has a written list of variable names, required permissions and the Dify version they were checked against.
Provision the vault in the customer tenant
The cloud or security team creates an Azure Key Vault in the subscription and region that the organization already uses for regulated workloads, and sets the access model and network rules according to its own policy. Keep the vault under the organization's own tenant and governance, with logging and deletion protection set as its policies require. Done when the vault exists, its URL is recorded, and a管理 administrator who is not the Dify operator can see it in the portal or CLI.
Assign a managed identity to the Dify host
The platform team enables a managed identity on the virtual machine or container host that runs the Dify api and worker services, or assigns a user-assigned identity if the organization prefers reusable identities. Authentication then uses that identity instead of a stored client secret, which keeps credentials out of the .env file. Done when the identity's object ID is recorded and the host can request a token for Azure Key Vault from its instance metadata endpoint.
Grant the host identity least-privilege vault access
An Azure administrator grants the host identity only the key or secret permissions the Dify release requires, scoped to this vault and not to the subscription. Use the access model chosen in the first step, whether role-based access control or a vault access policy. Ask the platform team to confirm in writing which operations Dify performs, so no broader role is granted by default. Done when a test read and write from the host succeed under this identity and an identity without the grant is refused.
Set the key storage option before first workspace creation
The operator sets the workspace encryption key storage variable and the vault connection values in the Dify environment file, using the names confirmed in the first step, and then starts the stack. Do this before any workspace is created, because keys for workspaces that already exist are not moved by changing this setting. Keep the file under restricted permissions and store it in the organization's secrets process. Done when the api service starts cleanly and its logs show no authentication errors against the vault.
Create a test workspace and confirm the key location
The operator creates a throwaway workspace on the non-production instance, which generates its encryption key. The team then checks the vault for a new key object created for that workspace, and confirms the key does not appear as a plain file on the host storage. Record the workspace identifier and the vault object name for the audit file. Done when the key is visible in the vault and absent from the local data volume.
Verify that the workspace reads its key back
The operator stores a test credential in the throwaway workspace, such as a dummy model provider key, restarts the api and worker services, and confirms the credential still decrypts and the workspace works. This proves the vault read path works after a restart, not just the initial write. Remove the test workspace and its vault object according to the retention policy once the check is recorded. Done when the credential decrypts after restart and the test evidence is saved with the deployment record.
Securing the Key Vault path next to SECRET_KEY
Moving workspace encryption keys into Azure Key Vault adds a dependency that sits beside SECRET_KEY, the value that signs sessions and encrypts OAuth credentials. The cards below cover how to keep those two secrets, the vault permissions, the env file that names the vault, and the upgrade routine in one deliberate operating model.
Document SECRET_KEY separately
SECRET_KEY signs session cookies and JWTs and encrypts OAuth credentials, and changing it after deployment logs out all users. Keep it in its own record, apart from the vault configuration, with its owner and the change window noted. Confirm that your runbook says who can rotate it and what breaks when it changes, so a vault change is never mistaken for a key rotation.
Scope the vault to the Dify identity
Grant the identity that Dify uses only the key operations the workspace key flow needs, and no vault administration rights. Confirm which identity your deployment authenticates with, whether a managed identity on the host or another approved method, and review who else holds access to the same vault. Treat any broader grant as a finding to fix before the first workspace is created.
Log and monitor vault access
Enable diagnostic logging on the vault and send its audit events to the same place your other security logs go. Build alerts for unexpected callers, failed key operations and access from outside the Dify host network. Confirm that someone reviews these alerts on a set schedule, because logs that nobody reads do not show a compromise.
Protect the env file naming the vault
The env file tells Dify which vault to use and how to authenticate, so its exposure reveals the target even when keys stay protected. Restrict file permissions to the service account, keep it out of version control and backups that leave your control, and check that container logs never echo its values. Record who may edit it and require a review for each change.
Test vault recovery before production
Confirm that a workspace can still be opened after the vault is made unavailable, rotated or restored in a test environment. Document the steps to restore access, including soft-delete and purge settings you choose for the vault. Run this test on a schedule and after each vault change, since a recovery plan that has never run is an assumption.
Add env variables to upgrade checks
Dify's docs recommend a backup before every upgrade and advise checking .env.example for new variables after upgrading. Add a step to your upgrade checklist that compares the current env file against the target release's example, and that confirms the vault settings and SECRET_KEY are still present. Confirm the release notes for each target version before you change production.
What buyers ask about Key Vault for Dify keys
Is Azure Key Vault for Dify workspace keys included in the Community edition?
The Community edition is free and limited to a single workspace, according to the Dify pricing page, and the Key Vault option is described in Dify's environment variable reference as a place workspace encryption keys can be stored. Whether your Community deployment can use it depends on the version you run and the configuration you set, so confirm that against the Dify environment variables reference for your release. Multi-workspace operation is a separate matter: the pricing page lists multiple workspaces as part of the self-hosted Enterprise edition, which is custom priced.
What does the Key Vault work cost, and what drives the effort?
DeployOpen does not publish a price list, so the cost follows from a written scope. The main drivers are how many Azure subscriptions and vaults you operate, whether a managed identity model already exists, how your network allows access to Key Vault from the Dify hosts, and how much of your existing key rotation process must be matched. Cost is mostly one-time design and configuration, plus any recurring retainer you choose for upgrades and rotation checks. Ask for a quote that lists each of these items separately.
How long does setup take in general terms?
Setup length depends on whether the Azure identity, networking and vault layout already exist, and on how many Dify instances need the same pattern. Work usually splits into design of vault and identity boundaries, configuration on the Dify side, a test on a non-production instance, and a documented rotation runbook. The timing is set in the fixed-scope agreement, so ask for a timeline tied to those phases rather than a generic duration.
What must our team provide before the work starts?
Expect to provide Azure subscription access with rights to create or read vaults and assign roles, a clear owner for the Key Vault and its access policies, network details for the hosts that run Dify, and a decision on where Dify runs. You also need the existing key lifecycle policy, the list of planned workspaces, and a contact who can approve a test rotation. Confirm with your Azure administrators which roles they will grant, since that decides how much of the setup your team can review.
Can our own platform team set this up without a partner?
Yes, if your team already runs Azure identity and Dify, and it can test the change outside production. The work needs managed identity assignment, vault access rights, a correct Dify configuration, and a rehearsed rotation. Most of the risk sits in the decisions made before the first workspace exists, so a team that has not done this before may want a design review even if it does the build itself. Your team can also use the Dify deployment overview to check the target layout.
What happens if we must change the storage choice later?
Changing from local storage to Key Vault after workspaces exist means the existing encryption keys and the data they protect must be handled carefully. Plan a migration window, confirm backups of the metadata database and any stored credentials, and test the move on a copy first. Because the choice is easier to make early, decide the storage model before the first workspace is created, and record the reasoning so a later change is an explicit project rather than a quiet configuration edit.
Does automatic key rotation remove the need for an operations process?
No. Automatic rotation in Key Vault reduces manual steps, but Dify still needs to pick up the new key version correctly, and your team must confirm that workspaces keep decrypting stored credentials after rotation. Keep a runbook for failed rotation, alerts on vault access errors, and a restore test from backup. Also check each Dify upgrade against the Dify releases on GitHub page, because minor releases arrive roughly monthly and may change configuration.
Limits to confirm before you commit to Key Vault
Each card names a point the team must verify in its own environment before choosing Key Vault for workspace keys. None of these points is settled by the public material alone, and the answers depend on the Dify release, the edition and the Azure setup you plan to run.
Release and key storage behavior
Confirm which Dify release you will deploy and how that release stores workspace encryption keys when Azure Key Vault is selected. The environment variable reference says keys can be stored locally or in Azure Key Vault, but the exact configuration keys and their behavior can differ between releases. Read the release notes for the version you plan to run, and test the configuration in a non-production instance before you commit.
Managed identity support
Confirm that your chosen release can authenticate to Key Vault with a managed identity rather than a client secret or certificate stored in the environment file. Check how the identity is attached to the host or container platform you run Dify on, and whether the Dify process picks up the identity without extra configuration. A client secret in .env would move the credential problem rather than remove it.
Automatic key rotation
Confirm whether your release rotates workspace keys automatically when the vault rotates them, or whether rotation is a manual, planned task. Ask how Dify re-reads a rotated key version, whether existing encrypted credentials need re-encryption, and whether a rotation can be tested on a copy of the database first. Record the answer, because it decides the runbook you will need.
Moving existing workspace keys
Confirm whether workspaces created with local storage can be moved to Key Vault after they hold credentials. If the migration path is not documented for your version, plan on the assumption that existing encrypted values may need to be re-entered or re-encrypted, and test that with a backup restored to a separate environment. Ask the vendor or your partner to put the answer in writing.
Community and Enterprise multi-workspace differences
Confirm how your edition handles multiple workspaces before you plan the key layout. The pricing page says Community is limited to a single workspace, while Enterprise adds multiple workspaces, so a multi-workspace key design may depend on Enterprise licensing. Ask whether each workspace can use its own vault key or whether all workspaces share one, since that choice affects blast radius and rotation effort.
Vault region and network rules
Confirm the Key Vault region, its firewall and private endpoint settings, and how Dify reaches the vault from your network. If the vault is unreachable at startup or during key retrieval, workspace credential access may fail, so check the availability of the vault against your Dify recovery objectives. Test a vault outage in a staging environment and document what users see.
How DeployOpen scopes and delivers Dify key management
DeployOpen plans the Azure Key Vault decision for Dify workspace encryption keys before the first workspace is created, because the choice shapes how keys are stored from the start. We scope, build, document and hand over the setup inside your own Azure subscription, and we can support it afterward under a retainer.
How we scope
- Confirm which Dify edition and workspace model you run, and whether multi-workspace use is in your plan
- Map the Azure subscription, vault placement, networking and identity owners who will operate the setup
- Record the managed identity design, key rotation ownership and the backup and recovery expectations in the written scope
- Agree deliverables and timelines in writing before any work starts, since engagements are fixed-scope
How we build
- Configure the Dify environment so workspace encryption keys are held in Azure Key Vault from the first deployment
- Set up managed identity access so the Dify services authenticate to the vault without stored client secrets
- Test automatic key rotation and confirm how existing encrypted data behaves after a rotation event
- Verify that a fresh workspace creates and uses keys in the vault, and that access is denied to unauthorized identities
How we hand over
- Document the vault layout, identity assignments, access policies and the rotation settings as built
- Provide a runbook covering key recovery, vault access reviews and what to check after a Dify upgrade
- Walk your platform, security and compliance owners through the configuration and the evidence it produces
- Confirm with your Azure and Dify administrators which settings we could not verify in your environment
How we support
- Offer ongoing support, upgrades and continuous testing as a retainer, scoped in writing
- Review vault permissions, rotation logs and identity assignments on the schedule agreed in the retainer
- Plan key-related changes ahead of Dify minor releases, which arrive roughly monthly, and test them first
- Prepare configuration and evidence for your compliance assessment, while independent auditors issue any reports
