Document Details

$vault=Get-AzRecoveryServicesVault -ResourceGroupName "testrg" -Name "testvault" Update-AzRecoveryServicesVault -IdentityType SystemAssigned -ResourceGroupName TestRG -Name TestVault $vault.Identity | fl

#Find the application id for your recovery services vault Get-AzADServicePrincipal -SearchString <principalName> #Identify a role with Set permission on Secret, like Key Vault Secret Office Get-AzRoleDefinition | Format-Table -Property Name, IsCustom, Id #Assign role to Recovery Services Vault identity Get-AzRoleDefinition -Name <roleName> #Assign by Service Principal ApplicationId New-AzRoleAssignment -RoleDefinitionName 'Key Vault Secrets Officer' -ApplicationId {i.e 00001111-aaaa-2222-bbbb-3333cccc4444} -Scope /subscriptions/{subscriptionid}/resourcegroups/{resource-group-name}/providers/Microsoft.KeyVault/vaults/{key-vault-name}

$sp = Get-AzADServicePrincipal -DisplayName MyVault $Set-AzKeyVaultAccessPolicy -VaultName myKeyVault -ObjectId $sp.Id -PermissionsToSecrets set

--- ## Save passphrase to Azure Key Vault for a new MARS installation Before proceeding to install the MARS agent, ensure that you have [configured the Recovery Services vault to store passphrase to Azure Key Vault](#configure-the-recovery-services-vault-to-store-passphrase-to-azure-key-vault) and you have successfully: 1. Created your Recovery Services vault. 2. Enabled the Recovery Services vault's system-assigned managed identity. 3. Assigned permissions to your Recovery Services vault to create Secret in your Key Vault. 4. Enabled soft delete and purge protection for your Key Vault. 5. To install the MARS agent on a machine, download the MARS installer from the Azure portal, and then [use installation wizard](install-mars-agent.md). 6. After providing the *Recovery Services vault credentials* during registration, in the **Encryption Setting**, select the option to save the passphrase to Azure Key Vault. :::image type="content" source="./media/save-backup-passphrase-securely-in-azure-key-vault/save-passphrase.png" alt-text="Screenshot shows the option to save the passphrase to Azure Key Vault to be selected." lightbox="./media/save-backup-passphrase-securely-in-azure-key-vault/save-passphrase.png"::: 7. Enter your *passphrase* or select **Generate Passphrase**. 4. In the *Azure portal*, open your *Key Vault*, copy the *Key Vault URI*. :::image type="content" source="./media/save-backup-passphrase-securely-in-azure-key-vault/copy-key-vault-url.png" alt-text="Screenshot shows how to copy the Key Vault URI." lightbox="./media/save-backup-passphrase-securely-in-azure-key-vault/copy-key-vault-url.png"::: 5. Paste the *Key Vault URI* in the *MARS console*, and then select **Register**. If you encounter an error, [check the troubleshooting section](#troubleshoot-common-scenarios) for more information. 8. Once the registration succeeds, the option to *copy the identifier to the Secret* is created and the passphrase is NOT saved to a file locally. :::image type="content" source="./media/save-backup-passphrase-securely-in-azure-key-vault/server-registration-success.png" alt-text="Screenshot shows the option to copy the identifier to the Secret gets creates." lightbox="./media/save-backup-passphrase-securely-in-azure-key-vault/server-registration-success.png"::: If you change the passphrase in the future for this MARS agent, a new version of the Secret will be added with the latest passphrase. You can automate this process by using the new KeyVaultUri option in `Set-OBMachineSetting command` in the [installation script](./scripts/register-microsoft-azure-recovery-services-agent.md). ## Save passphrase to Azure Key Vault for an existing MARS installation If you have an existing MARS agent installation and want to save your passphrase to Azure Key Vault, [update your agent](upgrade-mars-agent.md) to version *2.0.9262.0* or above and perform a change passphrase operation. After updating your MARS agent, ensure that you have [configured the Recovery Services vault to store passphrase to Azure Key Vault](#configure-the-recovery-services-vault-to-store-passphrase-to-azure-key-vault) and you have successfully: 1. Created your Recovery Services vault. 2. Enabled the Recovery Services vault's system-assigned managed identity. 3. Assigned permissions to your Recovery Services vault to create Secret in your Key Vault. 4. Enabled soft delete and purge protection for your Key Vault To save the passphrase to Key Vault: 1. Open the *MARS agent console*. You should see a banner asking you to select a link to save the passphrase to Azure Key Vault. Alternatively, select **Change Properties** > **Change Passphrase** to proceed. :::image type="content" source="./media/save-backup-passphrase-securely-in-azure-key-vault/save-passphrase-key-vault.png" alt-text="Screenshot shows how to start changing passphrase for an existing MARS installation." lightbox="./media/save-backup-passphrase-securely-in-azure-key-vault/save-passphrase-key-vault.png"::: 2. In the **Change Properties** dialog box, the option to *save passphrase to Key Vault by providing a Key Vault URI* appears. >[!Note] >If the machine is already configured to save passphrase to Key Vault, the Key Vault URI will be populated in the text box automatically. :::image type="content" source="./media/save-backup-passphrase-securely-in-azure-key-vault/enter-key-vault-url.png" alt-text="Screenshot shows the option to save passphrase to Key Vault by providing a Key Vault URI gets generated." lightbox="./media/save-backup-passphrase-securely-in-azure-key-vault/enter-key-vault-url.png"::: 3. Open the *Azure portal*, open your *Key Vault*, and then *copy the Key Vault URI*. :::image type="content" source="./media/save-backup-passphrase-securely-in-azure-key-vault/copy-key-vault-url.png" alt-text="Screenshot shows how to copy the Key Vault URI." lightbox="./media/save-backup-passphrase-securely-in-azure-key-vault/copy-key-vault-url.png"::: 4. *Paste the Key Vault URI* in the *MARS console*, and then select **OK**. If you encounter an error, [check the troubleshooting section](#troubleshoot-common-scenarios) for more information. 5. Once the change passphrase operation succeeds, an option to *copy the identifier to the Secret* gets created and the passphrase is NOT saved to a file locally. :::image type="content" source="./media/save-backup-passphrase-securely-in-azure-key-vault/passphrase-saved-to-key-vault.png" alt-text="Screenshot shows an option to copy the identifier to the Secret gets created." lightbox="./media/save-backup-passphrase-securely-in-azure-key-vault/passphrase-saved-to-key-vault.png"::: If you change the passphrase in the future for this MARS agent, a new version of the *Secret* will be added with the latest passphrase. You can automate this step by using the new KeyVaultUri option in [Set-OBMachineSetting](/powershell/module/msonlinebackup/set-obmachinesetting?view=msonlinebackup-ps&preserve-view=true) cmdlet. ## Retrieve passphrase from Azure Key Vault for a machine If your machine becomes unavailable and you need to restore backup data from the Recovery Services vault via [alternate location restore](restore-all-files-volume-mars.md#volume-level-restore-to-an-alternate-machine), you need the machine’s passphrase to proceed. The passphrase is saved to Azure Key Vault as a Secret. One Secret is created per machine and a new version is added to the Secret when the passphrase for the machine is changed. The Secret is named as `AzBackup-machine fully qualified name-vault name`. To locate the machine’s passphrase: 1. In the *Azure portal*, open the *Key Vault used to save the passphrase for the machine*. We recommend you to use one Key Vault to save all your passphrases. 2. Select **Secrets** and search for the secret named `AzBackup-<machine name>-<vaultname>`. :::image type="content" source="./media/save-backup-passphrase-securely-in-azure-key-vault/locate-passphrase.png" alt-text="Screenshot shows bow to check for the secret name." lightbox="./media/save-backup-passphrase-securely-in-azure-key-vault/locate-passphrase.png"::: 3. Select the **Secret**, open the latest version and *copy the value of the Secret*. This is the passphrase of the machine to be used during recovery. :::image type="content" source="./media/save-backup-passphrase-securely-in-azure-key-vault/copy-passphrase-from-secret.png" alt-text="Screenshot shows selection of the secret." lightbox="./media/save-backup-passphrase-securely-in-azure-key-vault/copy-passphrase-from-secret.png"::: If you have a large number of Secrets in the Key Vault, use the Key Vault CLI to list and search for the secret.