Migrating Complex AD FS Claim Rules to Entra ID Custom Authentication Extensions
Retiring the final stubborn AD FS Relying Party Trusts holding custom SQL/REST attribute store claim transforms by migrating them into Entra ID `OnTokenIssuanceStart` Custom Authentication Extensions.
Executive Summary and Authentication Threat Context
Many enterprises migrate 95% of applications cleanly out of AD FS yet remain trapped paying for redundant WAP/AD FS farms over the last 5%: legacy ERPs and banking portals demanding custom claims computed live from internal SQL tables or HR partner stores (AD FS Attribute Store Claim Rules). With Microsoft Entra Custom Authentication Extensions (OnTokenIssuanceStart), Entra ID securely invokes an authenticated REST webhook (Azure Functions) milliseconds before signing a SAML or OIDC token.
From an architectural evolution standpoint, this foundational design connects directly to modern platform controls. Unblocking the final 5% of enterprise SAML/OIDC applications left behind during 2022–2023 AD FS App Migrations and Federation Retirement, OnTokenIssuanceStart Custom Claims Providers close the door on legacy federation farms.
Trust Boundaries, Policy Evaluation, and Design Principles
TokenIssuanceStart Custom Claims Providerintercepts token issuance cleanly in real time to inject dynamic claims (partnerCode,erpRoles) sourced from external APIs or databases without bloating Entra directory schemas.- Secures the webhook using first-party Entra bearer tokens validated specifically against your registered extension app identity rather than brittle shared API secrets.
- Eliminates the final technical blocker preventing permanent AD FS and WAP server shutdown.
- Every Conditional Access and authentication-strength policy must stage in
Report-Onlymode while excluding two dedicated cloud-onlyBreak-Glassaccounts to prevent tenant-wide administrative lockouts.
Prerequisites, Licensing Scope, and RBAC Separation
- Licensing: Microsoft Entra ID P1/P2 (M365 E3/E5) supporting Custom Claims Providers across workforce tenants.
- Compute & RBAC: Warm Azure Functions (
EP1Premium or Always-On App Service) paired with Application Insights, managed underCustom Authentication Extension AdministratorandApplication Administrator. - Timeout Budget: External API + SQL lookups must resolve well below 2 seconds end-to-end under morning login bursts.
Technical Verification, Session Controls, and Enforcement
PowerShell Policy Audit and Report-Only Validation
Querying configured Custom Authentication Extensions and verifying Enterprise Application assignments via Graph:
- Execution Environment and Prerequisites: Requires Microsoft.Graph.
- Least Privilege and Operation Separation: Run with scoped Least-privilege Graph `.Read.All` scopes (delegated admin role only for writes) privileges. All statements above are **read-only (
Get-*/Test-*/Search-*)** verification checks making no direct configuration edits; still validate module/network prerequisites in a test cohort first. - Security Control Mapped and Boundary Note: Verifies active policy state and guards against silent drift or mis-scoped rollouts without blind production changes.
# 1. Inspect Custom Authentication Extensions registered in Microsoft Graph
Connect-MgGraph -Scopes "CustomAuthenticationExtension.Read.All", "Application.Read.All"
Invoke-MgGraphRequest -Method GET -Uri "https://graph.microsoft.com/v1.0/identity/customAuthenticationExtensions" |
Select-Object -ExpandProperty value | Select-Object id, displayName, '@odata.type'
# 2. Verify target Enterprise Application Service Principal properties
Get-MgServicePrincipal -Filter "displayName eq 'Legacy-ERP-SAML'" |
Select-Object Id, DisplayName, AppIdSign-In Telemetry and KQL Verification Query
KQL query inspecting OnTokenIssuanceStart latency and error codes (1003018 / 1003020) in Entra SigninLogs:
// Execution Scope: Read-only hunting/audit query (Log Analytics Reader / Security Reader)
// Data Source: Microsoft Entra ID Diagnostic Settings -> Log Analytics / Microsoft Sentinel (SigninLogs / AuditLogs)
SigninLogs
| where TimeGenerated > ago(14d)
| where AuthenticationProcessingDetails has_any ("CustomAuthenticationExtension", "TokenIssuanceStart") or toint(Status.errorCode) in (1003018, 1003020)
| project TimeGenerated, UserPrincipalName, AppDisplayName, Status, AuthenticationProcessingDetails
| summarize Events = count() by AppDisplayName, tostring(Status.errorCode), tostring(Status.failureReason)
| order by Events descCritical Architectural Assessment, Lockout Risks, and Rollback Strategy
- Using Consumption Serverless Hosting with Cold Starts: Cold-start latency past 2 seconds induces silent morning sign-in failures (error
1003018/1003020). - Forgetting to Bind the Custom Claims Provider Inside the Enterprise App: Simply registering the extension in Entra does nothing until attached under Enterprise Application -> Single sign-on ->
Attributes & Claims. - Risks Mitigated vs. Residual Limitations: Conditional Access baselines,
Authentication Strengths,CAE, and token protection substantially curtail password spray, MFA fatigue, and stolen-cookie replay; however, they do not stop shadow SaaS apps lacking Entra SSO, legacy clients lacking token-binding support, or post-authentication data abuse inside legitimately accessed applications. - New Dependencies and Production Failure Modes: Enforcement relies on
Entra ID P1/P2licensing accuracy, compliant-device telemetry latency, and low-latency external REST availability when invokingCustom Authentication Extensions. Deploying strict grant controls without exclusions locks out emergency IT operations across the entire tenant. - Rollback and Pilot Validation Procedure: Stage every new Conditional Access control in
Report-Only(enabledForReportingButNotEnforced) mode while excluding two cloud-onlyBreak-Glassaccounts; recover from unintended blocks by signing in with a Break-Glass account and switching the offending policy back toReport-Only.
Verified Primary Sources & Open-Source Repositories
This architectural guide was cross-corroborated against the official advisories, Microsoft Learn docs, and open-source PowerShell / KQL repositories below.
Multi-Channel Distribution Summary (X & LinkedIn Draft)
Toggle X (Twitter) & LinkedIn sharing drafts
Multi-Channel Distribution Summary (X & LinkedIn Draft)
Toggle X (Twitter) & LinkedIn sharing draftsMigrating complex AD FS SQL/REST claim transforms cleanly to Entra ID Custom Authentication Extensions. #EntraID #ADFS #CustomClaims
Finishing AD FS Decommissions: Injecting dynamic claims via Entra ID OnTokenIssuanceStart within strict 2,000ms latency budgets using warm Azure Functions.