Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[Key Vault] Update administration README for MHSM and custom role definitions #16307

Merged
merged 1 commit into from
Jan 26, 2021
Merged

[Key Vault] Update administration README for MHSM and custom role definitions #16307

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
99 changes: 76 additions & 23 deletions sdk/keyvault/azure-keyvault-administration/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,7 @@
# Azure KeyVault Administration client library for Python
# Azure Key Vault Administration client library for Python

>**Note:** The Administration library only works with [Managed HSM][managed_hsm] – functions targeting a Key Vault will fail.

Azure Key Vault helps solve the following problems:
- 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
Expand All @@ -24,7 +27,7 @@ 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.
* 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
This document demonstrates using [DefaultAzureCredential][default_cred_ref]
Expand Down Expand Up @@ -74,14 +77,23 @@ a more appropriate name for your service principal.
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 `<your-resource-group-name>` and `<your-key-vault-name>` with your own, unique names and `<your-service-principal-object-id>` with the value from above):
* Create the managed HSM and grant the above mentioned application authorization to perform administrative operations on the managed HSM (replace `<your-resource-group-name>` and `<your-managed-hsm-name>` with your own, unique names and `<your-service-principal-object-id>` with the value from above):
```Bash
az keyvault create --hsm-name <your-key-vault-name> --resource-group <your-resource-group-name> --administrators <your-service-principal-object-id> --location <your-azure-location>
az keyvault create --hsm-name "<your-managed-hsm-name>" --resource-group "<your-resource-group-name>" --administrators <your-service-principal-object-id> --location "<your-azure-location>"
```

* 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.
```Bash
openssl req -newkey rsa:2048 -nodes -keyout cert_0.key -x509 -days 365 -out cert_0.cer
openssl req -newkey rsa:2048 -nodes -keyout cert_1.key -x509 -days 365 -out cert_1.cer
openssl req -newkey rsa:2048 -nodes -keyout cert_2.key -x509 -days 365 -out cert_2.cer
az keyvault security-domain download --hsm-name "<your-managed-hsm-name>" --sd-wrapping-keys ./certs/cert_0.cer ./certs/cert_1.cer ./certs/cert_2.cer --sd-quorum 2 --security-domain-file <your-managed-hsm-name>-SD.json
```

* Use the above mentioned Azure Key Vault name to retrieve details of your Vault which also contains your Azure Key Vault URL:
* Use the above mentioned managed HSM name to retrieve details of your managed HSM instance which also contains your manged HSM URL (`hsmUri`):
```Bash
az keyvault show --hsm-name <your-key-vault-name>
az keyvault show --hsm-name "<your-managed-hsm-name>"
```

#### Create a client
Expand All @@ -90,10 +102,9 @@ Once the **AZURE_CLIENT_ID**, **AZURE_CLIENT_SECRET** and
[DefaultAzureCredential][default_cred_ref] will be able to authenticate the
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
get from the Azure CLI or the Azure Portal. In the Azure Portal, this URL is
the vault's "DNS Name".
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 managed HSM's URL, which you can
get from the Azure CLI (shown above).

##### Create a KeyVaultAccessControlClient
```python
Expand All @@ -102,7 +113,7 @@ from azure.keyvault.administration import KeyVaultAccessControlClient

credential = DefaultAzureCredential()

client = KeyVaultAccessControlClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
client = KeyVaultAccessControlClient(vault_url="https://my-managed-hsm-name.managedhsm.azure.net/", credential=credential)
```

##### Create a KeyVaultBackupClient
Expand All @@ -112,7 +123,7 @@ from azure.keyvault.administration import KeyVaultBackupClient

credential = DefaultAzureCredential()

client = KeyVaultBackupClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
client = KeyVaultBackupClient(vault_url="https://my-managed-hsm-name.managedhsm.azure.net/", credential=credential)
```

## Key concepts
Expand All @@ -135,6 +146,7 @@ A `KeyVaultBackupClient` performs full key backups, full key restores, and selec
This section conntains code snippets covering common tasks:
* Access Control
* [List all role definitions](#list-all-role-definitions "List all role definitions")
* [Set, Get, and Delete a role definition](#set-get-and-delete-a-role-defintion "Set, Get, and Delete a role definition")
* [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
Expand All @@ -150,30 +162,66 @@ from azure.keyvault.administration import KeyVaultAccessControlClient, KeyVaultR

credential = DefaultAzureCredential()

client = KeyVaultAccessControlClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
client = KeyVaultAccessControlClient(vault_url="https://my-managed-hsm-name.managedhsm.azure.net/", credential=credential)

# this will list all role definitions available for assignment
role_definitions = client.list_role_definitions(role_scope=KeyVaultRoleScope.global_value)
role_definitions = client.list_role_definitions(role_scope=KeyVaultRoleScope.GLOBAL)

for role_definition in role_definitions:
print(role_definition.id)
print(role_definition.role_name)
print(role_definition.description)
```

