Set-PimSmtpRelayPassword
Store the SMTP relay password in the environment's Key Vault
Purpose
Put the SMTP relay password of a PIM Manager environment into its Key Vault, and let the environment's managed identities read that one secret.
When to run it
When PIM Manager sends mail through an SMTP relay (Settings > Mail & alerting, or Get Started > Mail sender > SMTP relay) and could not write the password itself, or when the relay password changes. Not needed for the shared-mailbox mode.
Who may run it
| Kind | Role | Scope | Why |
|---|---|---|---|
| azureRbac | Key Vault Secrets Officer | the environment's Key Vault | Writes the secret. When you can manage the vault's access (User Access Administrator or Owner) but not its secrets, the script grants you this role on that one vault and retries. |
| azureRbac | User Access Administrator | the environment's Key Vault (Owner or Role Based Access Control Administrator work too) | Gives each sending identity read access on the one secret, and, when needed, gives you Key Vault Secrets Officer on the vault. |
| azureRbac | Reader | the subscription (-SubscriptionId) | Finds the vault by name in the subscription. |
| azureRbac | Contributor | the resource group (-ResourceGroup), only with -CreateVault | Creates the Key Vault when it does not exist. |
| other | browser sign-in to Azure (first-party public client 'Microsoft Azure PowerShell'), or the Invardia Support app (-AdminAppId + -AdminSecret) | Azure Resource Manager and Key Vault in your tenant | No PowerShell module and no certificate. The Support app's secret is accepted only for Invardia support; a person signs in in the browser. |
What it changes
| Where | Action | What | Permission / role | Scope | Why | Undo |
|---|---|---|---|---|---|---|
| Azure Resource Manager | create | Key Vault -VaultName (Azure RBAC authorisation, standard SKU, soft delete 90 days, the resource group's region) -- only with -CreateVault and only when it does not exist | the resource group -ResourceGroup | The relay password must live in the environment's own vault, never in SQL, the page or a log. | Delete the Key Vault (it stays soft-deleted for 90 days; purge it to remove it at once). | |
| Azure Key Vault | create | secret -SecretName (default PIM-SmtpRelayPassword) holding the SMTP relay password, content type 'PIM Manager SMTP relay password'; a new version when it exists. The value is read back to compare and never printed. | the Key Vault -VaultName | PIM Manager reads the password at send time with its managed identities. | Delete the secret (Key Vault > Secrets), or set the previous version back. | |
| Azure Resource Manager | grant | Azure role assignment for the account running the script (Microsoft.Authorization/roleAssignments) -- ONLY when Key Vault refuses the secret write | Key Vault Secrets Officer | the Key Vault -VaultName (that vault only) | Someone who manages the vault's access but not its secrets can then write the secret without a second person. | Key Vault > Access control (IAM) > remove your 'Key Vault Secrets Officer' assignment. |
| Azure Resource Manager | grant | Azure role assignment for each -ManagedIdentityObjectId (the Manager's and the engine job's identities), with a fixed name so a re-run does not create a second one | Key Vault Secrets User | the one secret only (<vault>/secrets/<secret name>), never the whole vault | The sending identities must read the password at send time, and nothing else in the vault. | Key Vault > the secret > Access control (IAM) > remove the assignment. |
| Local machine | create | the result file -OutFile (JSON: vault, secret name, what was created and granted; never the password) -- only when -OutFile is given and not under -WhatIf | the path you pass | For automation that reads the outcome. | Delete the file. |
What it only reads
- the Key Vaults of the subscription (to find -VaultName), and the vault's authorisation model
- the resource group's region (only with -CreateVault)
- the secret, right after writing it, to compare it (never printed)
Parameters
| Parameter | Required | Default | What it does |
|---|---|---|---|
| -TenantId | yes | Your tenant id; a sign-in in another tenant is refused. | |
| -SubscriptionId | yes | The subscription that holds the environment's Key Vault. | |
| -VaultName | yes | The environment's Key Vault. | |
| -SecretName | no | PIM-SmtpRelayPassword | The secret name. |
| -ManagedIdentityObjectId | no | Object ids of the identities that send (the Manager's and the engine job's); each gets read access on the secret only. | |
| -Password | no | asked twice at the prompt | The relay password as a SecureString. Never type it as plain text on the command line. |
| -CreateVault | no | off | Create the vault when it does not exist (needs -ResourceGroup). |
| -ResourceGroup | no | Where -CreateVault creates the vault. | |
| -AdminAppId | no | Invardia support only: the Invardia Support app's application id (with -AdminSecret) instead of the browser sign-in. | |
| -AdminSecret | no | Invardia support only: the Invardia Support app's secret. | |
| -OutFile | no | Write the result (no password) as JSON to this file. |
Preview with -WhatIf
Signs in, finds the vault, asks for no password, and prints one "What if:" line per change: create the vault (with -CreateVault), write the secret, the Key Vault Secrets Officer grant to you (only if the write would be refused), and Key Vault Secrets User on the secret for each managed identity. Nothing is written, no -OutFile either.
Undo
Remove the 'Key Vault Secrets User' assignments on the secret and any 'Key Vault Secrets Officer' assignment the script gave you on the vault, delete the secret, and delete the vault if the script created it.
Network
It connects to: login.microsoftonline.com, management.azure.com, <vault>.vault.azure.net, localhost (the browser returns the sign-in to a local port on this computer)
Download and run
Run these lines in PowerShell: the first downloads the script into the current folder, the second runs it.
Invoke-WebRequest https://invardia.com/support/pim/Set-PimSmtpRelayPassword.ps1 -OutFile Set-PimSmtpRelayPassword.ps1
.\Set-PimSmtpRelayPassword.ps1 -TenantId <TenantId> -SubscriptionId <SubscriptionId> -VaultName <VaultName>To check the download first, compare its SHA-256 with the published one:
SHA-256 d4c3cf438d00af14d53f7f95af08299e7609c4f5789415f09a14fe3a86aba6b2
Checksums: SHA256SUMS.txt · Version 3.0.70
Before you run it, compare the file's SHA-256 with its line in SHA256SUMS.txt.
Every parameter: Get-Help .\Set-PimSmtpRelayPassword.ps1 -Full · Source: Set-PimSmtpRelayPassword.ps1
Every script, identity and permission for your security review: PIM Manager