12. Multi-factor authentication

MFA, sometimes referred to as two-factor authentication or 2FA, is a security enhancement that allows you to present two pieces of evidence - your credentials - when logging in to an account. Your credentials fall into any of these three categories:

  • something you know (like a password or PIN),

  • something you have (like a smart card),

  • something you are (like your fingerprint). Your credentials must come from two different categories to enhance security, so entering two different passwords would not be considered multi-factor.

12.1. TOTP

TOTP(Time-Based One-Time Password Algorithm) is most common used 2fa authentication method come from RFC6238. The algorithm to compute a TOTP code is TOTP(K,C) = Truncate(HMAC-SHA-1(K,C)) where K is secret key shared by server and client, C is time step C = (T - T0) / X (T0 is zero and X is step usually 30s)

There are 3 steps for the whole TOTP authentication:

  1. Server generate a random secret K for client, composed with a URI otpauth://totp/{label}?secret={secret}&issuer={issuer}, display with a QR code.

  2. User use authenticator application (Google authenticator or Microsoft authenticator) on his mobile phone to scan the QR code (This step is mainly to remember the password generated by the server).

  1. When user logon, the authenticator will compute a 6 digital code, the code is changed every 30s (with the Truncate algorithm by the app, so the important is the mobile device should sync time with server). The code is the one time password used to validate for the server.

12.2. TOTP API design

These API endpoints and workflows allow users to generate a TOTP secret key, set up TOTP authentication, validate TOTP tokens, and disable TOTP when necessary.

12.2.1. TOTP Secret Generation:

  • API Endpoint: POST /totp/secret

  • Workflow:

    • Generate a unique TOTP secret key for the user.

    • Store the secret key securely on the server (not ready for TOTP validation).

    • Return the TOTP URI with secret to the client as a response.

    • The user get TOTP URI that they can scan or enter into a TOTP authenticator app (such as Google Authenticator).

12.2.2. TOTP Setup:

  • API Endpoint: POST /totp/setup

  • Workflow:

    • Receive the TOTP secret key from the client.

    • Verify the secret key against the stored secret key on the server.

    • If the secret key is valid, associate it with the user’s account.

    • Return a success response to the client.

12.2.3. TOTP Validation:

  • API Endpoint: POST /totp/validate

  • Workflow:

    • Receive the TOTP token from the client.

    • Retrieve the user’s TOTP secret key from the server.

    • Verify the TOTP token against the secret key.

    • If the token is valid, return a success response to the client.

    • If the token is invalid, return an error response to the client.

12.2.4. TOTP Disable:

  • API Endpoint: POST /totp/disable

  • Workflow:

    • Remove the TOTP secret key association from the user’s account.

    • Invalidate any existing TOTP tokens for the user.

    • Return a success response to the client.

12.3. 2FA in AppMesh

User could active 2FA for itself, the registration will show a QR code for add the user account to the authenticator app. the administrator can also force enable 2FA for a user.

When user logon from command line, the 2FA is required.

12.4. 2FA and more

Usually, 2FA will be a addon to existing JWT authentication, this can be two step validation, 2FA authentication validation information can add to JWT payload, so next time, if no abnormal login, no need require 2FA every time.

The server need record and detect login event, if any risk detected, request client to do the 2FA authentication:

  • login from a new device

  • login from a new location

  • access privacy data

  • do administration operation

For totally backend API integration, request side can implement Truncate algorithm to compute TOTP key.

12.5. Reference