MFA Integration Guide – CoffeeBean Technology

Scope

This document aims to detail the integration aspects with the Multi-Factor Authentication (MFA) Platform provided by CoffeeBean Technology.

The main scope focuses on the use of factor management and factor authentication flows provided via the authorization endpoint, following the OAuth 2.0 framework standard.

Platform

CoffeeBean Technology’s MFA platform is composed of three main modules:

MFA APIs: A set of RESTful APIs to be used by public (frontend) or private (backend) client applications.
MFA Plugin: Automated user interfaces for end-user factor management and authentication.
MFA Admin: The platform’s administrative dashboard.

MFA Plugin

The MFA Plugin automates all user interfaces for factor management and authentication flows.

The integration interface with the plugin is based on the OAuth 2.0 authorization framework. The OAuth 2.0 protocol defines two main endpoints:

Authorization Endpoint: Used for user interaction to obtain the necessary authorizations.
Token Endpoint: Used by the client application to obtain an access token based on the user’s granted permissions.

The MFA Plugin leverages the authorization endpoint to provide the required user interactions for managing factors (register, remove, view) and authenticating using previously registered factors.

The simplified diagram below illustrates a basic integration flow, where the client application redirects the user to the authorization endpoint. The user completes the required interactions and is then redirected back to the application using the originally provided redirect_uri, along with the specified response_type, such as an access token.

The authorization endpoint accepts several parameters (see API documentation), including the scope, which defines whether the interaction is for factor management (management) or user authentication (authentication).

Factor Management Flow

The goal of the factor management flow is to allow already authenticated users in the client application to manage their MFA factors. Supported actions include:

Registering new factors
Removing previously registered factors
Viewing all registered factors

To implement this flow, simply redirect the browser to the authorization endpoint with the scope parameter set to management.

According to the endpoint documentation, the management scope requires two additional parameters:

context_type: must be set to mfa_token
context_value: must be an MFA token generated for the currently authenticated user

To generate the MFA token, call the following API on the backend:

POST /oauth/token

With the parameters:

grant_type: https://mfa.coffeebeantech.com/oauth/grant_types/username
username: the unique user identifier (e.g., email, user_id, username, etc.)
scope: management

Important:
For security reasons, this POST /oauth/token request must be performed on the backend of the client application using client_id/client_secret authentication, since the client_secret is a private key that must not be exposed on the frontend.

The final step in the integration is for the client application to implement the redirect callback, known as redirect_uri, which receives the configured response_type. Currently, the accepted response_type is token, which returns the OAuth 2.0 access token for the authorization session.

Example:

HTTP/1.1 302 Found
Location: http://example.com/cb#access_token=6814cd360205e1245d2834ffab3c3c9103b71a5075a9cda4626b4d5c&state=xyz&token_type=Bearer&expires_in=600

In the management flow, the callback (redirect_uri) may optionally check whether the user has any registered factors (via GET /authenticators) and display a message or even persist a flag in the user’s profile to indicate whether a second factor is enabled.
The client-side callback logic is beyond the scope of this document.

Summary – Factor Management Flow

To summarize, the integration steps for the factor management flow are:

Generate the MFA token for the currently authenticated user (backend integration).
Redirect the browser flow to the authorization endpoint (GET /oauth/authorize) with the MFA token and management scope (frontend integration).
Implement the callback (redirect_uri) to receive the access_token if needed (frontend integration).

Factor Authentication Flow

The purpose of the factor authentication flow is to allow users to authenticate using a previously registered second factor to obtain a valid session in the client application.

To implement this flow, redirect the browser to the authorization endpoint with the scope parameter set to authentication.

According to the endpoint documentation, the authentication scope accepts various context_type and context_value combinations. You can pass either:

an MFA token generated via POST /oauth/token, or
a simple username (e.g., email or user ID).

With this information, the authentication flow will display the verified factors registered by the user, allowing them to choose a factor to authenticate.
If the user has only one registered factor, they will automatically receive the challenge (e.g., SMS code) and an input box to enter it.

After successful second-factor authentication, the browser will be redirected to the callback (redirect_uri), just like in the management flow.
At this point, the client application should validate the access token by calling the GET /validations API and checking the following response fields:

username: Confirm that the username in the received access token matches the one that completed first-factor authentication (e.g., email/password).
success_count: Confirm that the user successfully authenticated with one of the registered factors.

If the access_token is successfully validated, the user’s session can be fully authorized in the client application.

Enabling the Factor Authentication Flow

Not all users of the client application will have a second factor registered. In such cases, redirecting them to the authorization endpoint could lead to a poor experience since no factors would be available for authentication.

Handling this scenario is a business logic decision and falls outside the scope of this document.

However, the CoffeeBean MFA platform offers a rich set of APIs to assist in making such decisions. For example, it’s possible to:

Generate an MFA token (POST /oauth/token) with the authentication scope for a user who has completed the first authentication step
Check for registered factors via GET /authenticators
If valid factors exist, proceed to redirect the user to the authorization endpoint using the authentication scope
If not, generate a new MFA token with the management scope and redirect them to register a factor
Alternatively, allow the user to log in normally and manage their factors later

As mentioned in the management flow, it’s also possible to persist a flag in the user’s profile indicating whether they have any registered MFA factors.

Summary – Factor Authentication Flow

To summarize, the integration steps for the factor authentication flow are:

Check whether the user must authenticate with a second factor
Redirect the browser to the authorization endpoint (GET /oauth/authorize), passing the username or MFA token and the authentication scope (frontend integration)
Implement the callback (redirect_uri) to receive the access_token (frontend integration)
Validate the access_token by checking username and success_count (backend integration)

MFA APIs

The complete API documentation is available here, containing detailed specifications for each endpoint.

To summarize, the main APIs used for integrating with the MFA Plugin are:

GET /oauth/authorize: Initiates factor management or authentication flows
POST /oauth/token: Generates an MFA token for a user
GET /validations: Returns all factor validation events for a user within the scope of an MFA token
GET /authenticators: Returns all registered MFA factors for a user