Skip to content

Add concurrent sessions based access control

You can effectively control the number of concurrent user sessions for an application by implementing the Session-Based conditional authentication template. Users are redirected to a dedicated page where they can manage their existing sessions or cancel the current authentication request if they exceed the number of allowed concurrent sessions.


Consider a scenario with two roles, admin and manager. Users belonging to these roles are limited to having only one active session at a time. If they try to initiate a second session, they will be presented with a list of their current sessions and offered with the following two options:

  • Terminate any of their existing sessions.
  • Cancel their current authentication attempt.


Configure the login flow

To configure the login flow with concurrent session-based access control:

  1. On the WSO2 Identity Server Console, click Applications.
  2. Select the relevant application and go to its Login Flow tab.
  3. Add concurrent session-based access control as follows.

    1. Go to Predefined Flows > Conditional Login Flows.

    2. Click Access Control > Session-Based > ADD.

    3. Click Confirm to replace any existing script with the selected predefined script.

  4. Update the following parameter in the script.

    Parameter Description
    rolesToStepUp Comma-separated list of user roles. Two-factor authentication should apply
    to users from these roles.

    For this example scenario, enter admin and manager.

    The number of allowed sessions for the user

    For this example scenario, enter 1 as we allow only one concurrent active sessions per user.

    The number of allowed sessions for the user

    For this example scenario, enter 1 as we allow only one concurrent active sessions per user.
    Use the same value assigned for MaxSessionCount.

  5. Click Update to confirm.

How it works

Shown below is the user age-based conditional authentication template.

// This script will prompt concurrent session handling
// to one of the given roles
// If the user has any of the below roles, concurrent session handling will be prompted
// and it will either kill sessions or abort login based on number of active concurrent user sessions
var rolesToStepUp = ['admin', 'manager'];
var maxSessionCount = 1;

var onLoginRequest = function(context) {
   executeStep(1, {
       onSuccess: function (context) {
       // Extracting authenticated subject from the first step
           var user = context.currentKnownSubject;
           // Checking if the user is assigned to one of the given roles
           var hasRole = hasAnyOfTheRolesV2(context, rolesToStepUp);

           if (hasRole) {
      + ' Has one of Roles: ' + rolesToStepUp.toString());
                   executeStep(2, {
                       authenticatorParams: {
                            local: {
                                 SessionExecutor: {
                                      MaxSessionCount: '1'
                   }, {});

Let's look at how this script works.

  1. When step 1 of the authentication flow is complete, the onLoginRequest function retrieves the authenticating user from the context.
  2. The function verifies whether the authenticating user is a member of the roles listed in rolesToStepUp.
  3. If the authenticating user is assigned to one or more roles in rolesToStepUp, authentication step 2 is prompted with maxSessionCount being passed as a parameter to the Active Sessions Limit handler.


Find out more about the scripting language in the Conditional Authentication API Reference.

Try it out

Follow the steps given below.

  1. Access the application URL.

  2. Log in to the application as a user belonging to the admin or manager.

  3. Attempt to log in as the same user from a second browser.

    Now, the user will receive a prompt, allowing them to either terminate one of their existing sessions or deny the authentication request for the second session.