Sessions

​

Sessions and JSON Web Tokens

A session is created when a user authenticates with Hanko (either by registering a new account or by signing in to an account). The session is represented by a JSON Web Token (JWT). JWTs encode claims about subjects (users) as JSON objects. They can also include a signature, in which case their structure is that of a JSON Web Signature (JWS). All JWTs issued by Hanko are signed JWSs.

API operations that establish a session (login, registration) return a session token in an X-Auth-Token header.

Subsequent requests to protected API endpoints must then provide the session token in a Cookie request header or alternatively in an Authorization header with the Bearer scheme (i.e. Authorization: Bearer <JWT>).

Upon session creation, a unique identifier is generated and stored in the database, linked to the corresponding user. This identifier is also included in the session JWT under the session_id claim. For subsequent requests, the API validates the JWT signature and uses the session_id to query the database for an active session match. This enables remote session revocation. As a result, if a user is logged in on one device but has multiple active sessions across other devices, the API’s Profile flow facilitates the listing and explicit termination of sessions on those devices. This functionality is also accessible through the UI via the Hanko Elements’ Profile Component.

​

Session validation

To manually validate a session you can use the API’s sessions/validate endpoint. You need to provide the session token in the request body. The endpoint validates the token’s expiry and signature and ensures that the encoded session_id matches a persisted session.

The session endpoint returns an object that contains information about the validity of a session, the session token’s expiry as well as claims about the user the session is associated with.

You can also use the Hanko Frontend SDK to check for session validity. See Using the Frontend SDK for details.

​

Session termination

Depending on your tenant’s configuration, there are various methods available for explicitly or implicitly terminating a session.

​

Explicit user logout

A user can explicitly request a logout. This requires a request to the /users/logout endpoint. A successful request clears session cookies and terminates the session associated with the session token.

​

Limiting session duration

Sessions can be terminated (or: become invalid) by exceeding an expiry. This expiry can be configured by setting the session duration. The session duration determines how long a user remains logged in after authenticating. By default, the session duration is set to 12 hours in the Hanko Cloud Console. You can change this to a value between 1 minute and 1 month to suit your application’s needs.

To change the session duration, follow these steps:

1. Log in to Hanko Cloud and select your project.
2. Navigate to Settings > Session.
3. Under Session duration, set the desired session duration and click Save.

​

Limiting concurrent session

Sessions can also be (implicitly) terminated by exceeding the number of allowed active sessions. By default, Hanko allows 5 concurrent sessions. If a user establishes another session, then the oldest session becomes invalid.

To configure the allowed amount of concurrent sessions:

1. Log in to Hanko Cloud and select your project.
2. Navigate to Settings > Session.
3. Under Session limit, enter the desired amount and click Save.

​

Limiting cookie retention period

You can configure the retention period of session cookies. Possible configurations are:

• Persistent (default): This type sets the Max-Age attribute of the cookie to the specified session duration (in seconds). The cookie will be automatically deleted from the browser once the specified expiry time has been reached.
• Session: This type sets the Max-Age attribute of the cookie to 0, resulting in the cookie being deleted from the browser when the browser tab or window is closed.
• Prompt: If you use Hanko Elements (+1.3) then selecting this type results in Hanko Elements displaying a Stay signed in checkbox on the login form which allows users to determine the cookie retention period: if the checkbox is checked, the cookie will be a Persistent cookie, if it is unchecked the cookie will be a Session cookie.

To configure the cookie retention period:

1. Log in to Hanko Cloud and select your project.
2. Navigate to Settings > Session.
3. Under Stay signed in (cookie type), select the desired type and click Save.

​

Session self-service

There are a number of configurations options for your tenant that provide control over how users manage their session through the profile.

​

Allowing session revocation

You can configure whether the Profile flow permits session revocation via the dedicated session_delete action. If you are using Hanko Elements version 1.3 or later, the Profile component provides interface elements that allow users to revoke active sessions, excluding the session currently in use. This session can be revoked manually through a manual logout.

To control self-service session revocation behaviour:

1. Log in to Hanko Cloud and select your project.
2. Navigate to Settings > Session.
3. Use the Allow session revocation toggle to allow or disallow end-user session revocation via profile.

​

Showing sessions on profile

You can control whether information about active sessions is returned in the Profile flow. If you use Hanko Elements (+1.3) then information about active sessions is displayed in the Profile component.

To control whether information about active sessions is returned from the Profile flow (and shown in Hanko Elements):

1. Log in to Hanko Cloud and select your project.
2. Navigate to Settings > Session.
3. Use the Show sessions on profile toggle to include information about active sessions in the profil API response (and the Hanko Elements profile component).

​

Session metadata retention

You can control whether active session metadata is persisted with a session and returned from session validation endpoints. This metadata currently includes the IP address and the user agent used to establish a session.

To control the type of metadata retained with a session:

1. Log in to Hanko Cloud and select your project.
2. Navigate to Settings > Session.
3. You can configure the following options:
   • Use the Acquire IP address toggle to include information about the IP (IPv4/IPv6) address used to establish the session.
   • Use the Acquire user agent toggle to include information about the user agent used to establish the session.

​

Session callbacks

You can hook into the session lifecycle by using the Hanko Frontend SDKs central client. See Using the Frontend SDK for details.

​

Administrative session management

The Admin API allows administrators to create sessions, list active sessions and delete sessions for a specific user.

​

Session JWT structure

The session JWT is a compact JWS. It is a string composed of three base64 URL safe encoded parts (header, payload and signature), separated by a dot (.). The JWT payload contains the claims about a user.

​

JWT Header

{
  "alg": "RS256",
  "kid": "2288bfa9-3214-4f19-9757-92631190420b",
  "typ": "JWT"
}

​

JWT Payload

{
  "aud": [ "example.com" ],
  "email": {
    "address": "user@example.com",
    "is_primary": true,
    "is_verified": true
  },
  "exp": 17123108000,
  "iat": 1712307200,
  "session_id": "140f3967-ab87-4caa-80bd-603ac59c545f",
  "sub": "9930ac89-1584-488c-bd63-1607f03ab1e8",
  "username": "johndoe"
}