Cloudentity Microservices

The following Cloudentity components are used to support MFA features in the Cloudentity stack.

AuthN Service

The AuthN Service exposes a set of REST APIs for user authentication, according to the various MFA types.

In general, the authentication APIs may be divided into two broad categories:

  • Identifier-based authentication APIs: These APIs are called anonymously (i.e. without an existing session), and are typically used to begin an authentication flow. The user’s identifier must be supplied in the request, along with at least one credential. Upon success, a session token is returned in the response, and an auth event is generated for this session.

    The following identifier-based authentication APIs are available:

    1. Identifier and Password Authentication

    2. Identifier and TOTP Authentication

  • Session-based authentication APIs: These APIs require an existing session — the session token must be supplied in the request, along with at least one credential. They are typically used to continue an existing authentication flow, or to perform stepped-up authentication to access a sensitive resource. Upon success, an auth event is generated for this session.

    The following session-based authentication APIs are available:

    1. Password Authentication

    2. TOTP Authentication

    3. OTP Authentication

    4. KBA Authentication

See the AuthN Service API guide for more details.

User Service

The User Service exposes a set of REST APIs for managing user records. For authentication flows, the User Service is used to register and maintain users and their credentials in the system.

Most MFA flows require a "setup" phase before authentication can be performed, which will be handled by the User Service.

  • For TOTP, the user must enter his/her auth secret into the Google Authenticator app and confirm it with the system.

  • For OTP, the user must successfully verify an email or mobile number to which the generated OTP will be sent.

  • For KBA, the user must select and supply answers for one or more KBA questions.

Many APIs are used for MFA setup — for more information about API flows related to MFA, see the flows guide. For more detailed information about the User Service, see the User Service API guide.

Session Service

The Session Service exposes a set of REST APIs for session verification and retrieval of details.

For MFA flows, the Session Service is primarily used to read MFA setup information from an existing session. Clients of these APIs, including the AuthN UI, can use this information to present MFA setup options to the user.

In particular, the authenticationIdentifier session attribute reflects the identifier used at the beginning of an authentication flow. Clients may utilize this attribute to display a welcome message to the user, regardless of whether the user authenticated by username, email, mobile, or another applicable identifier.

See the Session Service API guide for more details.

Authorization Service (authz-service)

The Authorization Service maintains authorization policies, and exposes APIs for managing and validating these policies.

Authorization policies are used to govern authentication and authorization flows. For example, consider an identifier + password + TOTP authentication flow:

  1. Authenticate using identifier and password

  2. View and confirm TOTP secret (attribute name googleAuthSecret) in order to complete TOTP setup

  3. Complete TOTP authentication

Then the following (pseudo) policy would guide a user through this flow:

If this session is invalid
  Prompt for identifier + password authentication
Else
  If user's googleAuthSecretAccepted is false
    Prompt for user to complete Google Authenticator setup
  Else
    If there is no TOTP Authentication event associated this session
      Prompt for TOTP Authentication
    Else
      Success - User has completed TOTP Authentication

See the Authorization Service API guide for more details.

AuthN Events Service

The AuthN Events Service supplements the Authorization Service’s policy validation engine by exposing APIs to manage auth events.

See the AuthN Events Service API guide for more details.

API Gateway

The API Gateway is a reverse-proxy server with configurable rules for exposing and hiding endpoints for the API microservices. It supplies a generic mechanism for enforcing authentication and authorization on a per-resource basis.

All external traffic to API services must be routed through the API Gateway.

See the API Gateway microservice guide for more details.

Low-Level API Service (LLA)

The Low-Level API Service provides a REST interface which allows other API services to access the datastore and session store. This microservice is designed for internal use only, and is a key component of the Cloudentity stack.

LLAs are not exposed publicly, internal LLA microservice documentation is available on request.

AuthN UI

The AuthN UI is the front-end interface for user authentication flows. It relies heavily on the Authorization Service policy validation engine, as well as the other API services, to guide users through various authentication processes.

This component is not required for MFA functionality — direct API calls may facilitate MFA flows in the absence of the AuthN UI.

Self-Service UI

The Self-Service UI is the front-end interface for user self-service functionality. Users who are authenticated may use this UI to update their MFA information, e.g. by adding and verifying a new email address.

This component is not required for MFA functionality — direct API calls may facilitate MFA setup and update in the absence of the Self-Service UI.

Administrative UI

The Administrative UI is the front-end interface for user management. Users with appropriate permissions may utilize this UI to force other users to reset their MFA credentials, or to send a verification email.

This component is not required for MFA functionality — direct API calls may facilitate user management in the absence of the Administrative UI.

Third-Party Components

The following third-party components are used to support MFA features in the Cloudentity stack.

LDAP Datastore — implementation: OpenDJ

The LDAP datastore holds all persistent data for users, organizations and entitlements. It also holds the global KBA configuration and OTP metadata.

Session Store — implementation: Hazelcast

The session store is used to manage all session information. It allows for storage, retrieval, validation, and invalidation of sessions.

NoSQL Database — implementation: Cassandra

The NoSQL database holds authorization policies managed by the Authorization Service.

Note
 The LDAP datastore may also be used for authorization policy storage.

Webserver — implementation: Nginx

The webserver is used for SSL termination and hosting of static web resources. In some cases it supplements the API Gateway with routing and cookie parameter translation.