Session Limitations

Target Audience: Users, Developers, Stakeholders

Introduction

The use of this feature should help to discourage your customers from sharing their account password and instead share their subscription (if applicable).

ADDON

This feature is an addon-function that has a separate activation- and monthly license-cost.

SSO2 required

This feature requires a working SSO2 single sign-on implementation already in place at your websites.

Session limitations lets you define a maximum number of sessions that can be active for an account at the same time. If the maximum number of sessions is exceeded, further logins are prevented without logging out one of the other active sessions.

From a technical point of view it means that upon a login-request where the number of active sessions exceeds the configured maximum number of sessions, the login-request will fail with error session_limit_reached and the session will still be anonymous.

The response for the login-request will besides the error also include a one-time password and a list of the currently active sessions which can be displayed to the customer. Then, depending on how SSO has been implemented on your website there can be different ways of handling this.

One strategy which we have implemented in Payway PAP and PCP is to let the customer choose which of the other active sessions the customer wants to logout. The application (PAP/PCP) will then logout the selected session(s) and then login the customer using the supplied one-time-password. If your implementation of SSO in your organisation uses the login-form in PCP then this is the strategy that will be used for your customers.

However, if you have implemented your own login functionality on your websites with your own login forms, you will need to handle the login-request in your own application and then you will have more options available when choosing how to deal with this scenario. You could develop the same kind of strategy as we have in PAP/PCP, but you could also implement a more aggressive strategy of handling multiple active sessions. For example, you could logout all sessions at once and maybe also issue a reset-password request for the account to make the account-holder set a new password.

Information about an account's current active sessions are available to view in PAP on the customer view ("Active sessions"), with support to logout a session for customer service staff.

A customer facing view is also available on "My Account" in PCP (My sessions) where the user can select to logout a selected session if so desired.

Both PAP and PCP fully support session limitations.

Required development for integrating applications

As an integrating application the following needs to be handled when session limitations are activated:

1. The authentication request can fail with error session_limit_reached and the application needs to display a list of active sessions to the customer.
2. The customer should be able to select one or several of the active sessions for logout.
3. The application should logout the selected sessions and then authenticate the current session using the one-time password supplied in the login-response.

Sample active session display in PCP

Optional development for integrating application

If an integrating application plays the role of "My Account" for an organisation, it is possible to develop support for "My sessions" in that application.

The application can then fetch a list of current active sessions for an account and display it for the customer, and let the customer logout one or several of the sessions.

Sample "My sessions" functionality in PCP

Activation

Info

Please contact Adeprimo Servicedesk when you wish to activate this feature in production!

Attention

Upon enabling activation, a job will be dispatched that will remove all current active sessions that exceeds the maximum number of sessions allowed. From an enduser perspective those users will experience a logout.

Activation and management of session limitations is available for Superusers under sub-menu "Session limits" which can be found in the "Security" section in PAP. Configuration options here are:

• Activate session limits
• Set the maximum number of active sessions per account

Session limits can be deactivated at any time which will take effect directly upon saving the configuration.

API

Changes

The most important change to SSO this feature adds, is the response to the authenticate call, where a new error message can be returned to the application and a new set of claims has been added.

If the error message is session_limit_reached is received when performing an authentication request, the following new claims will also be available.

Claim	Description
slm	The current session limit configured.
ses	An array of active sessions in JSON format.
otp	A one-time password that should be used for login of the user.

The slm and ses claims should be used to inform the user about the current session limits and for displaying the current active sessions associated with the account logging in.

After the user has selected sessions to logout, the application needs to logout these sessions using the logout request.

When the sessions have been logged out, the application then needs to issue a new authenticate request for the user, but this time including the otp claim and without the usr and pwd claims.

Overview

Error handling

Too many sessions

If the user still have too many active sessions after logging out one or more sessions, the application will get a new session_limit_reached error with a new one-time password and session-list. If the user has active sessions below the configured maximum after a one-time password authentication the new session will be authenticated and active.

Invalid OTP

If the otp in the authentication request doesn't have a match in the SSO database, error message invalid_otp will be returned in the response. The suggestion in this case is to let the user re-authenticate, entering username and password again.

Otp consumed or expired

A one-time password is valid for 5 minutes, if an old one-time password is found in the authentication request, error message otp_consumed_or_expired will be returned in the response. The suggestion in this case is to let the user re-authenticate, entering username and password again.

New method - list sessions

Description

A new method has been added to the public SSO API which can be used to get a list of currently active sessions associated with a specific account. This API should be used if an application need to provide a view of the current sessions for a logged-in customer (My sessions).

Request

The request to the sessions-endpoint is a server-to-server operation. You create a HTTP POST-request with a JSON payload containing the encoded JWT. You sign the token with the secret related to the API-client that you use.

Param	Description
t	Encoded JWT-token.

Example logout request:

