1# Guide for migrating to azure-keyvault-secrets from azure-keyvault 2 3This guide is intended to assist in the migration to `azure-keyvault-secrets` from `azure-keyvault`. It will focus on side-by-side comparisons for similar operations between the two packages. 4 5Familiarity with the `azure-keyvault` package is assumed. For those new to the Key Vault client library for Python, please refer to the [README for `azure-keyvault-secrets`](https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/keyvault/azure-keyvault-secrets/README.md) rather than this guide. 6 7## Table of contents 8 9* [Migration benefits](#migration-benefits) 10* [Important changes](#important-changes) 11 - [Separate packages and clients](#separate-packages-and-clients) 12 - [Client constructors](#client-constructors) 13 - [Async operations](#async-operations) 14 - [Set a secret](#set-a-secret) 15 - [Retrieve a secret](#retrieve-a-secret) 16 - [List properties of secrets](#list-properties-of-secrets) 17 - [Delete a secret](#delete-a-secret) 18* [Additional samples](#additional-samples) 19 20## Migration benefits 21 22A natural question to ask when considering whether or not to adopt a new version or library is what the benefits of doing so would be. As Azure has matured and been embraced by a more diverse group of developers, we have been focused on learning the patterns and practices to best support developer productivity and to understand the gaps that the Python client libraries have. 23 24There were several areas of consistent feedback expressed across the Azure client library ecosystem. One of the most important is that the client libraries for different Azure services have not had a consistent approach to organization, naming, and API structure. Additionally, many developers have felt that the learning curve was difficult, and the APIs did not offer a good, approachable, and consistent onboarding story for those learning Azure or exploring a specific Azure service. 25 26To try and improve the development experience across Azure services, a set of uniform [design guidelines](https://azure.github.io/azure-sdk/python/guidelines/index.html) was created for all languages to drive a consistent experience with established API patterns for all services. A set of [Python-specific guidelines](https://azure.github.io/azure-sdk/python_design.html) was also introduced to ensure that Python clients have a natural and idiomatic feel with respect to the Python ecosystem. Further details are available in the guidelines for those interested. 27 28### Cross Service SDK improvements 29 30The modern Key Vault client library also provides the ability to share in some of the cross-service improvements made to the Azure development experience, such as 31- using the new [`azure-identity`](https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/identity/azure-identity/README.md) library to share a single authentication approach between clients 32- a unified logging and diagnostics pipeline offering a common view of the activities across each of the client libraries 33 34## Important changes 35 36### Separate packages and clients 37 38In the interest of simplifying the API `azure-keyvault` and `KeyVaultClient` were split into separate packages and clients: 39 40- [`azure-keyvault-certificates`](https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/keyvault/azure-keyvault-certificates/README.md) contains `CertificateClient` for working with certificates. 41- [`azure-keyvault-keys`](https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/keyvault/azure-keyvault-keys/README.md) contains `KeyClient` for working with keys and `CryptographyClient` for performing cryptographic operations. 42- `azure-keyvault-secrets` contains `SecretClient` for working with secrets. 43 44### Client constructors 45 46Across all modern Azure client libraries, clients consistently take an endpoint or connection string along with token credentials. This differs from `KeyVaultClient`, which took an authentication delegate and could be used for multiple Key Vault endpoints. 47 48#### Authenticating 49 50Previously in `azure-keyvault` you could create a `KeyVaultClient` by using `ServicePrincipalCredentials` from `azure.common`: 51 52```python 53from azure.common.credentials import ServicePrincipalCredentials 54from azure.keyvault import KeyVaultClient 55 56credentials = ServicePrincipalCredentials( 57 client_id="client id", 58 secret="client secret", 59 tenant="tenant id" 60) 61 62client = KeyVaultClient(credentials) 63``` 64 65Now in `azure-keyvault-secrets` you can create a `SecretClient` using any credential from [`azure-identity`](https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/identity/azure-identity/README.md). Below is an example using [`DefaultAzureCredential`](https://docs.microsoft.com/python/api/azure-identity/azure.identity.defaultazurecredential?view=azure-python): 66 67```python 68from azure.identity import DefaultAzureCredential 69from azure.keyvault.secrets import SecretClient 70 71credential = DefaultAzureCredential() 72 73secret_client = SecretClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential) 74``` 75 76### Async operations 77 78The modern `azure-keyvault-secrets` library includes a complete async API supported on Python 3.5+. To use it, you must first install an async transport, such as [aiohttp](https://pypi.org/project/aiohttp/). See [azure-core documentation](https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/core/azure-core/CLIENT_LIBRARY_DEVELOPER.md#transport) for more information. 79 80Async operations are available on async clients, which should be closed when they're no longer needed. Each async client is an async context manager and defines an async `close` method. For example: 81 82```python 83from azure.identity.aio import DefaultAzureCredential 84from azure.keyvault.secrets.aio import SecretClient 85 86credential = DefaultAzureCredential() 87 88# call close when the client is no longer needed 89client = SecretClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential) 90... 91await client.close() 92 93# alternatively, use the client as an async context manager 94client = SecretClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential) 95async with client: 96 ... 97``` 98 99### Set a secret 100 101In `azure-keyvault` you could set a secret by using `KeyVaultClient`'s `set_secret` method, which required a vault endpoint, secret name, and value. This method returned a `SecretBundle` containing the secret. 102 103```python 104secret_bundle = client.set_secret( 105 vault_base_url="https://my-key-vault.vault.azure.net/", 106 secret_name="secret-name", 107 value="secret-value" 108) 109secret_value = secret_bundle.value 110``` 111 112Now in `azure-keyvault-secrets` you can set a secret by using `set_secret` with a secret name and value. This returns the created secret (as a `KeyVaultSecret`). 113 114```python 115secret = secret_client.set_secret(name="secret-name", value="secret-value") 116secret_value = secret.value 117``` 118 119### Retrieve a secret 120 121In `azure-keyvault` you could retrieve a secret (in a `SecretBundle`) by using `get_secret` and specifying the desired vault endpoint, secret name, and secret version. You could retrieve the versions of a secret with the `get_secret_versions` method, which returned an iterator-like object. 122 123```python 124from azure.keyvault import SecretId 125 126secret_items = client.get_secret_versions( 127 vault_base_url="https://my-key-vault.vault.azure.net/", 128 secret_name="secret-name" 129) 130 131for secret_item in secret_items: 132 secret_id = SecretId(secret_item.id) 133 secret_version = secret_id.version 134 135 secret_bundle = client.get_secret( 136 vault_base_url="https://my-key-vault.vault.azure.net/", 137 secret_name="secret-name", 138 secret_version=secret_version 139 ) 140 secret_value = secret_bundle.value 141``` 142 143Now in `azure-keyvault-secrets` you can retrieve the latest version of a secret (as a `KeyVaultSecret`) by using `get_secret` and providing a secret name. 144 145```python 146secret = secret_client.get_secret(name="secret-name") 147 148print(secret.name) 149print(secret.value) 150 151# get the version of the secret 152secret_version = secret.properties.version 153``` 154 155### List properties of secrets 156 157In `azure-keyvault` you could list the properties of secrets in a specified vault with the `get_secrets` method. This returned an iterator-like object containing `SecretItem` instances. 158 159```python 160secrets = client.get_secrets(vault_base_url="https://my-key-vault.vault.azure.net/") 161 162for secret in secrets: 163 print(secret.attributes.content_type) 164``` 165 166Now in `azure-keyvault-secrets` you can list the properties of secrets in a vault with the `list_properties_of_secrets` method. This returns an iterator-like object containing `SecretProperties` instances. 167 168```python 169secrets = secret_client.list_properties_of_secrets() 170 171for secret in secrets: 172 print(secret.name) 173 print(secret.content_type) 174``` 175 176### Delete a secret 177 178In `azure-keyvault` you could delete all versions of a secret with the `delete_secret` method. This returned information about the deleted secret (as a `DeletedSecretBundle`), but you could not poll the deletion operation to know when it completed. This would be valuable information if you intended to permanently delete the deleted secret with `purge_deleted_secret`. 179 180```python 181deleted_secret = client.delete_secret( 182 vault_base_url="https://my-key-vault.vault.azure.net/", 183 secret_name="secret-name" 184) 185 186# this purge would fail if deletion hadn't finished 187client.purge_deleted_secret( 188 vault_base_url="https://my-key-vault.vault.azure.net/", 189 secret_name="secret-name" 190) 191``` 192 193Now in `azure-keyvault-secrets` you can delete a secret with `begin_delete_secret`, which returns a long operation poller object that can be used to wait/check on the operation. Calling `result()` on the poller will return information about the deleted secret (as a `DeletedSecret`) without waiting for the operation to complete, but calling `wait()` will wait for the deletion to complete. Again, `purge_deleted_secret` will permanently delete your deleted secret and make it unrecoverable. 194 195```python 196deleted_secret_poller = secret_client.begin_delete_secret(name="secret-name") 197deleted_secret = deleted_secret_poller.result() 198 199deleted_secret_poller.wait() 200secret_client.purge_deleted_secret(name="secret-name") 201``` 202 203## Additional samples 204 205* [Key Vault secrets samples for Python](https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/keyvault/azure-keyvault-secrets/samples) 206* [General Key Vault samples for Python](https://docs.microsoft.com/samples/browse/?products=azure-key-vault&languages=python)