[Key Vault] Address administration feedback (Azure#19099)

Co-authored-by: Charles Lowell <chlowe@microsoft.com>

Author: mccoyp

sdk/keyvault/azure-keyvault-administration/CHANGELOG.md

@@ -3,21 +3,35 @@
 ## 4.0.0b4 (Unreleased)
 ### Changed
 - Key Vault API version 7.2 is now the default
+- `KeyVaultAccessControlClient.delete_role_assignment` and
+  `.delete_role_definition` no longer raise an error  when the resource to be
+  deleted is not found
+- Raised minimum azure-core version to 1.11.0
 
 ### Added
-- `KeyVaultAccessControlClient.set_role_definition` accepts an optional 
+- `KeyVaultAccessControlClient.set_role_definition` accepts an optional
   `assignable_scopes` keyword-only argument
 
 ### Breaking Changes
+- `KeyVaultAccessControlClient.delete_role_assignment` and
+  `.delete_role_definition` return None
 - Changed parameter order in `KeyVaultAccessControlClient.set_role_definition`.
   `permissions` is now an optional keyword-only argument
-- Renamed `BackupOperation` to `KeyVaultBackupOperation`
-- Renamed `RestoreOperation` to `KeyVaultRestoreOperation`
-- Renamed `SelectiveKeyRestoreOperation` to 
-  `KeyVaultSelectiveKeyRestoreOperation`
-- Renamed `KeyVaultBackupClient.begin_selective_restore` to `begin_selective_key_restore`
-  - Changed parameter order from `folder_url, sas_token, key_name` to
-    `key_name, folder_url, sas_token`
+- Renamed `BackupOperation` to `KeyVaultBackupOperation`, and removed all but
+  its `folder_url` property
+- Removed `RestoreOperation` and `SelectiveKeyRestoreOperation` classes
+- Removed `KeyVaultBackupClient.begin_selective_restore`. To restore a
+  single key, pass the key's name to `KeyVaultBackupClient.begin_restore`:
+  ```
+  # before (4.0.0b3):
+  client.begin_selective_restore(folder_url, sas_token, key_name)
+
+  # after:
+  client.begin_restore(folder_url, sas_token, key_name=key_name)
+  ```
+- Removed `KeyVaultBackupClient.get_backup_status` and `.get_restore_status`. Use
+  the pollers returned by `KeyVaultBackupClient.begin_backup` and `.begin_restore`
+  to check whether an operation has completed
 - `KeyVaultRoleAssignment`'s `principal_id`, `role_definition_id`, and `scope`
   are now properties of a `properties` property
   ```
@@ -32,6 +46,12 @@
   - `denied_actions` -> `not_actions`
   - `allowed_data_actions` -> `data_actions`
   - `denied_data_actions` -> `denied_data_actions`
+- Renamed argument `role_assignment_name` to `name` in
+  `KeyVaultAccessControlClient.create_role_assignment`, `.delete_role_assignment`,
+  and `.get_role_assignment`
+- Renamed argument `role_definition_name` to `name` in
+  `KeyVaultAccessControlClient.delete_role_definition` and `.get_role_definition`
+- Renamed argument `role_scope` to `scope` in `KeyVaultAccessControlClient` methods
 
 ## 4.0.0b3 (2021-02-09)
 ### Added

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

@@ -81,7 +81,7 @@ a more appropriate name for your service principal.
     ```Bash
     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
@@ -165,12 +165,12 @@ credential = DefaultAzureCredential()
 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)
+role_definitions = client.list_role_definitions(KeyVaultRoleScope.GLOBAL)
 
-for role_definition in role_definitions:
-    print(role_definition.id)
-    print(role_definition.role_name)
-    print(role_definition.description)
+for definition in role_definitions:
+    print(definition.id)
+    print(definition.role_name)
+    print(definition.description)
 ```
 
 ### Set, Get, and Delete a role definition
@@ -180,33 +180,34 @@ for role_definition in role_definitions:
 ```python
 import uuid
 from azure.identity import DefaultAzureCredential
-from azure.keyvault.administration import KeyVaultAccessControlClient, KeyVaultDataAction, KeyVaultPermission
+from azure.keyvault.administration import (
+    KeyVaultAccessControlClient,
+    KeyVaultDataAction,
+    KeyVaultPermission,
+    KeyVaultRoleScope
+)
 
 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()
