Aura – authentication

Docs:

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

account-linking dialog

Description of the account-linking dialog, one of the dialogs that handles users’ account linking

Introduction

The account-linking dialog is included in the global linking library.

It is in charge of handling user’s account linking for channels using integrated authentication, that is, channels that already have a proper user’s identifier that should be linked with the corresponding auraId and that cannot handle Kernel authentication directly:

WebClient
Facebook
WhatsApp

This dialog launches authentication in Kernel based on browser navigation. It includes several steps to validate the Terms and Conditions of the services and to launch the user’s autentication in the OB authenticator and in Kernel that, in the end, would register the auraId in Aura users’ database.

Environment variables

Property	Type	Scope	Description
LINKING_FP_ACCESS_SESSIONS_ENDPOINT	string	Local	URL to Kernel Access Sessions API
LINKING_FP_CALLBACK_LOGIN_URL	string	Local	URL to redirect to authentification login
LINKING_FP_CALLBACK_LOGOUT_URL	string	Local	URL to redirect to authentification logout
LINKING_TERMS_AND_CONDITIONS_URL	string	Local	URL to terms and conditions HTML file. By default: `/documents/termsandconditions.html`
SAFETY_CHECK_ENDPOINT	string	Local	URL API client endpoint

Docs:

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

Global authentication dialogs

Global authentication dialogs support different types of authentication in Aura

Global authentication dialogs include:

Docs:

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

Channels authentication

How an Aura channel can authenticate users, in different scenarios

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.

The Aura channel should launch an authorize request to authenticate the end user. Follow Kernel documentation about how to consume APIs.
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.
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.

Docs:

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

get-oauth-url dialog

Description of the get-oauth-url dialog, one of the dialogs that handles users’ account linking

The get-oauth-url dialog is included in the global linking library.

This dialog returns to the channel the oauth URL to launch the account linking.

Docs:

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

account-remove dialog

Description of the account-remove dialog, one of the dialogs that handles users’ account linking

The account-remove dialog is included in the global linking library.

This dialog launches the logout process in Kernel based on browser navigation.

It includes several steps to remove the login session from Kernel and in the OB authenticator that, in the end, would remove the auraId from the Aura Users’ database.

Docs:

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

seamless-account-remove dialog

Description of the seamless-account-remove dialog, one of the dialogs that handles users’ account linking

The seamless-account-remove dialog is included in the global linking library.

This dialog launches seamless logout in Kernel.

It counts on several steps to remove the login session from Kernel and in the OB authenticator that, in the end, would remove the auraId from the Aura users’ database.

Docs:

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

onboarding-whatsapp dialog

Description of the global onboarding-whatsapp dialog for WhatsApp channel

Introduction

The onboarding-whatsapp dialog is a simple dialog that returns some personalized messages for WhatsApp or other channel.

The dialog returns three messages with all the information necessary for the user’s onboarding and the Terms and Conditions acceptance.

According to the type of user (authenticated or anonymous), the messages will be different:

For anonymous users, the messages returned will be:

onboarding:onboarding.welcome
onboarding:onboarding.privacy
onboarding:onboarding.terms-and-conditions

For authenticated users, the returned messages will be:

onboarding:onboarding.auth.welcome
onboarding:onboarding.auth.privacy
onboarding:onboarding.auth.terms-and-conditions

If one of these texts are filled with " " in the locales, this message will not be sent, excepting terms-and-conditions text, which is mandatory. The first two messages, welcome and privacy, are only sent the first time this user arrives to the dialog. In succeeding interactions, only terms-and-conditions message will be returned.

Terms and conditions

aura-bot redirects to this dialog when Terms and Conditions settings are set, and the user has not accepted them yet.

More info about Terms and Conditions settings and flows here.

Docs:

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

Description of the whatsapp-otp-login dialog, that handles SMS-OTP authentication in this channel

Introduction

