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 supports time-based one-time passwords (TOTP) that are compatible with
standard authenticator apps like Google Authenticator, Microsoft Authenticator, and Authy The use of Email is also available as an alternative, with one-time codes sent to the user’s inbox. Different users within your Tenant can be configured either with TOTP, Email, or no 2FA/MFA.

What Is MFA?

MFA requires users to provide two forms of identification:

1. Something they know – Their password
2. Something they have – A one-time code from an authenticator app (TOTP), or from email

This significantly reduces the risk of unauthorized access, even if a password is compromised. Authenticator app MFA uses TOTP as specified in RFC 6238: time-based codes that change every 30 seconds. Email MFA delivers short lived codes to the user’s inbox instead of using an app.

How MFA Works

The steps below describe the authenticator app (TOTP) path, which is the main flow. Email MFA is simpler for users who prefer inbox codes: they receive a one-time code by email and enter it on the same verification screen instead of using an app.

First-Time Setup

When authenticator app 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. For authenticator-app MFA, that flow typically looks like this:

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 an MFA code during every login:

1. User enters their username and password
2. If password is correct, the service prompts for the MFA code
3. The user enters the MFA code – typically the current 6-digit code from their authenticator app (codes refresh every 30 seconds). With email MFA, they use the code from their email instead.
4. If the code is valid, login proceeds and tokens are issued

The service validates the code whether it came from an app or from email.

Resetting MFA

If a user loses their device or needs to reset their MFA, administrators can reset it for them. When authenticator app 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}/v2/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}/v2/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}/v2/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 MFA enrollment (including the TOTP secret used for both app and email-based MFA) is cleared. If they are configured for authenticator app MFA then they will need to complete MFA setup again on their next login – for example by scanning the QR code again for an authenticator app. If they are configured for email MFA then there is no user setup required, and codes will simply be emailed to them.

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.