Session Termination Via Session Management REST API in WSO2 Identity Server
WSO2 Identity Server supports different user session management capabilities.
Imagine, you have logged into two applications AppA and AppB. As an end-user you may want to manage your user sessions. You may want to terminate one session, or terminate all sessions, or you want to see all your active sessions. In order to support your use cases, WSO2 IS provides User Session management REST APIs.
WSO2 IS User Session management REST API
WSO2 IS supports session management using REST APIs. It has
- Me API (used by a user to manage his/her sessions)
- Admin API (used by the admin to manage user sessions.)
Both Me and Admin APIs support the following functionalities:
Get all user sessions
Terminate a particular session.
Terminate all user sessions.
Play around with Session Management using MyAccount App
To play around with these REST api, refer to WSO2 IS doc space.
My Account app uses session management REST API to provide these capabilities. An end-user can manage his/her sessions using the My Account app. In prior versions, Dashboard app supported these session management capabilities via Admin services..
How to get view all sessions using your MyAccount app.
- Go to https://localhost:9443/myaccount (https://<IS server Hostname:port>/myaccount)
- Click on Security
- view Active IDP sessions sections.
This uses GET /me/sessions api to get all active sessions. You can expand each active browser session and terminate the session. Else you can click on Terminate all, and revoke all sessions.
What is sso-session binding?
WSO2 IS supports two tokens binding types OOTB:
- cookie-based binding.
2. sso-session based binding.
In cookie-based binding, IS binds token to a cookie atbv cookie. This is implemented to improve the security of SPAs.
sso-session based binding is intended to bind accesstokens to CommonAuthId cookie. (This cookie used for session management of users in WSO2 IS irrespective of inbound protocols). We can consider this binding type as a subset of cookie-based binding. In cookie-based binding, IS binds to a cookie called atbv cookie, which is a generic cookie. But in sso-session binding, IS binds tokens to coomonAuthId cookie.
Basically, this binding type is designed to generate different tokens for each new browser instance.
With this, you can avoid the same access token getting shared with multiple browser instances of the same application.
This binding type is supported for authorization code grant type. With this sso-session binding, all the accesstokens issued for code grant flow, are bound to sessions.
Session Termination using Session Management REST APIs
When you terminate the sessions using session management REST API, WSO2 IS will :
Revoke the respective access token.
Send logout notifications.
With these two improvements, managing user sessions and tokens is made much easier.
1. Revoke the respective access token.
- From IS 5.12-m5 version onwards, IS revokes the access tokens mapped with the sessions via REST API. For an example, when a user terminates the session via the REST API, the respective access token will be revoked.
- This is applicable for authorization code grant, implicit flow, refresh token grant, and hybrid flows.
- If there is no any binding is enabled, then in some cases the same accesstoken will be shared among the applications in the different browser sessions . In that case, if one application session is terminated, the respective token will also be revoked. This leads to a situation where the applications will also lose the accesstoken. Because the same accesstoken is used in many sessions. This has a mapping of one access token to many sessions
Eg: session to token mapping (without any binding type)
+-----------+--------------------+
| token | session |
+-----------+--------------------+
| token1 | session1 |
| token1 | session2 |
| token2 | session3 |
| token3 | session4 |
+-----------+--------------------+- So it is always recommended to use sso-session binding if you are using session management rest api to terminate the sessions (if the grant-type is authorization code). In that situation, only there will be a one to one mapping for token and sessions.
Eg: session to token mapping with sso-session binding type
+-----------+--------------------+
| token | session |
+-----------+--------------------+
| token1 | session1 |
| token2 | session2 |
| token3 | session3 |
| token4 | session4 |
+-----------+--------------------+- When you revoke one session using the API, the corresponding mapped accesstoken will be revoked (irrespective of binding type).
2. Send back-channel logout notification.
- When you terminate a session using session management REST API, all the applications in the same browser sessions will get back-channel logout notifications. (If the apps configured back-channel logouts).
- IS sends back-channel logout notification for the logout endpoints of the application.
- Refer to this doc to know how to configure OIDC back-channel logout with WSO2 IS
When a back-chanel logout notification is sent, an web application can consume it and get the notification for session termination.
But SPAs can’t rely on back-channel logouts. When a session is terminated via rest api, IS revokes the accesstoken as well. So SPAs can make use of this feature and when a SPA tries to access an API and if the SPA gets unauthorized errror response. Then the application can trigger logout by itself.
These revoking the accesstokens and trigger logout notifications are already supported by Identity Server when an external user invokes a logout request and terminates the session.
But from IS 5.12.0-m5 onwards, these capabilities are supported when the session is terminated via session termination REST APIs.
Reference
