Give PIM Manager your own address (custom host name)

Written by the PIM Manager team for PIM Manager 2.4.576 · 2026-10-10

Every PIM Manager gets a generated address from Azure Container Apps, for example ca-pim-manager.<generated-name>.<region>.azurecontainerapps.io. This guide gives it a second address in your own domain, for example pim-manager.contoso.com or pim-manager.corp.contoso.local.

One script does it: Set-PimManagerCustomHost.ps1. What it does depends on how your environment was built:

A public environment cannot use a private-only name. Azure proves you own the name by looking it up in public DNS before it issues the certificate. A name such as pim-manager.corp.contoso.local can never pass that check, so the script refuses it on a public environment (it refuses names ending in .local, .lan, .internal, .intranet, .corp, .home, .localdomain and .private). For a public environment, use a public subdomain you own, or keep the generated address. A private name needs a private (internal) environment; see Install in private mode.

What you get

• The PIM Manager answers on your name, with a certificate for that name.
• The generated address keeps working. The script adds the name; it does not remove or change the generated one.
• Sign-in works on the new name: the script adds https://<your name>/.auth/login/aad/callback to the reply URLs of the PIM Manager’s sign-in app registration.
• The name is added to the PIM Manager’s list of known host names (PIM_MANAGER_HOSTNAMES). Links in notification mail then use your name. See Mail links for when that switch happens.
• A stable address. The generated address changes if the environment is ever rebuilt; your name does not (you re-run this script after a rebuild, see After an environment rebuild).

What this guide does not cover

