Purpose
The purpose of this article is to provide a safe, ordered process for moving an existing PowerShell Universal OpenID Connect sign-in from one Microsoft Entra tenant to another without rebuilding the PowerShell Universal server.
Scope
This article applies when all of the following are true:
- PowerShell Universal is already using Microsoft Entra ID (Azure AD) with OpenID Connect.
- The existing PowerShell Universal server is staying in place.
- The public URL and callback path are expected to remain the same.
- A new app registration or enterprise application exists, or will be created, in the target tenant.
- The change needs a rollback path.
This article does not cover SAML2, Windows Authentication, or a full host migration.
Scenario
You have a working PowerShell Universal instance that already signs users in through OpenID Connect against a source Microsoft Entra tenant. Users are moving to a target tenant, but the PowerShell Universal server is staying in place.
In this situation, PowerShell Universal usually does not need to be rebuilt. The main change is the tenant-owned OpenID Connect configuration.
One common source of confusion is that the active OpenID Connect configuration may be managed in Security -> Authentication or in a repository-backed authentication.ps1 file, while appsettings.json is only handling hosting, Kestrel, or database settings.
The following usually stay the same:
- PowerShell Universal server and install
- Public URL
- Redirect URI
- Callback path such as /auth/signin-oidc
- Basic OpenID Connect flow such as response type code
The following usually change:
- Authority
- Client ID
- Client Secret
- Target-tenant assignment or consent posture
- Group claims, app roles, or claim mappings
- Any tenant-specific group or object IDs used in PowerShell Universal role mappings
Checklist
1. Back up the current working configuration.
Record the current provider settings before changing anything. If the instance is repository-backed, also back up the active authentication file such as C:\ProgramData\UniversalAutomation\Repository\.universal\authentication.ps1.
2. Confirm where the active OpenID Connect settings are coming from.
Do not assume appsettings.json is the active source. If the OpenID Connect block in appsettings.json is blank or disabled, but Security -> Authentication shows a live provider treat the provider or authentication.ps1 as the source of truth.
3. Keep the stable PowerShell Universal surface unchanged.
Unless the migration also includes a host or URL move, keep the same public URL, redirect URI, and callback path.
4. Prepare the target-tenant values first.
Collect the target tenant authority URL, client ID, client secret, redirect URI, scope set, assignment or consent posture, and at least one target-tenant validation user.
5. Update the tenant-specific values together.
Replace Authority, Client ID, and Client Secret as one change set. If your configuration also includes tenant-specific metadata or resource values, review those at the same time.
6. Test authentication first.
Sign in with a target-tenant user who should have administrative access. Confirm the sign-in page redirects to the target tenant and that the user reaches the PowerShell Universal portal.
7. Test authorization second.
A successful sign-in does not prove that roles and access are correct. Review Security -> Identities, Security -> Roles, and any repository-backed role files such as roles.ps1. If the environment uses Azure app roles, group claims, or claim-based PowerShell Universal roles, those mappings may need to be recreated or remapped for the target tenant.
8. Replace any tenant-specific mappings.
Source-tenant group object IDs, app-role assignments, and claim values do not automatically carry over to the target tenant. Replace them with target-tenant equivalents before declaring the cutover complete.
9. Keep rollback simple.
If the new tenant does not work, restore the previous Authority, Client ID, and Client Secret in the same configuration surface and test the old sign-in path again.
Post-Migration Checklist
- The login page points to the target tenant.
- The redirect URI still exactly matches the existing public URL and callback path.
- The target validation user reaches the PowerShell Universal portal.
- The resolved PowerShell Universal identity is what you expect.
- Required roles, apps, APIs, or endpoints behave correctly.
- No active role mappings still reference source-tenant group or object IDs.
Conclusion
A tenant-to-tenant OpenID Connect move in PowerShell Universal is usually a controlled identity-provider change, not a PowerShell Universal rebuild.
Keep the host URL and callback path stable, update the tenant-specific OpenID Connect values together, then validate sign-in and authorization separately. If the new tenant fails, restore the previous values in the same configuration surface.