Aura – aura-authentication

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Aura authentication API definition

Description of Aura Authentication API swagger

Download swagger file

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Aura authentication flow

Description of the authentication flow for Aura users

The authentication validation process

Before starting a conversation with aura-bot, the channel needs to set a valid auraId and a fresh DirectLine token, if accessing via Direct Line, that should be sent as authorization header of bearer type in the request to the bot.

Find further information about Direct Line request in MS DirectLine API description.

Authentication validation in aura-bot consists of two phases:

Validate that the Direct Line token is a valid one, generated by the bot instance running behind aura-bot.
Validate the Aura credentials of the user, currently only based on Kernel authentication. If request authentication fails, the message is no longer processed, and an unauthenticated error response is returned to the channel.

An Aura channel should send its auraId in the from.id field of the request to the bot. Once the Direct Line token has been validated, aura-bot reads the from.id field to validate it:

Firstly, aura-bot checks if the auraId exists in the AuraUsers database and, if exists, then goes on with the authentication in Kernel.
- If the channel allows anonymous users: In the happening that the received auraId does not exist in the AuraUsers database, then the user is marked as anonymous and the Kernel authentication validation is not launched.
- If the channel does not allow anonymous users, then an UNAUTHENTICATED error is sent to the channel, informing that the Kernel authentication process must be relaunched before going on.
Kernel authentication validation:
- A new fresh Kernel accessToken is requested for the userId and authorizationId related to the auraId.
- If the authorizationId is invalid or no longer exists in Kernel, then an UNAUTHENTICATED error is sent to the channel, informing that the Kernel authentication process must be relaunched before going on.
- Then a fresh Kernel introspect token is requested, so deeper information about the user identities and permissions for aura-bot is obtained.
- Finally, the Kernel UserProfile info is obtained and processed to obtain further information about the user’s contract, for instance, its subscription type.
- After that, all this information is stored in a cache during the time when Kernel accessToken is valid. During this period, the authentication validation process is avoided.
- Besides, all this information is set in the AuraUser model and stored in the conversation context of the bot to be available during the rest of the conversation messages processing.

The authentication process is managed by the fourth-platform-authorization-middleware.

Users data storage

Authenticated users

Users database

When a user authenticates with the basic authentication mechanism of a channel, the user’s information is created/updated in MongoDB and aura-bot accesses it through the aura-authentication-api API Aura Services API published in Kernel.

For instance, in WhatsApp, when the user authenticates with SMS-OTP, her information is stored in AuraUsers database.

Local cache

It is the node cache that each pod has with information from the users.

The information is saved on each request and expires in 5 minutes, configurable via AURA_USER_LOCAL_CACHE_TTL environment variable.

Remote cache

Mongo cache with aura-bot users’ information. It is shared by all pods.

The information is saved on each request and expires in 1 hour, configurable via AURA_MONGODB_BOT_COLLECTION_CACHES_INDEX_TTL environment variable.

Anonymous users

Local cache

Node cache to store anonymous users’ information, who are accessing each pod.

The information expires in 5 minutes, configurable via AURA_USER_LOCAL_CACHE_TTL environment variable.

Both types of users

BotFramework conversational cache

This is the conversational cache of BotFramework, which is called internally in aura-bot persistentData.

It is a MongoDB cache with three parts: ConversationData, UserData and AuthData. Therefore, as this section is related to users’ information, it is stored in the last two sections.

Find more information about cache module.

How does the authenticated user’s cache expire?

The expiration of the cache depends on different factors:

The TTL of each cache element.
Kernel accessToken is no longer valid.
If the accountRemovalTimestamp of the conversational cache is greater than the timestamp of the cache

Authentication process flowchart

The following flowchart shows the authentication process:

Authentication steps

getUserData()

This function gets the user’s data from AuraUsers database, accessing through the Aura Services API published in Kernel.

If the endpoint returns a 404 error, null is returned by the function because in this case the user is anonymous, but it depends on the channel configuration to mark it as an error, if the channel does not support anonymous users ( for example, novum-mytelco channel), or as a valid anonymous users, for channels that allowed them (such as WhatsApp or Aura Webclient).

If other error is returned, the function throws an error and the authentication flow ends.

In the normal flow, the endpoint returns a user and the function returns a AuraUserModel object:

{
   "userAuraId":"c2aa81f0-abd9-444f-b7cb-47c179f10556",
   "userAuraIdGlobal":"d065dba31c79090a9e3c5afa94558d0c39ffa90c8e136931a5a12069418efad5",
   "userChannel":{
      "id":"45494a5b-835a-4fff-a813-b3d2be529dbe",
      "dialogs":[

      ],
      "outputMessageFormat":null,
      "allowAnonymous":null,
      "name":null,
      "shortName":null,
      "fpaAuthIntegrated":null
   },
   "authorizationId":"",
   "userPhoneNumber":"+34600000003",
   "userClientId":"up24456789",
   "timestamp":1575366984,
   "userPhoneType":null,
   "userSubscriptionType":null,
   "userAccessToken":null,
   "introspectScopes":null,
   "userProfile":null,
   "userType":null,
   "userAccountNumber":null
}

getChannelConfiguration()

This method returns an ChannelConfiguration object. This function tries to obtain the channel configuration by the channelId or channelName passed as parameters.

{
  "dialogLibraries": [
    {
      "name": "common",
      "dialogs": [
        {
          "id": "greetings",
          "allowAnonymous": true,
          "triggerConditions": [
            {
              "intent": "intent.common.greetings"
            }
          ]
        }
      ]
    }
  ],
  "id": "45494a5b-835a-4fff-a813-b3d2be529dbe",
  "name": "novum-mytelco",
  "nlp": {
    "enabled": true,
      "enabled": true
    }
  },
  "prefix": "nov",
  "requestOptions": {
    "requestOptionsVersion": {
      "1": {
        "channel": "directline"
      }
    }
  },
  "responseOptions": {
    "dialogContext": {
      "cardActions": {
        "generate": "always",
        "generateList": true
      },
      "defaultListType": "ordinalCardinal",
      "disabled": false,
      "normalizeTerms": true,
      "processFromClient": true,
      "promptChoice": {
        "generate": "always",
        "generateList": true
      },
      "returnToClient": false
    }
  },
  "security": {
    "authPurposes": "customer-self-service identify-customer aura-technical-problems-purpose",
    "channelId": "novum-mytelco"
  }
}

getInitialUserType()

This method returns an initial approach of the userType, because at this point some user types cannot be inferred.

Depending on the channel configuration and the user returned by getUserData(), there are four possible scenarios:

getUserData() returns a valid user
- The user has userType
  - User.userType is returned
- The user does not have userType
  - Undefined is returned
getUserData() returns null
- The channel allows anonymous
  - Anonymous is returned
- The channel does not allow anonymous
  - Unauthenticated is returned

At this point, we can have three different flows:

If the user is anonymous, it is returned with the minimal data available.
If the user is unauthenticated and the channel have integrated auth, getIntegratedAuthIntent() is called but if the channel does not have integrated auth, an error is returned and the authentication ends.
If the user is undefined or other type, it starts the flow to obtain the data from Kernel.

getIntegratedAuthIntent() (Only unauthenticated users)

This method returns the intent to redirect to the integrated authentication.

This intent is returned in user.redirectIntent provided by the authentication function.

getUserAccessToken()

This method constructs the options object with scopes, purposes, authorizationId, deviceId, security.channelId and userId. Afterwards, it makes the request and obtain the token.

If an error occurs, the function will throw an error and the authentication ends with error.

security.channelId is added when requesting the jwt-bearer.

getUserProfile()

This method returns the user profile from Kernel. If there is any error, it will be thrown and the authentication will end with error.

