SSO Using JSON Web Token

Enabling and Configuring

On the Sisense Admin page for SSO, enable and configure the identity protocol. Individual fields are described below. Some options are not supported in older versions.

  1. Enable Single Sign On Configuration.
  2. Select JWT.
  3. Complete the following SSO configuration fields:

Remote Login URL

Enter the URL to be redirected to for Login request.

Remote Logout URL

Enter the URL to be redirected to for Logout.

Shared Secret

The Shared Secret ensures that you are authorized to use the JWT token to enter Sisense.

User Attributes

Email Claim

The attribute's name in the token (used in the handler's coding) identifies the user’s login/email.

First Name Claim

The attribute's name in the token (used in the handler's coding) that identifies the user’s first name.

Last Name Claim

The attribute's name in the token (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.

Defining User Roles

Use Defaults

Each new user is assigned a default role according to the selection you make from one of following options:

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 and select a group in this field. Each new user is assigned to the selected default group.

Define by Group

Select this option if you have defined a Group Claim for every new user. Each new user is assigned default roles according to the selection you make below.

Groups Claim. 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.

  1. Select a group.
  2. Select the user role.

If the user is associated with multiple groups, the one with the highest role is assigned. Click Add after each group.

Creating New Users and Modifying User Permissions

Use the toggle to enable your SSO configuration to create new users and modify existing user permissions under the following circumstances:

Use Defaults:

  • Activating this toggle enables creating new Sisense users.
  • Deactivating this toggle prevents new users from logging in to Sisense.

Define by Groups:

  • Activating this toggle enables creating 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.

If at any point you misconfigure the SSO session, and you are unable to login via SSO, you can use the direct login: https://0.0.0.0/app/account#/login (select the IP or site URL).

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 a 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

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 Single Sign-On using JWT 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 needs to 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. In your browser, open the Configuration Manager located at http://localhost:3030.
  2. In SSO Return to, enter your base URL.
  3. 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.


.r.