When a client requests access to an application, the application does not authenticate the client directly, for instance, by validating the client's login credentials against an internal database. Instead, the application uses a Secure Token Service (STS) mechanism that authenticates the client and grants it a security token.
The metadata and authentication settings of the application relying on STS uses the tokens for validating the users and controlling their access to the specific areas of application.
The token consists of a set of encrypted JSON data records that include multiple elements, to name a few:
- the identity and group membership of the client (user name, user ID, user role and granted application access);
- information regarding the lifetime of the token;
- the issuer of the token;
The token issuing mechanism requires end-user interaction, i.e. the user provides credentials for the login.
Each time the user submits valid login credentials on the application login page, the authentication server presents the token to the user to gain access to the resources provided by the application. Once the user is logged in, each subsequent request will include the token, allowing the user to access routes, services, and resources that are permitted with that token:
Additionally, such an approach enhances data transfer security by limiting the token lifetime to a specific period. When the token expires, the user has to re-login and a new security token is issued automatically.
The token is protected from manipulation with a strong encryption algorithm using a unique secret string that is generated during the Matrix42 installation process.
STS settings during system install
The Secure Token Service is enabled by default during the system installation process on the Security Configuration step.
The unique secret string used in the token encryption is automatically generated for the hostname specified during installation and stored in the STS configuration file.
Managing token lifetime
Automatically issued for the end-user session token has an expiration date. Each time the token expires user is redirected to the application's login page.
The Administrator who has access directly to the application server can manually edit the secure token lifetime in the
<?xml version="1.0"?> <configuration> <configSections> <section name="stsconfig" type="Matrix42.STS.WM.Config.OAuth2Config, Matrix42.STS.WM"/> </configSections> <stsconfig stshost="https://host_name.matrix42.de" <!--hostname specified during system istall--> clientsecret="12client34secret56" <!--data used in the token encryption--> audiencesecret="aUdIEncE_sEcRet" <!--data used in the token encryption--> tokenlifetime="960"> <!--token lifetime in minutes. Default value is set to 16 hours--> </stsconfig> </configuration>
The default token lifetime is applied for the end-users session only.
Public API requests
Although the encryption mechanism is common both for the end-user sessions and the public API requests, the token issuing and lifetime for the latter is managed manually in the dedicated area of the Administration application → Integration → Web Services Tokens page.