{
    "id": "up24456789",
    "name": "ESP - Usuario de Prueba 2 - prepago",
    "id_document": {
      "country": "ESP",
      "type": "NIF",
      "value": "712724440A"
    },
    "identities": [
      {
        "type": "phone_number",
        "id": "+34600000003",
        "services": ["mobile_prepaid"],
        "roles": ["owner", "admin"]
      }
    ]
}

getAnonymousUserProfile()

This method returns the user profile from Kernel, for anonymous users. If there is any error, it will be thrown and the authentication will end with error.

[
  {
    "identities": [
      {
        "roles": [
          "owner"
        ],
        "id": "12SIME16",
        "services": [
          "authentication"
        ],
        "type": "uid"
      },
      {
        "roles": [
          "owner",
          "basic",
          "admin"
        ],
        "id": "+34680395460",
        "services": [
          "mobile_postpaid"
        ],
        "type": "phone_number"
      },
      {
        "roles": [
          "owner",
          "basic",
          "admin"
        ],
        "id": "+34911725467",
        "services": [
          "landline",
          "internet"
        ],
        "type": "phone_number"
      },
      {
        "id": "CD53D6C5285CB60DD8E50052C1DBFADDDA033613",
        "type": "uid",
        "roles": [
          "owner"
        ],
        "services": [
          "authentication"
        ]
      }
    ],
    "id": "CD53D6C5285CB60DD8E50052C1DBFADDDA033613"
  }
]

encodeAnonymousData()

This method sets the userId and auraIdGlobal for anonymous users. These values are needed to be stored in KPIs.

{
  "userId": "76661cf96c2bda27c4fb016627f2d74af1c3cee496b76cf5d7bc2b2ad8a38cb2",
  "auraIdGlobal": "8eeb101175bfe9c247e9d10669c0d1696e8034f8e1a12b25b54780e00de0e1c1!616e6f6e796d6f7573"
}

getAuraUserType()

This method returns the final userType and the userIdentity.

First of all, identities are filtered and only the type phone_number with services prepaid, postpaid, control, hybrid or internet are returned.
After that, we need to select the phone number of the user among the numbers filtered.
- If we have more than 1 number and userData do not have userPhoneNumber (the user has not been logged with phone number), the userType returned is multimsisdn and userIdentity is undefined.
- If there is only 1 phone number, userType is monomsisdn.
- If there are many phones but we also have userPhoneNumber in userData, this phone is searched in phones array and if found, the user is considered monomsisdn although it is multimsisdn.

Monomsisdn users return userType (prepaid, postpaid or control) and userIdentity filled:

{
   "type":"phone_number",
   "id":"+34600000003",
   "services":[
      "mobile_prepaid"
   ],
   "roles":[
      "owner",
      "admin"
   ],
   "phone_type":"mobile",
   "subscription_type":"prepaid",
   "identifier":"+34600000003"
}

getIntrospect()

This method returns the scopes, purposes and boundScopes for this user from Kernel.

{
   "scopes":[
      "event-low-data-read",
      "insights-data-usage-result-read",
      "mobile-balance-transfer-write",
      "auraid-read",
      "webviews-phone-number-read",
      ...
   ],
   "purposes":[
      "sim-upgrade-suggestion",
      "identify-customer",
      "customer-self-service",
      "aura-read-insight-events",
      "device-recommendations",
      "detect-abnormal-usage"
   ],
   "identifierBoundScopes":[

   ]
}

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Aura Authentication API environment variables

Notation

List of environment variables defined for Aura Authentication API

Properties marked in bold are mandatory.
Properties marked in italics are optional.