The whatsapp-otp-login dialog is a global dialog to make the user login in the WhatApp channel.

Currently, it only supports SMS-OTP authentication.

Access to the Kernel WhatsApp API.

📃 Check the dialog’s code in the aura-bot-libraries Github repository.

Flows

The dialog flow is divided in several steps, which are described in the following sections.

Additionally, a sequence flow is included in Operational flowcharts: WhatsApp OTP (LoA2) authentication.

Check if the user is already authenticated

When the dialog flow starts, it checks if the current user is already authenticated, verifying if the type of user is anonymous.

If so, the dialog flow ends with the text resource login.otp.already.signin. If not, it starts a sub-dialog to verify the phone number to send the SMS code.

Check if current number is corporate

In this step, if configured so, the system checks if the current phone number is corporate, to allow using it in next steps.

If check is not enabled or user is not corporate, go to the following step for prompting a new phone number.
Otherwise, ask the user if she wants to use current number.

Prompt a phone number

This step prompts the user to enter the phone number he wants to log in with in Aura, thus the dialog will send the SMS-OTP code to that phone number.

If the phone number format is correct:
1. If configured to check the prompted number and the number is not corporate, ask for a new phone number (until max number of retries is reached).
2. Otherwise, it starts a sub-dialog to verify the SMS authcode.
If the format is wrong, the dialog will prompt again to enter with correct format until the maximum number of attempts is reached (See settings section). When the user reaches this maximum, the dialog ends with the text resource login.otp.too.many.phone.kos.

To send this code to the user phone, the send code endpoint from Kernel is called. This endpoint returns an authentication_id that will be used in the next step to validate the OTP code.

Insert SMS OTP code

This step prompts the user to enter the SMS authcode sent to phone number provided on the previous step.

When the user enters the correct code, the dialog starts the following step in order to register the user.
If the authcode is wrong, the dialog will prompt again to enter the correct authcode until the maximum number of attempts is reached (See settings section).

When the user reaches the maximum authcode attempts the dialog ends with the text resource login.otp.too.many.sms.kos. A new code can be sent by sending the text resource login.otp.newCode.command which makes the bot to send a new auth code to the phone number provided.

To validate the code, the Kernel validate code endpoint is called with the code received by the user and the authentication_id returned in the previous api call. This call returns all the necessary data to register the user in Aura.

Register user

This step registers the user in Aura ecosystem and redirects to onboarding T&C with the intent intent.onboarding.terms-and-conditions or the requested intent before authentication if T&C are already accepted.

To do this registry, the method GET /users/aura-id/{auraId} from aura-authentication-api is called and the user is registered with the data obtained from Kernel in the previous step.

The redirect to onboarding (or the intent set) is done if the field actions.afterLogin is present in the channel configuration. An example of this configuration is shown below:

 {
  "name": "whatsapp",
  "prefix": "wa",
  "type": "whatsapp",
  "responseOptions": {
      "versions": {
          "v1": {
            "singleMessage": true,
          }
      }
  }
  .
  .
  .
  "actions": 
    "afterLogin": {
        "type": "redirect",
        "action": "REDIRECT.COMMAND",
        "data": {
            "auraCommand": {
            "type": "suggestion",
            "value": {
                "intent": "intent.onboarding.terms-and-conditions"
            }
            }
        }
    }
  }
  .
  .
  .

This configuration is used to generate the redirect command that will be sent to launch the intent. If there is an intent requested before authentication and the T&C are already accepted, the intent set in configuration will be overwritten with the requested intent.

NOTE The user can cancel login flow at any moment by sending the text resource login.otp.cancel.command.

Sequence diagram