### Set, Get, and Delete a role definition

`set_role_definition` can be used to either create a custom role definition or update an existing definition with the specified name.

```python
import uuid
from azure.identity import DefaultAzureCredential
from azure.keyvault.administration import KeyVaultAccessControlClient, KeyVaultDataAction, KeyVaultPermission

credential = DefaultAzureCredential()

client = KeyVaultAccessControlClient(vault_url="https://my-managed-hsm-name.managedhsm.azure.net/", credential=credential)

# create the custom role definition
role_scope = "/" # the global scope
definition_name = uuid.uuid4()
permissions = [KeyVaultPermission(allowed_data_actions=[KeyVaultDataAction.READ_HSM_KEY])]
created_definition = client.set_role_definition(
role_scope=role_scope, permissions=permissions, role_definition_name=definition_name
)

# update the custom role definition
permissions = [
KeyVaultPermission(allowed_data_actions=[], denied_data_actions=[KeyVaultDataAction.READ_HSM_KEY])
]
updated_definition = client.set_role_definition(
role_scope=role_scope, permissions=permissions, role_definition_name=definition_name
)

# get the custom role definition
definition = client.get_role_definition(role_scope=role_scope, role_definition_name=definition_name)

# delete the custom role definition
deleted_definition = client.delete_role_definition(role_scope=role_scope, role_definition_name=definition_name)
```

### 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
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, KeyVaultRoleScope

credential = DefaultAzureCredential()

client = KeyVaultAccessControlClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
client = KeyVaultAccessControlClient(vault_url="https://my-managed-hsm-name.managedhsm.azure.net/", credential=credential)

# this will list all role assignments
role_assignments = client.list_role_assignments(role_scope=KeyVaultRoleScope.global_value)
role_assignments = client.list_role_assignments(role_scope=KeyVaultRoleScope.GLOBAL)

for role_assignment in role_assignments:
print(role_assignment.name)
Expand All @@ -182,15 +230,15 @@ for role_assignment in role_assignments:
```

### 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-all-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) section.

```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)
client = KeyVaultAccessControlClient(vault_url="https://my-managed-hsm-name.managedhsm.azure.net/", credential=credential)

role_scope = "/" # the global scope
role_definition_id = "<role-definition-id>" # Replace <role-definition-id> with the id of a definition returned from the previous example
Expand Down Expand Up @@ -226,7 +274,7 @@ 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)
client = KeyVaultBackupClient(vault_url="https://my-managed-hsm-name.managedhsm.azure.net/", credential=credential)

# blob storage container URL, for example https://<account name>.blob.core.windows.net/backup
blob_storage_url = "<your-blob-storage-url>"
Expand Down Expand Up @@ -254,7 +302,7 @@ 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)
client = KeyVaultBackupClient(vault_url="https://my-managed-hsm-name.managedhsm.azure.net/", credential=credential)

sas_token = "<your-sas-token>" # replace with a sas token to your storage account

Expand All @@ -281,14 +329,16 @@ 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)
client = KeyVaultAccessControlClient(vault_url="https://my-managed-hsm-name.managedhsm.azure.net/", credential=credential)

try:
client.get_role_assignment("/", "which-does-not-exist")
except ResourceNotFoundError as e:
print(e.message)
```

Clients from the Administration library can only be used to perform operations on a managed HSM, so attempting to do so on a Key Vault will raise an error.

## Next steps

Content forthcoming
Expand All @@ -297,6 +347,8 @@ Content forthcoming
For more extensive documentation on Azure Key Vault, see the
[API reference documentation][reference_docs].

For more extensive documentation on Managed HSM, see the [service documentation][managed_hsm].

## Contributing
This project welcomes contributions and suggestions. Most contributions require
you to agree to a Contributor License Agreement (CLA) declaring that you have
Expand All @@ -319,9 +371,10 @@ contact [email protected] with any additional questions or comments.
[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/
[default_cred_ref]: https://aka.ms/azsdk/python/identity/docs#azure.identity.DefaultAzureCredential
[keyvault_docs]: https://docs.microsoft.com/azure/key-vault/
[managed_hsm]: https://docs.microsoft.com/azure/key-vault/managed-hsm/
[pip]: https://pypi.org/project/pip/
[pypi_package_administration]: https://aka.ms/azsdk/python/keyvault-administration/pypi
[reference_docs]: https://aka.ms/azsdk/python/keyvault-administration/docs
Expand Down