Ad Fs

---
name: ad-fs
description: "Expert agent for Active Directory Federation Services. Provides deep expertise in claims-based authentication, SAML/OIDC federation, WAP, claims rules, relying party trusts, and migration to Entra ID. WHEN: \"AD FS\", \"ADFS\", \"federation services\", \"claims rules\", \"relying party trust\", \"WAP\", \"Web Application Proxy\", \"SAML federation AD\", \"AD FS migration\", \"token signing certificate\"."
license: MIT
---

# AD FS

This skill covers Active Directory Federation Services (AD FS). It has deep knowledge of claims-based authentication, SAML 2.0 and OIDC federation, claims rules, relying party trusts, and migration strategies to Entra ID.

**Important context:** Microsoft recommends Entra ID (Azure AD) for new federation deployments. AD FS is in maintenance mode -- no new feature investment. Existing AD FS deployments should plan migration to Entra ID. This agent covers both operating AD FS and migrating away from it.

## Identity and Scope

AD FS provides federation services for on-premises Active Directory environments. It enables:
- Single Sign-On (SSO) to web applications via SAML 2.0, WS-Federation, and OAuth 2.0/OIDC
- Claims-based authentication (transform AD attributes into claims for applications)
- Extranet access via Web Application Proxy (WAP)
- B2B federation with external organizations

## How to Approach Tasks

When you receive a request:

1. **Classify** the request:
   - **Federation setup** -- Configure relying party trusts, claims rules, endpoints
   - **Troubleshooting** -- Token issuance failures, certificate issues, WAP problems
   - **Migration** -- Plan migration from AD FS to Entra ID
   - **Security** -- Certificate management, extranet lockout, monitoring
   - **Upgrade** -- AD FS farm upgrades (2016/2019 farms)

2. **Determine AD FS version** -- AD FS 4.0 (Server 2016) or AD FS 5.0 (Server 2019). Older versions (2.0, 3.0) are out of support.

3. **Analyze** -- Apply AD FS-specific reasoning, considering claims pipeline, certificate trust chains, and protocol requirements.

4. **Recommend** -- Provide actionable guidance. For new deployments, always recommend Entra ID instead.

## Core Expertise

### AD FS Architecture

```
Internet                    |  DMZ              |  Internal Network
                            |                   |
Client --> WAP (443) -------|--- AD FS Farm ----|--- AD DS (DCs)
                            |   (443, internal) |
                            |                   |--- SQL Server (config DB)
                            |                   |    or WID
```

**Components:**
- **AD FS farm** -- One or more AD FS servers sharing a configuration database
- **Web Application Proxy (WAP)** -- Reverse proxy in DMZ for extranet access. Not a federation server -- it proxies requests to AD FS.
- **Configuration database** -- WID (Windows Internal Database) for small farms (up to 5 servers) or SQL Server for large farms
- **Certificate store** -- Token-signing, token-decryption, and SSL/TLS certificates

### Claims Pipeline

Every token issuance flows through the claims pipeline:

```
1. Claims Provider Trust (incoming claims)
   --> Acceptance Transform Rules (filter/transform incoming claims)
   
2. AD FS Engine
   --> Authorization Rules (permit/deny access)
   
3. Relying Party Trust (outgoing claims)
   --> Issuance Transform Rules (create/transform claims for the application)
   
4. Token Generation
   --> Sign token with token-signing certificate
   --> Return to client
```

### Claims Rule Language

AD FS uses a custom claims rule language:

```
# Pass through an AD attribute as a claim
c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname"]
 => issue(store = "Active Directory",
    types = ("http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
             "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname",
             "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname"),
    query = ";mail,givenName,sn;{0}", param = c.Value);

# Transform a claim (map AD group to application role)
c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/groupsid",
   Value == "S-1-5-21-xxx-yyy-zzz-1234"]
 => issue(Type = "http://schemas.microsoft.com/ws/2008/06/identity/claims/role",
    Value = "AppAdmin");

# Authorization rule (permit only specific group)
c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/groupsid",
   Value == "S-1-5-21-xxx-yyy-zzz-5678"]
 => issue(Type = "http://schemas.microsoft.com/authorization/claims/permit",
    Value = "true");
```

### Relying Party Trust Configuration

```powershell
# Add a SAML relying party trust
Add-AdfsRelyingPartyTrust -Name "MyApp" `
    -MetadataUrl "https://app.example.com/saml/metadata" `
    -IssuanceTransformRules $transformRules `
    -IssuanceAuthorizationRules $authRules

# Add an OIDC/OAuth relying party trust
Add-AdfsRelyingPartyTrust -Name "MyAPI" `
    -Identifier "api://my-api" `
    -IssuanceTransformRules $transformRules

# Add OAuth client (for OIDC/OAuth apps)
Add-AdfsClient -ClientId "my-client-id" `
    -Name "My Web App" `
    -RedirectUri "https://app.example.com/callback" `
    -Description "OIDC web application"
```

### Certificate Management

AD FS uses three certificate types:

| Certificate | Purpose | Rotation | Impact |
|---|---|---|---|
| **Token-signing** | Signs issued tokens (SAML assertions, JWTs) | Auto-rollover (default: 20 days before expiry) | All relying parties must trust new certificate |
| **Token-decryption** | Decrypts encrypted tokens from claims providers | Auto-rollover | Claims providers must update their encryption cert |
| **SSL/TLS (service communication)** | HTTPS endpoint for AD FS service | Manual renewal | Affects all client connections |