Property	Type	Description	Modifiable by OB?
AURA_AUTHENTICATION_BLOCK_MODE	string	DEPRECATED. No longer used during installations. Flag to indicate if the server allows users’ registration, users’ reading or everything. Possible values: `write`, `writeread` and `unblocked`. By default, `unblocked`.	NO
AURA_AUTHORIZATION_HEADER	string	Complete authorization header to be sent to aura-authentication-api, with the following format: `APIKEY xxxxxx`.	YES, but only if the previous APIKey was deprecated.
AURA_CHANNELS_CONFIGURATION_API_ENDPOINT	string	Endpoint for aura-configuration-api.	NO
AURA_DEFAULT_LOCALE	string	Culture code to be used by default in the current deployment: `de-de`, `en-gb`, `es-es`, `pt-br`.	NO
AURA_DEFAULT_TIME_ZONE	string	Timezone where the service is running.	NO
AURA_DIRECTLINE_API_ENDPOINT	string	Direct Line API URL to create tokens and conversations in the current environment. By default, `https://directline.botframework.com/v3/directline/conversations`.	NO
AURA_DIRECTLINE_SECRETS	string	Comma-separated list of strings with all the existing Direct Line secrets of the current instance to be used to generate tokens and conversations.	NO
AURA_ENCRYPTION_ALGORITHM	string	Encryption algorithm that will be used to validate the APIKey. By default: `aes-256-cbc`.	NO. It would break APIKey and state validation.
AURA_ENCRYPTION_IV_LENGTH	number	Size for the initialization vector used by the encryption algorithm that validates the APIKey and the state.	NO. It would break APIKey and state validation.
AURA_ENCRYPTION_IV_POSITION	number	Position where to insert the initialization vector in the final string with the encrypted payload. By default: `35`.	NO. It would break APIKey and state validation.
AURA_ENCRYPTION_KEY	string	Encryption key or comma-separated list of encryption keys to be used in the environment. It is mainly used to decrypt the APIKeys or user state during login and to encrypt sensible data, such as async-callback parameters during login.	NO. It would break database encrypted data and APIKey validation.
AURA_ENVIRONMENT_NAME	string	Name of the environment where the aura-authentication-api is deployed. For example: `ap-next`, `es-dev` or `de-pre`.	NO
AURA_ERROR_CODES_CREDENTIALS	string	Credentials error codes returned by the IDP in `error_codes` field. Used to send the correct error response to the user.	YES, if any code must return this type of response.
AURA_ERROR_CODES_TIMEOUT	string	Timeout error codes returned by the IDP in `error_codes` field. Used to send the correct error response.	YES, if any code must return this type of response.
AURA_ERROR_DESCRIPTIONS_CREDENTIALS	string	Credentials error descriptions returned by IDP in `error_description` field. Used to send the correct error response. For example: `IDPSEGU_ERROR 205, IDPSEGU_ERROR 424`	YES, if any error description must return this type of response.
AURA_ERROR_DESCRIPTIONS_TIMEOUT	string	Timeout error descriptions returned by IDP in `error_description` field. Used to send the correct error response. For example: `IDPSEGU_ERROR 300`	YES, if any error description must return this type of response.
AURA_FP_AUTHSERVER_ENDPOINT	string	URL of the Kernel authentication server. It MUST end with `/`	NO
AURA_FP_CLIENT_ID	string	Client ID to be logged in as Kernel .application.	NO
AURA_FP_CLIENT_ISSUER	string	URL of endpoint where Aura public key is published.	NO
AURA_FP_CLIENT_SECRET	string	Client password to be logged in as Kernel application.	NO
AURA_FP_ISSUER	string	URL of the endpoint serving Aura’s public key of the environment.	NO
AURA_FP_PRIVATE_KEY	string	Base64 string with the Aura private key used to cipher OpenId requests.	NO
AURA_FP_PRIVATE_KEY_ID	string	ID to find the private key in the key storage of the docker container. It is also used to generate the proper output for the public key. By default, `8dfe2155bbfe54079ba640560ae930411e93a008`.	NO, it depends on the `AURA_FP_PRIVATE_KEY`
AURA_HTTP_KEEP_ALIVE	boolean	Flag to indicate whether not the outgoing HTTP connections should be established with keep alive or not. By default, `true`.	NO
AURA_HTTP_KEEP_ALIVE_MSECS	number	Number of milliseconds to keep HTTP connections open. By default, `100000`.	NO
AURA_HTTP_MONKEY_PATCHER_ENABLED	boolean	Flag to indicate whether Monkey Patcher is used in service.	NO
AURA_HTTP_PATHS_LOG_DISABLED	string	Comma-separated string with the outgoing path that should not be logged. By default, `aura-kpis`, `static-resources`, `healthz`, `ping`, `aura-configuration`. The paths in this variable will be added to the default ones.	YES, add the values to be filtered as a comma-separated list of paths.
AURA_HTTP_REQUEST_MAX_SOCKETS	number	Maximum number of HTTP sockets open in the server. By default, `100`	NO. Only if indicated by Aura Global Team.
AURA_HTTP_REQUEST_TIMEOUT	number	Number of milliseconds to wait for an HTTP request to be established. By default, `20000`.	NO. Only if indicated by Aura Global Team.
AURA_IGNORE_LOGGING_PATH	string	Comma-separated string with all the incoming paths which requests should not be logged. By default, `/ping,/local-ping`	YES
AURA_IMAGE_SUCCESS	string	Path to the image file to be added in the HTML templates to indicate, in integrated authentication, that the process was successful. By default, no file is configured. It will be read from `AURA_STATIC_RESOURCE_PROVIDER_ENDPOINT` using `AURA_STATIC_RESOURCE_PROVIDER_SAS_TOKEN` as credentials.	YES
AURA_INTERNAL_RETRIES	number	Number of retries for internal calls. By default, `1`	NO, except if requested
AURA_LOCALE_FOLDER	string	Local path in the aura-authentication-api docker container where locale files are found. By default, `./locale`.	NO
AURA_LOCALE_FORCE_IMPORT	boolean	Flag to indicate whether or not remote locale files are to be used instead the local ones. By default, `false`.	NO
AURA_LOCALE_REMOTE_BACKUP	boolean	Flag to indicate whether or not remote locale files are to be backup before overwriting them. By default, `false`.	NO
AURA_LOCALE_REMOTE_CONTAINER	string	Azure Storage blob container where remote locale files are stored. By default, `static-resources`.	NO
AURA_LOCALE_REMOTE_CONTAINER_PREFIX	string	Azure Storage blob container prefix where remote locale files are stored. By default, `authentication/locale`.	NO
AURA_LOGGING_FORMAT	string	Format to be used in monitoring logs: `json` or `dev`(more visual format). By default: `json`.	NO. Only for development, set it to `dev`.
AURA_LOGGING_LEVEL	string	Level to be used in monitoring logs, from more to less verbose: `'TRACE', 'DEBUG', 'INFO', 'WARN', 'ERROR', 'FATAL', 'OFF'`. By default: `INFO`.	YES, for development set it to `DEBUG`. In pre/production should be `INFO` or `ERROR`. For the analysis of an issue in pre/production it may be changed to `DEBUG`.
AURA_MAKEUP_MODE	string	Allow dev mode of the makeup with the value `local`. By default: `full`.	NO, only for development, set it to `local`.
AURA_MICROSOFT_AZURE_STORAGE_COMMON_ACCESS_KEY	string	Microsoft Storage password of the common storage. Currently used for KPI storing.	NO. Only if Operations Team changes it.
AURA_MICROSOFT_AZURE_STORAGE_COMMON_ACCOUNT	string	Microsoft Storage account of the common storage. Currently used for KPI storing.	NO. Only if Operations Team changes it.
AURA_MICROSOFT_AZURE_STORAGE_ACCESS_KEY	string	Microsoft Storage password of the deployment.	NO
AURA_MICROSOFT_AZURE_STORAGE_ACCOUNT	string	Microsoft Storage account of the environment.	NO
AURA_MICROSOFT_AZURE_STORAGE_CONFIGURATION_CONTAINER	string	Aura configuration container name. Default: ‘aura-configuration’	NO
AURA_MONGODB_CACHE_COLLECTION	string	Name of the MongoDB collection where cache is stored. By default: `dev-cache`.	NO
AURA_MONGODB_CACHE_INDEX	string	Index used in TwoLevelsCache of aura-behavior-manager. By default, `id`.	YES, only for development environments.
AURA_MONGODB_CACHE_TTL	number	Lifetime of cache used by aura-behavior-manager. It MUST be disabled in PRE and PRO environments. By default, `3600` seconds (1h).	YES, only for development environments.
AURA_MONGODB_PASSWORD	string	MongoDB password to access `MONGODB_USER_DB` in `AURA_MONGODB_URI`.	NO. Only if the credentials must be updated.
AURA_MONGODB_POOL_SIZE	number	Number of connections open with the database in the pool. By default, `60`.	NO. Only if indicated by Aura Global Team.
AURA_MONGODB_SSL	boolean	Flag to indicate whether or not mongodb connection must use SSL. By default, `false`.	NO
AURA_MONGODB_URI	string	MongoDB URI of the MongoDB server of the current environment.	NO
AURA_MONGODB_USER_COLLECTION	string	Name of the MongoDB collection where aura users are stored.	NO
AURA_MONGODB_USER_DB	string	Name of the MongoDB database where aura users are stored.	NO
AURA_MONGODB_USER_LAST_ACCESS_UPDATE_INTERVAL	number	Number of milliseconds to wait to update the last access of user. By default: 86400000 milliseconds	NO
AURA_MONGODB_USERNAME	string	MongoDB username to access `MONGODB_USER_DB` in `AURA_MONGODB_URI`.	NO. Only if the credentials must be updated.
AURA_MONGODB_MAX_POOL_SIZE	number	Maximum number of connections in the MongoDB pool. By default, `60`.	NO
AURA_MONGODB_MIN_POOL_SIZE	number	Minimum number of connections in the MongoDB pool. By default, `2`.	NO
AURA_MONGODB_MAX_IDLE_TIME_MS	number	Maximum idle time in milliseconds for connections in the MongoDB pool. By default, `30000` (30 seconds).	NO
AURA_MONGODB_RETRY_WRITES	boolean	`true` if retry writes are enabled in the MongoDB connection. By default, `true`.	NO
AURA_MONGODB_RETRY_READS	boolean	`true` if retry reads are enabled in the MongoDB connection. By default, `true`.	NO
AURA_MONGODB_HEARTBEAT_FREQUENCY_MS	number	Frequency in milliseconds of the heartbeat in the MongoDB connection. By default, `2000` (2 seconds).	NO
AURA_MONGODB_SERVER_SELECTION_TIMEOUT_MS	number	Timeout in milliseconds for server selection in the MongoDB connection. By default, `5000` (5 seconds).	NO
AURA_MONGODB_SOCKET_TIMEOUT_MS	number	Timeout in milliseconds for socket operations in the MongoDB connection. By default, `45000` (45 seconds).	NO
AURA_CONNECTION_TIMEOUT_MS	number	Timeout in milliseconds for establishing a connection to the MongoDB server. By default, `10000` (10 seconds).	NO
AURA_MONGODB_READ_PREFERENCE	string	Read preference for the MongoDB connection. By default, `primaryPreferred`. Possible values: `primary`, `primaryPreferred`, `secondary`, `secondaryPreferred`, `nearest`.	NO
AURA_REDIRECT_URI	string	URL to redirect integrated authentication requests.	NO
AURA_REDIS_MODE	string	Mode of Redis distribution. Values: `CLUSTER`, `SENTINEL`, `SINGLE`. By default: `SENTINEL`.	NO
AURA_REDIS_SENTINEL_INSTANCE_NAME	string	Name of the Redis instance. Use in `SENTINEL` mode.	NO
AURA_REDIS_HOSTS	string	A string with list of nodes separated by ‘,’, including host and port separated by ‘:’. For example: “localhost:port,localhost2:port2”.	NO
AURA_REDIS_DATABASE	number	Database number for `SINGLE` or `SENTINEL` mode. By default: `0`.	YES
AURA_REDIS_PASSWORD	string	String with Redis password.	YES
AURA_ENVIRONMENT_PREFIX	string	Prefix that will be used by all Redis keys when using redis-connector. This allows mixing in a single Redis service messages coming from different environments in the same Azure subscription. By default: ``. (empty)	YES
AURA_REDIS_USE_CONNECTION_POOL	string	Use pool connections for Redis. By default: `true`.	YES
AURA_REDIS_CACHE_TTL	number	Seconds to expire cache documents in Redis cache. By default: `3600` (1h).	YES
AURA_REDIS_CONNECTION_POOL_MIN	number	Minimum number of connections in the pool. By default: `2`.	YES
AURA_REDIS_CONNECTION_POOL_MAX	number	Maximum number of connections in the pool. By default: `100`.	YES
AURA_REDIS_MAX_RECONNECT_RETRIES	number	Number of retries to connect to Redis. By default: `25`	YES
AURA_REDIS_MAX_RECONNECT_INTERVAL	number	Time in milliseconds to wait before reconnecting to Redis. By default: `5000`.	YES
AURA_RESOURCES_FOLDER	string	Local path in the aura-authentication-api docker container where static resources are found. By default, `./settings/resources`.	NO
AURA_SEED_ID	string	Seed used to generate userIds for anonymous users.	NO
AURA_SERVICE_ENVIRONMENT	string	Type of environment: `'DEV', 'PRE', 'PRO'`. By default, `DEV`. It is used during locale translation, to get the correct text reference.	NO
AURA_SERVICE_PORT	number	Port where the aura-authentication-api is listening. By default, `2367`	NO
AURA_STATIC_RESOURCE_PROVIDER_ENDPOINT	string (url)	Azure Storage endpoint where static resources are stored. By default, it is not configured. Only needed if the environment handles integrated authentication and the files have to be uploaded to Azure Storage.	NO
AURA_STATIC_RESOURCE_PROVIDER_SAS_TOKEN	string	Azure Storage SAS token to access the container where the static resources are stored. By default, it is not configured. Only needed if the environment handles integrated authentication and the files have to be uploaded to Azure Storage.	NO. Only if the credentials have to be renewed.
AURA_STATIC_RESOURCES_CONTAINER	string	Azure Storage blob container where static resources are stored. By default, `static-resources`.	NO
AURA_STATIC_RESOURCES_CONTAINER_PREFIX	string	Azure Storage blob container prefix where static resources are stored. By default, `authentication/resources`.	NO
AURA_TRUSTED_HOSTNAMES	string	Comma-separated list of the trusted domains URL of the current environment, to validate non integrated signup and login requests.	YES, all the trusted domains must be added.
AURA_VALID_REGISTER_STATE_MINUTES	number	Number of minutes to expire a received user state during integrated authentication. By default, `10`.	NO
AURA_SHUTDOWN_GRACEFUL_TTL	string	Number of milliseconds to wait until all aura-authentication-api tasks are done before shutting each pod down. By default `25000` (25 seconds)	NO
AURA_VERSION	string	Number of the Aura’s release being executed.	NO
DEV_AURA_AUTH_BEHAVIOR_MICROSOFT_AZURE_STORAGE_SETTINGS_FILE	string	Name of the configuration file route used by aura-behavior-manager. By default, `aura-bot/aura-auth-behavior-manager.json`. It is only valid for development environments.	YES, in development environments
DEV_AURA_AUTH_BEHAVIOR_CRON_PATTERN	string	Cron pattern to set the refresh time of aura-behavior-manager configuration. By default, `/5 * * *` (every 5 minutes). It is only valid for development environments.	YES, in development environments.
DEV_AURA_BEHAVIOR_MANAGER_ACTIVE	boolean	Flag to indicate whether or not aura-behavior-manager module should be activated in the current deployment. It is only valid for development environments.	YES, in development environments.

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Users authentication

