Document Details
Save Backup Passphrase Securely In Azure Key Vault
β
This page contains Windows bias
About This Page
This page is part of the Azure documentation. It contains code examples and configuration instructions for working with Azure services.
Bias Analysis
Bias Types:
β οΈ
windows_tools
β οΈ
missing_linux_example
β οΈ
windows_first
Summary:
The documentation is heavily oriented toward Windows environments, specifically referencing the MARS agent, which is a Windows-only backup solution. All operational instructions and screenshots are based on the MARS console, a Windows GUI application. There are no Linux equivalents, examples, or mentions of cross-platform support. Automation references (such as Set-OBMachineSetting) are for Windows PowerShell only. The documentation does not acknowledge or provide alternatives for Linux users.
Recommendations:
- Clearly state at the beginning that the MARS agent and this workflow are Windows-only, and provide links to equivalent Linux backup solutions (such as Azure Backup for Linux VMs or Azure CLI-based backup).
- If possible, include parity documentation for Linux-based backup agents and how to securely store their credentials/passphrases in Azure Key Vault.
- Where automation is discussed, mention whether similar automation is available for Linux (e.g., via shell scripts or Azure CLI) or clarify that it is not supported.
- Add a comparison table or section outlining backup options for both Windows and Linux, with links to relevant documentation for each platform.
Create pull request
Scan History
| Date | Scan ID | Status | Bias Status |
|---|---|---|---|
| 2025-09-11 00:00 | #108 | completed | β Clean |
| 2025-08-11 00:00 | #77 | completed | β Clean |
| 2025-08-10 00:00 | #76 | completed | β Clean |
| 2025-08-09 00:00 | #75 | completed | β Clean |
| 2025-08-08 00:00 | #74 | completed | β Clean |
| 2025-08-07 00:00 | #73 | completed | β Clean |
| 2025-08-06 00:00 | #72 | completed | β Clean |
| 2025-08-05 00:00 | #71 | completed | β Clean |
| 2025-08-03 00:00 | #69 | completed | β Clean |
| 2025-08-01 00:00 | #67 | completed | β Clean |
| 2025-07-31 00:00 | #66 | completed | β Clean |
| 2025-07-30 00:00 | #65 | completed | β Clean |
| 2025-07-29 00:01 | #64 | completed | β Clean |
| 2025-07-28 00:00 | #63 | completed | β Clean |
| 2025-07-27 00:00 | #62 | completed | β Clean |
| 2025-07-26 00:01 | #61 | completed | β Clean |
| 2025-07-25 00:00 | #60 | completed | β Clean |
| 2025-07-24 00:00 | #59 | completed | β Clean |
| 2025-07-23 00:00 | #58 | completed | β Clean |
| 2025-07-22 00:01 | #57 | completed | β Clean |
| 2025-07-21 00:00 | #56 | completed | β Clean |
| 2025-07-19 13:51 | #54 | completed | β Clean |
| 2025-07-17 00:00 | #53 | completed | β Clean |
| 2025-07-13 21:37 | #48 | completed | β Biased |
| 2025-07-09 13:09 | #3 | cancelled | β Clean |
| 2025-07-08 04:23 | #2 | cancelled | β Biased |
Flagged Code Snippets
$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.