User Session Management Service in WSO2 Identity Server

Imagine that you have logged into several applications in different browsers and now you want to terminate these sessions.

🤔 How you are going to achieve this?
One thing you can do is navigate to each of these applications and logout one by one.

What if you miss a session or else if there is an active session for you that you are not aware of? 😱

With the WSO2 Identity Server 5.9.0 release, managing your sessions is made much easier. The user session management service is one of the latest features that are introduced with 5.9.0.

The user session management service provides the functionality to monitor, and terminate the active sessions of users of WSO2 Identity Server.

Before the 5.9.0 release, the session management feature requires the WSO2 IS- Analytics server to monitor the sessions. But now, with WSO2 Identity Server 5.9.0, session management is handled from the Identity Server itself thus the deployment is made easier.

The session management service will provide information such as the IP address, user agent, accessed time of the session and details of the application related. From this information, you can easily identify the active sessions and terminate them if they are required no longer.

Administrative users have the authority to monitor the sessions of the other users and terminate the sessions if required. Therefore, if the sessions are compromised, admin users can terminate the sessions.

This service can be accessed in two different ways.

1. Monitor the sessions via the user dashboard
2. Monitor the sessions via REST API

☑ ️Prerequisites
Before trying the session management service, you need to create few sessions for a user. You can create active sessions for the users as follows.

1. Register a service provider in the WSO2 Identity Server so that the authentication for the application will be handled by the Identity Server.
2. Login to the application with valid credentials.

You may access the service using any of the two approaches mentioned above.

💻 Monitor the sessions via the user dashboard

WSO2 Identity Server has a user portal where the end users can log in and manage their profiles. This is also known as account self-service.

The user dashboard can be accessed from the URL https://localhost:9443/dashboard/. When you log in to the dashboard, you can see various gadgets that are responsible for managing security questions, the password and user profile. The functionalities of the dashboard are decided upon the permission levels of the logged-in user.

👨 End-User Perspective

My Login Sessions gadget performs session management actions. If you go inside this gadget, you can see the session information of the logged-in user.

User portal of the end-user

In this example, I have logged in as Alex. (I have created a few sessions for Alex before.)

If you click on the “View details” button of the “My Login Sessions” gadget, the active session information will be displayed as follows.

Session details of logged in user

The session information contains the IP address of the device, the time in which the session is initiated and the user agent of the session which has details related to device, browser and OS. For each session, there is a “TERMINATE” action button. You can click on this button and proceed with the confirmation if you want to revoke the specific session.

👮 Administrative User Perspective

As I mentioned above also, the admin users have the privilege to monitor and manage the sessions of the other users. In the admin user’s dashboard, there is a separate gadget named “Monitor User Login Sessions” which has this capability.

User portal of the admin user

In this gadget, the admin user can search for session information of any user. When the required name is entered in the search area, the active session information of that user is displayed if there are any.

Admin user also can perform the “terminate” action on the sessions of the other users.

⚙ Monitor the sessions via the REST API

As RESTful APIs are now favored over SOAP APIs, WSO2 Identity Server 5.9.0 has implemented RESTful APIs for core management capabilities and end-user interactions. There is a separate set of REST APIs for the session management service.

The session management service has 3 endpoints as of now. These APIs are responsible for the following functionalities.

1. Retrieve the session information of the logged-in user
2. Terminate a specific session identified by the session id of the logged-in user
3. Terminate all the sessions of the logged-in user

All these APIs are secured and the authorization is required to access the APIs. You may use basic authentication, OAuth2 common flows or the mutual SSL for authentication. If none of the authentication element is sent with the API invocation request, the 401 Unauthorized HTTP response will be returned.

The base URL for these APIs will be localhost:9443/t/{tenant.domain}/api/users/v1.

Let’s see in detail how each of these APIs can be called and the response. I will call the APIs from the same user Alex.

1. Retrieve the session information of the logged-in user

This API retrieves the session information of the logged-in user.

API :

GET      /me/sessions

Sample Request:

Sample Request:’
curl -X GET   https://localhost:9443/t/carbon.super/api/users/v1/me/sessions   -H 'Accept: application/json' -H 'Authorization: Basic YWxleDphbGV4MTIz' -k

Sample Response:

{
    "userId": "447c646f-4271-4782-a00a-da995d21d16b",
    "sessions": [
        {
            "applications": [
                {
                    "subject": "alex",
                    "appName": "saml2-web-app-pickup-dispatch",
                    "appId": "3"
                }
            ],
            "userAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/73.0.3683.103 Safari/537.36",
            "ip": "127.0.0.1",
            "loginTime": "1574535591876",
            "lastAccessTime": "1574535591876",
            "id": "82cd41211a7bbf4b7903f208935893010d3277ece6fe80bad280159c7871be2c"
        }
    ]
}

2. Terminate a specific session identified by the session id of the logged-in user

There are two DELETE APIs for the session management service. This API will terminate a specifically given session of the logged-in user. The session is identified by a unique ID.

API:

DELETE    /me/sessions/{session-id}

Sample Request:

curl -X DELETE   https://localhost:9443/t/carbon.super/api/users/v1/me/sessions/<session_id>   -H 'Authorization: Basic YWxleDphbGV4MTIz' -k

Sample Response:

204   No Content

3. Terminate all the sessions of the logged-in user

From this DELETE API, all the active sessions of the logged-in user are terminated. On the successful execution of the request, the response code of 204 is returned.

API:

DELETE     /me/sessions/

Sample Request:

curl -X DELETE  https://localhost:9443/t/carbon.super/api/users/v1/me/sessions -H 'Authorization: Basic YWxleDphbGV4MTIz' -k

Sample Response:

204    No Content

References

[1] You can follow the Quick Start Guide or Configuring Single Sign-On documentation to create sessions.

[2] You can refer to the official documentation for Session Management APIs for more details.

[3] All the possible errors that can occur while invoking these APIs are listed in this error catalog.

[4] You can try out the APIs using the postman collection available in WSO2 samples repository.

[5] You can see all the cool features of WSO2 Identity Server 5.9.0 from this blog.

Thank you for reading.