From 9fe96d1902062ea70c16c35703d53b8174d812e0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?McCoy=20Pati=C3=B1o?= <39780829+mccoyp@users.noreply.github.com> Date: Wed, 16 Jun 2021 09:51:15 -0700 Subject: [PATCH] [Key Vault] Update READMEs with RBAC information (#19275) --- .../azure-keyvault-administration/README.md | 22 +++++++++++++++++-- .../azure-keyvault-certificates/README.md | 3 +++ sdk/keyvault/azure-keyvault-keys/README.md | 4 ++++ sdk/keyvault/azure-keyvault-secrets/README.md | 2 ++ 4 files changed, 29 insertions(+), 2 deletions(-) diff --git a/sdk/keyvault/azure-keyvault-administration/README.md b/sdk/keyvault/azure-keyvault-administration/README.md index 2da914b4a2cf..4f4db75005f6 100644 --- a/sdk/keyvault/azure-keyvault-administration/README.md +++ b/sdk/keyvault/azure-keyvault-administration/README.md @@ -14,6 +14,8 @@ and other secrets ([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 +[Package (PyPI)][pypi_package_administration] | [API reference documentation][reference_docs] | [Product documentation][keyvault_docs] + ## Getting started ### Install packages Install [azure-keyvault-administration][pypi_package_administration] and @@ -26,7 +28,7 @@ authentication as demonstrated below. ### Prerequisites * An [Azure subscription][azure_sub] -* Python 2.7, 3.5.3, or later +* Python 2.7 or a recent version of Python 3 (this library doesn't support end-of-life versions) * A [managed HSM][managed_hsm]. If you need to create one, see the final two steps in the next section for details on creating the managed HSM with the Azure CLI. ### Authenticate the client @@ -77,10 +79,11 @@ a more appropriate name for your service principal. export AZURE_TENANT_ID="tenant id" ``` -* Create the managed HSM and grant the above mentioned application authorization to perform administrative operations on the managed HSM (replace `` and `` with your own, unique names and `` with the value from above): +* Create the managed HSM and grant the above mentioned service principal authorization to perform administrative operations on the managed HSM (replace `` and `` with your own, unique names and `` with the value from above): ```Bash az keyvault create --hsm-name "" --resource-group "" --administrators --location "" ``` + This service principal is automatically added to the "Managed HSM Administrators" [built-in role][built_in_roles]. * Activate your managed HSM to enable key and role management. Detailed instructions can be found in [this quickstart guide](https://docs.microsoft.com/azure/key-vault/managed-hsm/quick-create-cli#activate-your-managed-hsm). Create three self signed certificates and download the [Security Domain](https://docs.microsoft.com/azure/key-vault/managed-hsm/security-domain) for your managed HSM: > **Important:** Create and store the RSA key pairs and security domain file generated in this step securely. @@ -96,6 +99,18 @@ a more appropriate name for your service principal. az keyvault show --hsm-name "" ``` +#### Controlling access to your managed HSM +The designated administrators assigned during creation are automatically added to the "Managed HSM Administrators" [built-in role][built_in_roles], +who are able to download a security domain and [manage roles for data plane access][access_control], among other limited permissions. + +To perform other actions on keys, you need to assign principals to other roles such as "Managed HSM Crypto User", which can perform non-destructive key operations: + +```Bash +az keyvault role assignment create --hsm-name --role "Managed HSM Crypto User" --scope / --assignee-object-id --assignee-principal-type +``` + +Please read [best practices][best_practices] for properly securing your managed HSM. + #### Create a client Once the **AZURE_CLIENT_ID**, **AZURE_CLIENT_SECRET** and **AZURE_TENANT_ID** environment variables are set, @@ -364,11 +379,14 @@ For more information, see the contact opencode@microsoft.com with any additional questions or comments. +[access_control]: https://docs.microsoft.com/azure/key-vault/managed-hsm/access-control [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/ +[best_practices]: https://docs.microsoft.com/azure/key-vault/managed-hsm/best-practices +[built_in_roles]: https://docs.microsoft.com/azure/key-vault/managed-hsm/built-in-roles [code_of_conduct]: https://opensource.microsoft.com/codeofconduct/ [default_cred_ref]: https://aka.ms/azsdk/python/identity/docs#azure.identity.DefaultAzureCredential [keyvault_docs]: https://docs.microsoft.com/azure/key-vault/ diff --git a/sdk/keyvault/azure-keyvault-certificates/README.md b/sdk/keyvault/azure-keyvault-certificates/README.md index 9b710e50e7f4..ec1d1077816f 100644 --- a/sdk/keyvault/azure-keyvault-certificates/README.md +++ b/sdk/keyvault/azure-keyvault-certificates/README.md @@ -109,6 +109,8 @@ az keyvault set-policy --name my-key-vault --spn $AZURE_CLIENT_ID --certificate- ``` > Possible certificate permissions: backup, create, delete, deleteissuers, get, getissuers, import, list, listissuers, managecontacts, manageissuers, purge, recover, restore, setissuers, update +If you have enabled role-based access control (RBAC) for Key Vault instead, you can find roles like "Key Vault Certificates Officer" in our [RBAC guide][rbac_guide]. + #### Create a client Once the **AZURE_CLIENT_ID**, **AZURE_CLIENT_SECRET** and **AZURE_TENANT_ID** environment variables are set, @@ -431,6 +433,7 @@ contact opencode@microsoft.com with any additional questions or comments. [pip]: https://pypi.org/project/pip/ [pypi_package_certificates]: https://pypi.org/project/azure-keyvault-certificates/ [certificate_client_docs]: https://aka.ms/azsdk/python/keyvault-certificates/docs#azure.keyvault.certificates.CertificateClient +[rbac_guide]: https://docs.microsoft.com/azure/key-vault/general/rbac-guide [reference_docs]: https://aka.ms/azsdk/python/keyvault-certificates/docs [certificates_client_src]: https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/keyvault/azure-keyvault-certificates/azure/keyvault/certificates [certificates_samples]: https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/keyvault/azure-keyvault-certificates/samples diff --git a/sdk/keyvault/azure-keyvault-keys/README.md b/sdk/keyvault/azure-keyvault-keys/README.md index f3e288a52e7f..0cb93cbd9e25 100644 --- a/sdk/keyvault/azure-keyvault-keys/README.md +++ b/sdk/keyvault/azure-keyvault-keys/README.md @@ -113,6 +113,8 @@ az keyvault set-policy --name my-key-vault --spn $AZURE_CLIENT_ID --key-permissi > - Key management: backup, delete, get, list, purge, recover, restore, create, update, import > - Cryptographic operations: decrypt, encrypt, unwrapKey, wrapKey, verify, sign +If you have enabled role-based access control (RBAC) for Key Vault instead, you can find roles like "Key Vault Crypto Officer" in our [RBAC guide][rbac_guide]. +If you are managing your keys using Managed HSM, read about its [access control][access_control] that supports different built-in roles isolated from Azure Resource Manager (ARM). #### Create a client Once the **AZURE_CLIENT_ID**, **AZURE_CLIENT_SECRET** and @@ -431,6 +433,7 @@ For more information, see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact opencode@microsoft.com with any additional questions or comments. +[access_control]: https://docs.microsoft.com/azure/key-vault/managed-hsm/access-control [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 @@ -449,6 +452,7 @@ contact opencode@microsoft.com with any additional questions or comments. [keyvault_docs]: https://docs.microsoft.com/azure/key-vault/ [pip]: https://pypi.org/project/pip/ [pypi_package_keys]: https://pypi.org/project/azure-keyvault-keys/ +[rbac_guide]: https://docs.microsoft.com/azure/key-vault/general/rbac-guide [reference_docs]: https://aka.ms/azsdk/python/keyvault-keys/docs [key_client_docs]: https://aka.ms/azsdk/python/keyvault-keys/docs#azure.keyvault.keys.KeyClient [crypto_client_docs]: https://aka.ms/azsdk/python/keyvault-keys/crypto/docs diff --git a/sdk/keyvault/azure-keyvault-secrets/README.md b/sdk/keyvault/azure-keyvault-secrets/README.md index da406b6c662c..7106dd052a00 100644 --- a/sdk/keyvault/azure-keyvault-secrets/README.md +++ b/sdk/keyvault/azure-keyvault-secrets/README.md @@ -114,6 +114,7 @@ az keyvault set-policy --name my-key-vault --spn $AZURE_CLIENT_ID --secret-permi > Possible permissions: > - Secret management: set, backup, delete, get, list, purge, recover, restore +If you have enabled role-based access control (RBAC) for Key Vault instead, you can find roles like "Key Vault Secrets Officer" in our [RBAC guide][rbac_guide]. #### Create a client Once the **AZURE_CLIENT_ID**, **AZURE_CLIENT_SECRET** and @@ -426,6 +427,7 @@ contact opencode@microsoft.com with any additional questions or comments. [keyvault_docs]: https://docs.microsoft.com/azure/key-vault/ [pip]: https://pypi.org/project/pip/ [pypi_package_secrets]: https://pypi.org/project/azure-keyvault-secrets/ +[rbac_guide]: https://docs.microsoft.com/azure/key-vault/general/rbac-guide [reference_docs]: https://aka.ms/azsdk/python/keyvault-secrets/docs [secret_client_src]: https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/keyvault/azure-keyvault-secrets/azure/keyvault/secrets [secret_client_docs]: https://aka.ms/azsdk/python/keyvault-secrets/docs#azure.keyvault.secrets.SecretClient