Skip to main content

SAML Federation Model

Summary​

Keymate supports SAML 2.0 federation by acting as both a Service Provider (SP) and an Identity Provider (IdP). As an SP, the platform receives SAML assertions from external identity providers and maps them to local identities. As an IdP, the platform issues SAML assertions to external service providers that rely on Keymate for authentication. This dual capability enables the platform to participate in federated identity ecosystems where different organizations exchange trust through SAML metadata and signed assertions.

Why It Exists​

Many enterprise and government environments use SAML 2.0 as their federation standard. Legacy systems, government portals, and enterprise applications often support SAML but not OIDC. SAML federation enables the platform to integrate with these systems without requiring protocol upgrades, bridging SAML-based trust relationships with the platform's OIDC-native identity model.

Where It Fits in Keymate​

SAML federation is a specific implementation of the broader federation model. It plugs into authentication flows as an external identity provider step. When the platform receives a SAML assertion, it maps the assertion's attributes to the identity model using configurable mappers. The resulting identity feeds into token issuance through the platform's standard claim assembly.

Boundaries​

This page covers SAML-specific federation mechanics. It does not cover:

How It Works​

Trust Establishment​

SAML federation begins with trust exchange between the platform and the external party. Each side publishes SAML metadata — an XML document describing endpoints, signing certificates, supported bindings, and name ID formats. Importing the external party's metadata establishes a trust relationship. The platform validates incoming assertions against the trusted certificates and rejects assertions from unknown or untrusted issuers.

SP-Initiated Flow​

In SP-initiated federation, the user starts at the platform (Service Provider):

  1. The user requests a protected resource
  2. The platform generates a SAML authentication request and redirects the user to the external IdP
  3. The user authenticates at the external IdP
  4. The external IdP creates a SAML response containing a signed assertion
  5. The user's browser posts the SAML response back to the platform's assertion consumer endpoint
  6. The platform validates the signature, checks the assertion's conditions (audience, time bounds, recipient)
  7. The platform extracts identity attributes from the assertion and maps them to a local user

IdP-Initiated Flow​

In IdP-initiated federation, the user starts at the platform acting as an IdP:

  1. An external service provider requests authentication from the platform
  2. The platform authenticates the user through its configured authentication flow
  3. The platform generates a SAML assertion containing the user's identity attributes
  4. The user's browser posts the assertion to the external SP's assertion consumer endpoint

Assertion Processing​

When the platform receives a SAML assertion as an SP, it processes the assertion through several validation steps:

  • Signature validation — verifies the assertion or response signature against the trusted IdP certificate
  • Condition evaluation — checks audience restriction, not-before and not-on-or-after time bounds, and one-time-use constraints
  • Subject extraction — reads the NameID and subject confirmation data
  • Attribute extraction — reads attribute statements and maps them to local identity attributes

Attribute Mapping​

SAML assertions carry attribute statements that the platform maps to local user attributes. Administrators configure mappers that define how SAML attribute names correspond to local attribute fields. Mapping supports:

  • Direct attribute mapping (SAML attribute name to local attribute)
  • Name ID mapping (using the SAML NameID as the local user identifier)
  • Role mapping (translating SAML group or role attributes into local roles)
  • Hardcoded values (setting a fixed attribute value for all users from a specific IdP)

Bindings and Protocols​

The platform supports standard SAML 2.0 bindings:

  • HTTP-POST — assertions transmitted as form-encoded data through the user's browser
  • HTTP-Redirect — authentication requests sent as URL-encoded query parameters

Diagram​

Example Scenario​

Scenario​

A government agency uses a SAML 2.0 identity provider for employee authentication. The agency configures the platform as a Service Provider that trusts the agency's IdP. An employee accesses the platform, authenticates at the agency's IdP, and receives a SAML assertion. The platform maps the assertion's attributes to a local user with organizational assignments.

Input​

  • Actor: Government employee accessing the platform
  • Resource: Platform resources protected by SAML federation
  • Action: SP-initiated SAML login
  • Context: Trust established through metadata exchange; attribute mappers configured for name, email, and department

Expected Outcome​

  • Applied — The platform redirects the employee to the agency's IdP. After authentication, the IdP returns a signed assertion. The platform validates the signature and conditions, extracts the employee's name, email, and department from the assertion attributes, maps them to the local user, and creates a session with organizational context.
  • Why: SAML metadata establishes trust between the platform and the IdP. Assertion validation confirms the IdP's signature and time bounds. Attribute mappers translate SAML attributes into local identity fields, enabling the user to operate within the platform's organizational model.

Common Misunderstandings​

  • "SAML federation replaces the platform's identity model" — No. SAML provides the external authentication. The platform maps the external identity into its own model with local roles, attributes, and organizational assignments.

  • "All SAML attributes automatically become token claims" — No. SAML attributes map to local user attributes through configured mappers. Only attributes with token visibility enabled appear in access tokens.

  • "IdP-initiated and SP-initiated flows are interchangeable" — They serve different use cases. SP-initiated flow starts from the platform; IdP-initiated flow starts from the external provider. Each requires specific configuration and has different security characteristics.

warning

Always validate SAML assertion signatures. Accepting unsigned assertions allows an attacker to forge identity claims. Configure the platform to reject assertions that do not carry a valid signature from the trusted IdP certificate.

Design Notes / Best Practices​

  • Exchange SAML metadata through a secure channel and verify certificate fingerprints. Metadata-based trust establishment is only as secure as the metadata exchange process.
  • Configure clock skew tolerance for assertion time validation. Network latency and clock drift between systems can cause valid assertions to fail time-bound checks.
  • Map a stable, unique identifier (such as a persistent NameID or employee number) rather than transient attributes. This prevents user duplication when external attribute values change.
tip

When migrating from a SAML-only environment to OIDC, configure the platform as both a SAML SP (for legacy systems) and an OIDC provider (for new applications). This enables gradual migration without disrupting existing SAML integrations.

  • Federating employee identity from a government SAML identity provider
  • Acting as a SAML IdP for legacy enterprise applications
  • Mapping SAML group assertions to platform roles
  • Bridging SAML federation with OIDC token issuance

Federation & External IdPs

General federation model and identity brokering

OIDC & OAuth Interaction Model

Protocol alternative for modern federation

Authentication Flows

Flow chains that SAML federation integrates with

Identity Model

Local identity that SAML assertions populate