Multi-Factor Authentication

OpenGate IAM provides MFA via the dedicated opengate-mfa-service (port 8086). It supports TOTP, Email OTP, and backup codes.

On this page

• Supported Methods
• MFA Login Flow
• TOTP Enrollment
• Email OTP
• Backup Codes
• Enforce MFA per Realm

Supported Methods

MFA Login Flow

When mfaRequired: true is set on a realm:

  Client                Auth Service              MFA Service
    │                        │                         │
    │ 1. POST credentials    │                         │
    │───────────────────────►│                         │
    │                        │ 2. Password valid       │
    │ 3. { status:           │                         │
    │      "MFA_REQUIRED",   │                         │
    │      mfa_token }       │                         │
    │◄───────────────────────│                         │
    │                        │                         │
    │ 4. POST /api/mfa/      │                         │
    │    totp/verify         │                         │
    │    { code, mfa_token } │────────────────────────►│
    │                        │                         │ 5. Verify TOTP
    │                        │◄────────────────────────│
    │                        │ 6. Issue access_token   │
    │◄───────────────────────│                         │

TOTP Enrollment

# Step 1 — Initiate enrollment
curl -X POST \
-H "Authorization: Bearer $TOKEN" \
http://localhost:8080/api/mfa/totp/enroll

Response:

{
"secret": "JBSWY3DPEHPK3PXP",
"qrCodeUri": "otpauth://totp/OpenGate:alice@example.com?secret=JBSWY3DPEHPK3PXP&issuer=OpenGate",
"enrollmentId": "enroll-uuid-123"
}

# Step 2 — Confirm with first 6-digit code from authenticator app
curl -X POST \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{ "enrollmentId": "enroll-uuid-123", "code": "123456" }' \
http://localhost:8080/api/mfa/totp/confirm

Email OTP

# Trigger email OTP (sends 6-digit code to verified email)
curl -X POST \
-H "Authorization: Bearer $TOKEN" \
http://localhost:8080/api/mfa/email-otp/send

# Verify the code (valid for 10 minutes)
curl -X POST \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{ "code": "847291" }' \
http://localhost:8080/api/mfa/email-otp/verify

Backup Codes

# Generate 10 one-time backup codes
curl -X POST \
-H "Authorization: Bearer $TOKEN" \
http://localhost:8080/api/mfa/backup-codes/generate

{
"codes": [
  "AAAA-BBBB", "CCCC-DDDD", "EEEE-FFFF",
  "GGGG-HHHH", "IIII-JJJJ", "KKKK-LLLL",
  "MMMM-NNNN", "OOOO-PPPP", "QQQQ-RRRR",
  "SSSS-TTTT"
]
}

Enforce MFA per Realm

curl -X PUT \
-H "Authorization: Bearer $ADMIN_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "mfaRequired": true }' \
http://localhost:8080/api/realms/my-realm

When enabled, every user in the realm must complete MFA before receiving tokens.