Register Secrets Hub in Azure AD

This topic describes how to register Secrets Hub in Azure AD in order to sync secrets.

Overview

To allow Secrets Hub to sync secrets from Privilege Cloud to Azure Key Vault, you need to register Secrets Hub as a client application in Azure AD. A client application registration is an Azure AD representation of an application that can be used to authenticate on behalf of a user and request access to resource applications.

To register Secrets Hub you can either run a PowerShell script or do it manually in Azure AD. For details, see Register Secrets Hub in Azure AD and Register Secrets Hub in Azure AD manually respectively.

The script does the following steps:

1. Creates the Secrets Hub app in Azure.

2. Provides Secrets Hub with the necessary permissions to sync secrets.

   • Permissions include: get, set, list, update, delete, and purge

   • If your Azure Key Vault has been configured to use Vault access policy, the script creates an access policy for Secrets Hub , where the principal is the Secrets Hub app.

   • If your Azure Key Vault has been configured to use Azure Role Based Access Control (RBAC), the script creates a role for Secrets Hub, where the principal is the Secrets Hub app.

   For a more detailed description of what this script does, see Azure script - detailed description.

Before you run the script

Before you run the script, collect the following information:

Run the Azure PowerShell script

Run the PowerShell script below to create the Secrets Hub app in Azure Key Vault and set its permissions.

For details on using Azure PowerShell, see Microsoft documentation.

You can run the script in these modes:

• Silent mode: edit the parameters in advance and then run the script.

• Interactive mode:  run the script and enter the parameters when prompted.

<path_to_script>/<script_file_name>.ps1 -AppClientDisplayName <app_client_display_name> -KeyVaultName <key_vault_name> -ResourceGroupName <resource_group_name>

param ( [Parameter(Mandatory=$true)][string]$AppClientDisplayName, [Parameter(Mandatory=$true)][string]$KeyVaultName, [Parameter(Mandatory=$true)][string]$ResourceGroupName);$ErrorActionPreference = "Stop";if (-not (Get-AzResourceGroup -Name $ResourceGroupName -ErrorVariable notPresent -ErrorAction SilentlyContinue)) { throw "App registration creation failed. Resource group $ResourceGroupName does not exist in subscription";}$appExists = Get-AzADApplication -DisplayName $AppClientDisplayName;$keyVault = Get-AzKeyVault -ResourceGroupName $ResourceGroupName -VaultName $KeyVaultName;if (-not ($keyVault)) { throw "App registration creation failed. Key Vault $KeyVaultName does not exist in resource group";}if ($appExists) { throw "Application named $AppClientDisplayName already exists in your subscription";}$appClient = New-AzADApplication -DisplayName $AppClientDisplayName;$newServicePrincipal = New-AzADServicePrincipal -ApplicationId $appClient.AppId;$clientSecret = New-AzADAppCredential -ApplicationId $appClient.AppId -EndDate (Get-Date).AddYears(1);if ($keyVault.EnableRBACAuthorization) { Write-Output "$KeyVaultName's access configuration is of type RBAC. Creating new Role..."; $azureSubscriptionId = (Get-AzContext).Subscription.Id; $RoleDefinitionName = "Secrets-Hub-$KeyVaultName-$AppClientDisplayName-Role"; try { $roleDefinition = [Microsoft.Azure.Commands.Resources.Models.Authorization.PSRoleDefinition]::new(); $roleDefinition.Name = $RoleDefinitionName; $roleDefinition.Actions = @(); $roleDefinition.Description = "provide read-write access to secrets in key vault"; $roleDefinition.Actions.Add("Microsoft.KeyVault/vaults/secrets/write"); $roleDefinition.Actions.Add("Microsoft.KeyVault/vaults/secrets/read"); $roleDefinition.DataActions = @(); $roleDefinition.DataActions.Add("Microsoft.KeyVault/vaults/secrets/delete"); $roleDefinition.DataActions.Add("Microsoft.KeyVault/vaults/secrets/purge/action"); $roleDefinition.DataActions.Add("Microsoft.KeyVault/vaults/secrets/update/action"); $roleDefinition.DataActions.Add("Microsoft.KeyVault/vaults/secrets/getSecret/action"); $roleDefinition.DataActions.Add("Microsoft.KeyVault/vaults/secrets/setSecret/action"); $roleDefinition.DataActions.Add("Microsoft.KeyVault/vaults/secrets/readMetadata/action"); $roleDefinition.AssignableScopes = @("/subscriptions/$azureSubscriptionId/resourceGroups/$ResourceGroupName/providers/Microsoft.KeyVault/vaults/$KeyVaultName"); New-AzRoleDefinition -Role $roleDefinition; Write-Output "$RoleDefinitionName created successfully!"; $retryCount = 5; $retryDelaySeconds = 1; $success = $false; for ($i = 1; $i -le $retryCount -and -not $success; $i++) { try { New-AzRoleAssignment -RoleDefinitionName $RoleDefinitionName ` -ApplicationId $appClient.AppId ` -Scope "/subscriptions/$azureSubscriptionId/resourceGroups/$ResourceGroupName/providers/Microsoft.KeyVault/vaults/$KeyVaultName"; $success = $true; Write-Output "Role permissions assigned successfully!"; } catch { Write-Host "Attempt $i failed: $($_.Exception.Message)"; Start-Sleep -Seconds $retryDelaySeconds; if ($i -eq $retryCount) { throw "Role permissions assignment failed. $($_.Exception.Message)"; } } } } catch { throw $_.Exception; }} else { Write-Output "$KeyVaultName's access configuration is of type Vault Access Policy. Creating new access policy..."; $appServicePrincipal = Get-AzADServicePrincipal -DisplayName $appClient.DisplayName; if ($appServicePrincipal) { Set-AzKeyVaultAccessPolicy -VaultName $KeyVaultName ` -ResourceGroupName $ResourceGroupName ` -ObjectId $appServicePrincipal.Id ` -PermissionsToSecrets get,set,list,delete,purge ; Write-Output "Access policy created successfully!"; } else { throw "Access policy creation failed. $appClient.DisplayName application has no service principal."; }}if ($clientSecret) { Write-Output "App created successfully with the relevant permissions!"; Write-Output "App Client credentials:"; $AppClientID = $appClient.AppId; Write-Output "App Client ID = $AppClientID"; $ClientPassword = $clientSecret.SecretText; Write-Output "App Client Secret = $ClientPassword";}

Register Secrets Hub in Azure AD manually

You need to provide Secrets Hub with the following permissions to sync secrets: get, set, list, update, delete, and purge.

To register Secrets Hub manually via the Microsoft Azure portal, do the following steps.

1. In the Microsoft Azure portal, create a new Secrets Hub application registration. Follow the instructions in the Microsoft Azure documentation.

2. If you have an RBAC permissions model, follow the instructions in the Microsoft Azure documentation to: 

   1. Create a new custom role.

   2. Grant the relevant permissions.

   3. Assign the app you created in the previous step.

3. If you have an access policy permissions model, follow the instructions in the Microsoft Azure documentation to:

   1. Create a new custom role.

   2. Grant the relevant permissions.

   3. Assign the app you created in the previous step.