Fourth Platform Authorization middleware

Introduction

fourth-platform-authorization-middleware validates the user’s credentials and the authorization of the auraId sent by the channel, in order to provide all the information of the user needed before the execution of any Aura use case.

It is always executed just after the init-middleware.

For further details about Aura authentication, please go to Aura authentication, in order to understand the different types of Aura users regarding authentication.

Modules

fourth-platform-authorization-middleware lays on two modules:

• FourthPlatformAuth: class that must implement IAuraAuthenticator interface. This class provides all the methods and properties required to handle Kernel authorization mechanisms.

• AuraUser: generic class depending on the authenticator provided, in this case FourthPlatformAuth, and that implements AuraUserBaseModel<IAuraAuthenticator>.

fourth-platform-authorization-middleware flow

The first step is to try to get the user details from the aura-bot cache. In order to improve performance, we try to get it from the local cache of the server and only go to the remote cache if needed. This is done both if the user is authenticated or anonymous, but reading from different caches.

The source code of this middleware is included in Aura Bot Platform middlewares - Github repository.

If the user’s authentication information is cached, the next step is to validate it. If valid, then kpi-handler is called to write the USER entity row, and the next middleware is called. If user’s authentication information is neither cached nor valid, then the authentication process is launched:

1. Get user’s information by auraId from Aura AuthenticationService, getting both the data of the user stored in Aura users database and her channel configuration.

2. If it is a valid authenticated user, then read user’s authorization data from Kernel.

   • The first step in Kernel authentication is to have a valid accessToken, granted for the scopes and purposes needed by the use cases managed by the channel.

   • Then, if the channel needs it, UserProfile is read from Kernel API. Out of it, the AuraUserType is calculated in order to know if the user is monomsisdn, multimsisdn, nomsisdn.

   • The last step is to get the introspection token to obtain a complete view of the user’s identification, related to her authorization_id. Then, all the scopes in the introspection will be merged together and added to the information of the user.

   • After data from Aura AuthenticationService and Kernel is read and processed, there is a valid AuraUser object that is stored in the userDataCache and in the corresponding UserState of aura-bot.

   • Then, the next middleware is executed.

   • Error cases:

     • If a new accessToken cannot be obtained because authorization_id is not valid, then aura-bot stops message processing and returns an activity with an UNAUTHENTICATED code in the channelData to the channel, indicating that the channel must relaunch user authentication with Kernel.

     • Any other error generating accessToken or getting UserProfile or IntrospectionToken will return an INTERNAL code error in the channel, so it should retry the communication after a while.

3. If the given auraId does not exist in Aura’s database, it is validated if the user can be treated as anonymous.

   • This is only possible if the request has the specific identifier of the channel in the channelData.appContext.application.id field and if that channel allows anonymous users.

   • Error cases:

     • In case of an error accessing Aura AuthenticationService, excepting 404 (user not found in Aura database), aura-bot will stop message processing and will return an INTERNAL code error in the channel, so it should retry the communication after a while.

     • If the auraId is not found in Aura users database and the channel does not allow anonymous users, then aura-bot stops message processing and returns an activity with an UNAUTHENTICATED code in the channelData to the channel, indicating that the channel must relaunch user authentication with Kernel.

     • If the channel provided in the request is not a valid one, then aura-bot will stop message processing and return an INTERNAL code error in the channel, informing that the request is not valid.

In all the cases, before leaving the fourth-platform-authorization-middleware, the kpi-handler will be called to write a new row in the USER entity file, with the result of the authentication.

The flow diagram of the process is included below: