Session Management

Introduction

When an end-user signs in to an application, the Mendix Runtime establishes a session that persists as long as the end-user remains active within the application. The session expires after a certain amount of inactivity, determined by the time elapsed since the last runtime request and the session timeout.

You can use authentication tokens to keep a session active while your end-users are not actively working in the app.

This approach provides a unified solution for session management, allowing long-lived sessions to be used in online, as well as offline applications, whether native or web-based. For example, you could customize the sign in to an online app to provide a “remember me” function so that end-users do not have to provide their credentials again if their session expires.

Authentication Token

Authentication tokens allow users to stay logged in for long periods of time. They store the authentication data of the user on the user’s device and use that to automatically create a new session when the previous session is expired.

Authentication Token Generation

When the runtime receives the get_session_data request, it checks the existence of the useAuthToken cookies. If present, it adds an additional HttpOnly cookie holding the generated unique authentication token authtoken. This token is then used in the subsequent actions to authenticate the user and extend the session when it expires.

This approach enhances security, as these cookies are inaccessible to anything other than the server.

Enable Authentication Token

If you want to generate authentication tokens in your online app, you have to use the Mendix 11 Client API.

The login method of this API allows you to pass the parameter useAuthToken. The value true enables the authentication token, false disables it. If the login action passes true to the runtime, the runtime adds an HttpOnly cookie useAuthToken indicating that an authentication token should be generated during the client startup.

You can also model your login page to provide end-users with a “remember me” option so they can decide whether they want to be remembered or not. For more information see Working with Authentication Tokens, below.

Working with Authentication Tokens

You can use authentication in both online and offline apps to remember the end-user. There are three ways Mendix suggests to do this:

• Use the SignIn activity from the NanoflowCommons module (version 5.0.0 or above) with the useAuthToken parameter set to true. This is the recommended and easiest method.
• Write your own JavaScript action using the login method of the mx-api module in the Mendix 11 Client API and setting the useAuthToken parameter to true.
• Write a Java action using the addMendixCookies method of the Runtime API, and setting the useAuthToken parameter to true.

Authentication Token Expiry

There is a custom runtime setting, com.mendix.webui.HybridAppLoginTimeOut that determines how long the authentication token is valid for. If no value is set, the token remains valid for one year.

Application Behavior

Native and Offline PWA Applications

This feature maintains backward compatibility, If end-users haven’t updated their apps on their devices, but the runtime is a newer version, it still functions correctly to support the previous session management methods.

Upgraded offline-first applications use the new authentication token system by default as calls to the login API enable the authentication token system.

If you do not want your offline-first app to create an authentication token, you can disable the use of authentication tokens by writing your own flow using the login method of the mx-api module in the Mendix 11 Client API but setting the useAuthToken parameter to false.

Online Applications

By default, authentication tokens will not be used in online Mendix apps. However, you can use them to remember the end-user. For more information see Working with Authentication Tokens, above.

Online apps still utilize the EnableKeepAlive setting to maintain uncommitted data which changes during the session. If that setting is disabled and useAuthToken is set to true, uncommitted changes will be lost if an action is performed after the session expires, which occurs after the SessionTimeout. In this case, the authentication token is used to reinitialize the session to keep user signed in, after which the application is reloaded.

Client-Runtime Session Management Flow

This diagram illustrates the interaction between the client and the runtime to initialize or retrieve the session.

Session Deletion

Sessions are deleted under two circumstances:

• When there is a database upgrade on application startup ‒ for example if there is a model change or if the database is new.

• During periodic cleanup of expired sessions.

  You can configure how often expired sessions are cleaned up using the ClusterManagerActionInterval runtime setting.

  You can configure when a session is considered expired using the SessionTimeout runtime setting.

When an anonymous session is deleted the associated anonymous user is deleted as well.