azure-keyvault-secrets
Advanced tools
Azure Key Vault helps solve the following problems:
Source code | Package (PyPI) | Package (Conda) | API reference documentation | Product documentation | Samples
Azure SDK Python packages support for Python 2.7 has ended 01 January 2022. For more information and questions, please refer to https://github.com/Azure/azure-sdk-for-python/issues/20691. Python 3.8 or later is required to use this package. For more details, please refer to Azure SDK for Python version support policy.
Install azure-keyvault-secrets and azure-identity with pip:
pip install azure-keyvault-secrets azure-identity
azure-identity is used for Azure Active Directory authentication as demonstrated below.
In order to interact with the Azure Key Vault service, you will need an instance of a SecretClient, as well as a vault url and a credential object. This document demonstrates using a DefaultAzureCredential, which is appropriate for most scenarios, including local development and production environments. We recommend using a managed identity for authentication in production environments.
See azure-identity documentation for more information about other methods of authentication and their corresponding credential types.
After configuring your environment for the DefaultAzureCredential to use a suitable method of authentication, you can do the following to create a secret client (replacing the value of VAULT_URL with your vault's URL):
VAULT_URL = os.environ["VAULT_URL"]
credential = DefaultAzureCredential()
client = SecretClient(vault_url=VAULT_URL, credential=credential)
NOTE: For an asynchronous client, import
azure.keyvault.secrets.aio'sSecretClientinstead.
A secret consists of a secret value and its associated metadata and management information. This library handles secret values as strings, but Azure Key Vault doesn't store them as such. For more information about secrets and how Key Vault stores and manages them, see the Key Vault documentation.
SecretClient can set secret values in the vault, update secret metadata, and delete secrets, as shown in the examples below.
This section contains code snippets covering common tasks:
set_secret
creates new secrets and changes the values of existing secrets. If no secret with the
given name exists, set_secret creates a new secret with that name and the
given value. If the given name is in use, set_secret creates a new version
of that secret, with the given value.
from azure.identity import DefaultAzureCredential
from azure.keyvault.secrets import SecretClient
credential = DefaultAzureCredential()
secret_client = SecretClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
secret = secret_client.set_secret("secret-name", "secret-value")
print(secret.name)
print(secret.value)
print(secret.properties.version)
get_secret retrieves a secret previously stored in the Key Vault.
from azure.identity import DefaultAzureCredential
from azure.keyvault.secrets import SecretClient
credential = DefaultAzureCredential()
secret_client = SecretClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
secret = secret_client.get_secret("secret-name")
print(secret.name)
print(secret.value)
update_secret_properties updates a secret's metadata. It cannot change the secret's value; use set_secret to set a secret's value.
from azure.identity import DefaultAzureCredential
from azure.keyvault.secrets import SecretClient
credential = DefaultAzureCredential()
secret_client = SecretClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
# Clients may specify the content type of a secret to assist in interpreting the secret data when it's retrieved
content_type = "text/plain"
# We will also disable the secret for further use
updated_secret_properties = secret_client.update_secret_properties("secret-name", content_type=content_type, enabled=False)
print(updated_secret_properties.updated_on)
print(updated_secret_properties.content_type)
print(updated_secret_properties.enabled)
begin_delete_secret
requests Key Vault delete a secret, returning a poller which allows you to wait for the deletion to finish. Waiting is
helpful when the vault has soft-delete enabled, and you want to purge (permanently delete) the secret as
soon as possible. When soft-delete is disabled, begin_delete_secret itself is permanent.
from azure.identity import DefaultAzureCredential
from azure.keyvault.secrets import SecretClient
credential = DefaultAzureCredential()
secret_client = SecretClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
deleted_secret = secret_client.begin_delete_secret("secret-name").result()
print(deleted_secret.name)
print(deleted_secret.deleted_date)
list_properties_of_secrets lists the properties of all of the secrets in the client's vault. This list doesn't include the secret's values.
from azure.identity import DefaultAzureCredential
from azure.keyvault.secrets import SecretClient
credential = DefaultAzureCredential()
secret_client = SecretClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
secret_properties = secret_client.list_properties_of_secrets()
for secret_property in secret_properties:
# the list doesn't include values or versions of the secrets
print(secret_property.name)
This library includes a complete set of async APIs. To use them, you must first install an async transport, such as aiohttp. See azure-core documentation for more information.
Async clients and credentials should be closed when they're no longer needed. These
objects are async context managers and define async close methods. For
example:
from azure.identity.aio import DefaultAzureCredential
from azure.keyvault.secrets.aio import SecretClient
credential = DefaultAzureCredential()
# call close when the client and credential are no longer needed
client = SecretClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
...
await client.close()
await credential.close()
# alternatively, use them as async context managers (contextlib.AsyncExitStack can help)
client = SecretClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
async with client:
async with credential:
...
set_secret creates a secret in the Key Vault with the specified optional arguments.
from azure.identity.aio import DefaultAzureCredential
from azure.keyvault.secrets.aio import SecretClient
credential = DefaultAzureCredential()
secret_client = SecretClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
secret = await secret_client.set_secret("secret-name", "secret-value")
print(secret.name)
print(secret.value)
print(secret.properties.version)
list_properties_of_secrets lists the properties of all of the secrets in the client's vault.
from azure.identity.aio import DefaultAzureCredential
from azure.keyvault.secrets.aio import SecretClient
credential = DefaultAzureCredential()
secret_client = SecretClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
secret_properties = secret_client.list_properties_of_secrets()
async for secret_property in secret_properties:
# the list doesn't include values or versions of the secrets
print(secret_property.name)
See the azure-keyvault-secrets
troubleshooting guide
for details on how to diagnose various failure scenarios.
Key Vault clients raise exceptions defined in azure-core. For example, if you try to get a key that doesn't exist in the vault, SecretClient raises ResourceNotFoundError:
from azure.identity import DefaultAzureCredential
from azure.keyvault.secrets import SecretClient
from azure.core.exceptions import ResourceNotFoundError
credential = DefaultAzureCredential()
secret_client = SecretClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
try:
secret_client.get_secret("which-does-not-exist")
except ResourceNotFoundError as e:
print(e.message)
This library uses the standard logging library for logging. Basic information about HTTP sessions (URLs, headers, etc.) is logged at INFO level.
Detailed DEBUG level logging, including request/response bodies and unredacted
headers, can be enabled on a client with the logging_enable argument:
from azure.identity import DefaultAzureCredential
from azure.keyvault.secrets import SecretClient
import sys
import logging
# Create a logger for the 'azure' SDK
logger = logging.getLogger('azure')
logger.setLevel(logging.DEBUG)
# Configure a console output
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)
credential = DefaultAzureCredential()
# This client will log detailed information about its HTTP sessions, at DEBUG level
secret_client = SecretClient(
vault_url="https://my-key-vault.vault.azure.net/",
credential=credential,
logging_enable=True
)
Similarly, logging_enable can enable detailed logging for a single operation,
even when it isn't enabled for the client:
secret_client.get_secret("my-secret", logging_enable=True)
Several samples are available in the Azure SDK for Python GitHub repository. These provide example code for additional Key Vault scenarios:
For more extensive documentation on Azure Key Vault, see the API reference documentation.
This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.
When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.
This project has adopted the Microsoft Open Source Code of Conduct. For more information, see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.
enable_cae=True is passed to all get_token requests.azure-core version to 1.31.07.5asyncio is no longer directly referenced by the library
(#33819)azure-core version to 1.29.5azure-common requirement7.5-preview.17.5-preview.1 is now the default7.4send_request method that can be used to send custom requests using the
client's existing pipeline (#25172)7.4 is now the defaultazure-core version to 1.24.0msrest requirementisodate>=0.6.1 (isodate was required by msrest)typing-extensions>=4.0.1verify_challenge_resource=False to client constructors to disable.
See https://aka.ms/azsdk/blog/vault-uri for more information.vault_url property of a KeyVaultSecretIdentifier
(#24446)azure-identity
1.8.0 or newer (#20698)managed property to SecretPropertiesazure-core version to 1.20.0get_token calls during challenge
authentication requests now pass in a tenant_id keyword argument
(#20698). See
https://aka.ms/azsdk/python/identity/tokencredential for more details on how to integrate
this parameter if get_token is implemented by a custom credential.managed property to SecretPropertiesget_token calls during challenge
authentication requests now pass in a tenant_id keyword argument
(#20698)azure-identity 1.7.1 or newer
(#20698)azure-core version to 1.15.0This is the last version to support Python 3.5. The next version will require Python 2.7 or 3.6+.
msrest version to 0.6.21KeyVaultSecretIdentifier that parses out a full ID returned by Key Vault,
so users can easily access the secret's name, vault_url, and version.x-ms-keyvault-region and x-ms-keyvault-service-version headers
are no longer redacted in logging outputazure-core version to 1.7.0CustomHookPolicy through the optional
keyword argument custom_hook_policyx-ms-client-request-idazure-common for multiapi supportrecoverable_days to CertificatePropertiesApiVersion enum identifying Key Vault versions supported by this packageSecretClient instances have a close method which closes opened sockets.
Used as a context manager, a SecretClient closes opened sockets on exit.
(#9906)azure.keyvault.secrets defines __version__msrest requirement to >=0.6.0KeyVaultErrorException
(#9690)set_secret now has positional parameters name and valueupdate_secret_properties now has positional parameters name and
(optional) versionlist_secrets to list_properties_of_secretslist_secret_versions to list_properties_of_secret_versionsdelete_secret to begin_delete_secretbegin_delete_secret and async delete_secret now return pollers that return a DeletedSecretSecret to KeyVaultSecretKeyVaultSecret properties created, expires, and updated renamed to created_on,
expires_on, and updated_onvault_endpoint parameter of SecretClient has been renamed to vault_urlvault_endpoint has been renamed to vault_url in all modelsSecret now has attribute properties, which holds certain properties of the
secret, such as version. This changes the shape of the returned Secret type,
as certain properties of Secret (such as version) have to be accessed
through the properties property.
update_secret has been renamed to update_secret_properties
The vault_url parameter of SecretClient has been renamed to vault_endpoint
The property vault_url has been renamed to vault_endpoint in all models
list_secrets and list_secret_versions return the correct typeThis release includes only internal changes.
azure.core.Configuration from the public API in preparation for a
revamped configuration API. Static create_config methods have been renamed
_create_config, and will be removed in a future release.azure-core 1.0.0b2
pip install azure-core==1.0.0b1 azure-keyvault-secrets==4.0.0b1Version 4.0.0b1 is the first preview of our efforts to create a user-friendly and Pythonic client library for Azure Key Vault. For more information about preview releases of other Azure SDK libraries, please visit https://aka.ms/azure-sdk-preview1-python.
This library is not a direct replacement for azure-keyvault. Applications
using that library would require code changes to use azure-keyvault-secrets.
This package's
documentation
and
samples
demonstrate the new API.
azure-keyvaultazure-keyvault-secrets contains a client for secret operations,
azure-keyvault-keys contains a client for key operationsazure.keyvault.secrets.aio namespace contains an async equivalent of
the synchronous client in azure.keyvault.secretsazure-identity credentials
azure-keyvault features not implemented in this libraryFAQs
Microsoft Azure Key Vault Secrets Client Library for Python
We found that azure-keyvault-secrets demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.
Security News
The Ultralytics' PyPI Package was compromised four times in one weekend through GitHub Actions cache poisoning and failure to rotate previously compromised API tokens.