Deploy-PimRfaBroker
Deploy the access-request (RFA) broker
Part of the PIM Manager release - not a standalone download; it runs via the product's own install command or the updater.
Purpose
Deploys the public access-request (RFA) broker of PIM Manager Pro: its storage account and tables, its network, its Container Apps environment and app, the storage rights and Easy Auth; with the inputs given it also registers the API audience, the broker's mail sender and PIM's RFA settings. Plan only unless -Apply.
When to run it
After the main installation, when the access-request portal (Pro add-on) is wanted. The broker is always public by design (an internal environment is refused); -ApiAllowedIps restricts it to known systems. Placement Shared puts it in its own subnet of the PIM VNet; Island in its own subscription. 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\Deploy-PimRfaBroker.ps1). When the store's SQL server is private, run it from inside the network so the settings step can reach it.
Who may run it
| Kind | Role | Scope | Why |
|---|---|---|---|
| azureRbac | Owner (or Contributor + User Access Administrator) | the PIM resource group (Shared) or the RFA subscription (Island) | Creates the storage account, tables, NSG, subnet, Container Apps environment, Log Analytics workspace and app, and assigns Storage Table Data Contributor on the storage account. |
| azureRbac | Network Contributor | the PIM VNet (Shared placement) | Adds the broker's subnet (delegated to Microsoft.App/environments) and its NSG. |
| entraRole | Application Administrator | the tenant (only with -TenantId: the API audience follow-up) | Set-PimRfaBrokerApiAuth.ps1 registers the 'PIM access request API' app so Entra application tokens are accepted. |
| other | Admin application with Exchange.ManageAsApp (-AdminAppId + -AdminCertThumbprint), only for the mail follow-up | Exchange Online (the sender mailbox only) | Initialize-PimMailSender.ps1 scopes the broker identity's send right to the sender mailbox; Exchange RBAC needs an application identity. Without it the step is printed as NEXT. |
| other | Member of the environment's SQL admin group (grp-pim-sql-admins) via -UseSignedInAccount, or the admin application | the environment's SQL database (only with -SqlServerFqdn: the settings follow-up) | Writes pim.Settings RfaSettings and switches the rfa.portal and api.broker feature gates on. |
What it changes
| Where | Action | What | Permission / role | Scope | Why | Undo |
|---|---|---|---|---|---|---|
| Azure (PIM resource group or RFA subscription) | create | storage account (Tables; shared-key access disabled, TLS 1.2, no public blob) and the RFA tables | the broker's resource group | The broker's only data store: requests, reviews, PINs, API keys. | Delete the storage account. | |
| Azure network | create | NSG nsg-<app> (deny to the PIM subnets) and the broker subnet delegated to Microsoft.App/environments (Shared), or its own VNet (Island) | the PIM VNet or the RFA subscription | The broker is isolated from PIM's own subnets. | Delete the subnet and the NSG (Island: the VNet). | |
| Azure Container Apps | create | the public Container Apps environment (with a Log Analytics workspace beside it) and the container app ca-pim-rfa with a system-assigned identity | the broker's resource group | Runs the broker (the PIM image, scale to zero by default). | Delete the container app, the environment and the workspace. | |
| Azure RBAC | grant | the broker app's identity and each engine identity (-EngineIdentityPrincipalIds) | Storage Table Data Contributor | the broker's storage account only | The broker writes requests; the engine pulls them. It is the broker's ONLY Azure right. | Remove the role assignments. |
| Container app | update | Easy Auth (Entra provider, unauthenticated = allow) and, with -ApiAllowedIps, the ingress allow-list | the broker app | The portal is PIN-based; /api/v1 needs a validated token or an API key. The allow-list makes the whole broker non-public. | Disable Easy Auth / remove the ingress rules. | |
| Microsoft Entra ID (only with -TenantId) | create | the 'PIM access request API' app registration (Set-PimRfaBrokerApiAuth.ps1) | the tenant | So Entra application tokens are accepted on the API. | Delete the app registration. | |
| Exchange Online (only with the admin application) | grant | the broker identity | send as the sender mailbox only (Exchange-scoped application RBAC, Initialize-PimMailSender.ps1) | the sender mailbox | The broker mails PINs and decisions. | Remove the management role assignment and scope (see Initialize-PimMailSender). |
| Environment SQL database (only with -SqlServerFqdn) | update | pim.Settings RfaSettings (store + portal URL, existing API app ids kept) and FeatureGates (rfa.portal + api.broker ON) | this environment | Tells PIM where the broker is; read back. | Manager > Settings > RFA broker & API: clear the store, and switch the two gates off. |
What it only reads
- the storage account, VNet, NSG, subnet, Container Apps environment and app (each step creates only what is missing)
- the existing role assignments on the storage account
- pim.Settings RfaSettings and FeatureGates (settings follow-up, before writing)
Parameters
| Parameter | Required | Default | What it does |
|---|---|---|---|
| -SubscriptionId | yes | The PIM subscription (GUID). | |
| -ResourceGroup | yes | The PIM resource group. | |
| -Placement | no | Shared | Shared (own subnet in the PIM VNet) or Island (own subscription, own VNet, not peered). |
| -RfaSubscriptionId | no | Island: the broker's own subscription (must differ from PIM's). | |
| -RfaResourceGroup | no | rg-pim-rfa | Island: the broker's resource group. |
| -Location | no | westeurope | The Azure region. |
| -VnetName | no | Shared: the PIM VNet (the broker gets its own subnet there). Island: its own VNet (default vnet-pim-rfa). | |
| -SubnetName | no | snet-pim-rfa | The broker subnet's name. |
| -SubnetPrefix | no | The broker subnet, an IPv4 CIDR of /27 or larger. | |
| -PimSubnetPrefixes | no | none | Shared: the PIM subnet prefixes the broker subnet's NSG denies traffic to. |
| -StorageAccountName | yes | The broker's storage account (3-24 lower-case letters / digits). | |
| -EnvironmentName | no | cae-pim-rfa | The broker's Container Apps environment. |
| -AppName | no | ca-pim-rfa | The broker's container app. |
| -Image | yes | The PIM Manager image (same as the jobs), e.g. <registry>.azurecr.io/pim-manager@sha256:<digest>. | |
| -AcrName | no | The registry name, pulled with the app's system identity. | |
| -SenderMailbox | yes | The PIM mail sender the broker sends as. | |
| -TenantName | no | The tenant name shown on the portal. | |
| -EngineIdentityPrincipalIds | yes | The engine (tick job) managed identity object id(s): they pull the requests from the store. | |
| -ApiAllowedIps | no | none | Allow ingress only from these IPv4 addresses / CIDRs (the API-only shape: the portal is then not public). |
| -MinReplicas | no | 0 | 0 (scale to zero) .. 2; 1 keeps one warm. |
| -ExistingEnvironmentName | no | Shared only: join an existing PUBLIC Container Apps environment instead of building one. | |
| -TenantId | no | Pins the sign-in to the PIM tenant; also runs the API audience follow-up. | |
| -ApiAppDisplayName | no | PIM access request API | The API app registration's name. |
| -AzureConfigDir | no | Ignored (the script no longer uses the Azure CLI); kept so older command lines still run. | |
| -AdminAppId | no | Admin application (client) id for the mail and settings follow-ups (with -AdminCertThumbprint). | |
| -AdminCertThumbprint | no | Thumbprint of the admin application's certificate in the local machine store. | |
| -UseSignedInAccount | no | false | The settings follow-up writes the store as the signed-in person (a member of the SQL admin group). |
| -SqlServerFqdn | no | The store's SQL server: runs the settings follow-up. | |
| -SqlDatabase | no | PimPlatform | The database. |
| -Apply | no | false | Run the steps. Without it the plan is printed only. |
Preview with -WhatIf
Validates the inputs and prints 'What if: Performing the operation "deploy <n> step(s)" on target "<placement> RFA broker in <resource group>"' and the numbered plan ('RFA broker deploy -- placement <p> -- PLAN ONLY'). -WhatIf wins over -Apply; no step runs and nothing is signed in to.
Undo
Delete the broker's container app, Container Apps environment, Log Analytics workspace, storage account, subnet and NSG (Island: the resource group), the 'PIM access request API' app registration and the broker's Exchange send scope; clear RfaSettings and switch rfa.portal / api.broker off in the Manager.
Network
It connects to: login.microsoftonline.com (sign-in), management.azure.com, graph.microsoft.com (API audience follow-up), outlook.office365.com (mail follow-up, Exchange admin API), <server>.database.windows.net:1433 (settings follow-up)
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