Session Overview

Descope implements the session management with two tokens to improve performance and security:

• Session Token
• Refresh Token

These tokens are implemented as JWTs (JSON Web Tokens), meaning that the information stored in the object is encrypted with the private key, and using the public key, any service can validate that the data was not tampered with by a malicious actor.

Your application server can validate the session token (short expiry time) without a connection to Descope service. If the application server finds the session token invalid, it calls the Descope service with the refresh token (longer expiry time) to get a new session token.

If the refresh token is invalid for some reason, such as a logout call or expiry time, then the user is forced to re-login.

Configurations for session management can be configured at a project level or tenant level. Please review the applicable guides for configuring session handling at a project or tenant level.

Descope Session JWT Structure

The Descope JWT contains standard and Descope specific claims:

• amr: (Authentication Methods References): An array of the authentication methods used.
• drn: (Descope Resource Name) References where the token is stored.
• exp: (Expiration Time): Specifies the expiration time of the token, represented as a UNIX epoch timestamp.
• iat: (Issued At): The time the JWT was issued, represented as a UNIX epoch timestamp.
• iss: (Issuer): Identifies the principal that issued the JWT. Within Descope's JWT, this is the Descope project ID.
• sub: (Subject): The principal that is the subject of the JWT. Within Descope's JWT, this is the User ID of the user within Descope.
• tenants: A list of associated tenants (represented by unique IDs) associated with this JWT. -- For each tenant:
  • permissions: A list of permissions granted to the subject within the context of that tenant.
  • roles: Roles associated with the subject for that specific tenant.

Below is an example of a Descope Session JWT with tenants associated to the user.

{
  "amr": [
    "email"
  ],
  "drn": "DS",
  "exp": 1692304651,
  "iat": 1692304051,
  "iss": "P2RFvFexVaxxNFK6rhP0ePtaGfTK",
  "sub": "U2RG6grrbT3REKYqk5yC4SjkMqzA",
  "tenants": {
    "T2U7vUH1NPy4JzWHruoOVIGyzYlu": {
      "permissions": [
        "AppSecEngineer",
        "Marketing",
        "Support"
      ],
      "roles": [
        "Engineering",
        "Product Manager"
      ]
    },
    "T2U7vVBqyZv6HdGtGLdnkgCbNxrC": {
      "permissions": [
        "AppSecEngineer",
        "Support"
      ],
      "roles": [
        "Support"
      ]
    }
  }
}