Aura – aura-user

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

User middleware

Description of user-middleware in charge of the validation of the user’s data

Introduction

user-middleware is the middleware in charge of validating auraId and channel.

This is needed in aura-groot because routing is currently done by channel, so if the request does not include channelId (mandatory only in channelData v3), the user must be checked in aura-authentication-api to obtain the channel of this user.

This middleware throws an error if there is not activity.from.id or if some error is returned by aura-authentication-api (except 404, because anonymous users should continue the flow).

This middleware also handles a basic user’s cache to avoid unnecessary calls to aura-authentication-api with every user’s request. This cache is implemented using bot UserState.

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

Purge expired Aura users

Guidelines for the elimination of expired Aura users, in order to minimize the number of documents in aura-users database. This will make data migration lighter.

Prerequirements

This step must be executed if the number of documents in the aura-users database is too large and there are a lot of expired users, i.e., users that accessed more than 6 months ago and did not come back to Aura for a time.
It must be executed on a weekly or monthly basis to avoid long executions. The frequency will depend on the amount of data in your database and how long it takes to remove the expired data.
A valid kubeconfig for the environment must be available
A valid token to be able to pull images from aura docker registry: auraregistry.azurecr.io must be available

Get the variables to access the database:

# substitute {{aura-environment with the environment you're configuring }}
export AURA_ENVIRONMENT={{aura-environment}}

$ kubectl -n $AURA_ENVIRONMENT get cm authentication-api -o json | jq -r ".data.AURA_MONGODB_URI"

{{mongo_uri}}

$ kubectl -n $AURA_ENVIRONMENT get cm authentication-api -o json | jq -r ".data.AURA_MONGODB_USERNAME"

{{mongo_user}}

$ kubectl -n $AURA_ENVIRONMENT get secret authentication-api -o json | jq -r ".data.AURA_MONGODB_PASSWORD|@base64d"

{{mongo_pass}}

$ kubectl -n $AURA_ENVIRONMENT get cm authentication-api -o json | jq -r ".data.AURA_MONGODB_USER_DB"

{{mongo_users_db}}

Process for expired users elimination

Access MongoDB console

This access depends on the deployment configuration:

If the environment database runs in an on-premise MongoDB server, set up the corresponding port-forward to the primary node of the replicaset:

# Review carefully the mongodb pod you're connecting to, it MUST be the primary of the replica set
# Review your local port carefully, to set a free one

$ kubeclt -n aura-system port-forward mongodb-0 27017:27017

# Set the proper mongo_uri to access via the port-forwarded connection
$ mongo_uri=mongodb://localhost:27017

If the environment database runs in Atlas, just connect to the {{mongo_uri}}, read from the environment configuration.

In the end, just open the MongoDB console:

$ mongo -u {{mongo_user}} -p {{mongo_pass}} {{mongo_uri}}

> use {{mongo_users_db}}

Check the number of expired users

Check how many users are expired in the database (Older than 180 days or without lastAccess field)

> db.users.find({ "$or": [ { "lastAccess": { "$exists": false }},{ "lastAccess": { "$lt": new Date(ISODate().getTime() - 1000 * 86400 * 180)} } ]}).count()

⚠️ If Movistar Plus is a valid channel in your deployment, then its users must not be considered in the query, because they are created from a backend and are assumed to be created beforehand.

> db.users.find({ "$and": [ { "$or": [ { "lastAccess": { "$exists": false }},{ "lastAccess": { "$lt": new Date(ISODate().getTime() - 1000 * 86400 * 180)} } ]}, { "channelId": { "$ne": "60f0ffda-e58a-4a96-aad9-d42be70b7b42" }} ]}).count()

Execute database-cleaner tool

The script iterates over all the users in the database, deleting those whose lastAccess is older than 180 days or without lastAccess field (meaning that they come from an old version of Aura where this field does not exist).

It will create some output files with the deleted users that can be used with mongoimport command to restore the deleted users, if needed. The output files with the deleted users will be split in files of 500Mb size each.

If the environment uses MongoDB on premise: Use with port-forwarding to the primary node of the cluster in the same host where the command is running:

# complete the {{mongodb_uri}} with the user and password of the database. You should obtain something like:
# mongodb_full_uri = mongodb://{{mongo_user}}:{{mongo_pass}}@{{mongodb_hosts_path}}

$ docker run -it --net=host -e MONGODB_USERS_DATABASE={{mongo_users_db}} -e MONGODB_URI={{mongodb_full_uri}} -v $(pwd)/output:/opt/cleaner/output auraregistry.azurecr.io/aura-tools/database-cleaner

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.