Usage Examples and Best Practices

On this page, we outline some use cases of the Authentication Manager (AM) as an authentication service supporting a web server offering services to users.

Consider a scenario where a web server provides its services to users on the network. Each user can access the application through a browser and view data. The application manager not only aims to restrict access solely to registered users but also intends to enforce access control to different data based on the permissions associated with individual users. To do this, it is necessary for the web server providing the service to interact with an authentication server, which will allow it to log in users, authenticate them with each call, and check their permissions.

This page illustrates how to perform the main user authentication and validation operations from a web server point of view. Additionally, there are diagrams that visually represent the flow of calls between services.

Log in of an unauthenticated user

When a user accesses the URL linked with the application, the web server receives a request on an endpoint responsible for populating the homepage, typically denoted as "/".

The first step when calling this endpoint is to examine the request for a token that authenticates and authorizes the requester. This token can be found either in the request header or within cookies.

In the absence of a token, authentication must proceed: the web server must engage with the Auth Manager at the /login endpoint, redirecting the user to the Identity Provider's web page for login using their credentials.

It's imperative to enable the /{auth-manager-URL}/authorize URL for redirects in the provider settings. Once the user inputs their credentials, a redirect to the /authorize endpoint of the AM is necessary, allowing the latter to retrieve the user's token and transmit it back to the web server within cookies.

Subsequently, the user is authenticated and authorized to access the application.

Request from an authenticated user

When the web server receives a request, it must first check for the presence of a token associated with the request. If a token is found in either the request's header or cookies, it needs to undergo evaluation on two fronts.

Firstly, the server must determine the validity of the token. This involves contacting the Auth Manager at the /apif/check-user-permissions endpoint, specifying an empty list of permissions. In this scenario, only the token verification process takes place, and if successful, a boolean value is returned to indicate its validity.

Once the token's validity has been confirmed, it must then be checked for expiration. This operation must be performed by the web server and it can be accomplished by decoding the token and comparing its expiration date with the current time.

If both checks pass successfully, the server can proceed with the requested operation. However, if either check fails, the user must be redirected to the login procedure to authenticate again.

Refresh an expiring token

When a user logs into the application and obtains a token, he utilize that token for all subsequent requests. After a certain period, typically determined by the Identity Provider, this token expires, thereby invalidating the user's authentication status and necessitating a fresh login.

To mitigate frequent logins, which could expose sensitive data and detract from user experience, providers introduce an additional token called a refresh token alongside the user's token. This refresh token serves as a means to request a new user token without requiring the user to log in again when the original token is close to expiration or has expired. However, it's essential to note that the refresh token also has a lifespan, and once it expires, the user will need to undergo the login process anew.

Upon receiving a request from the user, the web server has to verify the validity and expiration status of the token. If the token has expired, the server should check the expiration of the refresh token. If the refresh token is also expired, the user has to be redirected to the login page. Otherwise, the refresh token can be used to obtain a new user token by invoking the /refresh_token endpoint of the Auth Manager. Subsequently, the authentication server provides the new user token, which has to be used to replace the token previously used.

It's important to maintain a seamless user experience by refreshing the token within a secure window before its expiration, ensuring uninterrupted access to the application's services.

Permissions check for a user

Every time a request is received by the web server, it must not only validate the associated user token but also ensure that the user holds the required permissions to access the requested resource.

This validation process can be carried out using the /apif/check-user-permissions endpoint of the Auth Manager, where the list of permissions is specified for evaluation along with the corresponding logic. It's important to note that the user is identified by the AM through their token, hence it must always be included in the endpoint call.

The response from the Auth Manager includes both the user's group memberships and a boolean value indicating whether the user possesses the specified permissions. This determination may involve all permissions or at least one, depending on the specified logic.

At this point, the web server is aware of the permissions associated with the user and can use this information to populate the page with the correct data.

Request from a user with expired token

It may happen that a user with an expired token sends a request to the web server.

The web server must detect the token expiration because it needs to check the associated token each time it receives a request.

When the server detects that the token has expired, it is necessary to redirect the user to the login page so that the user can authenticate again and obtain a new token. To do so, the /login endpoint provided by the Auth Manager can be used.

Log out of a user

A user should have the capability to request a logout from the web application.

Upon invoking a logout endpoint, the web server is tasked with executing all necessary procedures to erase all user-related information and communicate with the provider to ensure a successful logout.

Depending on the handling of user tokens and sessions, it may be imperative to clear cache and session data associated with the current user. Subsequently, the web server should reach out to the Auth Manager at the /logout endpoint to initiate the logout process with the provider. It's crucial to specify the logout URL in the request to the Auth Manager.

At the end of this process, the user is successfully logged out from the application. To make new requests, the user will need to go through a new login operation.

Retrieve application token

A web application may need to perform preliminary or background checks to maintain the structure and consistency of data. In these cases, it may be necessary to obtain a token that allows interaction with other services in the architecture or access to data.

Since there is no user involved in this phase, the token that can be retrieved by the application is called an Application Token and can be requested by the server to the Auth Manager using the dedicated endpoint /apif/oauth/application-token.

To invoke the endpoint, the web server must have its authentication credentials and pass them within the payload of the request. The Auth Manager will respond with an application token.

Web server flowchart for authentication and authorization

In this flowchart, the behavior that a web server should maintain to handle user requests by performing the necessary authentication and permission checks is outlined. In addition to authenticating and authorizing users, in this example the web server performs background operations on the data, so it needs to obtain an application token at service startup.