Skip to main content

Authentication Flows

Summary​

Keymate authenticates users through configurable flow chains — ordered sequences of authentication steps that the platform executes during login. Each flow defines which steps run, in what order, and under what conditions. Flows support browser-based interactive login, direct credential exchange for programmatic access, and post-authentication steps such as organizational context selection. Administrators compose flows from reusable authenticator modules, enabling each realm to tailor its authentication experience without code changes.

Why It Exists​

Enterprise environments require different authentication experiences for different contexts. A government agency portal requires credential validation followed by department selection. An internal service uses direct credential exchange without user interaction. A high-security workflow demands additional verification before granting access. Configurable flows address this variety by separating the authentication logic into composable steps that administrators assemble into the right sequence for each scenario.

Where It Fits in Keymate​

Authentication flows execute at the entry point of the identity lifecycle. The identity model defines the user representation that flows establish. Successful flow completion produces a session and an access token carrying the authenticated identity. MFA and step-up policies determine which additional steps a flow includes. Federation introduces external identity verification as a flow step.

Boundaries​

This page covers the flow chain model, step composition, and how flows produce authenticated sessions. It does not cover:

How It Works​

Flow Chain Model​

An authentication flow consists of an ordered chain of authenticator steps. The platform executes each step in sequence. Each step either succeeds (allowing the chain to continue), fails (terminating authentication), or requires user interaction (pausing until the user responds). Steps declare their execution requirement — required, conditional, alternative, or disabled — which determines how the platform handles step outcomes.

Browser Flow​

The browser flow handles interactive login through a web interface. A typical browser flow includes:

  1. Credential collection — the platform presents a login form and validates the submitted credentials against the identity store or an external credential system
  2. Multi-factor verification — if configured, the platform requests an additional authentication factor (one-time password, CAPTCHA, or another verification method)
  3. Organizational context selection — for users with multiple department assignments, the platform presents a selection step where the user chooses their active organizational context
  4. Session creation — the platform creates an authenticated session and issues tokens

Each step in the chain is a pluggable authenticator module. Administrators compose different combinations to create the required login experience.

Direct Grant Flow​

The direct grant flow handles non-interactive authentication for programmatic clients. The client submits credentials directly (typically through the token endpoint), and the platform validates them without user interaction. This flow skips interactive steps like form rendering and context selection, making it suitable for service-to-service communication and automated processes.

Post-Authentication Steps​

After primary credential validation, flows can include post-authentication steps that enrich the session before token issuance:

  • Department selection — when a user holds assignments in multiple departments, the flow presents a selection interface. The selected department becomes the active organizational context, and the platform creates an Organization ticket binding the session to that assignment.
  • Attribute synchronization — the platform can synchronize user attributes from external sources during authentication, updating the local identity store with current values.
  • Session note population — custom authenticator steps can attach additional metadata to the session, which protocol mappers later project into token claims.

Custom Authenticator Modules​

The platform supports custom authenticator modules that extend the standard flow capabilities. These modules integrate external credential systems, specialized verification services, or domain-specific authentication logic. Each module implements a standard interface, making it composable with any flow chain.

Flow Selection​

The platform selects which flow to execute based on the authentication context:

  • Client type determines whether the browser flow or direct grant flow applies
  • Realm configuration maps flow names to specific flow chains
  • Authentication request parameters can trigger alternative flows (such as step-up requirements)

Diagram​

Example Scenario​

Scenario​

A user with assignments in three departments accesses a government portal. The realm's browser flow requires credential validation, one-time password verification, and department selection. The user completes all steps and selects the Tax Division as their active context.

Input​

  • Actor: User with assignments in Tax Division, Compliance Division, and HR Division
  • Resource: Government portal protected by browser flow
  • Action: Interactive login through the browser
  • Context: Realm browser flow configured with credential validation, OTP, and department selection steps

Expected Outcome​

  • Applied — The platform validates credentials, verifies the one-time password, presents three department options, and creates a session bound to the Tax Division context after the user selects it
  • Why: The flow chain executes each configured step in order. The department selection step reads the user's organizational assignments and creates an Organization ticket for the selected context. The resulting token carries Tax Division claims.

Common Misunderstandings​

  • "All users go through the same flow" — No. The platform selects the flow based on client type and realm configuration. Different clients can trigger different flows, and step-up policies can extend a flow at runtime.

  • "Failing one step always blocks authentication" — Not necessarily. Steps with an "alternative" execution requirement allow the flow to continue if an alternative step succeeds. Only "required" steps block the entire flow on failure.

  • "Department selection happens after token issuance" — No. Department selection is a post-authentication step within the flow, before session and token creation. The token carries the selected department context from the start.

warning

Changing a realm's authentication flow affects all users authenticating through that realm. Test flow changes in a staging environment before applying them to production realms.

Design Notes / Best Practices​

  • Compose flows from small, focused authenticator steps. A step that validates credentials should not also handle department selection — separate concerns enable flexible recombination.
  • Use conditional execution requirements for optional steps. A CAPTCHA step configured as "conditional" runs only when the platform detects risk signals, avoiding unnecessary friction for low-risk logins.
  • Configure the department selection step for realms where users hold multiple organizational assignments. Without this step, the platform uses the user's default assignment.
tip

When introducing a new authenticator module, add it to the flow as "disabled" first, then switch to "alternative" for gradual rollout before making it "required."

  • Composing a multi-step government portal login with credential validation, OTP, and department selection
  • Configuring direct grant authentication for automated service clients
  • Adding a CAPTCHA step to protect public-facing login forms
  • Integrating an external credential system as a custom authenticator step

MFA & Step-Up Authentication

Multi-factor methods and conditional enforcement

OIDC & OAuth Interaction Model

Protocol-level token and session interactions

Federation & External IdPs

External identity providers as authentication sources

Token Claims & Context

How authentication results appear in access tokens