MFA & Step-Up Authentication
Summary
Keymate strengthens authentication through multi-factor verification and context-driven step-up enforcement. The platform supports multiple second-factor methods — including email-delivered one-time passwords (OTP) and CAPTCHA challenges — as configurable steps within authentication flows. Step-up authentication enables the platform to require additional verification when a user attempts a sensitive operation, raising the authentication strength without forcing a full re-login.
Why It Exists
Passwords alone provide insufficient security for enterprise and government systems. Compromised credentials grant full access unless a second factor blocks unauthorized use. Multi-factor authentication adds a verification step that requires something the user possesses (an OTP delivered to their email) or a challenge that validates human presence (CAPTCHA). Step-up authentication extends this by enforcing stronger verification for high-risk actions while keeping low-risk operations frictionless.
Where It Fits in Keymate
MFA and step-up are steps within authentication flows. The flow chain determines when and whether a second factor runs. The authentication result — including the factors completed — feeds into the session and influences the authentication level claim in access tokens. Downstream services can read the authentication level to enforce step-up requirements for sensitive operations. Federation can carry the external provider's multi-factor status into the platform's authentication context.
Boundaries
This page covers MFA methods and step-up enforcement. It does not cover:
- Flow chain composition — see Authentication Flows
- Token claim structure — see Token Claims & Context
- Federation-provided authentication levels — see Federation & External IdPs
- Session lifecycle and timeout policies — see Session Governance
How It Works
Multi-Factor Methods
The platform supports multiple second-factor methods, each implemented as a pluggable authenticator module:
- Email-based OTP — the platform generates a time-based one-time password and delivers it to the user's registered email address. The user submits the code within a configured time window. The platform enforces attempt limits and supports a resend mechanism with its own limit.
- CAPTCHA challenge — the platform presents a challenge that validates human presence. CAPTCHA protects against automated credential stuffing and brute-force attacks. The CAPTCHA step integrates with the flow chain and can run conditionally based on risk signals.
Step-Up Authentication
Step-up authentication raises the authentication strength during an active session. When a user attempts a sensitive operation, the protecting service reads the authentication level from the access token and determines whether the current level meets the operation's requirement. If not, the service triggers a step-up flow that prompts the user for additional verification without terminating the existing session.
The platform tracks the authentication level as a claim in the access token. Each completed authentication factor contributes to the level. A password-only login results in a base level; adding OTP raises it; a federated login with a qualified electronic signature raises it further.
Conditional Execution
MFA steps support conditional execution within the flow chain. Administrators configure conditions that determine when a second factor is required:
- Always required — every authentication attempt includes the MFA step
- Conditional — the MFA step runs when specific conditions are met (such as login from an unrecognized location, after a risk signal, or for specific client applications)
- Disabled — the MFA step is skipped entirely
This conditional model prevents unnecessary friction for low-risk logins while enforcing strong verification when risk indicators are present.
Authentication Level Tracking
The platform assigns an authentication level based on the factors completed during the authentication flow. This level persists in the session and appears as a claim in the access token. The levels represent increasing verification strength:
- Level 1 — single-factor authentication (password or basic credential)
- Higher levels — additional factors completed (OTP, CAPTCHA, federated multi-factor, qualified electronic signature)
Federated identity providers can report their own authentication level and multi-factor status, which the platform incorporates into the overall level assessment.
Credential Lifecycle
OTP credentials follow a lifecycle within the authentication flow:
- The platform generates the OTP code based on the realm's OTP policy (algorithm, time period, digit count)
- The platform delivers the code to the user's email
- The user submits the code within the configured validity window
- The platform validates the code and, on success, clears the OTP credential
- If the user does not receive the code, a resend option generates a new code (subject to resend limits)
Diagram
Example Scenario
Scenario
A realm configures email-based OTP as a required second factor for the browser flow. A user logs in with their credentials, receives an OTP code by email, and submits it. The resulting access token carries an elevated authentication level.
Input
- Actor: User with a registered email address
- Resource: Platform login through browser flow
- Action: Credential submission followed by OTP verification
- Context: Realm browser flow requires credential validation and email OTP as a second factor
Expected Outcome
- Applied — The platform validates the user's credentials, generates an OTP code, delivers it to the user's email, and waits for submission. After the user submits the correct code within the time window, the platform creates a session with an elevated authentication level. The access token carries the higher level claim.
- Why: The flow chain requires both credential validation and OTP verification. Completing both factors raises the authentication level. The token's authentication level claim reflects the completed factors.
Common Misunderstandings
-
"MFA always requires a mobile app" — No. The platform's OTP delivery uses email. Mobile authenticator app support depends on realm configuration and available authenticator modules.
-
"Step-up authentication creates a new session" — No. Step-up verification raises the authentication level within the existing session. The platform issues a new token with the updated level without terminating the current session.
-
"CAPTCHA is a full authentication factor" — CAPTCHA validates human presence, not user identity. It protects against automated attacks but does not replace identity verification. The platform treats CAPTCHA as a flow step that complements credential-based authentication.
Configure OTP time windows that balance security and usability. A window that is too short frustrates users who experience email delivery delays. A window that is too long increases the risk of OTP interception.
Design Notes / Best Practices
- Use conditional MFA execution to balance security and user experience. Require MFA for high-risk scenarios (new device, administrative operations) and skip it for trusted contexts.
- Configure resend limits on OTP delivery to prevent abuse. Unlimited resend allows an attacker to flood the user's email inbox.
- Track the authentication level in access tokens and enforce minimum levels at the service boundary. This enables granular step-up requirements per operation without centralizing enforcement.
When integrating with a federated identity provider that supports multi-factor authentication, configure the platform to read the provider's authentication level and multi-factor status from the federation response. This avoids asking the user for a second factor that the external provider already verified.
Related Use Cases
- Requiring email-based OTP for all browser-based logins
- Adding CAPTCHA protection to public-facing login forms
- Enforcing step-up authentication for administrative operations
- Incorporating federated authentication levels into platform MFA decisions