Description of users’ authentication process in Aura Bot. Discover the different types of users and how they can authenticate in Aura

Introduction

aura-bot supports different types of users, each of them with access to specific services and use cases:

Authenticated users
Anonymous users

In the authentication process, aura-bot carries out the following summarized steps:

Obtains information from the users
Validates it
If the validation is successful, and depending on the type of user, aura-bot allows accessing to different services
Stores the user’s data

The detailed process is described in users’ authentication flow.

The authentication of a user implies the acceptance of Terms and Conditions, which are handled by aura-bot.

In certain scenarios (use cases) where the user is unauthenticated, it is required to redirect specific intents that need authentication. Find here the complete information regarding login redirections.

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Aura users types

Description of the different users types existing in Aura

Introduction

Aura supports different types of users: authenticated and anonymous, each of them with access to specific services and use cases. The following sections include detailed information about each type.

Authenticated users

Aura securely knows the identity of the users, as they must have successfully completed the authentication flow.

They can be classified into different groups regarding their type of subscription. This classification depends on the different countries, but in general terms, there are three main types of authenticated users: postpaid, prepaid, hybrid / control.

Authenticated users can access any use case in Aura, providing that the use case supports authenticated users or the specific subscription type of the user, defined through context filters.

In case the authorization process of an Aura user fails:

If the channel does not allow anonymous users, then the request is marked as failed and a status with the unauthenticated error is returned to the channel. This indicates that the channel should relaunch the authentication of the user to get a valid auraId.

Anonymous users

Anonymous users are unauthenticated users but with authorized access to certain Aura’s use cases: to those which support the anonymous user’s type. In every case, Aura’s experience is different for each type of users.

Within anonymous users, there is a specific type named identifiable users in which the channel auraId univocally identifies a user in the channel.

It also depends on the channel, as different Aura channels can support both types of users (anonymous-identifiable and authenticated) or only authenticated ones.

Due to some restrictions in Kernel, from Kiss release onwards, anonymous users also have userId and auraGlobalId. These fields, in contrast to authenticated users, are not obtained from Kernel but auto-generated by aura-bot and aura-authentication-api in some cases, to be stored in KPIs. The values are generated to maintain the same value between channels to allow the user identification if possible.

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Aura Authentication API endpoints

Description of Aura Authentication API endpoints, categorized by how they can be accessed or by their usage

Endpoints by access

aura-authentication-api counts on:

Internal endpoints: they are only allowed to APIKeys generated for aura-groot/aura-bot.
Public endpoints: they are publicly open and all valid APIKeys for the current environment can access them.
Endpoints published in Kernel, i.e. they are publicly open but they are only allowed to APIKeys generated for Kernel. Read Aura Services API published in Kernel for further information.

The following section explains every endpoint, showing whether it is internal, public, Kernel or a mix.

Endpoints by usage

Register new users

GET /users/aura-id: Endpoint published in Kernel, used by Aura Channels that handle their own authentication mechanisms. They must call this endpoint to get a valid authenticated Aura user to start a conversation. This method retrieves the already existing user if the data sent exists or create a new user with the data, otherwise. Authorized by APIKey.
GET /users/aura-id/{auraId}: Internal method used only by aura-groot/aura-bot in order to create a new user when the auraId is based on the external service authentication, such as for WhatsApp users. Authorized by APIKey.
GET /users/auraid/integrated: Endpoint used as callback during non-integrated authentication request. This endpoint is used by Aura clients account linking process without integrated authentication. It is called by Kernel after creating the authentication session, to add the Aura user record. No authorization header. Validation done by a ciphered query param.

