Migrate an app from AD FS to Microsoft Entra ID

Migrating one app from AD FS to Microsoft Entra ID means recreating its SAML relying party trust as an Entra enterprise application, then switching the application to trust Entra instead of AD FS. You export the trust, copy the identifier and reply URL into Basic SAML Configuration, rebuild claim rules under Attributes & Claims, assign the same groups, test, and change the app's IdP sign-in URL, issuer, and signing certificate. Then disable the AD FS trust, but keep it, so rollback is one command. This recipe is the hands-on procedure for one app. Sequencing, sign-in method choice, and domain conversion are in the AD FS to Entra migration guide.

Before you start

Check the app's readiness in the AD FS application migration dashboard: Entra ID > Enterprise apps > Usage & Insights > AD FS application migration. It needs Entra ID P1 or P2, Microsoft Entra Connect, and the Connect Health agents for AD FS. It only lists relying parties with sign-ins in the last 30 days and excludes Microsoft relying parties.

The wizard supports SAML apps only. It sets the identifier, reply URL, group assignments, and compatible claims, but does not migrate the signing certificate or create Conditional Access policies. Microsoft's SAML migration notes list two capabilities that cannot be migrated today: the WS-Trust ActAs pattern and SAML artifact resolution.

1. Export the relying party trust

On a federation server, capture the full configuration so you can map it and so you have a record if you roll back. Get-AdfsRelyingPartyTrust accepts -Name or -Identifier.

$rp = Get-AdfsRelyingPartyTrust -Name "FabrikamApp"
$rp | Format-List *            # review identifiers, endpoints, rules, access policy
$rp | Export-Clixml .\FabrikamApp-rp.xml

Record the identifier, the SAML assertion consumer endpoints, the issuance transform (claim) rules, the access control policy, and any encryption certificate.

Check: The export file exists and the identifier matches what the app sends as its entity ID. Common failure: Exporting the wrong trust when several share a display name prefix. Query by -Identifier to be exact. Rollback: Nothing to undo; this step is read-only.

2. Create the enterprise application

Browse to Entra ID > Enterprise apps > All applications > New application (quickstart). Pick the gallery entry if the vendor has one. For a custom line-of-business app, select Create your own application and add it as a non-gallery application. Microsoft recommends non-gallery apps for custom SAML 2.0 apps (migration stages).

Check: The app appears under All applications. Common failure: "Application with same identifier already exists." Every app in the tenant needs a unique identifier, so remove or change the duplicate first. Rollback: Delete the enterprise application. It carries no traffic until cutover.

3. Configure Basic SAML Configuration

Open the app, select Single sign-on > SAML, and choose Edit on Basic SAML Configuration (SAML setup).

Check: The values match the export from step 1 character for character, including trailing slashes. Common failure: Apps with multiple reply URL endpoints. Microsoft says these need configuration through PowerShell or the admin center rather than a single field. Rollback: Edit the fields back; nothing is live yet.

4. Rebuild claims in Attributes & Claims

Edit Attributes & Claims. By default the Name ID is the user principal name. Match the AD FS rule that issues the claim ending in NameIdentifier; Entra can source Name ID from mail, mail prefix, employee ID, extension attributes 1-15, or on-premises SamAccountName. Add the other claims the app consumes, such as email, given name, surname, and groups.

AD FS regular expressions do not translate directly. The dashboard's claim rule tests point you to functions such as IfEmpty(), StartWith(), Contains(), Extract(), Trim(), and ToLower(), and ADD rules become multiple transformations.

Check: Compare a SAML response from AD FS and one from Entra for the same user. Claim names, formats, and values should match. Common failure: An attribute such as samAccountName is unavailable because it is not synced. Fix the Entra Connect sync scope. Rollback: Delete the added claims.

5. Download the signing certificate

In SAML Certificates, download Certificate (Base64) or Certificate (Raw), or the Federation Metadata XML, in whatever format the app expects. Entra generates a self-signed certificate valid for three years and emails notifications 60, 30, and 7 days before expiry (certificate management). Add a team distribution list to the notification addresses.

Check: The certificate thumbprint in the download matches the Active certificate. Common failure: Uploading the AD FS token-signing certificate to the app. The wizard does not migrate it, and Entra signs with its own key. Rollback: Not applicable until cutover.

6. Assign users and groups

Under Users and groups > Add user/group, assign the same groups the AD FS access control policy permitted (assignment). Group-based assignment needs P1 or P2, and assignment does not cascade to nested groups. Add Conditional Access for this app now, because the wizard does not create it. The Conditional Access baseline is the starting set.

Check: A pilot user sees the app in My Apps. Common failure: Access granted through a nested group in AD FS fails in Entra. Assign the direct group. Rollback: Remove the assignment.

7. Test against a non-production instance

Point a test instance of the app at your production tenant first, as Microsoft's migration stages suggest. Use Test in the Test single sign-on section of the SAML page, then sign in through My Apps as a pilot user.

Check: The pilot user lands in the app with the right role or permissions. Common failure: AADSTS errors naming the reply URL or identifier mean a mismatch with step 3. Rollback: Re-point the test instance to AD FS.

8. Cut over and keep the rollback path

In the production app, replace the IdP settings with Entra's values from the SAML page:

IdP sign-in URL:   https://login.microsoftonline.com/<tenant-id>/saml2
IdP issuer:        https://sts.windows.net/<tenant-id>/
Signing cert:      the Base64 certificate from step 5
Metadata (option): https://login.microsoftonline.com/<TenantDomainName>/FederationMetadata/2007-06/FederationMetadata.xml

Then stop AD FS issuing tokens for the app without deleting the trust. Disable-AdfsRelyingPartyTrust makes AD FS refuse to issue tokens for that relying party.

Disable-AdfsRelyingPartyTrust -TargetName "FabrikamApp"

Check: New sign-ins to the app show in the Entra sign-in logs and not in AD FS. Common failure: The app cached AD FS metadata and keeps redirecting to AD FS. Clear the cached metadata or restart the app's SAML module. Rollback: Restore the AD FS IdP settings in the app and run Enable-AdfsRelyingPartyTrust -TargetName "FabrikamApp".

Verify it works

1. Sign in from My Apps and with an SP-initiated sign-in from the app's own URL. Both should succeed.
2. In Entra ID > Monitoring & health > Sign-in logs, filter on the application. Successful sign-ins should show the expected Conditional Access result.
3. Decode the SAML response with a browser SAML tracer. Confirm the Issuer is https://sts.windows.net/<tenant-id>/, the Audience is your entity ID, and the Name ID format matches the old one.
4. After the app's normal usage cycle, confirm Connect Health shows no new requests for this relying party. Remove the trust only when you no longer need the rollback path.

Retiring the AD FS trust also shrinks the federation trust abuse surface: every relying party that still trusts the AD FS token-signing key is one an attacker with that key can impersonate users to.

Related

• AD FS to Microsoft Entra ID migration guide
• SAML 2.0, SAML, and federation
• Federation trust abuse and SAML forgery
• Microsoft Entra Conditional Access baseline
• Break-glass accounts in Microsoft Entra ID