Skip to content

Commit ff3e122

Browse files
iscai-msftiscai-msft
authored
[keyvault] administration package readme (#13489)
1 parent 576953d commit ff3e122

File tree

4 files changed

+312
-2
lines changed

4 files changed

+312
-2
lines changed

‎sdk/keyvault/azure-keyvault-administration/README.md

Lines changed: 309 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,308 @@
1-
# Azure Key Vault Administration client library for Python
1+
# Azure KeyVault Administration client library for Python
2+
Azure Key Vault helps solve the following problems:
3+
- Vault administration (this library) - role-based access control (RBAC), and vault-level backup and restore options
4+
- 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
5+
access to the keys used to encrypt your data
6+
- Secrets management
7+
([azure-keyvault-secrets](https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/keyvault/azure-keyvault-secrets)) -
8+
securely store and control access to tokens, passwords, certificates, API keys,
9+
and other secrets
10+
- Certificate management
11+
([azure-keyvault-certificates](https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/keyvault/azure-keyvault-certificates)) -
12+
create, manage, and deploy public and private SSL/TLS certificates
213

314
## Getting started
15+
### Install packages
16+
Install [azure-keyvault-administration][pypi_package_administration] and
17+
[azure-identity][azure_identity_pypi] with [pip][pip]:
18+
```Bash
19+
pip install azure-keyvault-administration azure-identity
20+
```
21+
[azure-identity][azure_identity] is used for Azure Active Directory
22+
authentication as demonstrated below.
23+
24+
### Prerequisites
25+
* An [Azure subscription][azure_sub]
26+
* Python 2.7, 3.5.3, or later
27+
* 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.
28+
29+
### Authenticate the client
30+
This document demonstrates using [DefaultAzureCredential][default_cred_ref]
31+
to authenticate as a service principal. However, this package's clients
32+
accept any [azure-identity][azure_identity] credential. See the
33+
[azure-identity][azure_identity] documentation for more information about other
34+
credentials.
35+
36+
#### Create and Get credentials
37+
This [Azure Cloud Shell][azure_cloud_shell] snippet shows how to create a
38+
new service principal. Before using it, replace "your-application-name" with
39+
a more appropriate name for your service principal.
40+
41+
* Create a service principal:
42+
```Bash
43+
az ad sp create-for-rbac --name http://your-application-name --skip-assignment
44+
```
45+
46+
> Output:
47+
> ```json
48+
> {
49+
> "appId": "generated app id",
50+
> "displayName": "your-application-name",
51+
> "name": "http://your-application-name",
52+
> "password": "random password",
53+
> "tenant": "tenant id"
54+
> }
55+
> ```
56+
57+
* Take note of the service principal objectId
58+
```Bash
59+
az ad sp show --id <appId> --query objectId
60+
```
61+
62+
63+
> Output:
64+
> ```
65+
> "<your-service-principal-object-id>"
66+
> ```
67+
68+
* Use the output to set **AZURE_CLIENT_ID** ("appId" above), **AZURE_CLIENT_SECRET**
69+
("password" above) and **AZURE_TENANT_ID** ("tenant" above) environment variables.
70+
The following example shows a way to do this in Bash:
71+
```Bash
72+
export AZURE_CLIENT_ID="generated app id"
73+
export AZURE_CLIENT_SECRET="random password"
74+
export AZURE_TENANT_ID="tenant id"
75+
```
76+
77+
* 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):
78+
```Bash
79+
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>
80+
```
81+
82+
* Use the above mentioned Azure Key Vault name to retrieve details of your Vault which also contains your Azure Key Vault URL:
83+
```Bash
84+
az keyvault show --hsm-name <your-key-vault-name>
85+
```
86+
87+
#### Create a client
88+
Once the **AZURE_CLIENT_ID**, **AZURE_CLIENT_SECRET** and
89+
**AZURE_TENANT_ID** environment variables are set,
90+
[DefaultAzureCredential][default_cred_ref] will be able to authenticate the
91+
clients.
92+
93+
There are two clients available in this package, below are snippets demonstrating how to construct
94+
each one of these clients. Constructing a client also requires your vault's URL, which you can
95+
get from the Azure CLI or the Azure Portal. In the Azure Portal, this URL is
96+
the vault's "DNS Name".
97+
98+
##### Create a KeyVaultAccessControlClient
99+
```python
100+
from azure.identity import DefaultAzureCredential
101+
from azure.keyvault.administration import KeyVaultAccessControlClient
102+
103+
credential = DefaultAzureCredential()
104+
105+
client = KeyVaultAccessControlClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
106+
```
107+
108+
##### Create a KeyVaultBackupClient
109+
```python
110+
from azure.identity import DefaultAzureCredential
111+
from azure.keyvault.administration import KeyVaultBackupClient
112+
113+
credential = DefaultAzureCredential()
114+
115+
client = KeyVaultBackupClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
116+
```
4117
5118
## Key concepts
6119
120+
### Role Definition
121+
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.
122+
123+
A role definition is specified as part of a role assignment.
124+
125+
### Role Assignment.
126+
A role assignment is the association of a role definition to a service principal. They can be created, listed, fetched individually, and deleted.
127+
128+
### KeyVaultAccessControlClient
129+
A `KeyVaultAccessControlClient` manages role definitions and role assignments.
130+
131+
### KeyVaultBackupClient
132+
A `KeyVaultBackupClient` performs full key backups, full key restores, and selective key restores.
133+
7134
## Examples
135+
This section conntains code snippets covering common tasks:
136+
* Access Control
137+
* [List all role definitions](#list-all-role-definitions "List all role definitions")
138+
* [List all role assignments](#list-all-role-assignments "List all role assignments")
139+
* [Create, Get, and Delete a role assignment](#create-get-and-delete-a-role-assignment "Create, Get, and Delete a role assignment")
140+
* Backup and Restore
141+
* [Perform a full key backup](#perform-a-full-key-backup "Perform a full key backup")
142+
* [Perform a full key restore](#perform-a-full-key-restore "Perform a full key restore")
143+
144+
### List all role definitions
145+
List the role definitions available for assignment.
146+
147+
```python
148+
from azure.identity import DefaultAzureCredential
149+
from azure.keyvault.administration import KeyVaultAccessControlClient
150+
151+
credential = DefaultAzureCredential()
152+
153+
client = KeyVaultAccessControlClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
154+
155+
# this is the global scope. This will list all role definitions available for assignment
156+
role_definitions = client.list_role_definitions(role_scope=KeyVaultRoleScope.global_value)
157+
158+
for role_definition in role_definitions:
159+
print(role_definition.id)
160+
print(role_definition.role_name)
161+
print(role_definition.description)
162+
```
163+
164+
### List all role assignments
165+
Before creating a new role assignment in the [next snippet](#create-get-and-delete-a-role-assignment), list all of the current role assignments
166+
167+
```python
168+
from azure.identity import DefaultAzureCredential
169+
from azure.keyvault.administration import KeyVaultAccessControlClient
170+
171+
credential = DefaultAzureCredential()
172+
173+
client = KeyVaultAccessControlClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
174+
175+
# this is the global scope. This will list all role assignments available for assignment
176+
role_assignments = client.list_role_assignments(role_scope=KeyVaultRoleScope.global_value)
177+
178+
for role_assignment in role_assignments:
179+
print(role_assignment.name)
180+
print(role_assignment.principal_id)
181+
print(role_assignment.role_definition_id)
182+
```
183+
184+
### Create, Get, and Delete a role assignment
185+
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)
186+
187+
```python
188+
import uuid
189+
from azure.identity import DefaultAzureCredential
190+
from azure.keyvault.administration import KeyVaultAccessControlClient
191+
192+
credential = DefaultAzureCredential()
193+
194+
client = KeyVaultAccessControlClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
195+
196+
role_scope = "/" # setting the scope to the global scope
197+
role_assignment_name = uuid.uuid4()
198+
role_definition_id = "<role-definition-id>" # Replace <role-definition-id> with the id of a definition returned from the previous example
199+
principal_id = "<your-service-principal-object-id>"
200+
201+
# first, let's create the role assignment
202+
role_assignment = client.create_role_assignment(role_scope, role_assignment_name, role_definition_id, principal_id)
203+
print(role_assignment.name)
204+
print(role_assignment.principal_id)
205+
print(role_assignment.role_definition_id)
206+
207+
# now, we get it
208+
role_assignment = client.get_role_assignment(role_scope, role_assignment.name)
209+
print(role_assignment.name)
210+
print(role_assignment.principal_id)
211+
print(role_assignment.role_definition_id)
212+
213+
# finally, we delete this role assignment
214+
role_assignment = client.delete_role_assignment(role_scope, role_assignment.name)
215+
print(role_assignment.name)
216+
print(role_assignment.principal_id)
217+
print(role_assignment.role_definition_id)
218+
```
219+
220+
### Perform a full key backup
221+
Back up your entire collection of keys. The backing store for full key backups is a blob storage container using Shared Access Signature authentication.
222+
223+
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).
224+
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)
225+
226+
```python
227+
from azure.identity import DefaultAzureCredential
228+
from azure.keyvault.administration import KeyVaultBackupClient
229+
230+
credential = DefaultAzureCredential()
231+
client = KeyVaultBackupClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
232+
233+
blob_storage_uri = "<your-blob-storage-uri>" # the URI to your storage account. Should contain the name of the specific container
234+
sas_token = "<your-sas-token>" # replace with the sas token to your storage account. See this snippet's description on help to retrieve
235+
236+
# performing a full key backup is a long-running operation. Calling `result()` on the poller will wait
237+
# until the backup is completed, then return an object representing the backup operation.
238+
backup_operation = client.begin_full_backup(blob_storage_uri, sas_token).result()
239+
240+
# this is the URI of the Azure blob storage container which contains the backup
241+
azure_storage_blob_container_uri = backup_operation.azure_storage_blob_container_uri
242+
243+
print(backup_operation.status)
244+
print(backup_operation.job_id)
245+
print(azure_storage_blob_container_uri)
246+
```
247+
248+
249+
### Perform a full key restore
250+
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.
251+
You will also need the `azure_storage_blob_container_uri` from the [above snippet](#perform-a-full-key-backup).
252+
253+
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).
254+
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)
255+
256+
```python
257+
from azure.identity import DefaultAzureCredential
258+
from azure.keyvault.administration import KeyVaultBackupClient
259+
260+
credential = DefaultAzureCredential()
261+
client = KeyVaultBackupClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
262+
263+
blob_storage_uri = "<your-blob-storage-uri>" # the URI to your storage account. Should contain the name of the specific container
264+
sas_token = "<your-sas-token>" # replace with the sas token to your storage account. See this snippet's description on help to retrieve
265+
266+
# Replace <azure-storage-blob-container-uri> with the blob storage container returned in the previous example
267+
azure_storage_blob_container_uri = "<azure-storage-blob-container-uri>"
268+
folder_name = azure_storage_blob_container_uri.split("/")[-1]
269+
270+
# performing a full key restore is a long-running operation. Calling `result()` on the poller will wait
271+
# until the restore is completed, then return an object representing the restore operation.
272+
restore_operation = client.begin_full_restore(blob_storage_uri, sas_token, folder_name).result()
273+
274+
print(restore_operation.status)
275+
print(restore_operation.job_id)
276+
```
8277
9278
## Troubleshooting
279+
### General
280+
Key Vault clients raise exceptions defined in [azure-core][azure_core_exceptions].
281+
For example, if you try to get a role assignment that doesn't exist, KeyVaultAccessControlClient
282+
raises [ResourceNotFoundError](https://aka.ms/azsdk-python-core-exceptions-resource-not-found-error):
283+
284+
```python
285+
from azure.identity import DefaultAzureCredential
286+
from azure.keyvault.administration import KeyVaultAccessControlClient
287+
from azure.core.exceptions import ResourceNotFoundError
288+
289+
credential = DefaultAzureCredential()
290+
client = KeyVaultAccessControlClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
291+
292+
try:
293+
client.get_role_assignment("/", "which-does-not-exist")
294+
except ResourceNotFoundError as e:
295+
print(e.message)
296+
```
10297
11298
## Next steps
12299
300+
Content forthcoming
301+
302+
### Additional Documentation
303+
For more extensive documentation on Azure Key Vault, see the
304+
[API reference documentation][reference_docs].
305+
13306
## Contributing
14307
This project welcomes contributions and suggestions. Most contributions require
15308
you to agree to a Contributor License Agreement (CLA) declaring that you have
@@ -26,4 +319,18 @@ This project has adopted the
26319
see the Code of Conduct FAQ or contact [email protected] with any
27320
additional questions or comments.
28321
29-
![Impressions](https://azure-sdk-impressions.azurewebsites.net/api/impressions/azure-sdk-for-python%2Fsdk%2Fkeyvault%2Fazure-keyvault-administration%2FFREADME.png)
322+
<!-- LINKS -->
323+
[azure_cloud_shell]: https://shell.azure.com/bash
324+
[azure_core_exceptions]: https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/core/azure-core#azure-core-library-exceptions
325+
[azure_identity]: https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/identity/azure-identity
326+
[azure_identity_pypi]: https://pypi.org/project/azure-identity/
327+
[azure_sub]: https://azure.microsoft.com/free/
328+
[default_cred_ref]: https://aka.ms/azsdk/python/identity/docs#azure.identity.DefaultAzureCredential
329+
[code_of_conduct]: https://opensource.microsoft.com/codeofconduct/
330+
[keyvault_docs]: https://docs.microsoft.com/azure/key-vault/
331+
[pip]: https://pypi.org/project/pip/
332+
[pypi_package_administration]: https://aka.ms/azsdk/python/keyvault-administration/pypi
333+
[reference_docs]: https://aka.ms/azsdk/python/keyvault-administration/docs
334+
335+
336+
![Impressions](https://azure-sdk-impressions.azurewebsites.net/api/impressions/azure-sdk-for-python%2Fsdk%2Fkeyvault%2Fazure-keyvault-administration%2FREADME.png)

‎sdk/keyvault/azure-keyvault-certificates/README.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ Azure Key Vault helps solve the following problems:
77
([azure-keyvault-secrets](https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/keyvault/azure-keyvault-secrets)) -
88
securely store and control access to tokens, passwords, certificates, API keys,
99
and other secrets
10+
- 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
1011

1112
[Source code][certificates_client_src] | [Package (PyPI)][pypi_package_certificates] | [API reference documentation][reference_docs] | [Product documentation][keyvault_docs] | [Samples][certificates_samples]
1213

‎sdk/keyvault/azure-keyvault-keys/README.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ and other secrets
99
- Certificate management
1010
([azure-keyvault-certificates](https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/keyvault/azure-keyvault-certificates)) -
1111
create, manage, and deploy public and private SSL/TLS certificates
12+
- 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
1213

1314
[Source code][key_client_src] | [Package (PyPI)][pypi_package_keys] | [API reference documentation][reference_docs] | [Product documentation][keyvault_docs] | [Samples][key_samples]
1415

‎sdk/keyvault/azure-keyvault-secrets/README.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@ create, store, and control access to the keys used to encrypt your data
1010
- Certificate management
1111
([azure-keyvault-certificates](https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/keyvault/azure-keyvault-certificates)) -
1212
create, manage, and deploy public and private SSL/TLS certificates
13+
- 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
1314

1415
[Source code][secret_client_src] | [Package (PyPI)][pypi_package_secrets] | [API reference documentation][reference_docs] | [Product documentation][keyvault_docs] | [Samples][secret_samples]
1516

0 commit comments

Comments
 (0)