MFA in SSO Flows
Enforce multi-factor authentication before Passport issues SSO assertions — configure MFA requirements per consumer, set step-up policies, and understand the supported MFA methods.
MFA Policy Levels
Passport supports MFA enforcement at multiple levels. Policies are evaluated in order — the most restrictive wins:
| Level | Setting Location | Description |
|---|---|---|
| Global | Tenant configuration | MFA required for all users in the tenant, regardless of which app they access |
| Consumer | Consumer registration | MFA required when accessing a specific application — overrides global if stricter |
| Role-based | Role configuration | MFA required for users with specific roles (e.g., all admin users must use MFA) |
| Step-up | Consumer registration | MFA required on each new session to this consumer, even if Passport session exists |
Supported MFA Methods
TOTP
Time-based One-Time Password. Compatible with Google Authenticator, Authy, Microsoft Authenticator, and any TOTP app. 6-digit code valid for 30 seconds.
SMS OTP
One-time code sent via SMS to the user's registered phone number. 6-digit code, 10-minute validity. Rate-limited to prevent abuse.
FIDO2 / WebAuthn
Hardware security keys (YubiKey, etc.) and platform authenticators (Windows Hello, Touch ID). Phishing-resistant — the strongest MFA option.
Email OTP
One-time code sent to the user's registered email address. Fallback option when other methods are unavailable. 10-minute validity.
Configuring MFA on a Consumer
// Consumer registration with MFA configuration
{
"consumerKey": "finance-erp",
"protocol": "SAML2",
"requireMfa": true,
"mfaPolicy": {
"stepUp": true,
"allowedMethods": ["totp", "fido2"],
"gracePerioMinutes": 0,
"exemptRoles": []
}
}
// requireMfa: true — MFA is required before assertion is issued
// stepUp: true — MFA is required on each new Passport session (not just first login)
// allowedMethods — restrict which MFA methods are accepted for this consumer
// gracePerioMinutes — allow minutes after password auth before MFA is enforced (0 = immediate)
// exemptRoles — roles that bypass MFA for this consumer (use carefully)MFA in OIDC — ACR Values
OIDC provides the acr_values parameter in the authorization request to request a specific authentication context. Passport supports the following ACR values:
| ACR Value | Meaning |
|---|---|
urn:passport:authn:password | Password authentication only |
urn:passport:authn:mfa | Password + any MFA method |
urn:passport:authn:mfa:totp | Password + TOTP specifically |
urn:passport:authn:mfa:fido2 | Password + FIDO2/WebAuthn |
// Request MFA in OIDC authorization request
GET /passport/authorize
?response_type=code
&client_id=finance-app
&scope=openid%20roles
&acr_values=urn:passport:authn:mfa
&...
// The resulting id_token will include:
{
"acr": "urn:passport:authn:mfa:totp",
"amr": ["pwd", "otp"]
}Step-Up Authentication Flow
Step-up authentication forces re-verification of the user's MFA even when an existing Passport session is valid. This is appropriate for high-security applications (financial systems, HR systems, admin consoles).
User has existing Passport session (already logged in)
User navigates to the finance ERP. Passport detects the existing session cookie.
Step-up required
Consumer has stepUp: true. Passport checks whether the current session has a recent MFA verification. If the last MFA was > 0 minutes ago (grace period), step-up is triggered.
MFA Challenge (without re-entering password)
Passport presents only the MFA challenge — the user is not asked for their password again since the session is still valid.
Assertion Issued
After successful MFA, Passport updates the session's MFA timestamp and issues the assertion to the consumer.
The exemptRoles configuration should never include administrative roles. Privileged accounts are high-value targets — compromising an admin account without MFA protection can result in complete tenant takeover. If your admin tool cannot support MFA, reconsider using it.