# SSO Using JWT

> How to configure the settings for the JWT (JSON Web Token) authentication protocol.

*Source: https://docs.sisense.com/main/SisenseLinux/single-sign-on-using-json-web-token.htm*

---

Last updated: June 10, 2026

|  |  |
| --- | --- |
| [Tier](https://www.sisense.com/pricing/#pricing) | [Deployment](https://docs.sisense.com/main/SisenseLinux/introduction-to-sisense-cloud-managed-services.md#ComparisonofManagedCloudandSelfHosted) |
| Grow    Enterprise | Cloud     On-Prem |

This page explains how to configure the settings for the JWT (JSON Web Token) authentication protocol.

To set the SSO options, go to the Single Sign On configuration page, (**Admin** tab > **Security & Access** > **Single Sign On**), and toggle on the **Single Sign On Configuration** option at the top of the page.

**Note:**

If at any point you misconfigure the SSO session, and you are unable to login via SSO, you can use the direct login:
  
`https://{IP_or_site_URL}/app/account/login`

Or, for a tenant:
  
`https://{IP_or_site_URL}/{tenant_name}/app/account/login`

See [Troubleshooting SSO Using JWT](https://docs.sisense.com/main/SisenseLinux/troubleshooting-single-sign-on-using-jwt.md) for detailed troubleshooting information.

## Enabling and Configuring

### General Section

The following options are configured in the **General** section of the **Single Sign On** page:

- **SSO can create new users and modify user permissions** - The exact effect of this toggle depends on which option you select for **Set Roles from Groups**, (which is in the **Groups** section, see [Groups Section](#Groups), below):

  - When **Use Defaults** is selected:

    - Activating this toggle enables the creation of new Sisense users.
    - Deactivating this toggle prevents new users from logging in to Sisense.
  - When **Define by Groups** is selected:

    - Activating this toggle enables the creation of new Sisense users.
    - Deactivating this toggle enables existing users to log in to Sisense, but Sisense permissions remain unchanged.
      New users are prevented from logging in to Sisense.
- **Method** - Select the **JWT** radio button.
- **Remote Login URL** - Enter the URL that Sisense should invoke to attempt remote authentication.
- **Remote Logout URL** - Enter the URL that Sisense should return users to after they log out.
- **Shared Secret** - JWT encryption public key that is used to ensure that you are authorized use the JWT token to enter Sisense.

### User Attributes Section

The following fields are configured in the **User Attributes** section of the **Single Sign On** page:

- **Email Claim (optional)** - The name of the attribute in the token, (that was used in the handler's coding) that identifies the
  user's login or email.
- **First Name Claim (optional)** - The name of the attribute in the token, (that was used in the handler's coding) that identifies the user's first name.
- **Last Name Claim (optional)** - The name of the attribute in the token, (that was used in the handler's coding) that identifies the user's last name.

To override these defaults, enter the names of each of the claims from your identity protocol.

### Groups Section

The options in the **Groups** section are different depending on which **Set Roles from Groups** option you select, **Use Defaults**, or **Define by Group**.

**Use Defaults**

If you select the **Use Defaults** option for **Set Roles from Groups**, each new user is assigned a default role according to the selection you make from **one** of following fields:

- **Default User Roles** - From the dropdown menu, select the default user role. Each new user is assigned
  to the selected default role. You cannot assign Admin roles to new users using this method.
- **Default User Groups** - Search for a group in this field and select it. Each new user is assigned to the
  selected default group.

**Define by Group**

Select the option **Define by Group** for **Set Roles from Groups** if you have defined a Group Claim for every new user. Every new user is assigned default roles
according to your selections:

- **Groups Claim (optional)** - The value of the Group claim as defined by your identity protocol. For example, if
  your provider refers to groups as Groups, this is the value you enter in Groups Claim. The user is assigned roles
  according to the Groups Claim.
- **Only associate users with the following group-role pairs** - Enable this option so that users are only
  associated with groups selected from this list. If the user is associated with multiple groups, the one with the highest role is assigned.  
  To create a group to role pairing, select a group (by search), select the user role (from drop-down list), and then click **Add**.

## Developing the SSO Handler

The SSO handler is used to integrate between Sisense and the given user's Login platform. To develop an SSO handler,
you need to write JWT integration code. The JWT handler contains the code needed to receive the user's request for
a Sisense session, and in turn generates the JWT token used to communicate with Sisense. There are many options for
programming languages for developing the handler, including PHP, C#, Net framework, and Javascript.

### Login

**Input**

Session cookie sent from the user browser containing the user login info which can be extracted.

**Output**

A redirect to the Sisense platform with the token, which establishes the Sisense session.

Follow these coding steps to develop the handler:

1. Extract an authenticated user's cookie.
2. Create a JWT (JSON Web Token) and assign the proper attributes. (See the table below.)
3. Encode the token.
4. Define a URL redirect including the token.
5. Perform a redirect to execute the SSO flow.

Set these attributes in the token:

| **Section** | **SSO protocol attribute** | **Required** | **Description** | **Sisense login validation/ logic** | Example: |
| --- | --- | --- | --- | --- | --- |
| Header | typ | Yes | Define the token type header as JWT | n/a | JWT |
| - | alg | Yes | Set the algorithm for encoding of the token to *HS256*. | Must be HS256 | HS256 |
| Body | iat | Yes | Issued at the time the token was generated. This is used to ensure that a given token gets used shortly after it is generated. The value must be the number of seconds since the UNIX epoch. Sisense allows up to five minutes clock skew.  The date must be an integer and not a float. | If the value is the same or earlier than what is stored in Sisense from the previous user session, the user is denied. | 1620740260 |
| - | tenantId | Depends | Should **not** be included in a claim for the main system tenant.  **Required** for organization tenants. | See section [JWT SSO for Organization Tenants](https://docs.sisense.com/main/SisenseLinux/managing-self-contained-tenants.md#JWTSSOforOrgTenants) (in [Managing Self-contained Tenants](https://docs.sisense.com/main/SisenseLinux/managing-self-contained-tenants.md)) for additional information. |  |
| - | Defined in Sisense Single Sign on Configuration - **Email Claim** | Yes | Email of the user being signed in, which is the unique user already setup in Sisense. | Cannot be blank. | John.doe@customer.com |
| - | Defined in Sisense Single Sign on Configuration - **Last Name Claim** | No | The last name assigned to the user account. | Cannot be blank. | Doe |
| - | Defined in Sisense Single Sign on Configuration - **First Name Claim** | No | The first name assigned to the user account. |  | John |
| - | jti | Yes | A unique string added to the token that makes the token unique.  This is a mechanism to prevent replay attacks on the site by making sure the token is used only once. | Must be unique and not the same as the previous user attempting to access Sisense. Validated as unique against MongoDB, (see [Troubleshooting SSO Using JWT](https://docs.sisense.com/main/SisenseLinux/troubleshooting-single-sign-on-using-jwt.md) for details). | SSOSession\_1 |
| - | exp | No | When the user's session expires, the UNIX epoch can be used if a customer wants to override Sisense settings for cookie expiration as defined under **Security Settings**. This does not work if **Session Inactivity** is selected in the Session Management section under **Security Settings**. | Needs to be set in the future, meaning later than the value set in "iat". |  |
| - | domain | No | If the customer passes in "sub" user logins that do not have the domains specified (e.g., TestUser as opposed to TestUser@customer.com), the domain can be specified.  This option is not recommended, and if possible, users should be created fully qualified with the @domain.com. |  |  |
| - | groups | No | For users that are created via the SSO login process, the customer can pass the user Group(s) in which the user can be assigned to (as opposed to administrating that via Admin tab under Users). The groups are assigned in the code using "[" and "]" to enclose the list, with the name of the group setup in Sisense and each separated by ",". | The user group must be set up in Sisense before the user logs in. Otherwise, the user receives the default access. | [TestGroup1, TestGroup2] |

### return\_to URL

After a user is successfully authenticated, Sisense returns them to the URL defined as the return\_to URL.

For example: https://yourcompany.sisense.com/dashboards/

**To define the return\_to URL in Sisense:**

1. Set `returnToURL` in **Admin > System Management > Configuration > Base Configuration > Sso > sso.returnTo**.
2. Click **Save**.

### Logout

Your parent application has a Logout button that deletes the user's cookie and redirects the user to the Login page.
The Sisense cookie must also be deleted to ensure that when a new user logs in they go through the SSO process again
and are logged in to Sisense correctly.

The logout flow works as follows:

1. When a logout is requested by the user, the Sisense configured "Logout Request URL" is accessed in order to
   perform the SSO logout procedure coded in the SSO Handler.
2. The handler includes code that discards the token created for the user session.
3. The user is redirected to the customer site that serves as a landing page after logging out from Sisense.

## Limitations

- If the **User Profile > API Token** setting is turned off on the system level, whenever a user who logs into the system via JWT SSO logs out of the web application (via API or UI), all of their existing API tokens are automatically invalidated.

  We strongly recommend not scheduling simultaneous ElastiCubes with custom code tables in this scenario.