Moving an application from SAML 2.0 to OpenID Connect looks like a protocol swap, but most failed migrations break on identifiers, claims and logout rather than on the protocol itself. Teams modernise for good reasons: native and mobile clients, API access through OAuth 2.0 access tokens, simpler JSON tooling and libraries that are better maintained than many XML signature stacks. This guide is the migration runbook: how to inventory federated applications, map SAML attributes to OIDC claims without creating duplicate accounts, run both protocols side by side, handle the differences in single logout, and test and roll back safely. It is written for identity engineers and application owners. The protocol comparison itself is in the SAML vs OIDC Guide and is not repeated here.
Key takeaways
- SAML is not being retired. No standards body has withdrawn SAML 2.0; this is a modernisation decision you schedule, so prioritise by risk and value rather than by a vendor deadline.
- The identifier is the migration. Decide how the old SAML NameID maps to the new OIDC subject before anything else; the issuer plus subject pair must link to the existing account, or users get duplicate or orphaned profiles.
- Never key accounts on email or display names. OIDC and Microsoft documentation both treat human readable claims as mutable; use the immutable subject or object identifier and keep email for display.
- Logout works differently. SAML Single Logout uses SessionIndex and LogoutRequest messages; OIDC uses RP-Initiated, Front-Channel or Back-Channel Logout with a sid claim, so session termination must be re-tested, not assumed.
- Dual running is the rollback plan. Keep the SAML trust live but monitored during the overlap, cut over by user group, then remove the SAML application, certificate and metadata so the old path cannot be abused.
What is changing and why
In a SAML integration the identity provider (IdP) sends a signed XML assertion to the service provider (SP), usually through a browser POST to an Assertion Consumer Service URL. In an OIDC integration the relying party (RP) runs the OAuth 2.0 authorisation code flow and receives a signed JSON Web Token, the ID Token, from the OpenID Provider (OP), plus optional access and refresh tokens. The migration replaces the SP trust (entity ID, ACS URL, signing certificate, attribute statements) with an OIDC client registration (client ID, redirect URIs, client authentication method, scopes and claims).
The reasons organisations give for migrating usually fall into four groups:
- Clients: SAML was designed around browser redirects; native, mobile and single page applications fit the OIDC and OAuth model, where the same sign-in also yields tokens for APIs.
- Library risk: SAML relies on XML Signature validation, and signature wrapping and canonicalisation bugs have been a recurring class of SP vulnerabilities. See the SAML Security Guide.
- Current guidance: RFC 9700, the OAuth 2.0 Security Best Current Practice (BCP 240, January 2025), gives a clear, modern baseline: PKCE, no implicit grant, exact redirect URI matching.
- Platform consolidation: retiring an on-premises federation server often triggers the work. The AD FS to Entra ID Migration covers moving the IdP; this guide covers changing the protocol an application speaks.
Official timeline and current status
There is no official end date for SAML. The table records the status of each specification involved, as published by the standards body and checked on 8 November 2026.
| Specification | Publisher | Status as published | What it means for the migration |
|---|---|---|---|
| SAML 2.0 Core | OASIS Security Services TC | OASIS Standard, 15 March 2005 | Still a current standard; existing SPs keep working |
| OpenID Connect Core 1.0 | OpenID Foundation | Final, incorporating errata set 2 (15 December 2023) | The target protocol; ID Token claims and subject rules come from here |
| OpenID Connect Back-Channel Logout 1.0 | OpenID Foundation | Final, incorporating errata set 1 (15 December 2023) | Server to server logout; replaces SAML SLO back channel bindings |
| OpenID Connect Front-Channel Logout 1.0 | OpenID Foundation | Separate specification | Browser based logout notification; affected by third party cookie blocking |
| RFC 9700, OAuth 2.0 Security BCP | IETF | Best Current Practice (BCP 240), January 2025 | Security baseline for every new OIDC client |
| NIST SP 800-63C-4 | NIST | Final, July 2025; current federation guideline (FAL1 to FAL3) | Defines assertion strength; applies equally to SAML assertions and ID Tokens |
Your real deadlines come from elsewhere: IdP signing certificate expiry dates, end of support for a federation server or SAML library, or an application vendor dropping SAML from a product edition. Record those per application in the inventory.
Who and what is affected
- Application owners: code or configuration changes at every SP. Commercial SaaS can only move if the vendor supports OIDC; check the vendor's documentation before planning.
- Identity engineers: new client registrations, claims configuration, Conditional Access or sign-on policy assignments that were scoped to the SAML application object.
- End users: possible re-consent prompts, a changed sign-in URL, and lost bookmarks if IdP-initiated SSO links pointed at the SAML endpoint.
- Provisioning: SCIM connectors and just-in-time provisioning rules often match on the SAML NameID; they must match on the new identifier too. See the SCIM Provisioning Guide.
- Machine identities: the OIDC client is itself a non-human identity with a credential (client secret, certificate or private key JWT) that needs an owner, rotation and monitoring.
- Audit and SOC: sign-in events move to a new application record, so detections, dashboards and access reviews built on the SAML app need updating.
Finding affected systems and identities
Build the inventory from the IdP outwards, then confirm with the application side.
- Export federated applications: list every SAML SP trust in the IdP with entity ID, ACS URLs, NameID format, signing certificate thumbprint and expiry, whether IdP-initiated SSO is enabled, and assigned users or groups.
- Record attribute statements: for each SP, the exact attribute names (often URIs such as the claims namespace URIs) and source fields. These become your claim map.
- Pull usage from sign-in logs: 30 to 90 days of sign-ins per application identifies dead integrations to decommission rather than migrate.
- Classify the NameID: persistent, transient, emailAddress or unspecified. An unspecified or email NameID usually means the application keys accounts on email, which is the highest migration risk.
- Check the application library: which SAML and OIDC libraries or vendor features the SP supports, and whether it supports PKCE, back-channel logout and private key JWT client authentication.
- Capture dependencies: access policies, MFA requirements, session lifetimes and provisioning connectors attached to the SAML application object.
| Inventory finding | Migration priority | Reason |
|---|---|---|
| No sign-ins in 90 days | Decommission | Removing the trust is cheaper and safer than migrating it |
| Needs API or native client access | High | OIDC plus OAuth delivers the tokens the app needs |
| Custom or unmaintained SAML library | High | Signature validation flaws are the main SAML SP risk |
| Well maintained SaaS with SAML only | Low or leave | Migration depends on the vendor; harden the SAML trust instead |
| Email or unspecified NameID | Plan carefully | Account linking must be designed before cutover |
Migration options
Mapping attributes to claims
OIDC Core defines the ID Token required claims as iss, sub, aud, exp and iat, with nonce required when the request carried one, and auth_time, acr and amr available for authentication context. The sub claim is defined as locally unique and never reassigned within the issuer, at most 255 ASCII characters and case sensitive. NIST SP 800-63C-4 adds that a subject identifier must never be processed without its issuer.
| SAML element | OIDC equivalent | Migration note |
|---|---|---|
| Issuer (IdP entity ID) | iss | Validate exactly against the discovery document value |
| NameID (persistent) | sub | Values usually differ; store a link table from old NameID to new iss plus sub |
| Audience restriction (SP entity ID) | aud (client ID) | Reject tokens whose aud is not your client ID |
| NotOnOrAfter, IssueInstant | exp, iat | Keep clock skew tolerance small |
| AuthnContextClassRef | acr, amr | Re-map any logic that required MFA from the assertion |
| Attribute statements (mail, givenname, groups) | email, given_name, groups or roles claims | Request only what the app uses; large group lists may need a separate lookup |
| SessionIndex | sid | Needed for per session logout |
| InResponseTo | state and nonce | Both must be generated per request and checked |
A concrete trap in Microsoft Entra ID: the sub claim is a pairwise identifier unique to each application ID, so two client registrations for the same user receive different sub values, while the oid claim is the same across applications in a tenant. Microsoft's ID token claims reference says applications must not use human readable data such as preferred_username, email or UPN to identify a user, because those values are mutable. If the SAML app keyed accounts on email, match once on a verified attribute during a supervised linking step, store oid or sub, and stop matching on email afterwards.
Choosing a cutover pattern
| Pattern | When to choose it | Trade-off |
|---|---|---|
| Dual protocol with a second login route | In-house apps where you control the code | Two code paths to secure for a period; best rollback |
| Vendor switch in SaaS settings | SaaS that supports both protocols | Often all-or-nothing per tenant; test in a sandbox tenant first |
| Identity proxy or gateway translation | Legacy apps that cannot change | Adds a component that holds credentials and must be hardened |
| Stay on SAML, harden | Stable SaaS without OIDC support | No modernisation, but lowest change risk |
Small organisations with a handful of SaaS apps usually do vendor switches one at a time. Large estates should run a factory: a standard claim map, a client registration template with PKCE, S256 and exact redirect URIs, private key JWT or certificate client authentication instead of shared secrets, and a fixed test pack per app. See the OAuth 2.0 and OpenID Connect Guide for the flows and the Azure Entra Client Secrets Security Guide for credential choices.
Logout differences
SAML Single Logout sends LogoutRequest messages tied to the SessionIndex from the original AuthnStatement. OIDC splits logout into separate specifications. RP-Initiated Logout sends the user to the OP's end_session_endpoint. Front-Channel Logout has the OP load each RP's logout URL in the browser; Microsoft Entra ID sends an HTTP GET to each signed-in app's front-channel logout URL and expects a 200 response. Back-Channel Logout has the OP POST a signed logout_token directly to the RP; the token must carry sub, sid or both, must contain the back-channel logout event, must not contain a nonce, and the RP answers 200 on success or 400 on failure. Microsoft also notes that signing out takes two steps, redirecting to the logout endpoint and clearing the application's own session cookies, and skipping either can leave the user signed in. Detail is in the OpenID Connect Logout and Session Management Guide.
Testing and rollback
- Register in parallel: create the OIDC client next to the existing SAML application, with the same user and group assignment and the same access policies. Do not delete or edit the SAML trust.
- Validate tokens with a library: signature against the JWKS from discovery, iss, aud, exp, nonce and state. Test negative cases: wrong audience, expired token, replayed code, mismatched redirect URI.
- Test identity linking: sign in with test accounts that have a renamed UPN, a changed email, a guest account and a disabled account, and confirm each lands on the right existing profile or is refused.
- Test policy parity: MFA, device and location policies must fire for the new client exactly as for the SAML app; compare sign-in log entries side by side.
- Test logout: single application logout, logout from another app, and session expiry. Confirm the server side session ends, not only the cookie.
- Pilot by group: move a small group via the new login route, then expand in rings; watch error rates and help desk tickets.
- Roll back by switching routes: because the SAML trust stays live, rollback is a configuration change at the app. Define the rollback trigger (for example sign-in failure rate above an agreed threshold) before the pilot.
- Decommission: after the agreed overlap with no SAML sign-ins, disable then delete the SAML application, remove its signing certificate from the SP and any metadata URLs, and update provisioning rules.
Risks of doing nothing
- Forgeable assertions: SAML trust depends on a signing key. In the SolarWinds SUNBURST and Golden SAML compromise, attackers who reached on-premises admin rights stole the token-signing certificate and signed their own tokens, logging in to federated services without passwords or MFA (ATT&CK T1606.002). See the Golden SAML and Federation Trust Abuse Defence Guide.
- Library decay: unmaintained SAML libraries stay exposed to signature validation flaws long after fixes ship elsewhere.
- Abandoned trusts: an unused SAML SP still accepts assertions; an inventory you never act on leaves trusts nobody monitors.
- Migration risks of its own: doing it badly is also a risk. OIDC clients carry secrets, and an over-broad API key can expose them, which is why private key JWT or certificate client authentication beats a shared secret.
Detection and measurement
- Log: new or changed client registrations, redirect URI changes, new client credentials, claim mapping changes, and any sign-in still hitting the SAML app after cutover.
- Correlate: application sign-ins with no matching IdP authentication event remain a forged token signal for both protocols.
- KPI 1: share of in-scope applications on OIDC with PKCE (S256).
- KPI 2: duplicate accounts created during migration (target zero).
- KPI 3: OIDC clients using shared secrets rather than certificate or private key JWT authentication.
- KPI 4: SAML trusts with no sign-ins for 30 days after cutover that are still enabled (target zero).
- KPI 5: logout test pass rate per application.
Framework mapping
| Framework | Reference | Relevance |
|---|---|---|
| NIST SP 800-53 Rev. 5 | IA-2, IA-8 | Federated identification and authentication of users |
| NIST SP 800-53 Rev. 5 | IA-5 | Client credentials and signing keys as authenticators |
| NIST SP 800-53 Rev. 5 | AC-12, SC-23 | Session termination and session authenticity across logout changes |
| NIST SP 800-53 Rev. 5 | CM-8 | Inventory of federated applications |
| NIST CSF 2.0 | PR.AA-01, PR.AA-03 | Identity management and authentication |
| MITRE ATT&CK | T1606.002 SAML Tokens | The forged assertion risk that motivates removing unused trusts |
Practitioner checklist
- Export every SAML trust with NameID format, certificate expiry and 90 day usage; decommission the unused ones first.
- Write the attribute to claim map per application and agree the stable identifier (sub or oid plus iss) before building.
- Register OIDC clients with authorisation code flow, PKCE S256, exact redirect URIs and no implicit grant.
- Use certificate or private key JWT client authentication and give each client an owner and rotation date.
- Copy access policies and MFA requirements to the new client and verify parity in sign-in logs.
- Test account linking with renamed, guest and disabled users; never match on email after the linking step.
- Re-implement logout with back-channel or front-channel logout and test server side session termination.
- Keep the SAML trust as the rollback route, with a written rollback trigger, then delete it and its certificate after the overlap.
- Update SCIM matching rules, detections and access reviews to the new application record.
Standards and references
- OpenID Foundation: OpenID Connect Core 1.0
- OpenID Foundation: OpenID Connect Back-Channel Logout 1.0
- OASIS: Assertions and Protocols for the OASIS Security Assertion Markup Language (SAML) V2.0
- IETF: RFC 9700 Best Current Practice for OAuth 2.0 Security
- NIST: SP 800-63C-4 Digital Identity Guidelines, Federation and Assertions
- Microsoft Learn: OpenID Connect on the Microsoft identity platform
- Microsoft Learn: ID token claims reference
- MITRE ATT&CK: Forge Web Credentials, SAML Tokens
Related NHI Mgmt Group resources: SAML vs OIDC Guide · AD FS to Entra ID Migration · OpenID Connect Logout and Session Management Guide · Golden SAML and Federation Trust Abuse Defence Guide