sequenceDiagram
    autonumber
    participant user
    participant auraBridge
    participant auraBot
    participant 4p
    participant auraAuth
    participant T&C API
    rect rgb(255, 255, 230)
    Note left of user: USER REQUESTS AN AUTHENTICATED UC
    user->>auraBridge: I want to see my billing data
    auraBridge->>auraBot: 
    auraBot->>auraBot: Dialog needs auth and user is anonymous. Redirect to whatsapp login
    auraBot->>auraBridge:  
    auraBridge->>user: login.otp.phone.number: Please enter your phone number
    user->>auraBridge: +34665762892
    auraBridge->>auraBot: 
    auraBot->>4p: Aura requests a new OTP sms
    4p->>user: (SMS) login.otp.sms.code.message: Your verification code is 6789
    4p->>auraBot: authorization_id
    auraBot->>auraBridge: 
    auraBridge->>user: login.otp.sms.sent.message: Please insert the code
    user->>auraBridge: 6789
    auraBridge->>auraBot: 
    auraBot->>4p: Aura validates the code
    4p->>auraBot: Returns user data
    auraBot->>auraAuth: Register user
    auraAuth->>auraBot: 200 OK
    alt
        Note left of T&C API: User already accepted authenticated T&C
        auraBot->>T&C API: Checks terms and conditions
        T&C API->>auraBot: 200 OK
        auraBot->>auraBridge: Response + Redirect intent
        auraBridge->>user: login.otp.success: Great! you are now signed in
        auraBridge->>auraBot: intent.billing from redirect intent
        auraBot->>auraBot: authenticates the user and executes the billing dialog
        auraBot->>auraBridge: 
        auraBridge->>user: "Here is your billing data"
    else
        Note left of T&C API: User needs to accept authenticated T&C
        auraBot->>T&C API: Checks terms and conditions
        T&C API->>auraBot: 404 Not found
        auraBot->>auraBridge: Response + Redirect intent
        auraBridge->>user: login.otp.success: Great! you are now signed in
        auraBridge->>auraBot: intent.onboarding.terms-and-conditions from redirect intent
        auraBot->>auraBot: authenticates the user and executes T&C dialog
        auraBot->>auraBridge: 
        auraBridge->>user: onboarding:onboarding.auth.welcome
        auraBridge->>user: onboarding:onboarding.auth.privacy
        auraBridge->>user: onboarding:onboarding.auth.terms-and-conditions
    else
        Note left of T&C API: Channel doesn't have terms and conditions config
        auraBot->>auraBridge: Response + Redirect intent
        auraBridge->>user: login.otp.success: Great! you are now signed in
        auraBridge->>auraBot: intent.billing from redirect intent
        auraBot->>auraBot: authenticates the user and executes the billing dialog
        auraBot->>auraBridge: 
        auraBridge->>user: "Here is your billing data"
    end
end

BotResponse settings

Currently, the dialog has a main intent intent.authentication.login and three auxiliary intents: otp-confirm-user-phone-number-dialog, intent.authentication.otp.phone.number and intent.authentication.otp.auth.code. These auxiliary intents are necessary to enable the flow between sub-dialogs.

        {
            "id": "whatsapp-otp-login-dialog",
            "triggerConditions": [
                {
                    "intent": "intent.authentication.login"
                }
            ]
        },
        {
            "id": "otp-confirm-user-phone-number-dialog",
            "triggerConditions": [
                {
                    "intent": "intent.otp.confirm.user.phone.number.dialog"
                }
            ]
        },
        {
            "id": "otp-phone-number-dialog",
            "triggerConditions": [
                {
                    "intent": "intent.authentication.otp.phone.number"
                }
            ]
        },
        {
            "id": "otp-sms-auth-code-dialog",
            "triggerConditions": [
                {
                    "intent": "intent.authentication.otp.auth.code"
                }
            ]
        }

Settings

This section lists and describes all the variables the whatsapp-otp-login dialog uses and that can be configured to adapt the environment:

Property	Type	Description	Default value
LINKING_FP_WHATSAPP_ENDPOINT	string	WhatsApp API endpoint
LINKING_WA_MAX_FP_SEND_SMS_RETRIES	number	Maximum SMS retries.	3
LINKING_WA_MAX_AUTHCODE_RETRIES	number	Maximum authcode retries.	3
LINKING_WA_MAX_PHONENUMBER_RETRIES	number	Maximum phonenumber retries.	3

Docs:

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

whatsapp-logout dialog

Description of the whatsapp-logout dialog, that handles the log out process for this channel

Introduction

The whatsapp-logout dialog is a global dialog in charge of the user’s logout in the WhatsApp channel.

📃 Check the dialog’s code in the aura-bot-libraries Github repository.

Flows

The flow of this dialog is simple. In the first step, a prompt is returned to the user to confirm if he wants to logout.

After that, if he accepts, certain actions are performed:

The user is deleted in Aura database calling the aura services API. If this call fails, an error will be returned, and the logout will fail.
The user is deleted in Kernel calling the logout endpoint. If this call fails, the flow continues normally returning a success message to the user and only showing an error log.
If the user is logged with LoA3, access session is deleted in Kernel calling access session delete endpoint. If this call fails, the flow continues normally returning a success message and only showing the error in logs.
The local cache is set to invalid to force the refresh next time the user interacts with Aura.

Docs:

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

Office 365 Authentication

Description of the Office 365 authentication made by ATRIA

Introduction

User authentication on ATRIA web interface is integrated with Office 365, using one internal component component (oauth2-proxy) and one external component (keycloak), managed by Novum

The oauth2-proxy component works as a reverse proxy, receiving requests and redirecting them to keycloak in case they are not authenticated.
Keycloak manages the application users and has a connector for Office 365, so it redirects to the Office365 login web to identify with the www.telefonica.com corporate account.
In case of correct login, it loads the proxified web with a cookie (and optionally, other headers) where the user is already logged in.

Authentication workflow

The authentication process will be transparent for the ATRIA web interface and, therefore, for developers.

The atria web interface may have no authentication at all, or a basic one, and oauth2-proxy and keycloak are in charge of the entire process:

The oauth2-proxy component will be deployed, configured and operated by the Aura DevOps team.
The keycloak component will be managed by the Novum team, including granting access to a user list.

Sequence diagram