+# create a custom role definition
 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
-)
+created_definition = client.set_role_definition(KeyVaultRoleScope.GLOBAL, permissions=permissions)
 
 # 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
+    KeyVaultRoleScope.GLOBAL, permissions=permissions, role_name=created_definition.name
 )
 
 # get the custom role definition
-definition = client.get_role_definition(role_scope=role_scope, role_definition_name=definition_name)
+definition = client.get_role_definition(KeyVaultRoleScope.GLOBAL, role_name=definition_name)
 
 # delete the custom role definition
-deleted_definition = client.delete_role_definition(role_scope=role_scope, role_definition_name=definition_name)
+deleted_definition = client.delete_role_definition(KeyVaultRoleScope.GLOBAL, role_name=definition_name)
 ```
 
 ### List all role assignments
@@ -221,43 +222,42 @@ credential = DefaultAzureCredential()
 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)
+role_assignments = client.list_role_assignments(KeyVaultRoleScope.GLOBAL)
 
-for role_assignment in role_assignments:
-    print(role_assignment.name)
-    print(role_assignment.principal_id)
-    print(role_assignment.role_definition_id)
+for assignment in role_assignments:
+    print(assignment.name)
+    print(assignment.principal_id)
+    print(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-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
+from azure.keyvault.administration import KeyVaultAccessControlClient, KeyVaultRoleScope
 
 credential = DefaultAzureCredential()
 
 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
 principal_id = "<your-service-principal-object-id>"
 
 # first, let's create the role assignment
-role_assignment = client.create_role_assignment(role_scope, role_definition_id, principal_id)
+role_assignment = client.create_role_assignment(KeyVaultRoleScope.GLOBAL, 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)
+role_assignment = client.get_role_assignment(KeyVaultRoleScope.GLOBAL, 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)
+role_assignment = client.delete_role_assignment(KeyVaultRoleScope.GLOBAL, role_assignment.name)
 print(role_assignment.name)
 print(role_assignment.principal_id)
 print(role_assignment.role_definition_id)
@@ -280,13 +280,13 @@ client = KeyVaultBackupClient(vault_url="https://my-managed-hsm-name.managedhsm.
 blob_storage_url = "<your-blob-storage-url>"
 sas_token = "<your-sas-token>"  # replace with a sas token to your storage account
 
-# 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_backup(blob_storage_url, sas_token).result()
+# Backup is a long-running operation. The client returns a poller object whose result() method
+# blocks until the backup is complete, then returns an object representing the backup operation.
+backup_poller = client.begin_backup(blob_storage_url, sas_token)
+backup_operation = backup_poller.result()
 
+# this is the Azure Storage Blob URL of the backup
 print(backup_operation.folder_url)
-print(backup_operation.status)
-print(backup_operation.job_id)
 ```
 
 
@@ -309,12 +309,10 @@ sas_token = "<your-sas-token>"  # replace with a sas token to your storage accou
 # URL to a storage blob, for example https://<account name>.blob.core.windows.net/backup/mhsm-account-2020090117323313
 blob_url = "<your-blob-url>"
 
-# 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_restore(blob_url, sas_token).result()
-
-print(restore_operation.status)
-print(restore_operation.job_id)
+# Restore is a long-running operation. The client returns a poller object whose wait() method
+# blocks until the restore is complete.
+restore_poller = client.begin_restore(blob_url, sas_token)
+restore_poller.wait()
 ```
 
 ## Troubleshooting

sdk/keyvault/azure-keyvault-administration/azure/keyvault/administration/__init__.py

@@ -12,8 +12,6 @@
     KeyVaultRoleAssignment,
     KeyVaultRoleAssignmentProperties,
     KeyVaultRoleDefinition,
-    KeyVaultRestoreOperation,
-    KeyVaultSelectiveKeyRestoreOperation,
 )
 
 
@@ -28,6 +26,4 @@
     "KeyVaultRoleAssignmentProperties",
     "KeyVaultRoleDefinition",
     "KeyVaultRoleScope",
-    "KeyVaultRestoreOperation",
-    "KeyVaultSelectiveKeyRestoreOperation",
 ]