Remove users

DELETE /admin/users/phone-numbers/{phone_number}: Endpoint published in Kernel, used by OB administrators to fulfill GDPR and remove users by phone number that are not longer Telefonica’s customers. Authorized by APIKey.
GET /users/auraid/integrated/logout: Public endpoint used as callback during non-integrated logout request. This endpoint is used by Aura clients account unlinking process without integrated authentication. It is called by Kernel after removing the authentication session, to remove the Aura user record. No authorization header. Validation done by a ciphered queryparam.
DELETE /users/{auraId}: Internal and also published in Kernel endpoint used by aura-bot and the non-integrated channels, to remove the information of an already logged in Aura user. Authorized by APIKey.

Gather users’ information

GET /users/{auraId}: Internal endpoint used by aura-groot/aura-bot to get and validate the information of an already logged in Aura user. Authorized by APIKey.
GET /users/aura-id-global/{aura_id_global}: Endpoint published in Kernel, used to get the last valid auraId for the channel, generated for the given auraIdGlobal. Authorized by APIKey.

Retrieve a valid Direct Line token from the current Aura Bot instance and start a conversation with it

GET /token: Public endpoint used by Aura channels accessing by Direct Line, to get a valid Direct Line-Token to access the bot in the selected environment. This endpoint just returns the token and its expiration time. Authorized by APIKey.
GET /token/wss: Public endpoint used by Aura channels accessing by Direct Line, to get a valid Direct Line-Token to access the bot in the selected environment. This endpoint returns the token, the websocket stream URL, the expiration time and some other fields returned by Direct Line API. Authorized by APIKey.

Public key (no APIKey)

GET /openid/issuer/.well-known/openid-configuration: Public endpoint to get the public key URL of aura-groot/aura-bot.
GET /openid/jwk: Public endpoint to get the public key configuration of aura-groot/aura-bot. Used to validate the requests signed with aura-groot/aura-bot private key.

Monitoring methods

GET /healthz: Internal health check endpoint to validate the server status by the Kubernetes cluster. No authorization header needed.
GET /ping: Endpoint published in Kernel to validate the server status.

Configuration method

GET /config: Public endpoint to return the name of the Azure Storage subdomain.

Metrics method

GET /metrics: Public endpoint where Prometheus requests the metrics.

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Aura Terms and Conditions API

Description of Aura Terms and Conditions API

Introduction

Temporary implementation of the Kernel TermsAndConditions API.

This is an internal, privileged API that allows Aura to save the user’s acceptation. As this API is not inside any secured deployment, an x-api-key header should be sent in every request.

This service is available in all the deployments with services needing Terms and Conditions handling, such as WhatsApp

Acceptance criteria

There may be different versions for the service T&C.
Only acceptations, not revocations, should be stored.
There should be a way to allow deleting all acceptations for a user.

Database schema

Terms and Conditions database contains the services collection with the following structure:

API

Create an acceptation for a service version T&C POST /v0/users/:user_id/services

POST /v0/users/9a47b037-825f-4ae7-bf55-6290efd5d036/services
Content-Type: application/json
x-api-key: 58e76225-d275-495b-a232-fdf3364ac277
{
	"version": "1",
	"name": "aura"
}

HTTP/1.1 201 Created
Content-Type: application/json
{
  "user_id": "9a47b037-825f-4ae7-bf55-6290efd5d036",
  "name": "aura",
  "version": "1",
  "status": "accepted",
  "created_at": "2019-08-08T15:19:48.259Z"
}

List user acceptations GET /v0/users/:user_id/services

GET /v0/users/9a47b037-825f-4ae7-bf55-6290efd5d036/services
x-api-key: 58e76225-d275-495b-a232-fdf3364ac277

HTTP/1.1 200 OK
Content-Type: application/json
[
  {
    "user_id": "9a47b037-825f-4ae7-bf55-6290efd5d036",
    "name": "aura",
    "version": "1",
    "status": "accepted",
    "created_at": "2019-08-08T15:19:48.259Z"
  }
]

get specific user acceptation GET /v0/users/:user_id/services/:name/:version

GET /v0/users/9a47b037-825f-4ae7-bf55-6290efd5d036/services/aura/1
x-api-key: 58e76225-d275-495b-a232-fdf3364ac277

HTTP/1.1 200 OK
Content-Type: application/json
{
  "user_id": "9a47b037-825f-4ae7-bf55-6290efd5d036",
  "name": "aura",
  "version": "1",
  "status": "accepted",
  "created_at": "2019-08-08T15:19:48.259Z"
}

delete all user acceptations DELETE /v0/users/:user_id/services

DELETE /v0/users/9a47b037-825f-4ae7-bf55-6290efd5d036/services
x-api-key: 58e76225-d275-495b-a232-fdf3364ac277

HTTP/1.1 204 No Content

Create an entry with custom status for a service version T&C POST /v0/users/:user_id/services/:status

POST /v0/users/9a47b037-825f-4ae7-bf55-6290efd5d036/services/pending
Content-Type: application/json
x-api-key: 58e76225-d275-495b-a232-fdf3364ac277
{
	"version": "1",
	"name": "aura"
}

HTTP/1.1 201 Created
Content-Type: application/json
{
  "user_id": "9a47b037-825f-4ae7-bf55-6290efd5d036",
  "name": "aura",
  "version": "1",
  "status": "pending",
  "created_at": "2019-08-08T15:19:48.259Z"
}

Update an entry with custom status for a service version T&C PUT /v0/users/:user_id/services/:status

PUT /v0/users/9a47b037-825f-4ae7-bf55-6290efd5d036/services/newStatus
Content-Type: application/json
x-api-key: 58e76225-d275-495b-a232-fdf3364ac277
{
	"version": "1",
	"name": "aura"
}

HTTP/1.1 201 Created
Content-Type: application/json
{
    "n": 1,
    "nModified": 1,
    "ok": 1
}

Metrics

prometheus

GET /metrics
HTTP/1.1 200 OK

...txt...

liveness prove

GET /ping
HTTP/1.1 200 OK
Content-Type: application/json

{
  "timestamp": 1567693845103,
  "uptime": 7026,
  "service": {
    "name": "tac",
    "version": "1.0.5"
  }
}

Development

docker-compose up

To clean database and start from scratch

docker-compose down -v

Configuration

The configuration comes from environment variables.

# the mongodb uri, including user/password and ssl configuration
export TAC_MONGODB_URI=mongodb://db:27017/tac
# API key that should be sent in every request in the `x-api-key` header
export TAC_APIKEY=58e76225-d275-495b-a232-fdf3364ac277

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

User authentication

Basic flows for users authentication in Aura

Non-integrated channels

For this kind of channels, the users always start as authenticated. The channel is responsible for authenticating the user in the OB and Kernel and for generating the auraId needed to prepare a valid request to Aura.

Further information about non-integrated channels can be found in Channels Authentication: non-integrated authentication.

This diagram must be executed just before sending messages to Aura for authenticated users.

⚠️ The request from Channel to IDP is not fully explained in the diagram. Follow Kernel documentation for a deep dive on how it works.

