SSO Using JWT

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.

See Troubleshooting SSO Using JWT 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, 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 (in Managing Self-contained Tenants) 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 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. 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.