Documentation base URLs use placeholder https://{your-tenant}.sso.id. Log in to show your tenant or custom domain.
Log in for Your Tenant URL
Chapter 7 — Phishing-Resistant Zero-Trust MFA

Multi-Factor Authentication & FIDO2 Passkeys

Protect every login with phishing-resistant FIDO2 / WebAuthn Biometric Passkeys (FaceID, TouchID, Windows Hello, YubiKey), TOTP Authenticator Apps, Email OTP, and Twilio / AWS SNS / MessageBird SMS OTP — including Multi-Factor Step-Up (requireMultipleFactors) across Tenants, Applications, Organizations, and Organization Units.

The Zero-Trust Story 1. Supported MFA Factors 2. FIDO2 Passkeys Deep-Dive 3. Multi-Factor Step-Up 4. SMS & Email OTP Gateways 5. MFA & Passkey APIs & AI Prompt
Security Story: Stopping Adversary-in-the-Middle (AiTM) Phishing Cold

How CloudPulse Upgraded from SMS Codes to FIDO2 Passkeys & Multi-Factor Step-Up

During a red-team penetration test, security researchers attempted a real-time reverse-proxy phishing attack against CloudPulse's administrators. Because CloudPulse had enabled FIDO2 WebAuthn Passkeys (fido2PasskeysEnabled) and Multi-Factor Step-Up (requireMultipleFactors) in /multi-factor and /settings, the browser's hardware enclave cryptographically bound the WebAuthn signature to https://{your-tenant}.sso.id/auth — rendering the phishing proxy 100% useless.

1. The Four Native MFA Factors in SSO.ID v2

Manage tenant-wide MFA factors in /multi-factor (or inside /settings → Security & MFA), and override them per Application, Organization, or Organization Unit:

1. FIDO2 / WebAuthn Passkeys (fido2PasskeysEnabled)

Hardware-backed asymmetric cryptography using Apple FaceID/TouchID, Windows Hello, Android Biometrics, or USB/NFC YubiKeys. Can be enforced as a second factor or enabled as Passkey-as-Primary Passwordless Login (passkeyAsPrimary).

2. TOTP Authenticator App (RFC 6238)

Time-based One-Time Passwords compatible with Google Authenticator, Microsoft Authenticator, Authy, 1Password, and Bitwarden via QR code enrollment.

3. Email Verification OTP (/api/multifactor/factors/email)

Delivers time-bound numeric verification codes through your custom SMTP server using your branded MFA OTP HTML email template.

4. SMS OTP (Twilio, AWS SNS, MessageBird)

Delivers SMS verification codes worldwide via your configured SMS gateway in /settings with live test verification (POST /api/settings/tenant/sms/test).

Flow Diagram Adaptive MFA & FIDO2 Passkey Evaluation Flow
flowchart TD P["Primary Login Verified (Password / Social / Passkey)"] --> POL{"MFA Required by Policy?"} POL -->|"Disabled"| OK["Issue Session & Tokens"] POL -->|"Optional / Grace Period"| ENR{"User Enrolled or Remembered?"} POL -->|"Enforced"| CH{"Select Enabled Factor"} ENR -->|"Trusted Device"| OK ENR -->|"Prompt Enrollment"| CH CH -->|"FIDO2 Passkey"| W["WebAuthn navigator.credentials.get()"] CH -->|"TOTP / Email / SMS"| OTP["Verify 6-Digit OTP Code"] W --> OK OTP --> OK
After primary credential verification, Auth.SSO.Id evaluates tenant/app/org MFA policy, grace periods, and trusted device cookies before issuing a session.
https://cloudpulse.us.beta.sso.id/multi-factor Click to zoom
Multi-Factor Authentication console at /multi-factor showing Phone Message, Email, sso.id Mobile App, and Authenticator App toggles.
Multi-Factor Authentication console at /multi-factor showing Phone Message, Email, sso.id Mobile App, and Authenticator App toggles.
https://cloudpulse.us.beta.sso.id/settings Click to zoom
Tenant Settings — Multi-Factor & FIDO2 Passkeys policy controls (enforcement, grace period, remember device, and passkey options).
Tenant Settings — Multi-Factor & FIDO2 Passkeys policy controls (enforcement, grace period, remember device, and passkey options).

