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 your 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 Azure Active Directory (Azure AD) authentication, which requires an Azure AD security principal to grant access. An Azure AD 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:

Manage keys, certificates, and secrets

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

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:

For secrets, you can use:

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:

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:

Social