[Az.KeyVault] User mi support for backup/restore hsm (#23916)

* user mi support for backup/restore hsm

* user mi support for backup/restore hsm

* user mi support for backup/restore hsm help

* user mi support for backup/restore hsm polish

* user mi support for backup/restore hsm polish

* user mi support for backup/restore hsm polish

* Update ChangeLog.md

* edge case

* edge case

Author: NoriZC

src/KeyVault/KeyVault.Test/PesterTests/ManagedHsmDataPlaneTests.Tests.ps1

@@ -6,9 +6,12 @@ $sut = (Split-Path -Leaf $MyInvocation.MyCommand.Path) -replace '\.Tests\.', '.'
 # ImportModules
 $hsmName = 'yeminghsm112901'
 $signInName = '[email protected]'
+$subscriptionId = '0b1f6471-1bf0-4dda-aec3-cb9272f09590'
 $storageAccount = 'bezstorageaccount'
 $containerName = 'backup'
 $keyName = 'test'
+$userManagedIdentityName = 'nori-identity'
+$resourceGroupName = 'nori-testhsm'
 # $sasToken = ConvertTo-SecureString -AsPlainText -Force 'insert sas token'
 $certs = "D:\sd1.cer", "D:\sd2.cer", "D:\sd3.cer" # for security domain
 $certsKeys = @{PublicKey = "D:\sd1.cer"; PrivateKey = "D:\sd1.key" }, @{PublicKey = "D:\sd2.cer"; PrivateKey = "D:\sd2.key" }, @{PublicKey = "D:\sd3.cer"; PrivateKey = "D:\sd3.key" }
@@ -176,6 +179,12 @@ Describe "BackupAndRestoreAzManagedHsm" {
         $script:backupUri | Should -Not -Be $null
     }
 
+    It "Backup a managed Hsm via User Assigned Managed Identity"{
+        Update-AzKeyVaultManagedHsm -UserAssignedIdentity "/subscriptions/$subscriptionId/resourceGroups/$resourceGroupName/providers/Microsoft.ManagedIdentity/userAssignedIdentities/$userManagedIdentityName"
+        $script:backupUri = Backup-AzKeyVault -HsmName $hsmName -StorageContainerUri $containerUri -UseUserManagedIdentity
+        $script:backupUri | Should -Not -Be $null
+    }
+
     It "Selective restore a key to managed HSM" {
         $script:backupUri = [System.Uri]::new($script:backupUri)
         $backupFolder = $script:backupUri.Segments[$script:backupUri.Segments.Length - 1]
@@ -192,6 +201,11 @@ Describe "BackupAndRestoreAzManagedHsm" {
         $restoreResult = Restore-AzKeyVault -HsmName $hsmName -StorageContainerUri $containerUri -BackupFolder $backupFolder -SasToken $sasToken -PassThru
         $restoreResult | Should -Be $True
     }
+
+    It "Restore a managed Hsm via User Assigned Managed Identity"{
+        $restoreResult = Restore-AzKeyVault -HsmName $hsmName -StorageContainerUri $containerUri -BackupFolder $backupFolder -UseUserManagedIdentity
+        $restoreResult | Should -Be $True
+    }
 }
 
 Describe "GetAzManagedHsmRoleDefinition" {

src/KeyVault/KeyVault/ChangeLog.md

@@ -18,6 +18,7 @@
         - Additional information about change #1
 -->
 ## Upcoming Release
+* Supported authentication via User Managed Identity by adding parameter `UseUserManagedIdentity` and making `SasToken` optional.
 
 ## Version 5.1.0
 * Added parameter `ByteArrayValue` in `Invoke-AzKeyVaultKeyOperation` to support operating byte array without conversion to secure string.

src/KeyVault/KeyVault/Commands/FullBackupRestore/BackupAzureManagedHsm.cs

@@ -20,7 +20,7 @@ public override void DoExecuteCmdlet()
             {
                 try
                 {
-                    WriteObject(Track2DataClient.BackupHsm(HsmName, StorageContainerUri, SasToken.ConvertToString()).AbsoluteUri);
+                    WriteObject(Track2DataClient.BackupHsm(HsmName, StorageContainerUri, SasToken?.ConvertToString()).AbsoluteUri);
                 }
                 catch (Exception ex)
                 {

src/KeyVault/KeyVault/Commands/FullBackupRestore/FullBackupRestoreCmdletBase.cs

@@ -1,5 +1,8 @@
-using Microsoft.Azure.Commands.Common.Authentication;
+using Microsoft.Azure.Commands.KeyVault.Properties;
+using Microsoft.Azure.Commands.Common;
+using Microsoft.Azure.Commands.Common.Authentication;
 using Microsoft.Azure.Commands.Common.Authentication.Abstractions;
+using Microsoft.Azure.Commands.Common.Exceptions;
 using Microsoft.Azure.Commands.KeyVault.Models;
 using Microsoft.WindowsAzure.Commands.Utilities.Common;
 using System;
@@ -39,9 +42,12 @@ public abstract class FullBackupRestoreCmdletBase : KeyVaultCmdletBase
             HelpMessage = "Name of the blob container where the backup is going to be stored.")]
         public string StorageContainerName { get; set; }
 
-        [Parameter(Mandatory = true, HelpMessage = "The shared access signature (SAS) token to authenticate the storage account.")]
+        [Parameter(Mandatory = false, HelpMessage = "The shared access signature (SAS) token to authenticate the storage account.")]
         public SecureString SasToken { get; set; }
 
+        [Parameter(Mandatory = false, HelpMessage = "Specified to use User Managed Identity to authenticate the storage account. Only valid when SasToken is not set.")]
+        public SwitchParameter UseUserManagedIdentity { get; set; }
+
         [Parameter(ParameterSetName = InputObjectStorageUri, Mandatory = true, ValueFromPipeline = true, HelpMessage = "Managed HSM object")]
         [Parameter(ParameterSetName = InputObjectStorageName, Mandatory = true, ValueFromPipeline = true, HelpMessage = "Managed HSM object")]
         public PSManagedHsm HsmObject { get; set; }
@@ -64,7 +70,22 @@ private void PreprocessParameterSet()
 
             if (this.IsParameterBound(c => c.StorageAccountName))
             {
-                StorageContainerUri = new Uri($"https://{StorageAccountName}.{DefaultContext.Environment.GetEndpoint(AzureEnvironment.Endpoint.StorageEndpointSuffix)}/{StorageContainerName}");
+                StorageContainerUri = new Uri($"https://{StorageAccountName}.blob.{DefaultContext.Environment.GetEndpoint(AzureEnvironment.Endpoint.StorageEndpointSuffix)}/{StorageContainerName}");
+            }
+
+            if (this.IsParameterBound(c => c.SasToken) && SasToken == null)
+            {
+                throw new AzPSArgumentException(Resources.SasTokenNotNull, ErrorKind.UserError);
+            }
+
+            if (this.IsParameterBound(c => c.SasToken) && this.UseUserManagedIdentity.IsPresent)
+            {
+                throw new AzPSArgumentException(Resources.UseManagedIdentityAndSasTokenBothExist, ErrorKind.UserError);
+            }
+
+            if (!this.IsParameterBound(c => c.SasToken) && !this.UseUserManagedIdentity.IsPresent)
+            {
+                throw new AzPSArgumentException(Resources.UseManagedIdentityAndSasTokenNeitherExist, ErrorKind.UserError);
             }
         }
 

src/KeyVault/KeyVault/Commands/FullBackupRestore/RestoreAzureManagedHsm.cs

@@ -31,11 +31,11 @@ public override void DoExecuteCmdlet()
                         {
                             if(KeyName == null)
                             {
-                                Track2DataClient.RestoreHsm(HsmName, StorageContainerUri, SasToken.ConvertToString(), BackupFolder);
+                                Track2DataClient.RestoreHsm(HsmName, StorageContainerUri, SasToken?.ConvertToString(), BackupFolder);
                             }
                             else
                             {
-                                Track2DataClient.SelectiveRestoreHsm(HsmName, KeyName,StorageContainerUri, SasToken.ConvertToString(), BackupFolder);
+                                Track2DataClient.SelectiveRestoreHsm(HsmName, KeyName,StorageContainerUri, SasToken?.ConvertToString(), BackupFolder);
                                 errorMsg = string.Format(Resources.SelectiveRestoreFailed, KeyName, HsmName);
                             }
                         }

src/KeyVault/KeyVault/KeyVault.csproj

@@ -12,7 +12,7 @@
   </PropertyGroup>
 
   <ItemGroup>
-    <PackageReference Include="Azure.Security.KeyVault.Administration" Version="4.3.0" />
+    <PackageReference Include="Azure.Security.KeyVault.Administration" Version="4.4.0-beta.1" />
     <PackageReference Include="Azure.Security.KeyVault.Keys" Version="4.3.0" />
     <PackageReference Include="Azure.Security.KeyVault.Certificates" Version="4.3.0" />
     <PackageReference Include="Portable.BouncyCastle" Version="1.8.8" />

src/KeyVault/KeyVault/Properties/Resources.Designer.cs

@@ -618,4 +618,13 @@ You can find the object ID using Azure Active Directory Module for Windows Power
   <data name="UpdateKeyVaultSetting" xml:space="preserve">
     <value>Update vault setting</value>
   </data>
+  <data name="SasTokenNotNull" xml:space="preserve">
+    <value>Please provide a valid SasToken or use Managed Identity for authentication.</value>
+  </data>
+  <data name="UseManagedIdentityAndSasTokenBothExist" xml:space="preserve">
+    <value>Parameter SasToken and UseUserManagedIdentity can not exist at the same time. Please choose either one as authentication method.</value>
+  </data>
+  <data name="UseManagedIdentityAndSasTokenNeitherExist" xml:space="preserve">
+    <value>Please choose either SasToken or UseUserManagedIdentity as authentication method.</value>
+  </data>
 </root>

src/KeyVault/KeyVault/Properties/Resources.resx

@@ -15,25 +15,27 @@ Fully backup a managed HSM.
 ### InteractiveStorageName (Default)
 ```
 Backup-AzKeyVault [-HsmName] <String> -StorageAccountName <String> -StorageContainerName <String>
- -SasToken <SecureString> [-DefaultProfile <IAzureContextContainer>] [-WhatIf] [-Confirm] [<CommonParameters>]
+ [-SasToken <SecureString>] [-UseUserManagedIdentity] [-DefaultProfile <IAzureContextContainer>] [-WhatIf]
+ [-Confirm] [<CommonParameters>]
 ```
 
 ### InteractiveStorageUri
 ```
-Backup-AzKeyVault [-HsmName] <String> -StorageContainerUri <Uri> -SasToken <SecureString>
- [-DefaultProfile <IAzureContextContainer>] [-WhatIf] [-Confirm] [<CommonParameters>]
+Backup-AzKeyVault [-HsmName] <String> -StorageContainerUri <Uri> [-SasToken <SecureString>]
+ [-UseUserManagedIdentity] [-DefaultProfile <IAzureContextContainer>] [-WhatIf] [-Confirm] [<CommonParameters>]
 ```
 
 ### InputObjectStorageUri
 ```
-Backup-AzKeyVault -StorageContainerUri <Uri> -SasToken <SecureString> -HsmObject <PSManagedHsm>
- [-DefaultProfile <IAzureContextContainer>] [-WhatIf] [-Confirm] [<CommonParameters>]
+Backup-AzKeyVault -StorageContainerUri <Uri> [-SasToken <SecureString>] [-UseUserManagedIdentity]
+ -HsmObject <PSManagedHsm> [-DefaultProfile <IAzureContextContainer>] [-WhatIf] [-Confirm] [<CommonParameters>]
 ```
 
 ### InputObjectStorageName
 ```
-Backup-AzKeyVault -StorageAccountName <String> -StorageContainerName <String> -SasToken <SecureString>
- -HsmObject <PSManagedHsm> [-DefaultProfile <IAzureContextContainer>] [-WhatIf] [-Confirm] [<CommonParameters>]
+Backup-AzKeyVault -StorageAccountName <String> -StorageContainerName <String> [-SasToken <SecureString>]
+ [-UseUserManagedIdentity] -HsmObject <PSManagedHsm> [-DefaultProfile <IAzureContextContainer>] [-WhatIf]
+ [-Confirm] [<CommonParameters>]
 ```
 
 ## DESCRIPTION
@@ -42,7 +44,7 @@ Use `Restore-AzKeyVault` to restore the backup.
 
 ## EXAMPLES
 
-### Example 1
+### Example 1 Backup an HSM to Storage Container using SAS token
 ```powershell
 $sasToken = ConvertTo-SecureString -AsPlainText -Force "?sv=2019-12-12&ss=bfqt&srt=sco&sp=rwdlacupx&se=2020-10-12T14:42:19Z&st=2020-10-12T06:42:19Z&spr=https&sig=******"
 
@@ -55,6 +57,31 @@ https://{accountName}.blob.core.windows.net/{containerName}/{backupFolder}
 
 The cmdlet will create a folder (typically named `mhsm-{name}-{timestamp}`) in the storage container, store the backup in that folder and output the folder URI.
 
+### Example 2 Backup an HSM to Storage Container via User Assigned Managed Identity Authentication
+```powershell
+# Make sure an identity is assigend to the Hsm
+Update-AzKeyVaultManagedHsm -UserAssignedIdentity "/subscriptions/{sub-id}/resourceGroups/{rg-name}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{identity-name}"
+Backup-AzKeyVault -HsmName myHsm -StorageContainerUri "https://{accountName}.blob.core.windows.net/{containerName}" -UseUserManagedIdentity
+```
+
+```output
+https://{accountName}.blob.core.windows.net/{containerName}/{backupFolder}
+```
+
+The cmdlet will backup the hsm in specific Storage Container and output the folder URI via User Assigned Managed Identity Authentication. The Managed Identity should be assigned access permission to the storage container.
+
+### Example 3 Backup an HSM to Storage Container using Storage Account Name and Storage Container
+```powershell
+Backup-AzKeyVault -HsmName myHsm -StorageAccountName "{accountName}" -StorageContainerName "{containerName}" -UseUserManagedIdentity
+```
+
+```output
+https://{accountName}.blob.core.windows.net/{containerName}/{backupFolder}
+```
+
+The cmdlet will create a folder (typically named `mhsm-{name}-{timestamp}`) in the storage container, store the backup in that folder and output the folder URI.
+
+
 ## PARAMETERS
 
 ### -DefaultProfile
@@ -110,7 +137,7 @@ Type: System.Security.SecureString
 Parameter Sets: (All)
 Aliases:
 
-Required: True
+Required: False
 Position: Named
 Default value: None
 Accept pipeline input: False
@@ -162,6 +189,21 @@ Accept pipeline input: False
 Accept wildcard characters: False
 ```
 
+### -UseUserManagedIdentity
+Specified to use User Managed Identity to authenticate the storage account. Only valid when SasToken is not set.
+
+```yaml
+Type: System.Management.Automation.SwitchParameter
+Parameter Sets: (All)
+Aliases:
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
 ### -Confirm
 Prompts you for confirmation before running the cmdlet.
 

src/KeyVault/KeyVault/help/Backup-AzKeyVault.md

@@ -15,28 +15,28 @@ Fully restores a managed HSM from backup.
 ### InteractiveStorageName (Default)
 ```
 Restore-AzKeyVault -BackupFolder <String> [-KeyName <String>] [-PassThru] [-HsmName] <String>
- -StorageAccountName <String> -StorageContainerName <String> -SasToken <SecureString>
- [-DefaultProfile <IAzureContextContainer>] [-WhatIf] [-Confirm] [<CommonParameters>]
+ -StorageAccountName <String> -StorageContainerName <String> [-SasToken <SecureString>]
+ [-UseUserManagedIdentity] [-DefaultProfile <IAzureContextContainer>] [-WhatIf] [-Confirm] [<CommonParameters>]
 ```
 
 ### InteractiveStorageUri
 ```
 Restore-AzKeyVault -BackupFolder <String> [-KeyName <String>] [-PassThru] [-HsmName] <String>
- -StorageContainerUri <Uri> -SasToken <SecureString> [-DefaultProfile <IAzureContextContainer>] [-WhatIf]
- [-Confirm] [<CommonParameters>]
+ -StorageContainerUri <Uri> [-SasToken <SecureString>] [-UseUserManagedIdentity]
+ [-DefaultProfile <IAzureContextContainer>] [-WhatIf] [-Confirm] [<CommonParameters>]
 ```
 
 ### InputObjectStorageUri
 ```
 Restore-AzKeyVault -BackupFolder <String> [-KeyName <String>] [-PassThru] -StorageContainerUri <Uri>
- -SasToken <SecureString> -HsmObject <PSManagedHsm> [-DefaultProfile <IAzureContextContainer>] [-WhatIf]
- [-Confirm] [<CommonParameters>]
+ [-SasToken <SecureString>] [-UseUserManagedIdentity] -HsmObject <PSManagedHsm>
+ [-DefaultProfile <IAzureContextContainer>] [-WhatIf] [-Confirm] [<CommonParameters>]
 ```
 
 ### InputObjectStorageName
 ```
 Restore-AzKeyVault -BackupFolder <String> [-KeyName <String>] [-PassThru] -StorageAccountName <String>
- -StorageContainerName <String> -SasToken <SecureString> -HsmObject <PSManagedHsm>
+ -StorageContainerName <String> [-SasToken <SecureString>] [-UseUserManagedIdentity] -HsmObject <PSManagedHsm>
  [-DefaultProfile <IAzureContextContainer>] [-WhatIf] [-Confirm] [<CommonParameters>]
 ```
 
@@ -46,14 +46,24 @@ Use `Backup-AzKeyVault` to backup.
 
 ## EXAMPLES
 
-### Example 1
+### Example 1 Restore a Key Vault
 ```powershell
 $sasToken = ConvertTo-SecureString -AsPlainText -Force "?sv=2019-12-12&ss=bfqt&srt=sco&sp=rwdlacupx&se=2020-10-12T14:42:19Z&st=2020-10-12T06:42:19Z&spr=https&sig=******"
 Restore-AzKeyVault -HsmName myHsm -StorageContainerUri "https://{accountName}.blob.core.windows.net/{containerName}" -BackupFolder "mhsm-myHsm-2020101308504935" -SasToken $sasToken
 ```
 
 The example restores a backup stored in a folder named "mhsm-myHsm-2020101308504935" of a storage container "https://{accountName}.blob.core.windows.net/{containerName}".
 
+### Example 2 Restore a Key Vault via User Assigned Managed Identity Authentication
+```powershell
+# Make sure an identity is assigend to the Hsm
+Update-AzKeyVaultManagedHsm -UserAssignedIdentity "/subscriptions/{sub-id}/resourceGroups/{rg-name}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{identity-name}"
+Restore-AzKeyVault -HsmName myHsm -StorageContainerUri "https://{accountName}.blob.core.windows.net/{containerName}" -BackupFolder "mhsm-myHsm-2020101308504935" -UseUserManagedIdentity
+```
+
+The example restores an HSM via User Assigned Managed Identity Authentication.
+
+
 ## PARAMETERS
 
 ### -BackupFolder
@@ -156,7 +166,7 @@ Type: System.Security.SecureString
 Parameter Sets: (All)
 Aliases:
 
-Required: True
+Required: False
 Position: Named
 Default value: None
 Accept pipeline input: False
@@ -208,6 +218,21 @@ Accept pipeline input: False
 Accept wildcard characters: False
 ```
 
+### -UseUserManagedIdentity
+Specified to use User Managed Identity to authenticate the storage account. Only valid when SasToken is not set.
+
+```yaml
+Type: System.Management.Automation.SwitchParameter
+Parameter Sets: (All)
+Aliases:
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
 ### -Confirm
 Prompts you for confirmation before running the cmdlet.