- Purpose
- Federate authentication to a corporate IdP so no local passwords exist.
- Prerequisites
- IdP administrator
- Redirect URI approved
- Agreed claim for the external identifier
- Architecture
- User → Integration Lab (SP) → IdP authorization endpoint → authentication → code → token endpoint → ID token validated → claims mapped → session.
Configuration
| Response type | code |
| Scopes | openid profile email |
| Claims | sub, email, given_name, family_name, external_id |
| PKCE | Required for public clients |
Implementation steps
- 01Register the client in the IdP and capture issuer, client id and secret.
- 02Configure the redirect URI exactly, including trailing path.
- 03Map claims to profile fields; choose the immutable claim for external_id.
- 04Validate issuer, audience, expiry, nonce and signature on every login.
- 05Decide whether unknown users are provisioned just in time or refused.
Examples
Example ID token claims
json
{
"iss": "https://login.example.com/tenant/v2.0",
"aud": "integrationLab-client-id",
"sub": "6f1a2c9e-1f2b-4b7a-9f5c-3d0f2a1b8c44",
"email": "jane.smith@example.com",
"given_name": "Jane",
"family_name": "Smith",
"external_id": "WC-8291",
"exp": 1756033500
}Testing procedure
- Login with a new user and confirm exactly one candidate is created
- Tamper with the signature and confirm rejection
Troubleshooting
invalid_redirect_uri
The registered URI must match character for character.
Duplicate accounts
external_id mapped to a mutable claim such as email. Use sub or employeeId.