Tags:

• aura-authentication
• aura-user

Categories:

• components

Aura Authentication API

Introduction

aura-authentication-api is the component in charge of the management of the users’ authentication in Aura. It is a web server with several endpoints dedicated to handle users in Aura or to allow the access of the users to aura-bot.

The web server is built on Typescript 4.3 using Nodejs as engine. It is api-first designed, using Open API v3 to provide the API definition.

The authorization used in the server is based on an APIKey, which is ciphered for the environment and generated to access to a group of endpoints or only to a given path or a specific consumer.

Find detailed information regarding aura-authentication-api:

• Communication protocol and components.
• Environment variables
• Endpoints
• Logout of Webclient users via redirection
• Aura authentication API Codebase
• Aura Authentication API definition

Communication protocol

aura-authentication-api communication protocol is completely synchronous, this means that the answer of a request is included in the HTTP response related to the incoming request.

Aura authentication API components

Server

The web server is implemented using express, that is the main web framework for Nodejs. It uses oas-tools on top of Express, to allow handling the Open API v3 file.

It is in charge of setting up all the rest of the components that are needed during a request processing, as well as reading the before mentioned swagger file and setting up all the routes defined in it.

Middlewares

Each route published in the API definition file is handled by a controller, but before a request lands on its controller, it goes through a series of middlewares, that provide some common steps needed by all the controllers of the server such as: request authorization, request validation, common parameters extraction, logging, metrics initialization, etc.

Controllers & Services

Then, the request lands on the controller. Each controller processes the request through a service in charge of implementing the logic. Once the request has been processed, the controller prepares and sends the response.

Database access

Some of the services of the aura-authentication-api access aura-users database to validate, get or update users’ information.

This database is a MongoDB one, with a collection that holds all the existing and valid Aura users. To access this collection, the server implements a data access object with the queries needed by the services. This object is a class called UserDao that provides a single access to the database, isolating the services from the real database schema and internal implementation.

The entity relationship diagram of this database is:

erDiagram
    users {
        string auraId
        string id
        string auraGlobalId
        string channelId
        string userId
        string authorizationId
        string authenticationType
        string authenticationIdentifier
        string idTokenHint
        date created
        date lastAccess
        date expiresAt
    }
    aura-version-control {
        string id
        string name
        string history
        date timestamp
        string version
    }

Collections description

• users:

  • _id: Internal MongoDB identifier. Not used by the service.
  • auraId: Identifier of the user in Aura.
  • auraGlobalId: Cross-channel identifier of the same authentication (type and identifier) of a user.
  • channelId: UUID that univocally identifies the channel that lead the authentication session in Aura.
  • userId: Kernel user identifier
  • authorizationId: Identifier of the authentication session in Kernel. UNIQUE.
  • authenticationType: Type of authentication used by the user. Values: email, uid, network, phone_number.
  • authenticationIdentifier: Identifier used by the user during the authentication.
  • idTokenHint: Token generated during the authentication of internal channels.
  • created: Date when the user was created.
  • lastAccess: Last date access of the user.
  • expiresAt: Time when the user authentication should be discarded.

• aura-version-control:

  • _id: Internal MongoDB identifier.
  • name: Name of the index being handled.
  • history: Array of objects with all the versions already applied.
  • timestamp: Date when the version was applied.
  • version: Version of the database-index definition file applied.

Users database cache

Users collection data stored in MongoDB are also cached in Redis to increase request’s speed. The time to live of these documents in cache is configurable with the aura-authentication-api environment variable AURA_REDIS_CACHE_TTL.

Anonymous users

aura-authentication-api can return auto-generated anonymous users if needed for anonymous KPIs instead of returning 404 if the user is anonymous.

To enable this feature, you should include two new headers when the call to the endpoint /aura-services/v1/users/{auraId} is done:

• return-anonymous: Boolean header to enable this feature.
• x-4p-channel-id: UUID which identifies the Aura channel. This is needed to generate a consistent user data for this anonymous user.