@startuml
title: Users authentication flow for non-integrated channels

    participant Channel #bdf492
    participant AuthenticationApi #FFFF99
    participant IdP #99FFFF
    participant KernelAuthServer #99FFFF
    participant KernelAuraServicesApi #99FFFF

    Channel -> IdP: POST /authorize
    IdP -> Channel: 200 OK {UserAuthenticationContext}
    Channel -> KernelAuthServer: POST /token
    Note over Channel,KernelAuthServer: Here a 3-legged accessToken is requested
    KernelAuthServer -> Channel: {token}
    Channel -> KernelAuraServicesApi: GET /users/aura-id
    KernelAuraServicesApi -> AuthenticationApi: GET /aura-services/v1/users/aura-id
    AuthenticationApi -> KernelAuraServicesApi: 200 OK {AuraUser}
    KernelAuraServicesApi -> Channel: 200 OK {AuraUser}
    Note over KernelAuraServicesApi,Channel: AuraUser contains the auraId needed to fulfil the requests to Aura.
@enduml

Integrated or federated channels

For this kind of channels, the users always start as anonymous and they can consume some generic questions use cases, those that do not need knowing who the user is to be resolved, such as FAQs or small talk use cases.

Once the user requests one use case that needs knowing her identity, then the authentication flow is launched by a dialog available in aura-bot. The auraId, in this case, is decided by the channel. Usually, its own user identifier is used. For instance, in the case of WhatsApp or Facebook, their own users identifier are received and used as auraId.

Further information about integrated channels can be found in Channels Authentication: integrated authentication.

This diagram substitutes the Specific functional Dialog step in the diagram New Direct Line message from anonymous user, assuming that the user has requested an authenticated use case. Not all the steps of this diagram have been included again in the sake of clarity of the diagram.

User authentication by redirection

Find further details about how this mechanism works in Kernel here.

@startuml
title: Users authentication flow for integrated channels with URL redirection

    participant AuthenticationApi #FFFF99
    participant AuraGroot #76bbe7
    participant AuraBot #41a0f9 
    participant AuraBridge #1add4d
    participant IdP #99FFFF
    participant KernelAuthServer #99FFFF
    participant KernelUserProfileApi #99FFFF

    AuraBot -> AuraBot: Executing a user message that raises a dialog that needs authentication
    AuraBot -> AuraBot: Main Dialog
    AuraBot -> AuraBot: ValidateAuthenticationForDialog
    AuraBot -> AuraBot: AuthenticationDialog
    AuraBot -> IdP: OPEN in webserver /authorize?state&redirectUri
    Note over AuraBot,IdP: At this moment, a web page with the login form is open
    IdP -> KernelAuthServer: Authentication status
    Note over KernelAuthServer,AuthenticationApi: In Aura, the redirectUri points to our AuthenticationApi
    KernelAuthServer -> AuthenticationApi: POST /aura-services/v1/users/auraid/integrated?code&state
    AuthenticationApi -> AuthenticationApi: validate(state)
    AuthenticationApi -> KernelAuthServer: POST /token {code}
    KernelAuthServer -> AuthenticationApi: 200 OK {token}
    AuthenticationApi -> KernelAuthServer: POST /introspect {token}
    KernelAuthServer -> AuthenticationApi: 200 OK {plainToken}
    AuthenticationApi -> AuthenticationApi: store(AuraUser)
    AuthenticationApi -> KernelAuthServer: 200 OK
    AuthenticationApi -> AuraBridge: sendAsyncCallback(AuraUser)
    AuraBridge -> AuraGroot: Send {UserCreatedActivity}
    AuraBridge -> AuthenticationApi: 200 OK
    AuraGroot -> AuraGroot: Middlewares
    AuraGroot -> AuraGroot: Recognizers (GetSkillByChannel)
    AuraGroot -> AuraBot: Send {UserCreatedActivity}
    AuraBot -> AuraGroot: 200 OK
    AuraBot -> AuraBot: Middlewares
    Note right of AuraBot: KPI entities are stored during Middlewares execution in local memory.\nEvery 2 minutes and before closing a POD, they are written in Azure Storage.
    AuraBot -> AuraBot: Recognizers
    AuraBot -> AuraBot: Main Dialog
    AuraBot -> AuraBot: ValidateAuthenticationForDialog
    AuraBot -> AuraBot: Execute Specific functional Dialog
    AuraBot -> AuraGroot: Send {responseActivity}
    AuraGroot -> AuraBot: 200 OK

User authentication using WhatsApp

Access these documents for further detail:

WhatsApp LoA2 authentication

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Authentication API metrics

List of metrics available in Aura Authentication API

http_request_duration_seconds

This metric is intended to store the information related to all the incoming HTTP requests received by aura-authentication-api. It is stored as a Summary in Prometheus, so every sample, besides the defined labels, also includes its duration.

This metric allows measuring the behavior of the requests from any given endpoint. Specifically, the duration since the request lands in aura-authentication-api until its HTTP response is returned:

The number of requests during a time
The average/min/max duration of these requests

Labels:

method: HTTP method used by the request being stored (GET, POST, PUT, DELETE, etc.).
host: host and domain where the request is being sent
path: specific endpoint of the request
status_code: HTTP status code returned in the response

This metric was stored since Greenday (6.0.0) release.

outgoing_request_duration_seconds

This metric is intended to store the information related to all the outgoing HTTP requests made by aura-authentication-api. It is stored as a Summary in Prometheus, so every sample, besides the defined labels, also includes its duration.

The metric allows measuring the behavior of the requests to any given endpoint:

The number of requests during a time
The average/min/max duration of these requests

Labels:

method: HTTP method used by the request being stored (GET, POST, PUT, DELETE, etc.)
host: host and domain where the request is being sent
path: specific endpoint of the request
status: HTTP status code returned in the response

This metric was stored since Camela (5.0.0) release.

aura_token_generate

This metric is intended to store the information related to Kernel accessToken generation, used during the integrated authorization process of the Aura users in aura-authentication-api.

It is intended to make it possible to set an alarm in the happening of any error during token validation. It is stored as a Summary in Prometheus.

Labels:

path: specific endpoint of the request.
httpStatus: HTTP status returned by Kernel in the response.
originStatus: status sent by Kernel in the body of the response in the happening of an error.
origin: channelId of the channel that needs the accessToken in Aura.

This metric was stored since Iron Maiden (7.2.0) release.

aura_component_version

This metric is intended to store the number of aura-authentication-api instances (pods) running each version of the code.

It is stored as a Gauge in Prometheus.

Labels:

version: version field in the package.json file included in the running docker container.
component: name of the component that is writing the metric.

This metric was stored since Barricada (5.3.0) release with the name of authentication_api_version and updated to aura_component_version in Iron Maiden (7.2.0).

aura_server_unhandled_error

This metric is intended to store the number of unhandled errors happening in aura-bridge. It is stored as a Counter in Prometheus.

Labels:

error: exception message that forced the unhandled error.

This metric was stored since Iron Maiden (7.2.0) release.

services_status

This metric is intended to store the number of success or errored checks of modules of the server. It is stored as a Counter in Prometheus.

Labels:

moduleId: Id of the module.
status: OK or ERROR

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Aura authentication API dashboard

Information provided by Authentication API dashboard

Aura services latency

Aura services latency graph shows mean latency rate for the different incoming calls.

The available metrics are defined in the following sections.

Graph metrics

Currently, these are the existing monitored incoming calls:

WhatsApp users’ retrieval

sum by (kubernetes_namespace,path)(rate(http_request_duration_seconds_sum{path=~"/aura-services/v1/users/whatsapp.*"}[1m]))/
sum by (kubernetes_namespace,path)(rate(http_request_duration_seconds_count{path=~"/aura-services/v1/users/whatsapp.*"}[1m]))

Get or create user

sum by (kubernetes_namespace,path)(http_request_duration_seconds_sum{app="authentication-api",path=~"/aura-services/v1/users/aura-id"})/
sum by (kubernetes_namespace,path)(http_request_duration_seconds_count{app="authentication-api",path=~"/aura-services/v1/users/aura-id"})

