Set-PimManagerCustomHost
Give the PIM Manager a custom host name
Part of the PIM Manager release - not a standalone download; it runs via the product's own install command or the updater.
Purpose
Gives the PIM Manager a custom host name (for example pim-manager.<your domain>) next to its generated Container Apps address: it adds and binds the name with a certificate, writes or prints the DNS records, and adds the name to the Manager's known host names and its sign-in reply URLs.
When to run it
After the installation, when people should reach the Manager on a name in your own domain. A public environment takes a public subdomain you own and a free managed certificate (create the printed CNAME and TXT records first, then re-run with -PublicDnsReady -- also with -Dns None); a private environment needs your own certificate (Key Vault PFX or PEM, or a PFX file) and a private DNS record: written into a private DNS zone that already exists, or printed for your DNS administrator (AD DNS). Run it again with -Remove to take the name off. It is part of the PIM Manager release package, not a separate download: run it from the package folder that Install-Invardia (or the guided install) downloaded and verified (.\tools\setup\Set-PimManagerCustomHost.ps1).
Who may run it
| Kind | Role | Scope | Why |
|---|---|---|---|
| azureRbac | Contributor | the PIM resource group | Adds (or with -Remove removes) the host name and the certificate on the Manager container app and its environment, and sets PIM_MANAGER_HOSTNAMES (a new revision). |
| azureRbac | Private DNS Zone Contributor | -PrivateDnsResourceGroup (default: the PIM resource group); only for a private environment with -Dns Auto / PrivateDnsZone | Lists the private DNS zones there, writes the A record into the EXISTING zone the name belongs to and links it to the -LinkVnetIds networks that are not linked yet. PIM never creates a zone. |
| azureRbac | Network Contributor | each virtual network in -LinkVnetIds (only when a link is created) | Linking a private DNS zone to a virtual network needs join rights on that network. |
| azureRbac | Key Vault Secrets User | the Key Vault named by -KeyVaultName (only with a Key Vault certificate) | Reads the certificate (its secret half: a PFX, or PEM that is converted to PFX in memory) straight into the upload; it is never written to disk. |
| entraRole | Application Administrator (or owner of the Manager's sign-in app registration) | the Manager's Easy Auth app registration (skipped with -SkipEasyAuth) | Adds (or with -Remove removes) https://<name>/.auth/login/aad/callback in its reply URLs. |
What it changes
| Where | Action | What | Permission / role | Scope | Why | Undo |
|---|---|---|---|---|---|---|
| Manager container app (ingress) | update | custom domain <name> (hostname add), then bound to its certificate (SNI); -Remove takes it off | the Manager app only; the other names and the app's secrets are kept | The point of the script: the Manager answers on the new name. | Run the script again with -Remove (or remove the custom domain in the Azure portal > Container App > Custom domains). | |
| Container Apps environment | create | a managed certificate (public environment) or an uploaded certificate from Key Vault (PFX or PEM) / PFX file (private environment), named after the host name | the PIM Container Apps environment | The name needs a certificate; a private environment cannot validate a free managed one. | -Remove deletes it when nothing else uses it (or delete it from the environment after removing the custom domain). | |
| Private DNS (private environment) | create | the A record <name> -> the environment's static IP in the EXISTING zone the name belongs to (the longest private zone the name ends with, or -DnsZone), and a link to each -LinkVnetIds network not linked to that zone yet. No zone is created: when none exists, the zone, record and links to create are printed | -PrivateDnsResourceGroup | So clients in those networks resolve the name. The record is read before it is written. | Delete the A record (and the links if nothing else uses them). -Remove prints the record to delete; it deletes no DNS. | |
| Manager container app (environment variables) | update | PIM_MANAGER_HOSTNAMES (the name appended once; -Remove takes it out) -- a new revision | the Manager app | The Manager knows the custom name. Mail links (the ManagerUrl setting) switch to it on the next signed-in Manager page only when ManagerUrl is empty or was auto-recorded as the generated address; a ManagerUrl set in Settings is never overwritten. | Run the script with -Remove (or remove the name from PIM_MANAGER_HOSTNAMES). | |
| Microsoft Entra ID | update | the Manager's sign-in app registration: reply URL https://<name>/.auth/login/aad/callback | that one app registration | Sign-in on the new name returns to the Manager. | Run the script with -Remove (or remove the reply URL from the app registration). |
What it only reads
- the Manager container app and its Container Apps environment (internal or external, static IP, default domain, verification id)
- the private DNS zones in -PrivateDnsResourceGroup, the existing record and the zone's virtual network links (before writing them)
- the Manager's Easy Auth configuration and its app registration's reply URLs
Parameters
| Parameter | Required | Default | What it does |
|---|---|---|---|
| -SubscriptionId | yes | The PIM subscription. | |
| -TenantId | yes | The tenant id. The REST session is pinned to it; a session of any other tenant is refused. | |
| -ResourceGroup | yes | The PIM resource group. | |
| -HostName | yes | The custom name, at least three labels (name.domain.tld). A public environment refuses private top-level names (.local, .corp, .lan, ...). | |
| -ManagerApp | no | ca-pim-manager | The Manager container app's name. |
| -KeyVaultName | no | The Key Vault holding your certificate (with -KeyVaultCertName). | |
| -KeyVaultCertName | no | The certificate's name in that Key Vault. PFX (PKCS #12) or PEM content type; PEM is converted to PFX in memory and needs PowerShell 7. | |
| -PfxPath | no | Your certificate as a PFX file, instead of Key Vault. | |
| -PfxPassword | no | The PFX password (a SecureString). | |
| -Dns | no | Auto | Auto (private environment: private DNS zone; public: print the public records), PrivateDnsZone, AdDns (print the record for your DNS administrator; PIM writes no AD DNS) or None (no DNS step; a public environment still needs -PublicDnsReady). |
| -PrivateDnsResourceGroup | no | the PIM resource group | Where your existing private DNS zone lives (for example the hub's DNS resource group). The longest zone there that the name ends with is used. |
| -LinkVnetIds | no | none | Resource ids of the virtual networks whose clients must resolve the name. Each is linked to the zone unless it is already linked (under any link name). |
| -DnsZone | no | AdDns: the name minus its first label; PrivateDnsZone: the longest existing zone | The DNS zone the name lives in, when the default is wrong (e.g. pim-manager.corp.contoso.local in zone contoso.local). |
| -AdDnsServer | no | -Dns AdDns: only fills the DNS server name into the printed lines. PIM never connects to it. | |
| -PublicDnsReady | no | false | Public environment (-Dns Auto or None): the CNAME and TXT records exist, so the name can be validated and bound. Without it the script stops after printing them. |
| -SkipEasyAuth | no | false | Do not add (or remove) the reply URL in the sign-in app registration. |
| -Remove | no | false | Take the name off: remove the binding and the certificate the script uploaded for it, the name from PIM_MANAGER_HOSTNAMES and the reply URL. Prints the DNS record to delete; PIM deletes no DNS and never a zone. |
Preview with -WhatIf
Reads the Manager app and its environment (and the private DNS zones), prints the plan (certificate type, DNS mode and every DNS record), then 'What if: Performing the operation "custom host name <name>" on target "ca-pim-manager"' and 'preview only -- nothing was changed'. Nothing is written. With -Remove the removal is previewed the same way.
Undo
Run the script again with -Remove: it removes the custom domain from the Manager app, deletes its certificate from the environment (when unused), removes the name from PIM_MANAGER_HOSTNAMES and the reply URL from the sign-in app registration, and prints the DNS record for you to delete.
Network
It connects to: login.microsoftonline.com (sign-in), management.azure.com, graph.microsoft.com (the reply URL), <vault>.vault.azure.net (only with a Key Vault certificate)
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