From 322f5e30e25aae2165bb2b736b019242d1fb3907 Mon Sep 17 00:00:00 2001 From: iscai-msft Date: Tue, 1 Sep 2020 16:36:43 -0400 Subject: [PATCH 01/11] add administration readme --- .../azure-keyvault-administration/README.md | 228 +++++++++++++++++- 1 file changed, 215 insertions(+), 13 deletions(-) diff --git a/sdk/keyvault/azure-keyvault-administration/README.md b/sdk/keyvault/azure-keyvault-administration/README.md index f4333cb7ed36..9d758e59eb4e 100644 --- a/sdk/keyvault/azure-keyvault-administration/README.md +++ b/sdk/keyvault/azure-keyvault-administration/README.md @@ -1,29 +1,231 @@ -# Azure Key Vault Administration client library for Python +# Azure KeyVault Administration client library for .NET +Azure Key Vault helps solve the following problems: +- Vault administration (this library) - full backup / restore, and key-level +role-based access control (RBAC) of vaults. +- Cryptographic key management ([azure-keyvault-keys](https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/keyvault/azure-keyvault-keys)) - create, store, and control +access to the keys used to encrypt your data +- Secrets management +([azure-keyvault-secrets](https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/keyvault/azure-keyvault-secrets)) - +securely store and control access to tokens, passwords, certificates, API keys, +and other secrets +- Certificate management +([azure-keyvault-certificates](https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/keyvault/azure-keyvault-certificates)) - +create, manage, and deploy public and private SSL/TLS certificates ## Getting started +### Install packages +Install [azure-keyvault-administration][pypi_package_administration] and +[azure-identity][azure_identity_pypi] with [pip][pip]: +```Bash +pip install azure-keyvault-administration azure-identity +``` +[azure-identity][azure_identity] is used for Azure Active Directory +authentication as demonstrated below. +### Prerequisites +* An [Azure subscription][azure_sub] +* Python 2.7, 3.5.3, or later +* A Key Vault. If you need to create one, See the final two steps in the next section for details on creating the Key Vault with the Azure CLI. + +### Authenticate the client +This document demonstrates using [DefaultAzureCredential][default_cred_ref] +to authenticate as a service principal. However, [KeyVaultAccessControlClient][rbac_client_docs] +accepts any [azure-identity][azure_identity] credential. See the +[azure-identity][azure_identity] documentation for more information about other +credentials. + +#### Create/Get credentials +This [Azure Cloud Shell][azure_cloud_shell] snippet shows how to create a +new service principal. Before using it, replace "your-application-name" with +a more appropriate name for your service principal. + +* Create a service principal: + ```Bash + az ad sp create-for-rbac --name http://my-application --skip-assignment + ``` + + > Output: + > ```json + > { + > "appId": "generated app id", + > "displayName": "my-application", + > "name": "http://my-application", + > "password": "random password", + > "tenant": "tenant id" + > } + > ``` + +* Take note of the service principal objectId + ```Bash + az ad sp show --id --query objectId + ``` + + + > Output: + > ``` + > "" + > ``` + +* Use the output to set **AZURE_CLIENT_ID** ("appId" above), **AZURE_CLIENT_SECRET** + ("password" above) and **AZURE_TENANT_ID** ("tenant" above) environment variables. + The following example shows a way to do this in Bash: + ```Bash + export AZURE_CLIENT_ID="generated app id" + export AZURE_CLIENT_SECRET="random password" + export AZURE_TENANT_ID="tenant id" + ``` + +* Create the Key Vault and grant the above mentioned application authorization to perform administrative operations on the Azure Key Vault (replace `` and `` with your own, unique names and `` with the value from above): + ```Bash + az keyvault create --hsm-name --resource-group --administrators --location + ``` + +* Use the above mentioned Azure Key Vault name to retrieve details of your Vault which also contains your Azure Key Vault URL: + ```Bash + az keyvault show --hsm-name + ``` + +#### Create a client +Once the **AZURE_CLIENT_ID**, **AZURE_CLIENT_SECRET** and +**AZURE_TENANT_ID** environment variables are set, +[DefaultAzureCredential][default_cred_ref] will be able to authenticate the +[KeyVaultAccessControlClient][rbac_client_docs]. + +Constructing the client also requires your vault's URL, which you can +get from the Azure CLI or the Azure Portal. In the Azure Portal, this URL is +the vault's "DNS Name". + +```python +from azure.identity import DefaultAzureCredential +from azure.keyvault.administration import KeyVaultAccessControlClient + +credential = DefaultAzureCredential() + +client = KeyVaultAccessControlClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential) +``` ## Key concepts +### Role Definition +A role definition defines the operations that can be performed, such as read, write, and delete. It can also define the operations that are excluded from allowed operations. + +A role definition is specified as part of a role assignment. + +### Role Assignment. +A role assignment is the association of a role definition to a service principal. They can be created, listed, fetched individually, and deleted. + +### KeyVaultAccessControlClient +A `KeyVaultAccessControlClient` provides both synchronous and asynchronous operations allowing for management of role definitions and role assignments. + ## Examples +This section conntains code snippets covering common tasks: +* [List the role definitions](#list-the-role-definitions "List the role definitions") +* [Create, Get, and Delete a role assignment](#create-get-and-delete-a-role-assignment "Create, Get, and Delete a role assignment") + +### List the role definitions +List the role definitions available for assignment. + +```python +from azure.identity import DefaultAzureCredential +from azure.keyvault.administration import KeyVaultAccessControlClient + +credential = DefaultAzureCredential() + +client = KeyVaultAccessControlClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential) + +role_definitions = client.list_role_definitions(role_scope="/") # this is the global scope + +for role_definition in role_definitions: + print(role_definition.id) + print(role_definition.role_name) + print(role_definition.description) +``` + +### Create, Get, and Delete a role assignment +Assign a role to a service principal. This will require a role definition id from the list retrieved in the [above snippet](#list-the-role-definitions) and the principal object id retrieved in the [Create/Get credentials](#create/get-credentials) + +```python +from azure.identity import DefaultAzureCredential +from azure.keyvault.administration import KeyVaultAccessControlClient + +credential = DefaultAzureCredential() + +client = KeyVaultAccessControlClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential) + +role_scope = "/" # setting the scope to the global scope +role_assignment_name = "" # must be a UUID +role_definition = "" # Replace with a role definition from the definitions returned from the previous example +principal_id = "" + +# first, let's create the role assignment +role_assignment = client.create_role_assignment(role_scope, role_assignment_name, role_definition.id, principal_id) +print(role_assignment.name) +print(role_assignment.principal_id) +print(role_assignment.role_definition_id) + +# now, we get it +role_assignment = client.get_role_assignment(role_scope, role_assignment.name) +print(role_assignment.name) +print(role_assignment.principal_id) +print(role_assignment.role_definition_id) + +# finally, we delete this role assignment +role_assignment = client.delete_role_assignment(role_scope, role_assignment.name) +print(role_assignment.name) +print(role_assignment.principal_id) +print(role_assignment.role_definition_id) + +``` + ## Troubleshooting +### General +Key Vault clients raise exceptions defined in [azure-core][azure_core_exceptions]. +For example, if you try to get a role assignment that doesn't exist, [KeyVaultAccessControlClient][rbac_client_docs] +raises [ResourceNotFoundError](https://aka.ms/azsdk-python-core-exceptions-resource-not-found-error): + +```python +from azure.identity import DefaultAzureCredential +from azure.keyvault.administration import KeyVaultAccessControlClient +from azure.core.exceptions import ResourceNotFoundError + +credential = DefaultAzureCredential() +client = KeyVaultAccessControlClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential) + +try: + client.get_role_assignment("/", "which-does-not-exist") +except ResourceNotFoundError as e: + print(e.message) +``` ## Next steps +Content forthcoming + ## Contributing -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 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 [cla.microsoft.com][cla]. -This project has adopted the -[Microsoft Open Source Code of Conduct][code_of_conduct]. For more information, -see the Code of Conduct FAQ or contact opencode@microsoft.com with any +This project has adopted the [Microsoft Open Source Code of Conduct][coc]. +For more information see the [Code of Conduct FAQ][coc_faq] +or contact [opencode@microsoft.com][coc_contact] with any additional questions or comments. -![Impressions](https://azure-sdk-impressions.azurewebsites.net/api/impressions/azure-sdk-for-python%2Fsdk%2Fkeyvault%2Fazure-keyvault-administration%2FFREADME.png) + +[azure_cloud_shell]: https://shell.azure.com/bash +[azure_core_exceptions]: https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/core/azure-core#azure-core-library-exceptions +[azure_identity]: https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/identity/azure-identity +[azure_identity_pypi]: https://pypi.org/project/azure-identity/ +[azure_sub]: https://azure.microsoft.com/free/ +[default_cred_ref]: https://aka.ms/azsdk/python/identity/docs#azure.identity.DefaultAzureCredential +[code_of_conduct]: https://opensource.microsoft.com/codeofconduct/ +[keyvault_docs]: https://docs.microsoft.com/azure/key-vault/ +[pip]: https://pypi.org/project/pip/ +[pypi_package_administration]: https://pypi.org/project/azure-keyvault-administration/ +[reference_docs]: https://aka.ms/azsdk/python/keyvault-keys/docs +[rbac_client_docs]: https://aka.ms/azsdk/python/keyvault-administration/docs#azure.keyvault.administration.KeyVaultAccessControlClient + + +![Impressions](https://azure-sdk-impressions.azurewebsites.net/api/impressions/azure-sdk-for-net%2Fsdk%2Ftables%2FAzure.Data.Tables%2FREADME.png) \ No newline at end of file From 1a790053f9b5e2aa09c94bafb8ca3bbc104ff8d6 Mon Sep 17 00:00:00 2001 From: iscai-msft Date: Tue, 1 Sep 2020 16:38:41 -0400 Subject: [PATCH 02/11] add mention of administration package to other libraries --- sdk/keyvault/azure-keyvault-certificates/README.md | 2 ++ sdk/keyvault/azure-keyvault-keys/README.md | 2 ++ sdk/keyvault/azure-keyvault-secrets/README.md | 2 ++ 3 files changed, 6 insertions(+) diff --git a/sdk/keyvault/azure-keyvault-certificates/README.md b/sdk/keyvault/azure-keyvault-certificates/README.md index a0789714242b..13284737269f 100644 --- a/sdk/keyvault/azure-keyvault-certificates/README.md +++ b/sdk/keyvault/azure-keyvault-certificates/README.md @@ -7,6 +7,8 @@ Azure Key Vault helps solve the following problems: ([azure-keyvault-secrets](https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/keyvault/azure-keyvault-secrets)) - securely store and control access to tokens, passwords, certificates, API keys, and other secrets +- Vault administration ([azure-keyvault-administration](https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/keyvault/azure-keyvault-administration)) - full backup / restore, and key-level +role-based access control (RBAC) of vaults. [Source code][certificates_client_src] | [Package (PyPI)][pypi_package_certificates] | [API reference documentation][reference_docs] | [Product documentation][keyvault_docs] | [Samples][certificates_samples] diff --git a/sdk/keyvault/azure-keyvault-keys/README.md b/sdk/keyvault/azure-keyvault-keys/README.md index 15f0a218147d..b844fcaee473 100644 --- a/sdk/keyvault/azure-keyvault-keys/README.md +++ b/sdk/keyvault/azure-keyvault-keys/README.md @@ -9,6 +9,8 @@ and other secrets - Certificate management ([azure-keyvault-certificates](https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/keyvault/azure-keyvault-certificates)) - create, manage, and deploy public and private SSL/TLS certificates +- Vault administration ([azure-keyvault-administration](https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/keyvault/azure-keyvault-administration)) - full backup / restore, and key-level +role-based access control (RBAC) of vaults. [Source code][key_client_src] | [Package (PyPI)][pypi_package_keys] | [API reference documentation][reference_docs] | [Product documentation][keyvault_docs] | [Samples][key_samples] diff --git a/sdk/keyvault/azure-keyvault-secrets/README.md b/sdk/keyvault/azure-keyvault-secrets/README.md index 7aebb1ad9b23..0714320e190c 100644 --- a/sdk/keyvault/azure-keyvault-secrets/README.md +++ b/sdk/keyvault/azure-keyvault-secrets/README.md @@ -10,6 +10,8 @@ create, store, and control access to the keys used to encrypt your data - Certificate management ([azure-keyvault-certificates](https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/keyvault/azure-keyvault-certificates)) - create, manage, and deploy public and private SSL/TLS certificates +- Vault administration ([azure-keyvault-administration](https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/keyvault/azure-keyvault-administration)) - full backup / restore, and key-level +role-based access control (RBAC) of vaults. [Source code][secret_client_src] | [Package (PyPI)][pypi_package_secrets] | [API reference documentation][reference_docs] | [Product documentation][keyvault_docs] | [Samples][secret_samples] From a11d9f1655a17557359195cdb42106bf7ea38841 Mon Sep 17 00:00:00 2001 From: iscai-msft Date: Wed, 2 Sep 2020 12:00:42 -0400 Subject: [PATCH 03/11] tiny spacing fix --- sdk/keyvault/azure-keyvault-administration/README.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/sdk/keyvault/azure-keyvault-administration/README.md b/sdk/keyvault/azure-keyvault-administration/README.md index 9d758e59eb4e..ad87b67f1fb8 100644 --- a/sdk/keyvault/azure-keyvault-administration/README.md +++ b/sdk/keyvault/azure-keyvault-administration/README.md @@ -1,7 +1,6 @@ # Azure KeyVault Administration client library for .NET Azure Key Vault helps solve the following problems: -- Vault administration (this library) - full backup / restore, and key-level -role-based access control (RBAC) of vaults. +- Vault administration (this library) - full backup / restore, and key-level role-based access control (RBAC) of vaults. - Cryptographic key management ([azure-keyvault-keys](https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/keyvault/azure-keyvault-keys)) - create, store, and control access to the keys used to encrypt your data - Secrets management From 3391309e95ef3c26ef6a167bda4aa82d4dbda9ce Mon Sep 17 00:00:00 2001 From: iscai-msft Date: Wed, 2 Sep 2020 12:05:34 -0400 Subject: [PATCH 04/11] implement Charles' suggestions for examples --- sdk/keyvault/azure-keyvault-administration/README.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/sdk/keyvault/azure-keyvault-administration/README.md b/sdk/keyvault/azure-keyvault-administration/README.md index ad87b67f1fb8..1356bff48c63 100644 --- a/sdk/keyvault/azure-keyvault-administration/README.md +++ b/sdk/keyvault/azure-keyvault-administration/README.md @@ -131,7 +131,8 @@ credential = DefaultAzureCredential() client = KeyVaultAccessControlClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential) -role_definitions = client.list_role_definitions(role_scope="/") # this is the global scope +# this is the global scope. This will list all role definitions available for assignment +role_definitions = client.list_role_definitions(role_scope="/") for role_definition in role_definitions: print(role_definition.id) @@ -143,6 +144,7 @@ for role_definition in role_definitions: Assign a role to a service principal. This will require a role definition id from the list retrieved in the [above snippet](#list-the-role-definitions) and the principal object id retrieved in the [Create/Get credentials](#create/get-credentials) ```python +import uuid from azure.identity import DefaultAzureCredential from azure.keyvault.administration import KeyVaultAccessControlClient @@ -151,12 +153,12 @@ credential = DefaultAzureCredential() client = KeyVaultAccessControlClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential) role_scope = "/" # setting the scope to the global scope -role_assignment_name = "" # must be a UUID -role_definition = "" # Replace with a role definition from the definitions returned from the previous example +role_assignment_name = uuid.uuid4() +role_definition_id = "" # Replace with the id of a definition returned from the previous example principal_id = "" # first, let's create the role assignment -role_assignment = client.create_role_assignment(role_scope, role_assignment_name, role_definition.id, principal_id) +role_assignment = client.create_role_assignment(role_scope, role_assignment_name, role_definition_id, principal_id) print(role_assignment.name) print(role_assignment.principal_id) print(role_assignment.role_definition_id) From f8be33999befacf1e5e659e354102fff7771fa49 Mon Sep 17 00:00:00 2001 From: iscai-msft Date: Wed, 2 Sep 2020 12:06:29 -0400 Subject: [PATCH 05/11] improve intro of client --- sdk/keyvault/azure-keyvault-administration/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sdk/keyvault/azure-keyvault-administration/README.md b/sdk/keyvault/azure-keyvault-administration/README.md index 1356bff48c63..a4bac913f6e6 100644 --- a/sdk/keyvault/azure-keyvault-administration/README.md +++ b/sdk/keyvault/azure-keyvault-administration/README.md @@ -113,7 +113,7 @@ A role definition is specified as part of a role assignment. A role assignment is the association of a role definition to a service principal. They can be created, listed, fetched individually, and deleted. ### KeyVaultAccessControlClient -A `KeyVaultAccessControlClient` provides both synchronous and asynchronous operations allowing for management of role definitions and role assignments. +A `KeyVaultAccessControlClient` manages role definitions and role assignments. ## Examples This section conntains code snippets covering common tasks: From fcd20f26802c415e2e78df0ced876ae002b45aee Mon Sep 17 00:00:00 2001 From: iscai-msft Date: Wed, 2 Sep 2020 12:55:47 -0400 Subject: [PATCH 06/11] unify sp name and fix links --- .../azure-keyvault-administration/README.md | 34 ++++++++++++------- 1 file changed, 21 insertions(+), 13 deletions(-) diff --git a/sdk/keyvault/azure-keyvault-administration/README.md b/sdk/keyvault/azure-keyvault-administration/README.md index a4bac913f6e6..1d5221277628 100644 --- a/sdk/keyvault/azure-keyvault-administration/README.md +++ b/sdk/keyvault/azure-keyvault-administration/README.md @@ -33,22 +33,22 @@ accepts any [azure-identity][azure_identity] credential. See the [azure-identity][azure_identity] documentation for more information about other credentials. -#### Create/Get credentials +#### Create and Get credentials This [Azure Cloud Shell][azure_cloud_shell] snippet shows how to create a new service principal. Before using it, replace "your-application-name" with a more appropriate name for your service principal. * Create a service principal: ```Bash - az ad sp create-for-rbac --name http://my-application --skip-assignment + az ad sp create-for-rbac --name http://your-application-name --skip-assignment ``` > Output: > ```json > { > "appId": "generated app id", - > "displayName": "my-application", - > "name": "http://my-application", + > "displayName": "your-application-name", + > "name": "http://your-application-name", > "password": "random password", > "tenant": "tenant id" > } @@ -141,7 +141,7 @@ for role_definition in role_definitions: ``` ### Create, Get, and Delete a role assignment -Assign a role to a service principal. This will require a role definition id from the list retrieved in the [above snippet](#list-the-role-definitions) and the principal object id retrieved in the [Create/Get credentials](#create/get-credentials) +Assign a role to a service principal. This will require a role definition id from the list retrieved in the [above snippet](#list-the-role-definitions) and the principal object id retrieved in the [Create and Get credentials](#create-and-get-credentials) ```python import uuid @@ -202,16 +202,24 @@ except ResourceNotFoundError as e: Content forthcoming -## Contributing +### Additional Documentation +For more extensive documentation on Azure Key Vault, see the +[API reference documentation][reference_docs]. -This project welcomes contributions and suggestions. Most contributions require +## Contributing +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 [cla.microsoft.com][cla]. +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][coc]. -For more information see the [Code of Conduct FAQ][coc_faq] -or contact [opencode@microsoft.com][coc_contact] with any +This project has adopted the +[Microsoft Open Source Code of Conduct][code_of_conduct]. For more information, +see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments. @@ -225,7 +233,7 @@ additional questions or comments. [keyvault_docs]: https://docs.microsoft.com/azure/key-vault/ [pip]: https://pypi.org/project/pip/ [pypi_package_administration]: https://pypi.org/project/azure-keyvault-administration/ -[reference_docs]: https://aka.ms/azsdk/python/keyvault-keys/docs +[reference_docs]: https://aka.ms/azsdk/python/keyvault-administration/docs [rbac_client_docs]: https://aka.ms/azsdk/python/keyvault-administration/docs#azure.keyvault.administration.KeyVaultAccessControlClient From 8f55308902fdcd7527d6f60b877be9ac0cc86b55 Mon Sep 17 00:00:00 2001 From: iscai-msft Date: Fri, 4 Sep 2020 12:24:56 -0400 Subject: [PATCH 07/11] add backup and restore snippets --- .../azure-keyvault-administration/README.md | 113 ++++++++++++++++-- 1 file changed, 106 insertions(+), 7 deletions(-) diff --git a/sdk/keyvault/azure-keyvault-administration/README.md b/sdk/keyvault/azure-keyvault-administration/README.md index 1d5221277628..a947f6646a53 100644 --- a/sdk/keyvault/azure-keyvault-administration/README.md +++ b/sdk/keyvault/azure-keyvault-administration/README.md @@ -90,10 +90,12 @@ Once the **AZURE_CLIENT_ID**, **AZURE_CLIENT_SECRET** and [DefaultAzureCredential][default_cred_ref] will be able to authenticate the [KeyVaultAccessControlClient][rbac_client_docs]. -Constructing the client also requires your vault's URL, which you can +There are two clients available in this package, below are snippets demonstrating how to construct +each one of these clients. Constructing a client also requires your vault's URL, which you can get from the Azure CLI or the Azure Portal. In the Azure Portal, this URL is the vault's "DNS Name". +##### Create a KeyVaultAccessControlClient ```python from azure.identity import DefaultAzureCredential from azure.keyvault.administration import KeyVaultAccessControlClient @@ -102,6 +104,17 @@ credential = DefaultAzureCredential() client = KeyVaultAccessControlClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential) ``` + +##### Create a KeyVaultBackupClient +```python +from azure.identity import DefaultAzureCredential +from azure.keyvault.administration import KeyVaultBackupClient + +credential = DefaultAzureCredential() + +client = KeyVaultBackupClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential) +``` + ## Key concepts ### Role Definition @@ -115,12 +128,20 @@ A role assignment is the association of a role definition to a service principal ### KeyVaultAccessControlClient A `KeyVaultAccessControlClient` manages role definitions and role assignments. +### KeyVaultBackupClient +A `KeyVaultBackupClient` performs full key backups, full key restores, and selective key restores. + ## Examples This section conntains code snippets covering common tasks: -* [List the role definitions](#list-the-role-definitions "List the role definitions") -* [Create, Get, and Delete a role assignment](#create-get-and-delete-a-role-assignment "Create, Get, and Delete a role assignment") - -### List the role definitions +* Access Control + * [List all role definitions](#list-all-role-definitions "List all role definitions") + * [List all role assignments](#list-all-role-assignments "List all role assignments") + * [Create, Get, and Delete a role assignment](#create-get-and-delete-a-role-assignment "Create, Get, and Delete a role assignment") +* Backup and Restore + * [Perform a full key backup](#perform-a-full-key-backup "Perform a full key backup") + * [Perform a full key restore](#perform-a-full-key-restore "Perform a full key restore") + +### List all role definitions List the role definitions available for assignment. ```python @@ -132,7 +153,7 @@ credential = DefaultAzureCredential() client = KeyVaultAccessControlClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential) # this is the global scope. This will list all role definitions available for assignment -role_definitions = client.list_role_definitions(role_scope="/") +role_definitions = client.list_role_definitions(role_scope=KeyVaultRoleScope.global_value) for role_definition in role_definitions: print(role_definition.id) @@ -140,8 +161,28 @@ for role_definition in role_definitions: print(role_definition.description) ``` +### List all role assignments +Before creating a new role assignment in the [next snippet](#create-get-and-delete-a-role-assignment), list all of the current role assignments + +```python +from azure.identity import DefaultAzureCredential +from azure.keyvault.administration import KeyVaultAccessControlClient + +credential = DefaultAzureCredential() + +client = KeyVaultAccessControlClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential) + +# this is the global scope. This will list all role assignments available for assignment +role_assignments = client.list_role_assignments(role_scope=KeyVaultRoleScope.global_value) + +for role_assignment in role_assignments: + print(role_assignment.name) + print(role_assignment.principal_id) + print(role_assignment.role_definition_id) +``` + ### Create, Get, and Delete a role assignment -Assign a role to a service principal. This will require a role definition id from the list retrieved in the [above snippet](#list-the-role-definitions) and the principal object id retrieved in the [Create and Get credentials](#create-and-get-credentials) +Assign a role to a service principal. This will require a role definition id from the list retrieved in the [above snippet](#list-all-role-definitions) and the principal object id retrieved in the [Create and Get credentials](#create-and-get-credentials) ```python import uuid @@ -174,10 +215,68 @@ role_assignment = client.delete_role_assignment(role_scope, role_assignment.name print(role_assignment.name) print(role_assignment.principal_id) print(role_assignment.role_definition_id) +``` + +### Perform a full key backup +Back up your entire collection of keys. The backing store for full key backups is a blob storage container using Shared Access Signature authentication. +For more details on creating a SAS token using the `BlobServiceClient`, see the sample [here](https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/storage/azure-storage-blob/samples/blob_samples_authentication.py#L105). +Alternatively, it is possible to [generate a SAS token in Storage Explorer](https://docs.microsoft.com/en-us/azure/vs-azure-tools-storage-manage-with-storage-explorer?tabs=windows#generate-a-shared-access-signature-in-storage-explorer) + +```python +from azure.identity import DefaultAzureCredential +from azure.keyvault.administration import KeyVaultBackupClient +from azure.core.exceptions import ResourceNotFoundError + +credential = DefaultAzureCredential() +client = KeyVaultBackupClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential) + +blob_storage_uri = "" # the URI to your storage account. Should contain the name of the specific container +sas_token = "" # replace with the sas token to your storage account. See this snippet's description on help to retrieve + +# performing a full key backup is a long-running operation. Calling `result()` on the poller will wait +# until the backup is completed, then return an object representing the backup operation. +backup_operation = client.begin_full_backup(blob_storage_uri, sas_token).result() + +# this is the URI of the Azure blob storage container which contains the backup +azure_storage_blob_container_uri = backup_operation.azure_storage_blob_container_uri + +print(backup_operation.status) +print(backup_operation.job_id) +print(azure_storage_blob_container_uri) ``` +### Perform a full key restore +Restore your entire collection of keys from a backup. The data source for a full key restore is a storage blob accessed using Shared Access Signature authentication. +You will also need the `azure_storage_blob_container_uri` from the [above snippet](#perform-a-full-key-backup). + +For more details on creating a SAS token using the `BlobServiceClient`, see the sample [here](https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/storage/azure-storage-blob/samples/blob_samples_authentication.py#L105). +Alternatively, it is possible to [generate a SAS token in Storage Explorer](https://docs.microsoft.com/en-us/azure/vs-azure-tools-storage-manage-with-storage-explorer?tabs=windows#generate-a-shared-access-signature-in-storage-explorer) + +```python +from azure.identity import DefaultAzureCredential +from azure.keyvault.administration import KeyVaultBackupClient +from azure.core.exceptions import ResourceNotFoundError + +credential = DefaultAzureCredential() +client = KeyVaultBackupClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential) + +blob_storage_uri = "" # the URI to your storage account. Should contain the name of the specific container +sas_token = "" # replace with the sas token to your storage account. See this snippet's description on help to retrieve + +# Replace with the blob storage container returned in the previous example +azure_storage_blob_container_uri = "" +folder_name = azure_storage_blob_container_uri.split("/")[-1] + +# performing a full key restore is a long-running operation. Calling `result()` on the poller will wait +# until the restore is completed, then return an object representing the restore operation. +restore_operation = client.begin_full_restore(blob_storage_uri, sas_token, folder_name).result() + +print(restore_operation.status) +print(restore_operation.job_id) +``` + ## Troubleshooting ### General Key Vault clients raise exceptions defined in [azure-core][azure_core_exceptions]. From d148684cbc07a490c83804d68d45ba22fe25ee6e Mon Sep 17 00:00:00 2001 From: iscai-msft Date: Fri, 4 Sep 2020 13:23:05 -0400 Subject: [PATCH 08/11] remove reference to .net --- sdk/keyvault/azure-keyvault-administration/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sdk/keyvault/azure-keyvault-administration/README.md b/sdk/keyvault/azure-keyvault-administration/README.md index a947f6646a53..a3080194a11d 100644 --- a/sdk/keyvault/azure-keyvault-administration/README.md +++ b/sdk/keyvault/azure-keyvault-administration/README.md @@ -1,4 +1,4 @@ -# Azure KeyVault Administration client library for .NET +# Azure KeyVault Administration client library for Python Azure Key Vault helps solve the following problems: - Vault administration (this library) - full backup / restore, and key-level role-based access control (RBAC) of vaults. - Cryptographic key management ([azure-keyvault-keys](https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/keyvault/azure-keyvault-keys)) - create, store, and control From 87185078dd32b22c1a477e056c3a0bf356b539c6 Mon Sep 17 00:00:00 2001 From: iscai-msft Date: Fri, 4 Sep 2020 15:59:35 -0400 Subject: [PATCH 09/11] fix blurb of library, remove unnecessary ResourceNotFoundError imports --- sdk/keyvault/azure-keyvault-administration/README.md | 4 +--- sdk/keyvault/azure-keyvault-certificates/README.md | 3 +-- sdk/keyvault/azure-keyvault-keys/README.md | 3 +-- sdk/keyvault/azure-keyvault-secrets/README.md | 3 +-- 4 files changed, 4 insertions(+), 9 deletions(-) diff --git a/sdk/keyvault/azure-keyvault-administration/README.md b/sdk/keyvault/azure-keyvault-administration/README.md index a3080194a11d..eab6aa609ca9 100644 --- a/sdk/keyvault/azure-keyvault-administration/README.md +++ b/sdk/keyvault/azure-keyvault-administration/README.md @@ -1,6 +1,6 @@ # Azure KeyVault Administration client library for Python Azure Key Vault helps solve the following problems: -- Vault administration (this library) - full backup / restore, and key-level role-based access control (RBAC) of vaults. +- Vault administration (this library) - role-based access control (RBAC), and vault-level backup and restore options - Cryptographic key management ([azure-keyvault-keys](https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/keyvault/azure-keyvault-keys)) - create, store, and control access to the keys used to encrypt your data - Secrets management @@ -226,7 +226,6 @@ Alternatively, it is possible to [generate a SAS token in Storage Explorer](http ```python from azure.identity import DefaultAzureCredential from azure.keyvault.administration import KeyVaultBackupClient -from azure.core.exceptions import ResourceNotFoundError credential = DefaultAzureCredential() client = KeyVaultBackupClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential) @@ -257,7 +256,6 @@ Alternatively, it is possible to [generate a SAS token in Storage Explorer](http ```python from azure.identity import DefaultAzureCredential from azure.keyvault.administration import KeyVaultBackupClient -from azure.core.exceptions import ResourceNotFoundError credential = DefaultAzureCredential() client = KeyVaultBackupClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential) diff --git a/sdk/keyvault/azure-keyvault-certificates/README.md b/sdk/keyvault/azure-keyvault-certificates/README.md index 13284737269f..2eaf42f4ed92 100644 --- a/sdk/keyvault/azure-keyvault-certificates/README.md +++ b/sdk/keyvault/azure-keyvault-certificates/README.md @@ -7,8 +7,7 @@ Azure Key Vault helps solve the following problems: ([azure-keyvault-secrets](https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/keyvault/azure-keyvault-secrets)) - securely store and control access to tokens, passwords, certificates, API keys, and other secrets -- Vault administration ([azure-keyvault-administration](https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/keyvault/azure-keyvault-administration)) - full backup / restore, and key-level -role-based access control (RBAC) of vaults. +- Vault administration ([azure-keyvault-administration](https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/keyvault/azure-keyvault-administration)) - role-based access control (RBAC), and vault-level backup and restore options [Source code][certificates_client_src] | [Package (PyPI)][pypi_package_certificates] | [API reference documentation][reference_docs] | [Product documentation][keyvault_docs] | [Samples][certificates_samples] diff --git a/sdk/keyvault/azure-keyvault-keys/README.md b/sdk/keyvault/azure-keyvault-keys/README.md index b844fcaee473..48920866e4b4 100644 --- a/sdk/keyvault/azure-keyvault-keys/README.md +++ b/sdk/keyvault/azure-keyvault-keys/README.md @@ -9,8 +9,7 @@ and other secrets - Certificate management ([azure-keyvault-certificates](https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/keyvault/azure-keyvault-certificates)) - create, manage, and deploy public and private SSL/TLS certificates -- Vault administration ([azure-keyvault-administration](https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/keyvault/azure-keyvault-administration)) - full backup / restore, and key-level -role-based access control (RBAC) of vaults. +- Vault administration ([azure-keyvault-administration](https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/keyvault/azure-keyvault-administration)) - role-based access control (RBAC), and vault-level backup and restore options [Source code][key_client_src] | [Package (PyPI)][pypi_package_keys] | [API reference documentation][reference_docs] | [Product documentation][keyvault_docs] | [Samples][key_samples] diff --git a/sdk/keyvault/azure-keyvault-secrets/README.md b/sdk/keyvault/azure-keyvault-secrets/README.md index 0714320e190c..4cc95452cbb9 100644 --- a/sdk/keyvault/azure-keyvault-secrets/README.md +++ b/sdk/keyvault/azure-keyvault-secrets/README.md @@ -10,8 +10,7 @@ create, store, and control access to the keys used to encrypt your data - Certificate management ([azure-keyvault-certificates](https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/keyvault/azure-keyvault-certificates)) - create, manage, and deploy public and private SSL/TLS certificates -- Vault administration ([azure-keyvault-administration](https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/keyvault/azure-keyvault-administration)) - full backup / restore, and key-level -role-based access control (RBAC) of vaults. +- Vault administration ([azure-keyvault-administration](https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/keyvault/azure-keyvault-administration)) - role-based access control (RBAC), and vault-level backup and restore options [Source code][secret_client_src] | [Package (PyPI)][pypi_package_secrets] | [API reference documentation][reference_docs] | [Product documentation][keyvault_docs] | [Samples][secret_samples] From 1e5ab238cbfec6a5178c90612b1313164d35469a Mon Sep 17 00:00:00 2001 From: iscai-msft Date: Fri, 4 Sep 2020 16:35:20 -0400 Subject: [PATCH 10/11] fix broken links bc of release ci --- sdk/keyvault/azure-keyvault-administration/README.md | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/sdk/keyvault/azure-keyvault-administration/README.md b/sdk/keyvault/azure-keyvault-administration/README.md index eab6aa609ca9..8cb6edd70ac8 100644 --- a/sdk/keyvault/azure-keyvault-administration/README.md +++ b/sdk/keyvault/azure-keyvault-administration/README.md @@ -28,8 +28,8 @@ authentication as demonstrated below. ### Authenticate the client This document demonstrates using [DefaultAzureCredential][default_cred_ref] -to authenticate as a service principal. However, [KeyVaultAccessControlClient][rbac_client_docs] -accepts any [azure-identity][azure_identity] credential. See the +to authenticate as a service principal. However, this package's clients +accept any [azure-identity][azure_identity] credential. See the [azure-identity][azure_identity] documentation for more information about other credentials. @@ -88,7 +88,7 @@ a more appropriate name for your service principal. Once the **AZURE_CLIENT_ID**, **AZURE_CLIENT_SECRET** and **AZURE_TENANT_ID** environment variables are set, [DefaultAzureCredential][default_cred_ref] will be able to authenticate the -[KeyVaultAccessControlClient][rbac_client_docs]. +clients. There are two clients available in this package, below are snippets demonstrating how to construct each one of these clients. Constructing a client also requires your vault's URL, which you can @@ -278,7 +278,7 @@ print(restore_operation.job_id) ## Troubleshooting ### General Key Vault clients raise exceptions defined in [azure-core][azure_core_exceptions]. -For example, if you try to get a role assignment that doesn't exist, [KeyVaultAccessControlClient][rbac_client_docs] +For example, if you try to get a role assignment that doesn't exist, KeyVaultAccessControlClient raises [ResourceNotFoundError](https://aka.ms/azsdk-python-core-exceptions-resource-not-found-error): ```python @@ -329,9 +329,8 @@ additional questions or comments. [code_of_conduct]: https://opensource.microsoft.com/codeofconduct/ [keyvault_docs]: https://docs.microsoft.com/azure/key-vault/ [pip]: https://pypi.org/project/pip/ -[pypi_package_administration]: https://pypi.org/project/azure-keyvault-administration/ +[pypi_package_administration]: https://aka.ms/azsdk/python/keyvault-administration/pypi [reference_docs]: https://aka.ms/azsdk/python/keyvault-administration/docs -[rbac_client_docs]: https://aka.ms/azsdk/python/keyvault-administration/docs#azure.keyvault.administration.KeyVaultAccessControlClient ![Impressions](https://azure-sdk-impressions.azurewebsites.net/api/impressions/azure-sdk-for-net%2Fsdk%2Ftables%2FAzure.Data.Tables%2FREADME.png) \ No newline at end of file From 94b9552b2165a394dbab0703e562a541eab12b4a Mon Sep 17 00:00:00 2001 From: iscai-msft <43154838+iscai-msft@users.noreply.github.com> Date: Fri, 4 Sep 2020 17:02:00 -0400 Subject: [PATCH 11/11] correct impression Co-authored-by: Charles Lowell --- sdk/keyvault/azure-keyvault-administration/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sdk/keyvault/azure-keyvault-administration/README.md b/sdk/keyvault/azure-keyvault-administration/README.md index 8cb6edd70ac8..87d44d9c670c 100644 --- a/sdk/keyvault/azure-keyvault-administration/README.md +++ b/sdk/keyvault/azure-keyvault-administration/README.md @@ -333,4 +333,4 @@ additional questions or comments. [reference_docs]: https://aka.ms/azsdk/python/keyvault-administration/docs -![Impressions](https://azure-sdk-impressions.azurewebsites.net/api/impressions/azure-sdk-for-net%2Fsdk%2Ftables%2FAzure.Data.Tables%2FREADME.png) \ No newline at end of file +![Impressions](https://azure-sdk-impressions.azurewebsites.net/api/impressions/azure-sdk-for-python%2Fsdk%2Fkeyvault%2Fazure-keyvault-administration%2FREADME.png)