Skip to content

ConnectSoft Identity Platform MFA

MFA is owned by Identity Service and projected into tokens by Authorization Server. Gateway and backend services use token assurance claims to enforce sensitive operations.

Ownership

Component Responsibility
Identity Service Stores factors, verifies challenges, manages recovery codes, records MFA status.
Authorization Server Requires MFA during login/step-up and emits amr/acr claims.
API Gateway Enforces MFA-aware route policies.
Backend services Enforce sensitive domain operations and may request step-up.
Shell/MFEs Present MFA UX and retry flows.

Supported Factors

  • TOTP authenticator apps are the default baseline factor.
  • Recovery codes are emergency backup credentials and must be one-time use.
  • SMS and email codes are weaker factors and should be used only with explicit risk acceptance.
  • WebAuthn/passkeys are the preferred future high-assurance factor.

Enrollment Flow

  1. User is authenticated.
  2. User starts enrollment in Identity Self-Service MFE.
  3. Identity generates factor setup data.
  4. User verifies first challenge.
  5. Identity marks factor enabled and issues recovery codes.
  6. Sensitive operations can now require MFA.

Login Challenge

  1. User completes primary authentication.
  2. Identity determines MFA is required.
  3. User submits factor proof.
  4. Identity verifies challenge.
  5. Authorization Server continues token issuance.
  6. Token contains amr and/or acr.

Example:

{
  "sub": "usr_123",
  "amr": ["pwd", "otp"],
  "acr": "urn:connectsoft:loa:2"
}

Step-Up MFA

Step-up MFA is required when the current session is valid but not strong enough for the requested operation.

Typical protected actions:

  • admin client changes;
  • client secret rotation;
  • signing key management;
  • MFA reset for another user;
  • tenant deletion;
  • privileged data export;
  • payment or payout operations.

Gateway or backend returns mfa_required, and Shell starts a step-up flow. After MFA succeeds, Authorization Server issues a token/session with stronger amr/acr, and the operation is retried.

Disable and Admin Reset

User-initiated MFA disable requires re-authentication and should require MFA when possible. Admin reset requires identity.admin, step-up MFA, support/audit reason, and notification to the affected user.

Federation MFA Mapping

Upstream MFA can be mapped into amr/acr only when provider and tenant trust policy allow it. If the upstream provider cannot prove MFA, local step-up is required.

Gateway and Backend Policies

Examples:

POST /api/auth/admin/clients
  require auth.admin
  require acr >= urn:connectsoft:loa:2

POST /api/identity/admin/users/{id}/mfa-reset
  require identity.admin
  require amr contains mfa

Audit Requirements

Audit these events:

  • MFA enrollment;
  • factor removal;
  • failed challenges;
  • recovery code use;
  • step-up completion;
  • admin reset;
  • upstream MFA trust decisions.