Azure Key Vault developer's guide
Azure Key Vault allows you to securely access sensitive information from within your applications:
- Keys, secrets, and certificates are protected without you're having to write the code yourself, and you can easily use them from your applications.
- You allow customers to own and manage their own keys, secrets, and certificates so you can concentrate on providing the core software features. In this way, your applications won't own the responsibility or potential liability for your customers' tenant keys, secrets, and certificates.
- Your application can use keys for signing and encryption yet keep the key management external from your application. For more information, see About keys.
- You can manage credentials like passwords, access keys, and SAS tokens by storing them in Key Vault as secrets. For more information, see About secrets.
- Manage certificates. For more information, see About certificates.
For general information on Azure Key Vault, see About Azure Key Vault.
Public previews
Periodically, we release a public preview of a new Key Vault feature. Try out public preview features and let us know what you think via azurekeyvault@microsoft.com, our feedback email address.
Create and manage key vaults
As with other Azure services, Key Vault is managed through Azure Resource Manager. Azure Resource Manager is the deployment and management service for Azure. You can use it to create, update, and delete resources in your Azure account.
Azure role-based access control (RBAC) controls access to the management layer, also known as the management plane. You use the management plane in Key Vault to create and manage key vaults and their attributes, including access policies. You use the data plane to manage keys, certificates, and secrets.
You can use the predefined Key Vault Contributor role to grant management access to Key Vault.
APIs and SDKs for key vault management
| Azure CLI | PowerShell | REST API | Resource Manager | .NET | Python | Java | JavaScript |
|---|---|---|---|---|---|---|---|
| Reference Quickstart |
Reference Quickstart |
Reference | Reference Quickstart |
Reference | Reference | Reference | Reference |
For installation packages and source code, see Client libraries.
Authenticate to Key Vault in code
Key Vault uses Microsoft Entra authentication, which requires a Microsoft Entra security principal to grant access. A Microsoft Entra security principal can be a user, an application service principal, a managed identity for Azure resources, or a group of any of these types.
Authentication best practices
We recommend that you use a managed identity for applications deployed to Azure. If you use Azure services that don't support managed identities or if applications are deployed on-premises, a service principal with a certificate is a possible alternative. In that scenario, the certificate should be stored in Key Vault and frequently rotated.
Use a service principal with a secret for development and testing environments. Use a user principal for local development and Azure Cloud Shell.
We recommend these security principals in each environment:
- Production environment: Managed identity or service principal with a certificate.
- Test and development environments: Managed identity, service principal with certificate, or service principal with a secret.
- Local development: User principal or service principal with a secret.
Azure Identity client libraries
The preceding authentication scenarios are supported by the Azure Identity client library and integrated with Key Vault SDKs. You can use the Azure Identity client library across environments and platforms without changing your code. The library automatically retrieves authentication tokens from users who are signed in to Azure user through the Azure CLI, Visual Studio, Visual Studio Code, and other means.
For more information about the Azure Identity client library, see:
| .NET | Python | Java | JavaScript |
|---|---|---|---|
| Azure Identity SDK .NET | Azure Identity SDK Python | Azure Identity SDK Java | Azure Identity SDK JavaScript |
Note
We recommended App Authentication library for Key Vault .NET SDK version 3, but it's now deprecated. To migrate to Key Vault .NET SDK version 4, follow the AppAuthentication to Azure.Identity migration guidance.
For tutorials on how to authenticate to Key Vault in applications, see:
- Use Azure Key Vault with a virtual machine in .NET
- Use Azure Key Vault with a virtual machine in Python
- Use a managed identity to connect Key Vault to an Azure web app in .NET
Manage keys, certificates, and secrets
Note
SDKs for .NET, Python, Java, JavaScript, PowerShell, and the Azure CLI are part of the Key Vault feature release process through public preview and general availability with Key Vault service team support. Other SDK clients for Key Vault are available, but they are built and supported by individual SDK teams over GitHub and released in their teams schedule.
The data plane controls access to keys, certificates, and secrets. You can use local vault access policies or Azure RBAC for access control through the data plane.
APIs and SDKs for keys
| Azure CLI | PowerShell | REST API | Resource Manager | .NET | Python | Java | JavaScript |
|---|---|---|---|---|---|---|---|
| Reference Quickstart |
Reference Quickstart |
Reference | Reference Quickstart |
Reference Quickstart |
Reference Quickstart |
Reference Quickstart |
Reference Quickstart |
Other Libraries
Cryptography client for Key Vault and Managed HSM
This module provides a cryptography client for the Azure Key Vault Keys client module for Go.
Note
This project is not supported by the Azure SDK team, but does align with the cryptography clients in other supported languages.
| Language | Reference |
|---|---|
| Go | Reference |
APIs and SDKs for certificates
| Azure CLI | PowerShell | REST API | Resource Manager | .NET | Python | Java | JavaScript |
|---|---|---|---|---|---|---|---|
| Reference Quickstart |
Reference Quickstart |
Reference | N/A | Reference Quickstart |
Reference Quickstart |
Reference Quickstart |
Reference Quickstart |
APIs and SDKs for secrets
| Azure CLI | PowerShell | REST API | Resource Manager | .NET | Python | Java | JavaScript |
|---|---|---|---|---|---|---|---|
| Reference Quickstart |
Reference Quickstart |
Reference | Reference Quickstart |
Reference Quickstart |
Reference Quickstart |
Reference Quickstart |
Reference Quickstart |
Usage of secrets
Use Azure Key Vault to store only secrets for your application. Examples of secrets that should be stored in Key Vault include:
- Client application secrets
- Connection strings
- Passwords
- Shared access keys
- SSH keys
Any secret-related information, like usernames and application IDs, can be stored as a tag in a secret. For any other sensitive configuration settings, you should use Azure App Configuration.
References
For installation packages and source code, see Client libraries.
For information about data plane security for Key Vault, see Azure Key Vault security features.
Use Key Vault in applications
To take advantage of the most recent features in Key Vault, we recommend that you use the available Key Vault SDKs for using secrets, certificates, and keys in your application. The Key Vault SDKs and REST API are updated as new features are released for the product, and they follow best practices and guidelines.
For basic scenarios, there are other libraries and integration solutions for simplified usage, with support provided by Microsoft partners or open-source communities.
For certificates, you can use:
- The Key Vault virtual machine (VM) extension, which provides automatic refresh of certificates stored in an Azure key vault. For more information, see:
- Azure App Service integration, which can import and automatically refresh certificates from Key Vault. For more information, see Import a certificate from Key Vault.
For secrets, you can use:
- Key Vault secrets with App Service application settings. For more information, see Use Key Vault references for App Service and Azure Functions.
- Key Vault references with Azure App Configuration to streamline your application's access to configuration and secrets. For more information, see Use Key Vault references in Azure App Configuration.
Code examples
For complete examples of using Key Vault with applications, see Azure Key Vault code samples.
Task-specific guidance
The following articles and scenarios provide task-specific guidance for working with Azure Key Vault:
- To access a key vault, your client application needs to be able to access multiple endpoints for various functionalities. See Accessing Key Vault behind a firewall.
- A cloud application running in an Azure VM needs a certificate. How do you get this certificate into this VM? See Key Vault virtual machine extension for Windows or Key Vault virtual machine extension for Linux.
- To assign an access policy by using the Azure CLI, PowerShell, or the Azure portal, see Assign a Key Vault access policy.
- For guidance on the use and lifecycle of a key vault and various key vault objects with soft-delete enabled, see Azure Key Vault recovery management with soft delete and purge protection.
- When you need to pass a secure value (like a password) as a parameter during deployment, you can store that value as a secret in a key vault and reference the value in other Resource Manager templates. See Use Azure Key Vault to pass secure parameter values during deployment.
Integration with Key Vault
The following services and scenarios use or integrate with Key Vault:
- Encryption at rest allows the encoding (encryption) of data when it's persisted. Data encryption keys are often encrypted with a key encryption key in Azure Key Vault to further limit access.
- Azure Information Protection allows you to manage your own tenant key. For example, instead of Microsoft managing your tenant key (the default), you can manage your own tenant key to comply with specific regulations that apply to your organization. Managing your own tenant key is also called bring your own key (BYOK).
- Azure Private Link enables you to access Azure services (for example, Azure Key Vault, Azure Storage, and Azure Cosmos DB) and Azure-hosted customer/partner services over a private endpoint in your virtual network.
- Key Vault integration with Azure Event Grid allows users to be notified when the status of a secret stored in Key Vault has changed. You can distribute new versions of secrets to applications or rotate near-expiration secrets to prevent outages.
- Protect your Azure DevOps secrets from unwanted access in Key Vault.
- Use secrets stored in Key Vault to connect to Azure Storage from Azure Databricks.
- Configure and run the Azure Key Vault provider for the Secrets Store CSI driver on Kubernetes.
Key Vault overviews and concepts
To learn about:
- A feature that allows recovery of deleted objects, whether the deletion was accidental or intentional, see Azure Key Vault soft-delete overview.
- The basic concepts of throttling and get an approach for your app, see Azure Key Vault throttling guidance.
- The relationships between regions and security areas, see Azure Key Vault security worlds and geographic boundaries.