Channels authentication

Scenarios for users’ authentication

Regarding authentication, an Aura channel can deal with two different scenarios, which are fully explained in the succeeding sections:

• Dealing with authenticated users
• Dealing with anonymous users

Authenticated users

Aura supports two types of authentication when referring to channels:

• Integrated (or federated) authentication: aura-bot is responsible for the user’s authentication, i.e., when the channel sends its user identifier to aura-bot, and the bot executes the user authentication.
• Non-integrated authentication: the channel executes all the authentication processes for the user and sends to Aura the resulting authorization_id.

Integrated authentication

The case of integrated authentication is characterized by the fact that the Aura channel is the one starting the authentication process, sending an account linking request to the aura-bot instance including the channel own user identifier, that will be used as a base for building an auraId.

It is used for those channels that cannot launch a Kernel authentication process themselves, before making a request to Aura. Therefore, all the authentication process is managed by the aura-bot instance making requests to Kernel when needed.

The message sent from the Aura channel to the aura-bot instance could contain a text similar to “I want to authenticate myself”, or an auraCommand with an account linking intent, or a use case that requires authentication.

Account linking auraCommand example:

{
  ...
  "from": {
    "id": "<channel-user-identifier>"
    ...
  },
  {
    "channelData": {
      "auraCommand": {
        "type": "suggestion",
        "value": {
          "intent": "intent.account.linking"
        }
      }
    }
  }
}

Channels with this authentication are:

• WhatsApp

Non-integrated authentication

In the case of non-integrated Authentication, the Aura channel must be registered as a Kernel Platform application, so it can have access to the Kernel Platform APIs.

Further information regarding this application registration process can be found in the Kernel documentation about getting credentials.

Please, remember to request access to the proper purpose that enables accessing to Aura Users APIs.

Once the Aura channel has been registered as an application, it will have access to the Kernel Platform Aura-Services API.

1. The Aura channel should launch an authorize request to authenticate the end user. Follow Kernel documentation about how to consume APIs.

2. Afterwards, the Aura channel should make a request to Aura getAuraId API.

   • Firstly, the channel generates a 3-legged access token for the given user, including the purpose to access the Aura-Services APIs.
   • Then, it makes a request to the GetAuraId endpoint.
     • The channel must call this API each time there is a new authorization session in the channel, because aura_id is only valid while the session or authorization_id is valid.
     • Remember to log every request to Kernel including the x-correlator header (correlation id for the different services), so all requests can be traced in the channel, Aura and Kernel, and it is possible to have an E2E view of each request. The same correlator should be used in all requests related to a single user interaction, it should be sent to Aura, Kernel, etc.

   You can cache the aura_id and send requests to Aura using that aura_id. If the aura_id is no longer valid, you will receive an error message like:

   Channel data v3 (current):

   "text": "<error_message>",
   "inputHint": "acceptingInput",
   "channelData": {
     "status": {
       "code": "ERROR.USER.UNAUTHENTICATED",
       "params": {"auraId": "received_aura_id"},
       "message": "Invalid aura user"
     }
   }
   

   Channel data v1 (obsolete):

   "text": "<error_message>",
   "inputHint": "acceptingInput",
   "channelData": {
     "Error": {
       "code": "UNAUTHENTICATED",
       "data": "received_aura_id",
       "message": "Invalid auraId"
     }
   }
   

   If you receive an error like these, you will need to:

   • Refresh the authorization_id by calling the authorize method from Telefonica Kernel auth-server.
   • Call the getAuraId API again from Kernel APIs.

3. The Telefonica Kernel Platform API calls the aura-services API that will validate if the user already exists or not.

   • If the user exists with the same user_id, authentication_context and authorization_id, the same user data will be returned to Kernel and to the Aura channel, including the aura_id of the user.
   • If the user does not exist, it is created in the Aura users’ database and the result is returned to the Aura channel, which can get the aura_id of the user.

Just in the case of non integrated authentication, the aura_id returned by Kernel API will be used as the from.id property in all requests to be sent to the aura-bot instance. For integrated authentication the channel just sends its internal user identifier.

Anonymous users

Anonymous users can only access a limited set of use cases that do not need granted access to any user data, for instance: generic questions or greetings.

• If a channel allows anonymous users, it would send an autogenerated aura_id in the from.id property of the request in UUID format.
• If the channel does not support anonymous users, the user will be considered unauthenticated and will return an error like in non-integrated authentication.

Usually, if a use case is for channels that support anonymous users, an authentication dialog will be launched, specific to each channel, which will allow the user to log in to access the use case. Channels that support anonymous users usually have integrated (federated) authentication. Some authentication use cases are SMS-OTP in WhatsApp channel.

If the intention of the user is one of the admitted without authentication, the corresponding response will be sent. Otherwise, a prompt to launch the authentication process or a message informing that anonymous users cannot access that information will be returned.

Users expiration

The time to expire a user can be configured by channel with the configuration variable authorizationIdExpiration.

Learn how to do it in the document Configure users expiration.