AD FS SAML

Audience: Windows Server administrators wiring Active Directory Federation Services (AD FS) as a SAML 2.0 IdP for TokenTimer Enterprise.

Multi-provider SSO: Configure AD FS under System Settings → Manage SSO providers (or bootstrap via sso-providers.json / Helm ssoProviders[]). Sign-in, ACS, and metadata URLs are slug-scoped. See the SAML quickstart first.

TokenTimer is the relying party (RP) / SAML SP; AD FS is the claims provider / IdP. AD FS speaks WS-Fed and SAML 2.0; use SAML 2.0.

See the SSO identity provider guides for prerequisites and callback URLs. Claim paths: Claim mapping.

URLs to register

Replace <slug> with your provider slug (e.g. adfs).

Purpose	Value
SAML ACS (Assertion Consumer Service)	https://tokentimer.example.com/auth/saml/<slug>/callback
SP metadata (optional import)	https://tokentimer.example.com/auth/saml/<slug>/metadata

AD FS endpoints (defaults):

Purpose	Value
IdP SSO (entry point)	https://fs.example.com/adfs/ls/
Federation metadata	https://fs.example.com/FederationMetadata/2007-06/FederationMetadata.xml

---

1. Add Relying Party Trust

On the AD FS server (AD FS Management console) (create RP trust):

1. Relying Party Trusts, Add Relying Party Trust, Claims aware.
2. Select Data Source:
   • Prefer Import data about the relying party from a URL if the AD FS server can reach https://tokentimer.example.com/auth/saml/<slug>/metadata; TokenTimer serves SP metadata at that path once SAML fields exist for the slug (readiness not required); or
   • Enter data about the relying party manually.
3. Manual settings:

Wizard step	Value
Display name	TokenTimer Enterprise
Profile	AD FS profile (SAML 2.0)
Certificate	Skip (assertion encryption optional; see below)
Enable support for the SAML 2.0 WebSSO protocol	Yes
Relying party SAML 2.0 SSO service URL	https://tokentimer.example.com/auth/saml/<slug>/callback (POST binding ACS)
Relying party trust identifier	SP entity ID on the provider row, e.g. https://tokentimer.example.com/saml

4. Access control policy: e.g. Permit everyone or group-restricted.
5. Finish and open Edit Claim Issuance Policy.

2. Claim rules

Add Issuance Transform Rules so the assertion carries what TokenTimer expects (claim rule template).

Rule A: LDAP attributes

Template: Send LDAP Attributes as Claims with the store Active Directory:

LDAP attribute	Outgoing claim type
E-Mail-Addresses	E-Mail Address (http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress)
Display-Name	Name (http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name)
Token-Groups - Unqualified Names	Group (http://schemas.xmlsoap.org/claims/Group)

Rule B: Name ID

Template: Transform an Incoming Claim:

Setting	Value
Incoming claim type	E-Mail Address (or UPN)
Outgoing claim type	Name ID
Outgoing name ID format	Email (or Persistent if you key identity on immutable IDs)

Persistent NameID is preferable for rename-safety; if you use email NameID, an email change in AD creates a new TokenTimer identity unless the subject claim path is configured to a stable attribute. See the Identity model.

3. Signature and certificates

1. AD FS signs assertions with its Token-signing certificate. Export it (Base64 X.509) from AD FS, Service, Certificates, and provide it to TokenTimer via SSO_<SLUG>_SAML_CERT (PEM) or upload in SSO Providers.
2. Certificate rollover: AD FS auto-rolls token-signing certs. Update the IdP cert on the provider (add the new cert during transition; TokenTimer supports a secondary cert per provider) before the old one is retired.
3. TokenTimer SP metadata does not require RP signing by default. If your policy requires signed AuthnRequests, configure SP signing (advanced fields in SSO Providers) and set the RP trust to require signed requests.

4. Optional: encrypted assertions

If your policy requires encryption, configure the RP trust Encryption certificate with the SP decryption certificate whose key you install on the provider (SSO_<SLUG>_SAML_DECRYPTION_KEY). Most deployments use TLS-only.

5. TokenTimer configuration

In System Settings → Manage SSO providers (slug e.g. adfs):

Field	Value
Entry point	https://fs.example.com/adfs/ls/
SP entity ID	https://tokentimer.example.com/saml
IdP cert	via SSO_ADFS_SAML_CERT env or UI upload

Claim paths (defaults already include AD FS URIs; align with your rules) in Claim mapping:

Field	Paths
Email	email, http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
Display name	displayName, http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
Groups	groups, http://schemas.xmlsoap.org/claims/Group
Subject	nameID

6. Verify

1. GET /api/auth/features returns your slug in providers.saml[] with signInReady: true.
2. Browse https://tokentimer.example.com/auth/saml/<slug>; complete AD FS login; land on the dashboard.
3. Audit LOGIN_SUCCESS with method=saml; idp_groups_seen reflects Token-Groups.
4. Map AD group names under System Settings → Single Sign-On (matching is case-insensitive).

Troubleshooting

Symptom	Likely cause	Fix
AD FS event 364 / invalid request	ACS URL or identifier mismatch	Match RP trust URL and identifier exactly
Signature validation failed	Wrong or rolled token-signing cert	Re-export cert; update provider IdP cert (use secondary cert during rollover)
No groups in assertion	Missing Token-Groups rule	Add LDAP claim rule with Group claim
NameID missing	No Name ID rule	Add transform rule to Name ID
Clock skew errors	Server time drift	Sync NTP on AD FS and TokenTimer hosts

Official references

• Create a Relying Party Trust
• Send LDAP attributes as claims
• AD FS certificates