```powershell
# Check certificate status
Get-AdfsCertificate

# Check auto-rollover status
Get-AdfsProperties | Select-Object AutoCertificateRollover, CertificateGenerationThreshold

# Manually rotate token-signing certificate
Update-AdfsCertificate -CertificateType Token-Signing -Urgent

# Export federation metadata (for relying parties to consume new certs)
# https://adfs.example.com/FederationMetadata/2007-06/FederationMetadata.xml
```

### Extranet Lockout

AD FS 2016+ includes extranet smart lockout:

```powershell
# Enable extranet smart lockout
Set-AdfsProperties -EnableExtranetLockout $true `
    -ExtranetLockoutThreshold 15 `
    -ExtranetObservationWindow (New-TimeSpan -Minutes 30) `
    -ExtranetLockoutRequirePDC $false

# AD FS 2019+ enhanced lockout with familiar/unfamiliar locations
Set-AdfsProperties -ExtranetLockoutMode AdfsSmartLockoutLogOnly  # Audit mode first
Set-AdfsProperties -ExtranetLockoutMode AdfsSmartLockoutEnforce  # Then enforce
```

### AD FS Troubleshooting

**Common issues:**

| Symptom | Investigation | Resolution |
|---|---|---|
| "An error occurred" on login | AD FS Admin event log, Event ID 364 | Check claims rules, certificate trust, relying party config |
| Token-signing cert mismatch | Compare AD FS cert thumbprint with RP metadata | Update federation metadata on RP side |
| WAP not connecting to AD FS | WAP event log, Test-WebApplicationProxySslCertificate | Certificate mismatch, firewall, DNS, trust expired |
| Loop redirect | Relying party redirect URI mismatch | Fix redirect URI in RP trust configuration |
| Clock skew errors | Token timestamps out of range | Sync time across AD FS farm, check NotBefore/NotOnOrAfter |
| Slow authentication | Enable AD FS performance counters | Database contention (WID to SQL migration), DC latency |

```powershell
# Check AD FS service health
Get-AdfsProperties | Select-Object HostName, FederationPassiveAddress, CurrentFarmBehavior

# Test token issuance
# Navigate to: https://adfs.example.com/adfs/ls/IdpInitiatedSignon.aspx

# Check AD FS event logs
Get-WinEvent -LogName "AD FS/Admin" -MaxEvents 50

# Verify WAP connectivity
Test-WebApplicationProxyConnection -FederationServiceName "adfs.example.com"
```

### AD FS 2016 vs 2019 Features

| Feature | AD FS 2016 (4.0) | AD FS 2019 (5.0) |
|---|---|---|
| OIDC/OAuth 2.0 | Supported | Enhanced (device flow, PKCE) |
| Azure MFA adapter | Built-in | Improved |
| Extranet lockout | Basic | Smart lockout with familiar locations |
| Password-less | Microsoft Passport | Enhanced password-less options |
| Activity reports | Not available | Application usage reports for migration |
| External auth providers | Limited | Plugin architecture |
| WS-Federation SLO | Not available | Single logout support |

## Migration to Entra ID

Microsoft's recommended migration path for AD FS:

### Migration Assessment

```powershell
# Use AD FS application activity report (AD FS 2019)
# In Azure portal: Entra ID > Usage & insights > AD FS application activity

# Or use AD FS Help migration tool
# https://adfshelp.microsoft.com/AadTrustClaims/ClaimsGenerator
```

### Migration Steps

1. **Inventory relying party trusts** -- List all applications using AD FS
2. **Categorize applications:**
   - Apps in Entra ID gallery (pre-integrated) -- Easy migration
   - Custom SAML/OIDC apps -- Configure manually in Entra ID
   - Apps requiring claims transformations -- Map AD FS claims rules to Entra claims mapping
   - Apps using WS-Federation -- Many can switch to SAML or OIDC
3. **Configure applications in Entra ID** -- Create enterprise applications or app registrations
4. **Test authentication** -- Validate SSO, claims, MFA, conditional access
5. **Cut over** -- Update DNS or application configuration to point to Entra ID
6. **Monitor** -- Verify sign-in logs in Entra ID, check for authentication failures
7. **Decommission AD FS** -- After all applications migrated, decommission AD FS farm

### Claims Rule Migration

Common AD FS claims rules and their Entra ID equivalents:

| AD FS Claims Rule | Entra ID Equivalent |
|---|---|
| Pass-through email, name, UPN | Default claims in SAML token configuration |
| Group-to-role mapping | Group claims with app roles |
| Custom claim from AD attribute | Claims mapping policy or optional claims |
| Authorization rules (permit/deny) | Conditional Access policies + app assignment |
| Transform claim values | Claims transformation rules or custom claims provider |

## Common Pitfalls

1. **Certificate auto-rollover surprises** -- Auto-rollover changes the token-signing cert. RPs that consume federation metadata automatically handle this. RPs with manually configured certs break.
2. **WID scaling limits** -- WID supports 5 AD FS servers and 100 relying party trusts. Beyond this, use SQL Server.
3. **WAP is not a WAF** -- WAP provides pre-authentication and HTTPS reverse proxy but not application-layer security (no XSS/SQLi protection).
4. **Delaying migration to Entra ID** -- AD FS is in maintenance mode. Every day on AD FS is technical debt. Plan migration proactively.
5. **Claims rule complexity** -- Complex claims rules are hard to debug. Use the claims rule debugger and test with `Set-AdfsRelyingPartyTrust -IssuanceTransformRulesFile`.