Get or create user

sum (label_replace(http_request_duration_seconds_sum{app="authentication-api",path=~"/aura-services/v1/users/aura-id/.*"},"path_set","$1","path","/aura-services/v1/users/aura-id/.*")) by (kubernetes_namespace,path_set) / 
sum (label_replace(http_request_duration_seconds_count{app="authentication-api",path=~"/aura-services/v1/users/aura-id/.*"},"path_set","$1","path","/aura-services/v1/users/aura-id/.*")) by (kubernetes_namespace,path_set)

Retrieves an Aura user by the given auraIdGlobal and the channelId

sum (label_replace(http_request_duration_seconds_sum{app="authentication-api",path=~"/aura-services/v1/users/aura-id-global/.*"},"path_set","$1","path","/aura-services/v1/users/aura-id-global/.*")) by (kubernetes_namespace,path_set) / 
sum (label_replace(http_request_duration_seconds_count{app="authentication-api",path=~"/aura-services/v1/users/aura-id-global/.*"},"path_set","$1","path","/aura-services/v1/users/aura-id-global/.*")) by (kubernetes_namespace,path_set)

Gets given authorization and identification information to register the user

sum (label_replace(http_request_duration_seconds_sum{app="authentication-api",path=~"/aura-services/v1/users/auraid/integrated/.*"},"path_set","$1","path","/aura-services/v1/users/auraid/integrated/.*")) by (kubernetes_namespace,path_set) / 
sum (label_replace(http_request_duration_seconds_count{app="authentication-api",path=~"/aura-services/v1/users/auraid/integrated/.*"},"path_set","$1","path","/aura-services/v1/users/auraid/integrated/.*")) by (kubernetes_namespace,path_set)

OpenID logout

sum by (kubernetes_namespace,path)(http_request_duration_seconds_sum{app="authentication-api",path=~"/aura-services/v1/users/auraid/integrated/logout"})/
sum by (kubernetes_namespace,path)(http_request_duration_seconds_count{app="authentication-api",path=~"/aura-services/v1/users/auraid/integrated/logout"})

New Direct Line token

sum by (kubernetes_namespace,path)(http_request_duration_seconds_sum{app="authentication-api",path=~"/aura-services/v1/token"})/
sum by (kubernetes_namespace,path)(http_request_duration_seconds_count{app="authentication-api",path=~"/aura-services/v1/token"})

New Direct Line token(wss)

sum by (kubernetes_namespace,path)(http_request_duration_seconds_sum{app="authentication-api",path=~"/aura-services/v1/token/wss"})/
sum by (kubernetes_namespace,path)(http_request_duration_seconds_count{app="authentication-api",path=~"/aura-services/v1/token/wss"})

JWT uri retrieval

sum by (kubernetes_namespace,path)(http_request_duration_seconds_sum{app="authentication-api",path=~"/aura-services/v1/openid/issuer/.well-known/openid-configuration"})/
sum by (kubernetes_namespace,path)(http_request_duration_seconds_count{app="authentication-api",path=~"/aura-services/v1/openid/issuer/.well-known/openid-configuration"})

JWT token retrieval

sum by (kubernetes_namespace,path)(http_request_duration_seconds_sum{app="authentication-api",path=~"/aura-services/v1/openid/jwk"})/
sum by (kubernetes_namespace,path)(http_request_duration_seconds_count{app="authentication-api",path=~"/aura-services/v1/openid/jwk"})

Get or create user

sum (label_replace(http_request_duration_seconds_sum{app="authentication-api",path=~"/users/aura-id/.*"},"path_set","$1","path","/users/aura-id/.*")) by (kubernetes_namespace,path_set) / 
sum (label_replace(http_request_duration_seconds_count{app="authentication-api",path=~"/users/aura-id/.*"},"path_set","$1","path","/users/aura-id/.*")) by (kubernetes_namespace,path_set)

User by phone number

sum (label_replace(http_request_duration_seconds_sum{app="authentication-api",path=~"/aura-services/v1/admin/users/phone-numbers/.*"},"path_set","$1","path","/aura-services/v1/admin/users/phone-numbers/.*")) by (kubernetes_namespace,path_set) / 
sum (label_replace(http_request_duration_seconds_count{app="authentication-api",path=~"/aura-services/v1/admin/users/phone-numbers/.*"},"path_set","$1","path","/aura-services/v1/admin/users/phone-numbers/.*")) by (kubernetes_namespace,path_set)

Graph visual

Request out error

Request out error graph shows error rate for outgoing requests with HTTP codes 4xx and 5xx, aggregated by 1 minute.

Graph metrics

sum by (kubernetes_namespace,path)(rate(outgoing_request_duration_seconds_count{app="authentication-api",status=~"4..|5.."}[1m]))

Graph visual

Microsoft APIs latency

Microsoft APIs latency graph shows mean latency rate for the different Microsoft APIs used.

Graph metrics

Currently, there are three monitored Microsoft endpoints:

Directline endpoint

sum by (kubernetes_namespace,path)(rate(outgoing_request_duration_seconds_sum{app="authentication-api",host=~"directline.botframework.com"}[1m]))/
sum by (kubernetes_namespace,path)(rate(outgoing_request_duration_seconds_count{app="authentication-api",host=~"directline.botframework.com"}[1m]))

Microsoft auth endpoint

sum by (kubernetes_namespace,path)(rate(outgoing_request_duration_seconds_sum{app="authentication-api",host=~"login.microsoftonline.com"}[1m]))/
sum by (kubernetes_namespace,path)(rate(outgoing_request_duration_seconds_count{app="authentication-api",host=~"login.microsoftonline.com"}[1m]))

Blob storage endpoint

sum by (kubernetes_namespace,path)(rate(outgoing_request_duration_seconds_sum{app="authentication-api",host=~"aura.*.blob.core.windows.net"}[1m]))/
sum by (kubernetes_namespace,path)(rate(outgoing_request_duration_seconds_count{app="authentication-api",host=~"aura.*.blob.core.windows.net"}[1m]))

Graph visual

Kernel APIs latency

Kernel APIs latency graph shows mean latency rate for the different Kernel APIs used.

Graph metrics

Currently, there are three monitored Kernel endpoints:

Kernel token retrieval endpoint

sum by (kubernetes_namespace,path)(rate(outgoing_request_duration_seconds_sum{app="authentication-api",host=~"auth.*",path="/token"}[1m]))/
sum by (kubernetes_namespace,path)(rate(outgoing_request_duration_seconds_count{app="authentication-api",host=~"auth.*",path="/token"}[1m]))

Kernel token introspection endpoint

sum by (kubernetes_namespace,path)(rate(outgoing_request_duration_seconds_sum{app="authentication-api",host=~"api.*",path=~"/token-introspection/.*"}[1m]))/
sum by (kubernetes_namespace,path)(rate(outgoing_request_duration_seconds_count{app="authentication-api",host=~"api.*",path=~"/token-introspection/.*"}[1m]))

Kernel open-id configuration endpoint

sum by (kubernetes_namespace,path)(rate(outgoing_request_duration_seconds_sum{app="authentication-api",host=~"auth.*",path="/.well-known/openid-configuration"}[1m]))/
sum by (kubernetes_namespace,path)(rate(outgoing_request_duration_seconds_count{app="authentication-api",host=~"auth.*",path="/.well-known/openid-configuration"}[1m]))

Graph visual

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Aura authentication server make-up process

The current section describes the make-up processes that take place within Aura authentication server

Manage MongoDB Indexes

The indexes configuration file is in /settings/makeup/aura-authentication-mongodb-indexes.json.

