Skip to main content

Federation & External IdPs

Summary​

Keymate federates identity from external sources by acting as an identity broker. The platform connects to external identity providers — OAuth 2.0 and OIDC providers, SAML identity providers, directory services, and custom credential systems — and translates their authentication assertions into the platform's internal identity model. Users authenticate at the external provider, and the platform maps the resulting identity into a local user with organizational assignments, roles, and attributes.

Why It Exists​

Organizations rarely operate a single identity source. Employees authenticate through corporate directories, citizens through government identity portals, partners through their own identity providers. Federation eliminates the need to create and manage separate credentials for each system. Users bring their existing identity, and the platform maps it into the organizational context where access decisions are made.

Where It Fits in Keymate​

Federation extends authentication flows by introducing external identity verification as a flow step. The OIDC and OAuth interaction model provides the protocol foundation for OIDC-based federation. SAML federation handles SAML-specific trust relationships. After federation establishes the user's identity, the identity model stores the linked local representation, and provisioning can synchronize attributes and group memberships from the external source.

Boundaries​

This page covers how the platform integrates external identity sources through federation. It does not cover:

How It Works​

Identity Brokering​

The platform acts as an identity broker between the user and the external identity provider. When a user initiates federated login:

  1. The platform redirects the user to the external identity provider
  2. The user authenticates at the external provider using their existing credentials
  3. The external provider returns an authentication assertion (OIDC token, SAML assertion, or credential response)
  4. The platform validates the assertion and extracts identity attributes
  5. The platform links the external identity to a local user (creating one if necessary)
  6. The authentication flow continues with any remaining steps (MFA, department selection)

External Identity Provider Types​

The platform supports several categories of external identity providers:

  • OIDC and OAuth 2.0 providers — standard protocol-based federation. The platform registers as a client with the external provider and uses Authorization Code flow with PKCE for secure token exchange. Supports configurable scopes for requesting specific identity claims.
  • SAML identity providers — assertion-based federation through SAML 2.0. See SAML Federation Model for details.
  • Directory services — LDAP and Active Directory integration. The platform queries the directory for user attributes, validates credentials against the directory, and synchronizes identity data. Directory federation supports attribute mapping, domain-based filtering, and account status synchronization.
  • Custom credential systems — integration with proprietary or domain-specific authentication services. Custom authenticator modules handle credential exchange with the external system and map the response into the platform's identity model.
  • Government identity providers — integration with national identity services that provide verified citizen identity through OAuth 2.0 flows. These integrations support authentication level validation and identity verification strength assessment.

User Linking and First Login​

When a federated user authenticates for the first time, the platform determines how to link the external identity to a local user:

  • Automatic linking — if an existing local user matches the external identity (by email, national identifier, or another configured attribute), the platform links them automatically
  • User creation — if no matching local user exists, the platform creates a new user and populates their profile from the external identity attributes
  • Manual linking — administrators can pre-configure external identity mappings before the user's first login

After linking, subsequent authentications through the same external provider skip user creation and directly establish the session for the linked local user.

Attribute Mapping​

Federation includes attribute mapping from the external identity to the local user profile. The platform maps external claims or directory attributes to local user attributes based on configurable mapping rules. Mapping supports:

  • Standard claim mapping (name, email, groups)
  • Custom attribute mapping (domain-specific fields from the external source)
  • Authentication context mapping (authentication level, verification method, multi-factor status)
  • Conditional mapping (apply different rules based on the external provider or user attributes)

Authentication Level and Trust​

External identity providers offer different levels of identity assurance. The platform tracks the authentication level reported by the external provider and can enforce minimum level requirements. A government identity portal may report five authentication levels (from basic password to qualified electronic signature), and the platform can require a specific minimum level for access to sensitive resources.

Sync Modes​

Federation supports configurable synchronization modes that control when external attributes update the local user:

  • Import on first login — external attributes populate the local user on first authentication only
  • Force sync on every login — external attributes overwrite local values on every authentication, keeping the local profile aligned with the external source

Diagram​

Example Scenario​

Scenario​

An Organization federates identity from a corporate directory service. An employee authenticates for the first time. The platform queries the directory, validates credentials, maps the employee's department and email, and creates a local user with an organizational assignment.

Input​

  • Actor: Employee authenticating for the first time via directory federation
  • Resource: Platform login
  • Action: Browser-based federated authentication
  • Context: The realm configures directory federation with attribute mapping for email, department, and account status. Sync mode set to import on first login.

Expected Outcome​

  • Applied — The platform validates credentials against the directory, creates a local user with the mapped email and department attributes, links the directory identity to the local user, and continues the authentication flow. The user receives a session and access token.
  • Why: Directory federation validates credentials externally and maps attributes to the local identity model. First-login creation establishes the local user. Subsequent logins authenticate against the directory and use the existing linked user.

Common Misunderstandings​

  • "Federation creates a separate identity for each external provider" — No. Multiple external identities can link to a single local user. A user who authenticates through both a directory service and a government identity portal links both to the same local identity.

  • "External identity attributes permanently override local values" — Only when sync mode is set to force sync. With import-on-first-login mode, subsequent attribute changes in the external source do not propagate unless explicitly synchronized.

  • "Federation bypasses the platform's authentication flow" — No. Federation is a step within the authentication flow. After the external provider validates the user, the flow can continue with additional steps such as MFA or department selection.

warning

When configuring automatic user linking by email, ensure that the external identity provider verifies email addresses. Linking by unverified email allows an attacker to claim another user's identity by registering a matching email at the external provider.

Design Notes / Best Practices​

  • Configure automatic linking with a verified unique identifier (national ID, employee number) rather than mutable attributes like email. This prevents identity conflicts when users change email addresses.
  • Use force sync mode for directory services that serve as the authoritative source for user attributes. Use import-on-first-login for external providers where the user manages their own profile locally after initial creation.
  • Enable authentication level tracking for government identity provider integrations. This enables downstream services to make authorization decisions based on the strength of identity verification.
tip

Test federation configurations with a small pilot group before enabling them realm-wide. Attribute mapping errors can create users with incorrect profiles that require manual cleanup.

  • Federating employees from a corporate Active Directory
  • Integrating a government identity portal for citizen authentication
  • Linking multiple external identities to a single platform user
  • Synchronizing user attributes from a directory on every login

SAML Federation Model

SAML-specific federation trust and assertion handling

Authentication Flows

Flow chains that federation plugs into

Provisioning & SCIM

Directory synchronization and user lifecycle

Identity Model

Local identity representation that federation populates