• The access request portal (the RFA broker, ca-pim-rfa) runs as its own app with its own generated address. This script does not give it a custom name, and no other PIM script does today. Not yet automated.
• The MCP endpoint (/mcp) is served by the PIM Manager itself, so it is reached on the new name too (https://pim-manager.contoso.com/mcp). It needs no extra step: its token check is tied to the app registration, not to the host name.

Prerequisites

No Azure CLI and no PowerShell modules. Every call is a REST call to Azure Resource Manager, Microsoft Graph and (for a Key Vault certificate) the vault. The script signs in in the browser to one tenant, the one you pass in -TenantId, and refuses to continue if the session belongs to any other tenant. If Invardia support runs it for you, it uses your tenant’s Invardia Support app session instead.

Run it from the release package folder that Install-Invardia (or the guided install) downloaded and verified: .\tools\setup\Set-PimManagerCustomHost.ps1. It loads the engine libraries next to it, so it does not work as a single downloaded file. Its documentation page is https://invardia.com/docs/pim/scripts/Set-PimManagerCustomHost/.

Rights

Who runs what

Step 0: Decide and collect

How the zone is chosen.

• Azure Private DNS zone: the script lists the private DNS zones in -PrivateDnsResourceGroup and uses the longest one your name ends with. The rest of the name is the record. With only contoso.local there, pim-manager.corp.contoso.local becomes record pim-manager.corp in contoso.local. If corp.contoso.local exists too, it wins and the record is pim-manager.
• AD DNS: the script cannot see your AD zones. It assumes the name minus its first label (corp.contoso.local), says so in the output, and tells you to pass -DnsZone contoso.local when your zone is a different parent.
• -DnsZone sets the zone explicitly in both modes. It must be a parent of the name.

Private (internal) environment

Step 1: Put the certificate in place (PKI administrator)

Issue a certificate whose subject or SAN is your name (or a wildcard covering it), with its private key.

• Key Vault: import it as a certificate, PFX (PKCS #12) or PEM. The script reads the certificate’s secret: a PFX is uploaded as it is, a PEM is converted to PFX in memory (this needs PowerShell 7; Windows PowerShell 5.1 stops with a message). Give the account running the script Key Vault Secrets User on the vault, and make sure the machine running the script can reach the vault (vault firewall or private endpoint).
• PFX file: copy it to the machine running the script. You pass the password as a SecureString.

Make sure the admin devices that will open the PIM Manager trust the issuing CA.

Step 2a: DNS with an Azure Private DNS zone (-Dns Auto or PrivateDnsZone)

The script writes the A record only into a zone that already exists in -PrivateDnsResourceGroup (default: the PIM resource group): the longest zone there that your name ends with, or -DnsZone (see How the zone is chosen). PIM never creates a zone named after your domain. A private zone corp.contoso.local linked to a VNet answers for every name in corp.contoso.local on that VNet, so your other names in that domain would stop resolving there. Create it only if no other DNS serves that domain for those networks.

If no zone fits, the plan (Step 3) prints what to create (shown here for the name minus its first label), and the real run binds the name but writes no DNS:

PIM did NOT create the Azure Private DNS zone 'corp.contoso.local' (it does not exist in resource group 'rg-dns').
  A private zone named after your domain answers for EVERY name in corp.contoso.local on each VNet linked to it -- create it
  only if no other DNS serves corp.contoso.local for those VNets. Otherwise add A pim-manager.corp.contoso.local -> 10.50.0.x in the DNS that does.
  To use a private zone: create zone 'corp.contoso.local' (or any parent zone of the name) in 'rg-dns', then re-run this
  script -- it picks the longest existing zone the name ends with (or -DnsZone) and adds:
    A     pim-manager.corp.contoso.local -> 10.50.0.x
    link  corp.contoso.local -> <vnet id> (registration off)
  then check (expect 10.50.0.x): Resolve-DnsName pim-manager.corp.contoso.local -Type A

When the zone exists, the script:

• writes the A record (pim-manager in corp.contoso.local, or pim-manager.corp in contoso.local) → the environment’s static private IP. It reads the record first and writes it only when it is not already exactly that one address. The record set is written whole, so any other address on that record is replaced.
• links the zone to each VNet in -LinkVnetIds that is not linked to it yet, with auto-registration off. A VNet that is already linked under any link name is left alone. New links are named link-<vnet name>.

Include every network whose clients must resolve the name: usually the hub (where your DNS resolver lives) and the PIM VNet. If your on-premises DNS forwards to an Azure DNS Private Resolver, add a conditional forwarder for the zone too.

Step 2b: DNS with Active Directory DNS (-Dns AdDns)

PIM writes nothing to your AD DNS and needs no DNS Server tools (RSAT). It prints, before anything is changed and also under -WhatIf:

• the one A record to add: pim-manager.corp.contoso.local → the environment’s static IP, in your existing zone (PIM creates no zone and never adds a wildcard). Without -DnsZone the script assumes the zone corp.contoso.local and prints a line saying so; if your zone is contoso.local, re-run with -DnsZone contoso.local and the record becomes pim-manager.corp in contoso.local;
• a ready-to-paste Add-DnsServerResourceRecordA line and a dnscmd line (with your server name if you passed -AdDnsServer);
• the check to run afterwards: Resolve-DnsName pim-manager.corp.contoso.local -Type A, expecting the static IP.

Your DNS administrator adds that record. The script still binds the name and updates the PIM Manager; only the DNS step is yours.

Step 3: Plan (changes nothing)

Key Vault certificate, Azure Private DNS zone in the hub’s DNS resource group:

$hub = '/subscriptions/<hub-subscription-id>/resourceGroups/rg-connectivity/providers/Microsoft.Network/virtualNetworks/vnet-hub'
$pim = '/subscriptions/<subscription-id>/resourceGroups/rg-pim/providers/Microsoft.Network/virtualNetworks/vnet-pim'
.\tools\setup\Set-PimManagerCustomHost.ps1 -SubscriptionId <subscription-id> -TenantId <tenant-id> -ResourceGroup rg-pim `
    -HostName pim-manager.corp.contoso.local -KeyVaultName kv-pim-contoso -KeyVaultCertName pim-manager-corp-contoso-local `
    -Dns PrivateDnsZone -PrivateDnsResourceGroup rg-dns -LinkVnetIds $hub,$pim -WhatIf

PFX file and AD DNS instead:

$pw = Read-Host 'PFX password' -AsSecureString
.\tools\setup\Set-PimManagerCustomHost.ps1 -SubscriptionId <subscription-id> -TenantId <tenant-id> -ResourceGroup rg-pim `
    -HostName pim-manager.corp.contoso.local -PfxPath .\pim-manager.pfx -PfxPassword $pw `
    -Dns AdDns -AdDnsServer dc01.corp.contoso.local -WhatIf

The plan reads the PIM Manager app and its environment, then prints:

• one line such as custom name pim-manager.corp.contoso.local on a private environment: certificate = keyvault, DNS = privatezone;
• the DNS record: DNS A pim-manager.corp.contoso.local -> 10.50.0.x;
• whether the private zone exists (and, if not, what to create), or the AD DNS lines;
• What if: Performing the operation "custom host name ..." on target "ca-pim-manager" and preview only -- nothing was changed.

Refusals you may see in the plan, and what they mean:

Step 4: Apply

Run the same command without -WhatIf. In order:

1. adds the name to the PIM Manager app (if it is not there yet);
2. uploads your certificate to the Container Apps environment, under a name derived from the host name (pim-manager-corp-contoso-local), and binds the name to it (SNI);
3. writes the private DNS record and links (Step 2a), or reminds you that PIM wrote nothing to AD DNS (Step 2b);
4. adds the name to PIM_MANAGER_HOSTNAMES on the PIM Manager. This creates a new revision, so the PIM Manager restarts once;
5. adds https://pim-manager.corp.contoso.local/.auth/login/aad/callback to the sign-in app registration.

It ends with == done: https://pim-manager.corp.contoso.local.

If the account cannot update the app registration, run with -SkipEasyAuth and ask an Entra administrator to add the reply URL above to the PIM Manager’s sign-in app registration (Authentication > Web > Redirect URIs). Until then, sign-in on the new name fails with a redirect-URI mismatch; the generated address still works.

Every step checks what exists first, so a failed run is fixed and re-run with the same command.

Public (external) environment

Step 1: Plan and get the records (changes nothing)

.\tools\setup\Set-PimManagerCustomHost.ps1 -SubscriptionId <subscription-id> -TenantId <tenant-id> -ResourceGroup rg-pim `
    -HostName pim-manager.contoso.com -WhatIf

No certificate parameters: on a public environment Azure issues a free managed certificate. The plan prints the two records for your public DNS:

  DNS  CNAME pim-manager.contoso.com -> ca-pim-manager.<generated-name>.<region>.azurecontainerapps.io
  DNS  TXT   asuid.pim-manager.contoso.com -> <verification id of the PIM Manager app>

The TXT record proves you own the name; the CNAME points the name at the PIM Manager. The verification id belongs to this app. If the app is ever recreated, it changes: take it from a fresh plan, never from an old note.

Running without -WhatIf and without -PublicDnsReady prints the same records and stops with Create the CNAME and TXT records above in your public DNS, then re-run with -PublicDnsReady. Nothing is changed.

Step 2: Create the records (DNS administrator)

In the public DNS zone contoso.com, create:

• CNAME pim-manager → the generated address shown in the plan;
• TXT asuid.pim-manager → the verification id shown in the plan.

Check from any machine that both resolve publicly before Step 3:

Resolve-DnsName pim-manager.contoso.com -Type CNAME
Resolve-DnsName asuid.pim-manager.contoso.com -Type TXT

Step 3: Apply

.\tools\setup\Set-PimManagerCustomHost.ps1 -SubscriptionId <subscription-id> -TenantId <tenant-id> -ResourceGroup rg-pim `
    -HostName pim-manager.contoso.com -PublicDnsReady

In order:

1. adds the name to the PIM Manager app;
2. requests the free managed certificate (CNAME validation) and waits for it, up to 20 minutes. If it does not issue, the run stops with are the CNAME and TXT (asuid) records in public DNS?; check the records and re-run;
3. binds the name to that certificate;
4. adds the name to PIM_MANAGER_HOSTNAMES (a new revision, one restart);
5. adds https://pim-manager.contoso.com/.auth/login/aad/callback to the sign-in app registration (or skip with -SkipEasyAuth, as in the private case).

Azure renews the managed certificate itself while the CNAME stays in place.

-Dns None on a public environment only means the plan prints no records for you. The free managed certificate still validates through public DNS, so the script still stops until you pass -PublicDnsReady, and names the CNAME and TXT records it needs.

Verify

From a machine that should reach the PIM Manager (inside your network for a private environment):

Resolve-DnsName pim-manager.corp.contoso.local -Type A          # private: the environment's static IP (10.50.0.x)
Resolve-DnsName pim-manager.contoso.com                         # public: CNAME to ...azurecontainerapps.io
Invoke-WebRequest https://pim-manager.contoso.com/ -MaximumRedirection 0 -SkipHttpErrorCheck |
    Select-Object StatusCode, @{n='Location';e={$_.Headers.Location}}   # 302 to login.microsoftonline.com -- never 200

Then:

1. Open https://<your name> in the browser. The certificate is valid for the name (no warning), and sign-in returns to the PIM Manager on your name.
2. Open the generated address. It still works.
3. Check the setting the PIM Manager uses for mail links (next section).

In the Azure portal you can also see the result: Container App ca-pim-manager > Custom domains shows the name as Secured, and Containers > Environment variables shows PIM_MANAGER_HOSTNAMES.

Mail links

Notification mail (from the engine, the scheduler and the PIM Manager) builds its Open in PIM Manager link from the setting ManagerUrl. The PIM Manager records it the first time a signed-in person opens it, when it is empty.

• If ManagerUrl was recorded automatically as the generated address, it is switched once to your name the next time someone signs in to the PIM Manager after this change (on any of its names).
• If someone set ManagerUrl by hand to another value, it is never overwritten. Change it yourself in the PIM Manager’s Settings.

The access request portal’s own link (RfaSettings.portalUrl) is not affected; see What this guide does not cover.

After an environment rebuild

A rebuild creates a new Container Apps environment and a new PIM Manager app, so the binding and the certificate in the environment are gone, and a private environment usually gets a new static IP. Run this script again with the same parameters. It rewrites the private DNS record to the new IP, re-uploads or re-requests the certificate, and re-adds the name and reply URL where they are missing. For a public environment, take the new verification id from a fresh plan and update the TXT record first. Rebuild-PimEnvExternal.ps1 also has a -CustomDomain parameter that binds a public name during the rebuild itself.

A normal re-deploy or nightly update does not remove the name: it updates the existing PIM Manager and keeps its custom domains, its environment variables and the existing reply URLs.

Change or remove the name

Re-running the script with a different -HostName adds a second name next to the first one; there is no rename.

To change the name: run the script for the new name (Steps above), check it works, then remove the old one as below.

To remove a name, run the script with -Remove (plan it first with -WhatIf):

.\tools\setup\Set-PimManagerCustomHost.ps1 -SubscriptionId <subscription-id> -TenantId <tenant-id> -ResourceGroup rg-pim `
    -HostName pim-manager.corp.contoso.local -Remove -WhatIf

Without -WhatIf it:

1. removes the name from the PIM Manager app (the other names stay);
2. deletes the certificate the script created for that name (pim-manager-corp-contoso-local) from the environment, only when no other name uses it. If Azure refuses because another app still binds it, the script warns and moves on;
3. removes the name from PIM_MANAGER_HOSTNAMES (a new revision);
4. removes https://<name>/.auth/login/aad/callback from the sign-in app registration (not with -SkipEasyAuth);
5. prints the DNS record(s) to delete. PIM deletes no DNS record and never a zone: your DNS administrator deletes them;
6. reminds you to check ManagerUrl in Settings (step 6 below).

By hand, if you cannot run the script, in this order:

Rollback