# Migrate an app from AD FS to Microsoft Entra ID

Source: https://startwithidentity.com/recipes/migrate-app-adfs-to-entra/
Last updated: 2026-11-05
License: content by Start with Identity. Cite the source URL.

---

Migrating one app from AD FS to [Microsoft Entra ID](https://startwithidentity.com/vendors/iam/microsoft-entra/) means recreating its [SAML](https://startwithidentity.com/glossary/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](https://startwithidentity.com/guides/implementation/adfs-to-entra-migration/).

## Before you start

Check the app's readiness in the [AD FS application migration](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/migrate-ad-fs-application-howto) 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.

| Dashboard status | What to do |
| --- | --- |
| Ready to migrate | Use **Begin migration** or follow the manual steps below |
| Needs review | Migrate, then fix the flagged settings |
| Additional steps required | Redesign first; some settings are unsupported |

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](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/migrate-adfs-saml-based-sso) 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](https://learn.microsoft.com/en-us/powershell/module/adfs/get-adfsrelyingpartytrust) accepts `-Name` or `-Identifier`.

```powershell
$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](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/add-application-portal)). 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](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/migrate-adfs-apps-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](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/delete-application-portal). 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](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/add-application-portal-setup-sso)).

| AD FS (relying party Properties) | Entra field |
| --- | --- |
| **Identifiers** tab | **Identifier (Entity ID)**, the Audience in the token |
| **Endpoints** tab, assertion consumer URL | **Reply URL (Assertion Consumer Service URL)** |
| App's SP-initiated sign-in URL | **Sign on URL** |
| **Endpoints** tab, sign-out URL | Logout URL |

**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](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/tutorial-manage-certificates-for-federated-single-sign-on)). 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](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/assign-user-or-group-access-portal)). 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](https://startwithidentity.com/recipes/entra-conditional-access-baseline/) is the starting set.

**Check:** A pilot user sees the app in [My Apps](https://myapps.microsoft.com/).
**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](https://learn.microsoft.com/en-us/powershell/module/adfs/disable-adfsrelyingpartytrust) makes AD FS refuse to issue tokens for that relying party.

```powershell
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](https://startwithidentity.com/techniques/federation-trust-abuse-saml-forgery/) 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](https://startwithidentity.com/guides/implementation/adfs-to-entra-migration/)
- [SAML 2.0](https://startwithidentity.com/standards/saml-2-0/), [SAML](https://startwithidentity.com/glossary/saml/), and [federation](https://startwithidentity.com/glossary/federation/)
- [Federation trust abuse and SAML forgery](https://startwithidentity.com/techniques/federation-trust-abuse-saml-forgery/)
- [Microsoft Entra Conditional Access baseline](https://startwithidentity.com/recipes/entra-conditional-access-baseline/)
- [Break-glass accounts in Microsoft Entra ID](https://startwithidentity.com/recipes/entra-break-glass-accounts/)