Once the make-up is executed, this file will be uploaded to the assigned repository [AURA-STORAGE]/aura-configuration/[AURA_VERSION]/aura-authentication-mongodb-indexes.json. If this remote file exists, it has priority over the local file.

This configuration is assigned in the make-up process by means of the following model:

   const options: MakeupMongoIndexManagerOptions = {
        mongodbConfiguration: {
            AURA_MONGODB_URI: configuration.AURA_MONGODB_URI,
            AURA_MONGODB_DB_NAME: configuration.AURA_MONGODB_USER_DB,
            AURA_MONGODB_USERNAME: configuration.AURA_MONGODB_USERNAME,
            AURA_MONGODB_PASSWORD: configuration.AURA_MONGODB_PASSWORD,
            AURA_MONGODB_POOL_SIZE: configuration.AURA_MONGODB_POOL_SIZE,
            AURA_MONGODB_SSL: configuration.AURA_MONGODB_SSL
        },
        fileConfiguration: {
            containerName: 'aura-configuration',
            localPath: 'settings/makeup',
            remotePath: '',
            files: [{ name: 'aura-authentication-mongodb-indexes.json', mimeType: 'application/json' }]
        },
        replaceLocalWithRemote: true,
        storageCredentials: {
            storageKey: configuration.AURA_MICROSOFT_AZURE_STORAGE_ACCESS_KEY,
            storageName: configuration.AURA_MICROSOFT_AZURE_STORAGE_ACCOUNT
        },
        uploadFromLocalToRemote: true,
        auraVersion: configuration.AURA_VERSION,
        ignoreDownloadErrors: true,
        ignoreUploadErrors: true,
        dataBaseSuffix: configuration.AURA_ENVIRONMENT_NAME
    };

Prepare Locale Resources

The language resources in Aura Authentication Service are located in /locale/:

de-de.json
en-gb.json
es-es.json

When starting an Aura Authentication Service, these files are loaded remotely from [AURA-STORAGE]/static-resources/authentication/locale/[AURA_VERSION]/.

In the make-up process, the language resources are uploaded to Azure Storage.

Process Resources

In the make-up process of Aura Authentication Service, the resources are loaded from /settings/resources/ and upload to [AURA-STORAGE]/static-resources/authentication/resources/[AURA_VERSION]/.

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Description of the process for redirecting intents that need authentication in cases where the user is unauthenticated.

Global authentication dialogs

There are 2 different dialogs to authenticate the user according to the channel:

account-linking dialog for channels using integrated authentication, for example, Aura Webclient.
whatsapp-otp-login dialog for SMS-OTP authentication in WhatsApp channel.

To redirect to login dialogs, we need a contextFilter with the redirectToIntent field set with the intent of the authentication dialog that we want to redirect.

This is done in the channel model:
triggerCondition model > conditionValidation model

For example, if we want to redirect to authentication in a channel, we need to add a configuration in the dialog as shown below:

{
  "name": "bill",
  "dialogs": [
    {
      "id": "balance-check",
      "triggerConditions": [
        {
          "intent": "intent.balance.check",
          "contextFilters": [
            {
              "name": "Anonymous redirect to linking",
              "type": "type",
              "conditions": "/type eq 'anonymous'",
              "true": {
                "name": "Anonymous redirect to linking",
                "breakDialogExecution": true,
                "breakFilterEval": true,
                "redirectToIntent": "intent.account.linking",
                "suggestions": false
              }
            }
          ]
        }
      ]
    }
  ]
}

In WhatsApp channel, the contextFilter will be the same but changing the redirectToIntent to the intent for WhatsApp authentication (intent.authentication.login):

{
  "triggerConditions": [
    {
      "intent": "intent.factotum-test.whatsapp-auth",
      "contextFilters": [
        {
          "name": "Anonymous redirect to linking",
          "type": "type",
          "conditions": "/type eq 'anonymous'",
          "true": {
            "name": "Anonymous redirect to linking",
            "breakDialogExecution": true,
            "breakFilterEval": true,
            "redirectToIntent": "intent.authentication.login",
            "suggestions": false
          }
        }
      ]
    }
  ]
}

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Terms and Conditions

Description of Terms and Conditions handled in Aura Bot Platform

Terms and conditions flow

When a user message arrives, the first step in authentication is to check if it is in cache. In case that it is not found, Terms & Conditions API is checked and if the user does not exist or has a pending status, it is redirected to T&C dialog.

Obviously, all the users with accepted status continue with the normal flow. In the Terms and Conditions dialog a record with status pending is stored in the T&C API if does not exist yet and the terms and conditions prompt is shown. If the user accepts, the status accepted is set in T&C API.

Anonymous and authenticated users have different T&C, so if both are configured, users should accept T&C twice: after the first message as anonymous and after the authentication.

Terms and conditions settings

Terms and Conditions settings

In Aura channel model, T&C are set in the termsAndConditionsconfiguration model. It is added to channels who need to enable this feature.

There are two fields with different configurations inside: authenticated and anonymous. Each of these settings will be used according to the type of user. It defines the version and service used in T&C API.

{
  "channel_id": "f7fd1021-41cd-588a-a461-387cc24be223",
  "name": "whatsapp",
  "termsAndConditions": {
    "authenticated": {
      "version": "1",
      "service": "whatsappAuth"
    },
    "anonymous": {
      "version": "1",
      "service": "whatsappAnonymous"
    }
  }
}

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Enable corporate anonymous users check

Guidelines for the activation and deactivation of corporate anonymous users check, both general steps and specific ones for the use case under development

Prerequirements

Request to Kernel and OB Operations Teams to provide a purpose for aura-bot client in Kernel that provides access to UserProfile API via client credentials flow. It should be something like aura-bot-search-customer-purpose.
Request to Kernel to update the aura-bot client in Kernel to include the new purpose in client credentials flow. For instance:

        {
            "name": "client_credentials",
            "scopes": [
                "whatsapp:app-admin",
                "whatsapp:app-messaging",
                "whatsapp:manage-templates"
            ],
            "purposes": [
                "auraid-admin",
                "aura-bot-search-customer-purpose"
            ]
        }

Activation

Set the following environment variable in aura-bot configmap or in the configuration file of the environment.

AURA_FP_CLIENT_CRED_PURPOSES: aura-bot-search-customer-purpose

Activate the validation in the corresponding channels. These channels must support anonymous users and the identifier coming from the channel must be a phonenumber, WhatsApp based channels, for instance. Add the following settings to your channel configuration:

    "security": {
        "anonymous": "identifiable",
        "anonymousSettings": {
            "checkPromptedNumber": false,
            "enableUserProfile": true
        }
    }

Further information regarding these settings is found in anonymousSettings and aura-configuration-api component.

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Aura Authentication API

aura-authentication-api is the component in charge of handling users in Aura.
Find in the current documents the description of this component, its architecture, components and processes.

Aura Virtual Assistant component

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

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.

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Aura Authentication API definition

Definition of APIs in aura-authentication-api component

Introduction

This section includes the API definition files that affects to the authentication processes in Aura:

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Aura Services API published in Kernel

Description of Aura Authentication API endpoints published in Kernel

Introduction

As mentioned in the endpoints section, some of the endpoints of the aura-authentication-api are published in Kernel, while others are only for internal usage and others are published in Internet because they can be called by any other service, with the proper credentials.

This section is dedicated to those published in Kernel.

aura-services API definition in Kernel

The API published in Kernel is not strictly the same as the one published in aura-authentication-api. In the end, they represent the very same service, but the former needs to provide the layer of Kernel authentication.

The API definition can be found in Kernel developers site, where both the different versions deployed in every environment are presented.

How to consume this API

This is a regular Kernel API, so in order to consume it, just follow the same instructions as for the rest of Kernel APIs: consuming APIs.