When the end-user executes login the server sends two authentication cookies to the mobile app. These cookies allow the end-user to be authenticated in subsequent server requests.
The server will handle the authentication cookies according to the type of authentication being used.
There are two types of authentication:
- Session authentication - The authentication cookies are destroyed when the end-user closes the app.
- Persistent authentication - The authentication cookies persist across multiple application starts.
The developer specifies the authentication type in the
RememberLogin parameter when calling the action
User_Login to login the users.
This section describes the two cookies used in the authentication mechanism of an OutSystems mobile app.
nr1<User Provider Name>:
- The server uses this cookie to enforce session expiration as needed;
- Contains information needed to ensure session authenticity;
- Set as
nr2<User Provider Name>:
- Provides information to the application code about the user identifier via Built-in function GetUserId();
- Contains information needed to avoid CSRF attacks;
- Not set as
Verifying Authentication Cookies
When executing a server call, the mobile app sends the authentication cookies to the server, having a CSRF token in a “X-CSRF-Token” request header.
The server validates the request by checking the following conditions:
- The request includes the X-CSRF-Token header;
- The request contains the two authentication cookies;
- Cookies information is authentic and was not forged;
- Login expiration period has not been reached.
If all conditions apply, the server authenticates the request as coming from the user identified in the cookies, otherwise the server will process the request as if it was coming from an anonymous user.
The authentication mechanism for OutSystems mobile apps includes caching capabilities to avoid the overhead of validating and updating authentication information in the database upon each request.
Within a defined period of time the server uses the information stored in the cookies to authenticate the requests of an authenticated session, instead of retrieving the authentication information from the database.
Configure Mobile App Authentication Settings
OutSystems mobile authentication mechanism is configurable per environment to meet different security requirements.
You are able to configure general mobile authentication settings and also specific settings for persistent and session authentication.
The following setting applies to both persistent and session authentication:
- Cache Time In Minutes - Number of minutes the authentication information sent by the device is considered valid by the server without the need to fetch it from the database. After this time, the server will validate the authentication tokens against the information stored in the database and supply new authentication tokens. If set to 0, the authentication cache mechanism is disabled.
The following settings are used for persistent authentication:
Max Idle Time - The maximum number of days a user will stay logged in (in the server) without communicating with the server. After this time has passed the user will need to log in again if the application goes online (connects to the server);
Cookie Expiration - The maximum number of days a user will stay logged in (in the application) without communicating with the server. After this time has passed the cookie expires and the application will need to go online (connect to the server) and the user will need to log in again.
The following setting is used for session authentication:
- Max Idle Time - Number of minutes between server calls that a user authentication is recognized by the server as being valid.
To configure the authentication settings for the mobile apps in your OutSystems environment, do the following:
- Go to the Service Center management console of your OutSystems environment;
- Go to the Administration section and select the Security tab;
Select the Mobile Applications Authentication area:
In this page you will also be able to generate new keys for authenticating and encrypting cookie values. This will force all the users of your mobile apps to login again in the next server request. To generate new keys, press the Generate button in Authentication and Encryption Keys area: