Multi-Factor Authentication (MFA)

Multi-Factor Authentication (MFA), also known as Two-Factor Authentication (2FA), adds an extra layer of security to user accounts. The Agglestone Authentication and User Management Service uses time-based one-time passwords (TOTP) that are compatible with standard authenticator apps like Google Authenticator, Microsoft Authenticator, and Authy.

What Is MFA?

MFA requires users to provide two forms of identification:

1. Something they know – Their password
2. Something they have – A code from their authenticator app

This significantly reduces the risk of unauthorized access, even if a password is compromised. The service uses TOTP (Time-based One-Time Password) as specified in RFC 6238, which generates time-based codes that change every 30 seconds.

How MFA Works

First-Time Setup

When MFA is enabled for a user (either by an administrator or during the login flow), they’ll be prompted to set up MFA on their first login attempt:

1. QR Code Display: The service generates a QR code that contains the TOTP secret
2. Scan with Authenticator App: The user scans the QR code with their favorite authenticator app (Google Authenticator, Microsoft Authenticator, Authy, etc.)
3. Verification: The user enters a code from their authenticator app to verify the setup
4. MFA Enabled: Once verified, MFA is enabled for that user

The QR code can be scanned with any TOTP-compatible authenticator app. The setup process is quick and straightforward, taking just a few seconds.

Subsequent Logins

After MFA is set up, users will be prompted for their authenticator code during every login:

1. User enters their username and password
2. If password is correct, the service prompts for the MFA code
3. User opens their authenticator app and enters the current 6-digit code
4. If the code is valid, login proceeds and tokens are issued

The authenticator codes change every 30 seconds, so users always enter a fresh code. The service validates the code against the user’s TOTP secret to ensure it’s correct.

Resetting MFA

If a user loses their device or needs to reset their MFA, administrators can reset it for them. When MFA is reset, the user will be prompted to set up MFA again on their next login.

Admin-Initiated MFA Reset

Administrators can reset a user’s MFA through the Users API:

// Reset user's MFA (admin operation)
public async Task ResetUserMfaAsync(string userId)
{
    var tenantId = "your-tenant-id";
    var request = new
    {
        resetTOTP = true
    };

    var response = await httpClient.PutAsJsonAsync(
        $"https://auth.agglestone.com/tenant/{tenantId}/api/Users/{userId}",
        request
    );
    response.EnsureSuccessStatusCode();
}

// Reset user's MFA (admin operation)
async function resetUserMfa(userId) {
  const tenantId = 'your-tenant-id';
  const response = await fetch(
    `https://auth.agglestone.com/tenant/${tenantId}/api/Users/${userId}`,
    {
      method: 'PUT',
      headers: {
        'Authorization': `Bearer ${adminToken}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        resetTOTP: true
      })
    }
  );

  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }
}

# Reset user's MFA (admin operation)
async def reset_user_mfa(user_id):
    tenant_id = "your-tenant-id"
    async with httpx.AsyncClient() as client:
        response = await client.put(
            f"https://auth.agglestone.com/tenant/{tenant_id}/api/Users/{user_id}",
            headers={
                "Authorization": f"Bearer {admin_token}",
                "Content-Type": "application/json"
            },
            json={
                "resetTOTP": True
            }
        )
        response.raise_for_status()

When MFA is reset, the user’s TOTP secret is cleared, and they’ll need to go through the QR code setup process again on their next login.

MFA Configuration

Administrators can configure MFA settings per tenant:

• MFA Attempt Limits: Configure the maximum number of failed MFA code attempts before lockout
• Lockout Period: Set how long users must wait after reaching the attempt limit before trying again
• Per-User Control: Enable or disable MFA for individual users

These settings allow you to balance security with user experience, ensuring strong protection without being overly restrictive.

> 📚 API Documentation: For detailed API documentation, request/response schemas, and to try out the endpoints interactively, visit the Swagger UI.

—

Ready to learn more? Check out the Login and Logout Guide to understand the authentication flow, or learn about Password Management for password reset functionality.