Set-PimEmergencyPassphrase
Set up the emergency override passphrase
Part of the PIM Manager release - not a standalone download; it runs via the product's own install command or the updater.
Purpose
Sets up the emergency override (break-glass) passphrase of one PIM Manager environment: stores its SHA-256 hash as a secret in the environment's key vault, gives the Manager's managed identity read access to that one secret, and points the Manager at the vault.
When to run it
Once per environment, before the emergency override is needed (Settings > Emergency override shows 'no emergency passcode configured' until it has run), and again to change the passphrase. Ring 1 first.
Who may run it
| Kind | Role | Scope | Why |
|---|---|---|---|
| azureRbac | Key Vault Secrets Officer (or Key Vault Administrator) | the environment's key vault | Writes the secret PIM-EmergencyPasscode and reads it back. |
| azureRbac | User Access Administrator or Role Based Access Control Administrator (or Owner) | the environment's key vault (the grant is made on one secret in it) | Creates the Azure role assignment that lets the Manager read that one secret. |
| azureRbac | Contributor (or Container Apps Contributor) | the resource group of the Manager container app | Reads the Manager app and sets its PIM_EmergencyVault setting (a new revision). |
What it changes
| Where | Action | What | Permission / role | Scope | Why | Undo |
|---|---|---|---|---|---|---|
| Azure Key Vault | create | secret PIM-EmergencyPasscode (-SecretName) holding the SHA-256 hex of the passphrase; a new version when it already exists | the environment's key vault | The Manager checks a typed passphrase against this hash. The clear passphrase is never stored, never on a command line, never logged. | Disable or delete the secret version in the key vault (break-glass activation is then refused until it is set again). | |
| Azure role assignment | grant | the Manager container app's managed identity (system- and/or user-assigned) | Key Vault Secrets User (Azure role 4633458b-17de-408a-b874-0445c86b69e6) | the one secret <vault>/secrets/PIM-EmergencyPasscode (not the whole vault) | So the Manager can read the hash -- least privilege: read access to that secret only. An existing grant on the vault or the secret is left alone. | Remove that role assignment on the secret (Azure portal > key vault > Secrets > the secret > Access control). |
| Azure Container Apps | update | environment variable PIM_EmergencyVault=<vault> on the Manager container app (read-modify-write; every other setting kept) | the Manager container app (-ManagerApp), a new revision | Tells the Manager which vault holds the passphrase. | Remove PIM_EmergencyVault from the container app (a new revision). | |
| Local file (only with -OutFile) | create | the result file named by -OutFile (never the passphrase or its hash) | this computer | For a caller that reads the outcome. | Delete the file. |
What it only reads
- the Manager container app (its managed identities and environment variables)
- the key vault (exists, uses Azure RBAC authorization) and its role assignments
- whether the secret already exists (to say CREATE or REPLACE)
Parameters
| Parameter | Required | Default | What it does |
|---|---|---|---|
| -SubscriptionId | yes | The environment's subscription (always explicit). | |
| -ResourceGroup | yes | The resource group of the Manager container app. | |
| -ManagerApp | no | ca-pim-manager | The Manager container app. |
| -ContainerName | no | The Manager's container, when the app has more than one. | |
| -VaultName | yes | The environment's own key vault (must use Azure RBAC authorization). | |
| -VaultResourceGroup | no | -ResourceGroup | The vault's resource group. |
| -SecretName | no | PIM-EmergencyPasscode | The secret name the Manager reads. |
| -Passphrase | no | The passphrase as a SecureString (at least 12 characters). Omit it to be prompted twice. Never plain text. | |
| -TenantId | yes | The tenant id. | |
| -UseSignedInAccount | no | false | Sign in as the az user (asserted to be a user in -TenantId and -SubscriptionId). The recommended way. |
| -AdminAppId | no | Automation: the admin application's client id (with -AdminCertThumbprint). | |
| -AdminCertThumbprint | no | Automation: the thumbprint of the admin application's certificate in the local machine store. | |
| -OutFile | no | Write the outcome as JSON to this file. |
Preview with -WhatIf
Asks for no passphrase. Signs in, reads the Manager app, the vault and its role assignments, and prints each change it would make: 'What if: would CREATE (or REPLACE) secret PIM-EmergencyPasscode in <vault>', 'What if: would GRANT Key Vault Secrets User on secret PIM-EmergencyPasscode to the Manager identity <id>', 'What if: would SET PIM_EmergencyVault=<vault> on <app> (new revision)'. Nothing is written.
Undo
Remove the Key Vault Secrets User role assignment on the secret, remove PIM_EmergencyVault from the Manager container app, and disable or delete the secret. Emergency override activation is then refused until the script runs again.
Network
It connects to: login.microsoftonline.com (sign-in / tokens), management.azure.com (Azure Resource Manager), <vault>.vault.azure.net (Key Vault data plane)
How it runs
Part of the PIM Manager release - not a standalone download; it runs via the product's own install command or the updater.
Release 3.0.70
Every script, identity and permission for your security review: PIM Manager