Multi-Factor Authentication

Authentication Factors

• Something you know: Password, PIN, security question
• Something you have: Phone, hardware token, authenticator app
• Something you are: Fingerprint, facial recognition, biometrics

How TOTP Works

1. A shared secret is generated and stored securely on the server
2. The secret is shared with the user's authenticator app (via QR code or manual entry)
3. Both server and app use the same algorithm to generate codes based on the current time
4. User enters the code from their app to verify they have the device
5. Server validates the code matches what it expects for the current time window

# Step 1: Normal OAuth2 authentication
POST /oauth/authorize
  client_id=YOUR_CLIENT_ID
  redirect_uri=YOUR_REDIRECT_URI
  scope=openid profile email
  state=RANDOM_STATE
  code_challenge=CODE_CHALLENGE
  code_challenge_method=S256

# Step 2: User enters username/password
# If MFA is enabled, server responds with:
{
  "mfa_required": true,
  "mfa_token": "temp_token_abc123"
}

# Step 3: User enters TOTP code
POST /oauth/authorize/mfa
Content-Type: application/json

{
  "mfa_token": "temp_token_abc123",
  "code": "123456"
}

# Step 4: On success, complete OAuth flow
Response: 302 Redirect
Location: YOUR_REDIRECT_URI?code=AUTH_CODE&state=RANDOM_STATE

Using Backup Codes

POST /oauth/authorize/mfa
Content-Type: application/json

{
  "mfa_token": "temp_token_abc123",
  "backup_code": "1234-5678"
}

Response:
{
  "success": true,
  "remaining_codes": 2
}

Recovery Options

TypeScript/React Example

import { useState } from 'react';
import { OAuth42Client } from '@oauth42/sdk';

const client = new OAuth42Client({
  clientId: 'your_client_id',
  redirectUri: 'http://localhost:3000/callback'
});

// Setup MFA
async function setupMFA(accessToken: string) {
  const response = await fetch('/api/mfa/setup', {
    headers: {
      'Authorization': `Bearer ${accessToken}`
    }
  });

  const { secret, qrCode, backupCodes } = await response.json();

  // Display QR code to user
  return { secret, qrCode, backupCodes };
}

// Verify MFA setup
async function verifyMFASetup(accessToken: string, code: string) {
  const response = await fetch('/api/mfa/verify-setup', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ code })
  });

  const result = await response.json();
  return result.success;
}

// Login with MFA
async function loginWithMFA(username: string, password: string) {
  // Step 1: Initial authentication
  const authResponse = await client.authenticate(username, password);

  if (authResponse.mfa_required) {
    // Step 2: Prompt for MFA code
    const mfaCode = await promptUserForMFACode();

    // Step 3: Complete MFA challenge
    const tokens = await client.completeMFA(
      authResponse.mfa_token,
      mfaCode
    );

    return tokens;
  }

  return authResponse.tokens;
}