2. FIDO2 / WebAuthn Passkey Ceremonies (Auth.SSO.Id)

SSO.ID v2 implements the W3C WebAuthn Level 2 specification natively on https://{your-tenant}.sso.id/auth:

1

Enrollment Ceremony (/auth/oauth/passkey/register-begin → /register-complete)

Logged-in users can register multiple passkeys (e.g., MacBook TouchID + iPhone FaceID + Backup YubiKey). The server issues a cryptographic challenge and Relying Party ID (rpId), the browser invokes navigator.credentials.create(), and the signed public key is stored in SSO.ID.

2

Authentication Ceremony (/auth/oauth/passkey/auth-begin → /auth-complete)

During sign-in, SSO.ID issues a PublicKeyCredentialRequestOptions challenge, the browser invokes navigator.credentials.get(), and SSO.ID verifies the cryptographic signature and counter (preventing cloned authenticator attacks).

3. Multi-Factor Step-Up (requireMultipleFactors) & Tier Overrides

For regulated financial, healthcare, or defense workloads, a single second factor may not suffice. Enabling Require Multiple Factors (requireMultipleFactors) on a Tenant, Application, Organization, or Organization Unit requires the user to complete all active factors configured for that tier before a token is issued.

4. Configuring Twilio, AWS SNS & MessageBird SMS Gateways

In /settings → Security & MFA / SMS Provider, choose your SMS provider:

  • Twilio: Account SID, Auth Token, and From Phone Number / Messaging Service SID.
  • AWS SNS: AWS Access Key ID, Secret Access Key, Region, and Sender ID.
  • MessageBird: Live API Access Key and Originator.
  • Click Send Test SMS (POST /api/settings/tenant/sms/test) to verify delivery before enabling SMS MFA for end users.

5. MFA & Passkey API Reference & AI Prompt

Method Endpoint Description
GET https://{your-tenant}.sso.id/api/multifactor/factors Lists all MFA factors and their status in the tenant (PUT /api/multifactor/factors/{id} updates a factor).
PUT https://{your-tenant}.sso.id/api/multifactor/factors/email Enables or disables Email OTP MFA at the tenant level.
GET / PUT https://{your-tenant}.sso.id/api/applications/{id}/factors Gets or updates MFA factors overridden for a specific Application (also available on /api/organizations/{id}/factors and /api/organization-units/{id}/factors).
POST https://{your-tenant}.sso.id/auth/oauth/passkey/register-begin Starts FIDO2 WebAuthn passkey registration (POST /auth/oauth/passkey/register-complete finishes).
POST https://{your-tenant}.sso.id/auth/oauth/passkey/auth-begin Starts FIDO2 WebAuthn passkey sign-in (POST /auth/oauth/passkey/auth-complete finishes).
AI Agent Prompt Implement FIDO2 Passkey Login & Step-Up MFA Verification 
You are a security engineer. Implement **FIDO2 Passkey Registration and Step-Up MFA Enforcement** in our web application using **SSO.ID v2** (`https://{your-tenant}.sso.id/auth` and `https://{your-tenant}.sso.id/api`).

1. Build a browser WebAuthn client (`passkeyService.ts`) that calls:
   - `POST https://{your-tenant}.sso.id/auth/oauth/passkey/register-begin` -> `navigator.credentials.create()` -> `POST https://{your-tenant}.sso.id/auth/oauth/passkey/register-complete`
   - `POST https://{your-tenant}.sso.id/auth/oauth/passkey/auth-begin` -> `navigator.credentials.get()` -> `POST https://{your-tenant}.sso.id/auth/oauth/passkey/auth-complete`
2. Build a backend middleware `requireStepUpMfa` for sensitive operations (such as wire transfers or API key creation) that checks the JWT `amr` (Authentication Methods References) claim and redirects the user to `https://{your-tenant}.sso.id/auth/oauth/authorize?prompt=login` if hardware/MFA verification is not present.