curl --request POST \
  --url https://payway-sso-stage.azurewebsites.net/sessions \
  --header 'Content-Type: application/json' \
  --data '{
    "t": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjaWQiOiI1ZjhkNDM5MWJkZjkyODExYTE3ZTc3ZTIiLCJhaWQiOiJhY2NvdW50X2lkIiwibmJmIjoxNjAzODkzNDI5LCJleHAiOjE2MDM5Nzk4MjksImlhdCI6MTYwMzg5MzQyOSwiaXNzIjoieW91cl9vcmdhbmlzYXRpb25faWQiLCJhdWQiOiJwdy1zc28ifQ.W9sywC1uYhGSH_nmmxUHJSCDTsvxoQlbnzXT-51b0ZI"
}'

The decoded JWT in the above example looks like this:

{
  "alg": "HS256",
  "typ": "JWT"
}
{
  "cid": "5f8d4391bdf92811a17e77e2",
  "aid": "account_id",
  "nbf": 1603893429,
  "exp": 1603979829,
  "iat": 1603893429,
  "iss": "your_organisation_id",
  "aud": "pw-sso",
}

Claim	Type	Description
cid	string	"Client ID", Your API-client ID
aid	string	"AccountID", this should always be the account ID for the logged in user.
nbf	int(epoch)	"Not before", this should be the epoch timestamp of when this token is created.
exp	int(epoch)	"Expires", this should be the epoch timestamp for 10 seconds after token was created.
iat	int(epoch)	"Issued At", this should be the epoch timestamp of when this token is created.
iss	string	"Issuer", this should be your Payway Organisation ID.
aud	string	"Audience", this should always be "pw-sso".

Endpoints:

Environment	URI
Stage	https://payway-sso-stage.azurewebsites.net/sessions
Production	https://sso.worldoftulo.com/sessions

Response

The response from the sessions request is a JSON payload containing an encoded JWT-token.

Example sessions response:

{
  "t": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjaWQiOiI1ZjhkNDM5MWJkZjkyODExYTE3ZTc3ZTIiLCJuYmYiOjE2MDM4OTM0MjksImV4cCI6MTYwMzk3OTgyOSwiaWF0IjoxNjAzODkzNDI5LCJpc3MiOiJ5b3VyX29yZ2FuaXNhdGlvbl9pZCIsImF1ZCI6InB3LXNzbyIsIm10ZCI6Imxpc3RfYWN0aXZlX3Nlc3Npb25zIiwiZXJyIjoiIiwic2xtIjo1LCJzZXMiOiJbe1wic2Vzc2lvbl9pZFwiOlwiYSBzZXNzaW9uIGlkXCIsXCJsYXN0X3NlZW5cIjpcIjIwMjItMTItMTRUMDk6Mzg6NDMuNjUzOTg3KzAwOjAwXCIsXCJjcmVhdGVkXCI6XCIyMDIyLTEyLTEzVDA5OjM4OjQzLjY1ODU4MSswMDowMFwiLFwiaXBfYWRkcmVzc1wiOlwiMTI3LjAuMC4xXCIsXCJicm93c2VyXCI6XCJDaHJvbWVcIixcIm9wZXJhdGluZ19zeXN0ZW1cIjpcIldpbmRvd3MgMTBcIn1dIn0.ciUVLSo1utHCLXgq76lvvFfZkY4NI1MYIGQYMNXEDdo"
}

The decoded JWT in the above example looks like this:

{
  "cid": "5f8d4391bdf92811a17e77e2",
  "nbf": 1603893429,
  "exp": 1603979829,
  "iat": 1603893429,
  "iss": "your_organisation_id",
  "aud": "pw-sso",
  "mtd": "list_active_sessions",
  "err": "",
  "slm": 5,
  "ses": "[{\"session_id\":\"a session id\",\"last_seen\":\"2022-12-14T09:38:43.653987+00:00\",\"created\":\"2022-12-13T09:38:43.658581+00:00\",\"ip_address\":\"127.0.0.1\",\"browser\":\"Chrome\",\"operating_system\":\"Windows 10\"}]"
}

Claim	Description
mtd	Name of method called.
slm	Current configured maximum number of active sessions
ses	An array of currently active sessions in JSON format.
err	If something went wrong this field will be hold an error code to help figure out the problem.
nbf	This is the epoch timestamp of when this token is created.
exp	This is the epoch timestamp for 10 seconds after token was created.
iat	This is the epoch timestamp of when this token is created.
iss	Will always be issued by "pw-sso".
aud	The client_id of the API-client the token was issued for.

Active sessions object

The claim ses will contain the current active sessions for an account and is returned in the authentication and sessions requests.

This claim contains a list of active sessions in the form of a JSON array. A sample array can look like:

[
  {
    "session_id": "a session id",
    "last_seen": "2022-12-14T09:52:17.9290199Z",
    "created": "2022-12-13T09:52:17.9290663Z",
    "ip_address": "127.0.0.1",
    "browser": "Chrome",
    "operating_system": "Windows 10"
  }
]

• Timestamps for last_seen and created are returned as UTC.
• The browser, operating_system and ip_address can be used to help the user identify which device is associated with the session.