Create backup and restore samples, various other updates

sdk/keyvault/Azure.Security.KeyVault.Administration/CHANGELOG.md

@@ -5,3 +5,4 @@
 ### Added
 
 - Add `KeyVaultAccessControlClient`.
+- Add `KeyVaultBackupClient`.

sdk/keyvault/Azure.Security.KeyVault.Administration/readme.md

@@ -10,7 +10,7 @@ The Azure Key Vault administration library clients support administrative tasks
 Install the Azure Key Vault administration client library for .NET with [NuGet][nuget]:
 
 ```PowerShell
-Install-Package Azure.Security.KeyVault.Administration --version 4.2.0-preview.1
+Install-Package Azure.Security.KeyVault.Administration --version 4.0.0-beta.1
 ```
 
 ### Prerequisites
@@ -81,10 +81,10 @@ Once you've populated the **AZURE_CLIENT_ID**, **AZURE_CLIENT_SECRET** and **AZU
 KeyVaultAccessControlClient client = new KeyVaultAccessControlClient(vaultUri: new Uri(keyVaultUrl), credential: new DefaultAzureCredential());
 
 // Retrieve all the role definitions.
-List<RoleDefinition> roleDefinitions = client.GetRoleDefinitions(RoleAssignmentScope.Global).ToList();
+List<KeyVaultRoleDefinition> roleDefinitions = client.GetRoleDefinitions(KeyVaultRoleScope.Global).ToList();
 
 // Retrieve all the role assignments.
-List<RoleAssignment> roleAssignments = client.GetRoleAssignments(RoleAssignmentScope.Global).ToList();
+List<KeyVaultRoleAssignment> roleAssignments = client.GetRoleAssignments(KeyVaultRoleScope.Global).ToList();
 ```
 
 ## Key concepts
@@ -109,9 +109,9 @@ The following section provides several code snippets using the `client` [created
 List the role definitions available for assignment.
 
 ```C# Snippet:GetRoleDefinitions
-Pageable<RoleDefinition> allDefinitions = client.GetRoleDefinitions(RoleAssignmentScope.Global);
+Pageable<KeyVaultRoleDefinition> allDefinitions = client.GetRoleDefinitions(KeyVaultRoleScope.Global);
 