sequenceDiagram
    actor Browser
    Browser->>+OAuth2 Proxy: Request /*
    OAuth2 Proxy-->>-Browser: Redirect to Keycloak's login page
    Browser->>+Keycloak: User login
    Keycloak->>Keycloak: O365 Login
    Keycloak-->>-Browser: Redirect to /oauth2/callback
    Browser->>+OAuth2 Proxy: Request /oauth2/callback
    OAuth2 Proxy->>+Keycloak: Get access token
    Keycloak-->>-OAuth2 Proxy: Send id & access token
    OAuth2 Proxy-->>-Browser: Send session cookie and redirect to /*
    Browser->>+OAuth2 Proxy: Request /*
    OAuth2 Proxy->>+Atria web interface: Request /*
    Atria web interface-->>-OAuth2 Proxy: HTTP response
    OAuth2 Proxy-->>-Browser: HTTP response

Authentication steps

The three main authentication steps are detailed below, together with the team in charge of its execution.

1. Installation

A new environment must be created using the aurak8s installer, where oauth2-proxy will be installed and configured.

Responsible teams: Novum

Once installed, it is necessary to create a new client in keycloak, with the redirection URL https://<deployed-env>/oauth2/callback and create a user group with the members that will have access.

OAuth2-proxy tips from Cross team

oauth2-proxy is designed to be installed one per environment.
Redis is necessary, and one instance per environment is also required to be installed.
In Kubernetes, virtualserver in Nginx is used to configured ingress traffic.

Keycloak tips from Novum team

Login: The only login screen will be the one from Office 365.
Logout: Usually, it is not required. If we want to use it, it will logout the user from O365 (for all web apps).
CORS: Identify static REST endpoints and configure two different rules.
Error codes: The web application will not see typically any auth error code.

2. Requesting access for users

Responsible teams: Aura ATRIA team and Novum

The Aura ATRIA team must pass a list to Novum team for requesting access for certain users.
Each user must have the following data:
- Name: Full name of the user
- Email: E-mail of the user
- Group: A list of keycloak groups to where the user must be added (typically, one per environment, dev, pre and pro)
The Novum team is in charge of providing access to these users.

3. Virtualserver

Responsible teams: Aura ATRIA DevOps team

Virtualserver is used to configured Nginx. We have two virtualserver in the authentication method:

aura-services virtualserver: we have to modify it to add two paths:
- /aura-mf-base-atria: redirect to aura-mf-base-atria if the user is logged in or if not to the next path.
- /oauth2/auth: redirect to oauth2-proxy service.
oauth virtualserver: redirect to oauth2-proxy service.

An example is shown below:

aura-services virtualserver /aura-mf-base-atria

    location /aura-mf-base-atria {
         auth_request /oauth2/auth;
         error_page 401 =302 https://auth-svc-ap-nine.auracognitive.com/oauth2/start?rd=$scheme://$host$request_uri;
         auth_request_set $user   $upstream_http_x_auth_request_user;
         auth_request_set $email  $upstream_http_x_auth_request_email;
         proxy_set_header X-User  $user;
         proxy_set_header X-Email $email;
         auth_request_set $token $upstream_http_authorization;
         proxy_set_header Authorization $token;
         auth_request_set $auth_cookie $upstream_http_set_cookie;
         add_header Set-Cookie $auth_cookie;
         auth_request_set $auth_cookie_name_upstream_1 $upstream_cookie_auth_cookie_name_1;
         if ($auth_cookie ~* "(; .*)") {
             set $auth_cookie_name_0 $auth_cookie;
             set $auth_cookie_name_1 "auth_cookie_name_1=$auth_cookie_name_upstream_1$1";
         }
         # Send both Set-Cookie headers now if there was a second part
         if ($auth_cookie_name_upstream_1) {
             add_header Set-Cookie $auth_cookie_name_0;
             add_header Set-Cookie $auth_cookie_name_1;
         }
         proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
         proxy_set_header Host            $http_host;
         proxy_pass http://aura-mf-base-atria:4000/aura-mf-base-atria;
    }

aura-services virtualserver /oauth2/auth

  - action:
      proxy:
        upstream: oauth2-proxy
    location-snippets: |
      proxy_pass_request_body off;
      proxy_set_header Content-Length "";
    path: /oauth2/auth

oauth virtualserver /

  routes:
  - action:
      proxy:
        upstream: oauth2-proxy
    path: /
  tls:
    secret: nginx-certificates
  upstreams:
  - name: oauth2-proxy
    port: 80
    service: oauth2-proxy

Aura – authentication

Docs:

account-linking dialog

Introduction

Environment variables

Docs:

Global authentication dialogs

Docs:

Channels authentication

Scenarios for users’ authentication

Authenticated users

Integrated authentication

Non-integrated authentication

Anonymous users

Users expiration

Docs:

get-oauth-url dialog

Docs:

account-remove dialog

Docs:

seamless-account-remove dialog

Docs:

onboarding-whatsapp dialog

Introduction

Terms and conditions

Docs:

whatsapp-otp-login dialog

Introduction

Flows

Check if the user is already authenticated

Check if current number is corporate

Prompt a phone number

Insert SMS OTP code

Register user

Sequence diagram

BotResponse settings

Settings

Docs:

whatsapp-logout dialog

Introduction

Flows

Docs:

Office 365 Authentication

Introduction

Authentication workflow

Sequence diagram

Authentication steps

1. Installation

OAuth2-proxy tips from Cross team

Keycloak tips from Novum team

2. Requesting access for users

3. Virtualserver