Guides
Multi-Factor Authentication Setup

Multi-Factor Authentication Setup

Multi-Factor Authentication (MFA) adds an extra layer of security by requiring users to provide multiple forms of verification. This guide covers setting up various MFA methods in Skycloak.

Overview

MFA requires users to provide two or more verification factors:

  • Something you know (password)
  • Something you have (phone, hardware token)
  • Something you are (biometrics)

Available MFA Methods

Time-Based One-Time Password (TOTP)

The most common MFA method using authenticator apps.

Supported Apps:

  • Google Authenticator
  • Microsoft Authenticator
  • Authy
  • 1Password
  • LastPass Authenticator

SMS-Based OTP

Send one-time codes via SMS (requires SMS gateway configuration).

Email-Based OTP

Send one-time codes via email (requires SMTP configuration).

WebAuthn/FIDO2

Hardware security keys and platform authenticators.

Supported Devices:

  • YubiKey
  • Google Titan Security Key
  • Windows Hello
  • Touch ID / Face ID

Enabling MFA for a Realm

Basic Setup

  1. Navigate to your realm in Skycloak
  2. Go to Authentication → Required Actions
  3. Enable desired MFA methods:
    • Configure OTP for TOTP
    • WebAuthn Register for security keys
    • Update Password (if forcing password reset)

Authentication Flow Configuration

  1. Go to Authentication → Flows
  2. Select Browser flow
  3. Add execution:
    • Click Add execution
    • Select OTP Form or WebAuthn Authenticator
    • Set to Required or Alternative

TOTP Configuration

Enabling TOTP

  1. In Authentication → Required Actions
  2. Enable Configure OTP
  3. Set as Default Action if needed

TOTP Policy Settings

Navigate to Authentication → OTP Policy:

OTP Type: Time-based (totp)
OTP Hash Algorithm: SHA256
Number of Digits: 6
Look Ahead Window: 1
OTP Token Period: 30

User Enrollment Flow

  1. User logs in with username/password
  2. Prompted to set up MFA
  3. Scan QR code with authenticator app
  4. Enter verification code
  5. Save recovery codes

WebAuthn/FIDO2 Setup

Enabling WebAuthn

  1. Go to Authentication → Required Actions
  2. Enable WebAuthn Register
  3. Configure WebAuthn Policy

WebAuthn Policy

Navigate to Authentication → WebAuthn Policy:

Relying Party Entity Name: Your Company
Signature Algorithms: ES256, RS256
Relying Party ID: yourdomain.com
Attestation Conveyance Preference: none
Authenticator Attachment: platform, cross-platform
Require Resident Key: No
User Verification Requirement: preferred

Passwordless Setup

For passwordless authentication:

  1. Create new authentication flow
  2. Add WebAuthn Passwordless Authenticator
  3. Set as alternative to username/password

SMS OTP Configuration

Prerequisites

  1. Configure SMS gateway provider
  2. Set up SMS authenticator SPI

Setup Steps

  1. Install SMS authenticator extension
  2. Configure provider settings:
    Provider: Twilio/AWS SNS/Custom
API Key: your-api-key
API Secret: your-api-secret
From Number: +1234567890
  3. Enable in authentication flow

Conditional MFA

Risk-Based MFA

Require MFA based on conditions:

// Require MFA for admin roles
function authenticate(context) {
    var user = context.user;
    var roles = user.getRealmRoleMappings();
    
    for (var i = 0; i < roles.size(); i++) {
        if (roles.get(i).getName() === "admin") {
            context.challenge("otp");
            return;
        }
    }
    context.success();
}

IP-Based MFA

Require MFA from untrusted networks:

// Require MFA outside corporate network
function authenticate(context) {
    var clientIP = context.httpRequest.getRemoteAddress();
    var trustedNetwork = "192.168.1.0/24";
    
    if (!isInNetwork(clientIP, trustedNetwork)) {
        context.challenge("otp");
        return;
    }
    context.success();
}

Recovery Options

Backup Codes

  1. Generate during MFA enrollment
  2. Store securely
  3. Single-use only
  4. Regenerate when depleted

Admin Override

Administrators can:

  • Reset user MFA
  • Temporarily disable MFA
  • Force re-enrollment

User Management

Enforcing MFA

For All Users

  1. Set MFA execution as Required in browser flow
  2. Add to default required actions

For Specific Groups

  1. Create custom authentication flow
  2. Use conditional authenticator
  3. Check group membership

For Specific Roles 

// Conditional MFA for roles
if (user.hasRole("sensitive-data-access")) {
    context.challenge("otp");
}

MFA Status Monitoring

View user MFA status:

  1. Go to Users → Select user
  2. Check Credentials tab
  3. View configured MFA methods

Testing MFA

Test Scenarios

  1. New User Enrollment

    • Register new account
    • Complete MFA setup
    • Verify login with MFA

  2. Existing User Migration

    • Enable MFA requirement
    • Test forced enrollment
    • Verify graceful upgrade

  3. Recovery Flow

    • Test with backup codes
    • Admin reset scenario
    • Re-enrollment process

Best Practices

  1. Gradual Rollout

    • Start with pilot group
    • Monitor adoption
    • Address issues before full deployment

  2. User Communication

    • Provide clear instructions
    • Offer multiple MFA options
    • Support documentation

  3. Security Considerations

    • Enforce strong MFA methods
    • Regular security reviews
    • Monitor suspicious patterns

  4. Backup Methods

    • Always provide recovery options
    • Multiple MFA methods
    • Admin override procedures

Troubleshooting

Common Issues

TOTP Time Sync Issues

Problem: Invalid code errors Solution:

  • Check device time settings
  • Increase look-ahead window
  • Sync time on user device

WebAuthn Not Working

Problem: Browser doesn’t prompt for security key Solution:

  • Check HTTPS requirement
  • Verify browser compatibility
  • Check Relying Party ID

SMS Delivery Failures

Problem: Users not receiving SMS codes Solution:

  • Verify SMS gateway configuration
  • Check carrier filtering
  • Review delivery logs

Compliance Considerations

Regulatory Requirements

  • PCI DSS: MFA for admin access
  • HIPAA: MFA for PHI access
  • SOC 2: MFA for production systems
  • GDPR: Strong authentication for personal data

Audit and Reporting

Monitor MFA usage:

  • Enrollment rates
  • Authentication success/failure
  • Method preferences
  • Recovery usage

Next Steps

SIEM Integration GuidePKCE Authentication Setup