-foreach (RoleDefinition roleDefinition in allDefinitions)
+foreach (KeyVaultRoleDefinition roleDefinition in allDefinitions)
 {
     Console.WriteLine(roleDefinition.Id);
     Console.WriteLine(roleDefinition.RoleName);
@@ -130,20 +130,20 @@ string definitionIdToAssign = "<roleDefinitionId>";
 // Replace <objectId> with the service principal object id from the Create/Get credentials section above
 string servicePrincipalObjectId = "<objectId>";
 
-RoleAssignmentProperties properties = new RoleAssignmentProperties(definitionIdToAssign, servicePrincipalObjectId);
+KeyVaultRoleAssignmentProperties properties = new KeyVaultRoleAssignmentProperties(definitionIdToAssign, servicePrincipalObjectId);
 RoleAssignment createdAssignment = client.CreateRoleAssignment(RoleAssignmentScope.Global, properties);
 
 Console.WriteLine(createdAssignment.Name);
 Console.WriteLine(createdAssignment.Properties.PrincipalId);
 Console.WriteLine(createdAssignment.Properties.RoleDefinitionId);
 
-RoleAssignment fetchedAssignment = client.GetRoleAssignment(RoleAssignmentScope.Global, createdAssignment.Name);
+KeyVaultRoleAssignment fetchedAssignment = client.GetRoleAssignment(KeyVaultRoleScope.Global, createdAssignment.Name);
 
 Console.WriteLine(fetchedAssignment.Name);
 Console.WriteLine(fetchedAssignment.Properties.PrincipalId);
 Console.WriteLine(fetchedAssignment.Properties.RoleDefinitionId);
 
-RoleAssignment deletedAssignment = client.DeleteRoleAssignment(RoleAssignmentScope.Global, createdAssignment.Name);
+KeyVaultRoleAssignment deletedAssignment = client.DeleteRoleAssignment(KeyVaultRoleScope.Global, createdAssignment.Name);
 
 Console.WriteLine(deletedAssignment.Name);
 Console.WriteLine(deletedAssignment.Properties.PrincipalId);
@@ -159,7 +159,7 @@ For example, if you try to retrieve a role assignment that doesn't exist in your
 ```C# Snippet:RoleAssignmentNotFound
 try
 {
-    RoleAssignment roleAssignment = client.GetRoleAssignment(RoleAssignmentScope.Global, "invalid-name");
+    KeyVaultRoleAssignment roleAssignment = client.GetRoleAssignment(KeyVaultRoleScope.Global, "invalid-name");
 }
 catch (RequestFailedException ex)
 {

sdk/keyvault/Azure.Security.KeyVault.Administration/samples/README.md

@@ -13,3 +13,5 @@ description: Samples for the Azure.Security.KeyVault.Administration client libra
 
 - Creating, getting, and deleting role assignments [synchronously](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/keyvault/Azure.Security.KeyVault.Administration/samples/Sample1_RbacHelloWorldSync.md) or [asynchronously](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/keyvault/Azure.Security.KeyVault.Administration/samples/Sample1_RbacHelloWorldAsync.md)
 - [Assigning roles for specific scopes](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/keyvault/Azure.Security.KeyVault.Administration/samples/Sample2_RbacScopeAssignment.md) 
+- Performing a full key backup and restore [synchronously](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/keyvault/Azure.Security.KeyVault.Administration/samples/Sample1_BackupHelloWorldSync.md) and [asynchronously](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/keyvault/Azure.Security.KeyVault.Administration/samples/Sample1_BackupHelloWorldAsync.md)
+- [Performing selective key restore]

sdk/keyvault/Azure.Security.KeyVault.Administration/samples/Sample1_BackupHelloWorldAsync.md

@@ -0,0 +1,69 @@
+# Performing a full key backup and restore (Async)
+
+This sample demonstrates how to a full key backup and restore in Azure Key Vault.
+To get started, you'll need a URI to an Azure Key Vault. See the [README](../README.md) for links and instructions.
+
+## Creating a KeyVaultBackupClient
+
+To create a new `KeyVaultBackupClient`, you'll need the endpoint to an Azure Key Vault and credentials.
+You can use the [DefaultAzureCredential][DefaultAzureCredential] to try a number of common authentication methods optimized for both running as a service and development.
+
+In the sample below, you can set `keyVaultUrl` based on an environment variable, configuration setting, or any way that works for your application.
+
+```C# Snippet:HelloCreateKeyVaultBackupClient
+KeyVaultBackupClient client = new KeyVaultBackupClient(new Uri(keyVaultUrl), new DefaultAzureCredential());
+```
+
+## Performing a full key backup
+
+Using the `KeyVaultBackupClient`, you can backup 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 [Azure Storage Blobs client README](blob_readme) and the [authentication samples](blob_auth).
+Alternatively, it is possible to [generate a SAS token in Storage Explorer](storage_explorer_sas)
+
+To ensure you have some keys for backup, you may want to first create a key using the `KeyClient`.
+To create a new `KeyClient` to create a key, see the [Creating a KeyClient](creating_keyvault) and [Creating a key](creating_key) samples.
+
+In the sample below, you can set `blobStorageUrl`, `blobContainerName`, and `sasToken` based on a environment variables, configuration settings, or any way that works for your application.
+
+```C# Snippet:HelloFullBackupAsync
+// Create a Uri with the storage container
+UriBuilder builder = new UriBuilder(blobStorageUrl)
+{
+    Path = blobContainerName,
+};
+
+// Start the backup.
+BackupOperation backupOperation = await Client.StartBackupAsync(builder.Uri, sasToken);
+
+// Wait for completion of the BackupOperation.
+var backupResult = await backupOperation.WaitForCompletionAsync();
+
+// Get the Uri for the location of you backup blob.
+Uri backupBlobUri = backupResult.Value;
+```
+
+## Performing a full key restore
+
+Using the `KeyVaultBackupClient`, you can restore your entire collection of keys from backup. The data source for full key restore is a storage blob accessed using Shared Access Signature authentication. 
+For more details on creating a SAS token using the `BlobServiceClient`, see the [Azure Storage Blobs client README](blob_readme) and the [authentication samples](blob_auth).
+Alternatively, it is possible to [generate a SAS token in Storage Explorer](storage_explorer_sas)
+
+```C# Snippet:HelloFullRestoreAsync
+// Get the folder name from the backupBlobUri returned from a previous BackupOperation
+var uriSegments = backupBlobUri.Segments;
+string folderName = uriSegments[uriSegments.Length - 1];
+
+// Start the restore.
+RestoreOperation restoreOperation = await Client.StartRestoreAsync(builder.Uri, sasToken, folderName);
+
+// Wait for completion of the RestoreOperation.
+var restoreResult = await restoreOperation.WaitForCompletionAsync();
+```
+
+<!-- LINKS -->
+[DefaultAzureCredential]: ../../../identity/Azure.Identity/README.md
+[creating_keyvault]: https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/keyvault/Azure.Security.KeyVault.Keys/samples/Sample1_HelloWorld.md#creating-a-keyclient
+[creating_key]: https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/keyvault/Azure.Security.KeyVault.Keys/samples/Sample1_HelloWorld.md#creating-a-key
+[blob_readme]: https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/storage/Azure.Storage.Blobs/README.md
+[blob_auth]: https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/storage/Azure.Storage.Blobs/samples/Sample02_Auth.cs
+[storage_explorer_sas]: 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

sdk/keyvault/Azure.Security.KeyVault.Administration/samples/Sample1_BackupHelloWorldSync.md

@@ -0,0 +1,78 @@
+# Performing a full key backup and restore (Sync)
+
+This sample demonstrates how to a full key backup and restore in Azure Key Vault.
+To get started, you'll need a URI to an Azure Key Vault. See the [README](../README.md) for links and instructions.
+
+## Creating a KeyVaultBackupClient
+
+To create a new `KeyVaultBackupClient`, you'll need the endpoint to an Azure Key Vault and credentials.
+You can use the [DefaultAzureCredential][DefaultAzureCredential] to try a number of common authentication methods optimized for both running as a service and development.
+
+In the sample below, you can set `keyVaultUrl` based on an environment variable, configuration setting, or any way that works for your application.
+
+```C# Snippet:HelloCreateKeyVaultBackupClient
+KeyVaultBackupClient client = new KeyVaultBackupClient(new Uri(keyVaultUrl), new DefaultAzureCredential());
+```
+
+## Performing a full key backup
+
+Using the `KeyVaultBackupClient`, you can backup 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 [Azure Storage Blobs client README](blob_readme) and the [authentication samples](blob_auth).
+Alternatively, it is possible to [generate a SAS token in Storage Explorer](storage_explorer_sas)
+
+To ensure you have some keys for backup, you may want to first create a key using the `KeyClient`.
+To create a new `KeyClient` to create a key, see the [Creating a KeyClient](creating_keyvault) and [Creating a key](creating_key) samples.
+
+In the sample below, you can set `blobStorageUrl`, `blobContainerName`, and `sasToken` based on a environment variables, configuration settings, or any way that works for your application.
+
+```C# Snippet:HelloFullBackupSync
+// Create a Uri with the storage container
+UriBuilder builder = new UriBuilder(blobStorageUrl)
+{
+    Path = blobContainerName,
+};
+
+// Start the backup.
+BackupOperation backupOperation = Client.StartBackup(builder.Uri, sasToken);
+
+// Wait for completion of the BackupOperation.
+while (!backupOperation.HasCompleted)
+{
+    backupOperation.UpdateStatus();
+    Thread.Sleep(3000);
+}
+
+// Get the Uri for the location of you backup blob.
+Uri backupBlobUri = backupOperation.Value;
+```
+
+## Performing a full key restore
+
+Using the `KeyVaultBackupClient`, you can restore your entire collection of keys from backup. The data source for full key restore is a storage blob accessed using Shared Access Signature authentication. 
+For more details on creating a SAS token using the `BlobServiceClient`, see the [Azure Storage Blobs client README](blob_readme) and the [authentication samples](blob_auth).
+Alternatively, it is possible to [generate a SAS token in Storage Explorer](storage_explorer_sas)
+
+```C# Snippet:HelloFullRestoreSync
+// Get the folder name from the backupBlobUri returned from a previous BackupOperation
+var uriSegments = backupBlobUri.Segments;
+string folderName = uriSegments[uriSegments.Length - 1];
+
+// Start the restore.
+RestoreOperation restoreOperation = Client.StartRestore(builder.Uri, sasToken, folderName);
+
+// Wait for completion of the RestoreOperation.
+while (!restoreOperation.HasCompleted)
+{
+    restoreOperation.UpdateStatus();
+    Thread.Sleep(3000);
+}
+var restoreResult = backupOperation.Value;
+```
+
+<!-- LINKS -->
+[DefaultAzureCredential]: ../../../identity/Azure.Identity/README.md
+[creating_keyvault]: https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/keyvault/Azure.Security.KeyVault.Keys/samples/Sample1_HelloWorld.md#creating-a-keyclient
+[creating_key]: https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/keyvault/Azure.Security.KeyVault.Keys/samples/Sample1_HelloWorld.md#creating-a-key
+[blob_readme]: https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/storage/Azure.Storage.Blobs/README.md
+[blob_auth]: https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/storage/Azure.Storage.Blobs/samples/Sample02_Auth.cs
+[storage_explorer_sas]: 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

sdk/keyvault/Azure.Security.KeyVault.Administration/samples/Sample1_RbacHelloWorldAsync.md

@@ -19,8 +19,8 @@ KeyVaultAccessControlClient client = new KeyVaultAccessControlClient(new Uri(key
 In order to assign a role to a service principal, we'll have to know which role definitions are available. Let's get all of them.
 
 ```C# Snippet:GetRoleDefinitionsAsync
-List<RoleDefinition> roleDefinitions = new List<RoleDefinition>();
-await foreach (var definition in client.GetRoleDefinitionsAsync(RoleAssignmentScope.Global))
+List<KeyVaultRoleDefinition> roleDefinitions = new List<KeyVaultRoleDefinition>();
+await foreach (var definition in client.GetRoleDefinitionsAsync(KeyVaultRoleScope.Global))
 {
     roleDefinitions.Add(definition);
 }
@@ -31,8 +31,8 @@ await foreach (var definition in client.GetRoleDefinitionsAsync(RoleAssignmentSc
 Before assigning any new roles, let's get all the current role assignments.
 
 ```C# Snippet:GetRoleAssignmentsAsync
-List<RoleAssignment> roleAssignments = new List<RoleAssignment>();
-await foreach (var assignment in client.GetRoleAssignmentsAsync(RoleAssignmentScope.Global))
+List<KeyVaultRoleAssignment> roleAssignments = new List<KeyVaultRoleAssignment>();
+await foreach (var assignment in client.GetRoleAssignmentsAsync(KeyVaultRoleScope.Global))
 {
     roleAssignments.Add(assignment);
 }
@@ -54,7 +54,7 @@ az ad signed-in-user show --query objectId
 string definitionIdToAssign = "<roleDefinitionId>";
 string servicePrincipalObjectId = "<objectId>";
 
-RoleAssignmentProperties properties = new RoleAssignmentProperties(definitionIdToAssign, servicePrincipalObjectId);
+KeyVaultRoleAssignmentProperties properties = new KeyVaultRoleAssignmentProperties(definitionIdToAssign, servicePrincipalObjectId);
 RoleAssignment createdAssignment = await client.CreateRoleAssignmentAsync(RoleAssignmentScope.Global, properties);
 ```
 
@@ -63,15 +63,16 @@ RoleAssignment createdAssignment = await client.CreateRoleAssignmentAsync(RoleAs
 To get an existing role assignment, we'll need the `Name` property from an existing assignment. Let's use the `createdAssignment` from the previous example.
 
 ```C# Snippet:GetRoleAssignmentAsync
-RoleAssignment fetchedAssignment = await client.GetRoleAssignmentAsync(RoleAssignmentScope.Global, createdAssignment.Name);
+KeyVaultRoleAssignment fetchedAssignment = await client.GetRoleAssignmentAsync(KeyVaultRoleScope.Global, createdAssignment.Name);
 ```
 
 # Deleting a Role Assignment
 To remove a role assignment from a service principal, the role assignment must be deleted. Let's delete the `createdAssignment` from the previous example.
 
 ```C# Snippet:DeleteRoleAssignmentAsync
-RoleAssignment deletedAssignment = await client.DeleteRoleAssignmentAsync(RoleAssignmentScope.Global, createdAssignment.Name);
+KeyVaultRoleAssignment deletedAssignment = await client.DeleteRoleAssignmentAsync(KeyVaultRoleScope.Global, createdAssignment.Name);
 ```
 
 <!-- LINKS -->
 [azure_cli]: https://docs.microsoft.com/cli/azure
+[DefaultAzureCredential]: ../../../identity/Azure.Identity/README.md

sdk/keyvault/Azure.Security.KeyVault.Administration/samples/Sample1_RbacHelloWorldSync.md

@@ -19,15 +19,15 @@ KeyVaultAccessControlClient client = new KeyVaultAccessControlClient(new Uri(key
 In order to assign a role to a service principal, we'll have to know which role definitions are available. Let's get all of them.
 
 ```C# Snippet:GetRoleDefinitionsSync
-List<RoleDefinition> roleDefinitions = client.GetRoleDefinitions(RoleAssignmentScope.Global).ToList();
+List<KeyVaultRoleDefinition> roleDefinitions = client.GetRoleDefinitions(KeyVaultRoleScope.Global).ToList();
 ```
 
 ## Listing All Role Assignments
 
 Before assigning any new roles, let's get all the current role assignments.
 
 ```C# Snippet:GetRoleAssignmentsSync
-List<RoleAssignment> roleAssignments = client.GetRoleAssignments(RoleAssignmentScope.Global).ToList();
+List<KeyVaultRoleAssignment> roleAssignments = client.GetRoleAssignments(KeyVaultRoleScope.Global).ToList();
 ```
 
 # Creating a Role Assignment
@@ -46,7 +46,7 @@ az ad signed-in-user show --query objectId
 string definitionIdToAssign = "<roleDefinitionId>";
 string servicePrincipalObjectId = "<objectId>";
 
-RoleAssignmentProperties properties = new RoleAssignmentProperties(definitionIdToAssign, servicePrincipalObjectId);
+KeyVaultRoleAssignmentProperties properties = new KeyVaultRoleAssignmentProperties(definitionIdToAssign, servicePrincipalObjectId);
 RoleAssignment createdAssignment = client.CreateRoleAssignment(RoleAssignmentScope.Global, properties);
 ```
 
@@ -55,15 +55,17 @@ RoleAssignment createdAssignment = client.CreateRoleAssignment(RoleAssignmentSco
 To get an existing role assignment, we'll need the `Name` property from an existing assignment. Let's use the `createdAssignment` from the previous example.
 
 ```C# Snippet:GetRoleAssignment
-RoleAssignment fetchedAssignment = client.GetRoleAssignment(RoleAssignmentScope.Global, createdAssignment.Name);
+KeyVaultRoleAssignment fetchedAssignment = client.GetRoleAssignment(KeyVaultRoleScope.Global, createdAssignment.Name);
 ```
 
 # Deleting a Role Assignment
 To remove a role assignment from a service principal, the role assignment must be deleted. Let's delete the `createdAssignment` from the previous example.
 
 ```C# Snippet:DeleteRoleAssignment
-RoleAssignment deletedAssignment = client.DeleteRoleAssignment(RoleAssignmentScope.Global, createdAssignment.Name);
+KeyVaultRoleAssignment deletedAssignment = client.DeleteRoleAssignment(KeyVaultRoleScope.Global, createdAssignment.Name);
 ```
 
 <!-- LINKS -->
 [azure_cli]: https://docs.microsoft.com/cli/azure
+[DefaultAzureCredential]: ../../../identity/Azure.Identity/README.md
+

sdk/keyvault/Azure.Security.KeyVault.Administration/samples/Sample2_RbacScopeAssignment.md

@@ -19,7 +19,7 @@ A role definition Id can be obtained from the `Id` property of one of the role d
 string definitionIdToAssign = "<roleDefinitionId>";
 string servicePrincipalObjectId = "<objectId>";
 
-RoleAssignmentProperties properties = new RoleAssignmentProperties(definitionIdToAssign, servicePrincipalObjectId);
+KeyVaultRoleAssignmentProperties properties = new KeyVaultRoleAssignmentProperties(definitionIdToAssign, servicePrincipalObjectId);
 RoleAssignment keysScopedAssignment = await client.CreateRoleAssignmentAsync(RoleAssignmentScope.Global, properties);
 ```