Configuring Sisense for Single Sign On

JWT is a token that represents your users credentials. Sisense uses the jti parameter (see below), which adds a unique ID to the token that prevents the token from being used more than once, preventing replay attacks.

SSO via the JWT Token Authentication Flow

The following is a diagram of the SSO authentication flow from your site or application to Sisense .

1. A user requests a resource from Sisense , typically a dashboard.
2. Sisense recognizes that no authenticated cookie is present. If you have enabled SSO in Sisense , the SSO handler redirects the user to your Remote Login URL defined in Sisense .
3. The user is challenged to authenticate their account.
4. Your Remote Login application authenticates your user and generates a JWT (JSON Web Token).
5. You redirect the user back to Sisense with the encoded JWT in a query string. Sisense sets a cookie that authenticates the user’s session until they end it or until you log them out via the Sisense REST API. For more information see Logging Users Out .
6. Sisense provides the authenticated user with the request resource.

Use Case
A common scenario that illustrates SSO is when an unauthenticated user navigates to your site in which Sisense is embedded via an iFrame. Sisense redirects this user to your SSO script. Your script authenticates the user through your login process and builds a JWT request with all the relevant credentials wrapped together. You then redirect the customer back to Sisense with the JWT payload. Sisense then decodes the user details from the JWT payload and grants the user a session.

Configuring SSO via the JWT Token in Sisense

There are three main steps to configuring SSO in Sisense :

1. Enable SSO in Sisense : An Administrator can enable SSO in Sisense and define the relevant Login and Logout URLs.

2. Create a JWT : After you authenticate a user, you generate a JWT with the user’s credentials to Sisense , so Sisense knows that this user is allowed to access resources from Sisense through your site.

3. Log Users Out : A user can access Sisense as long as a session is maintained. To end a session, the user’s cookie that Sisense provides must be deleted. To delete this cookie, you can use the Sisense REST API.

Enabling SSO via the JWT Token in Sisense

For Sisense to recognize that your users should be authenticated through SSO, you must enable SSO in Sisense .

To access and set up SSO via JWT:

1. In Sisense , click the Admin tab.

2. In the menu, click Single Sign On.

3. Select JWT.

4. Fill in the following SSO configuration fields:

   • Remote Login URL : This is the URL that Sisense will invoke to attempt remote authentication. In that endpoint, the participating application user authentication script is triggered and the JWT payload is generated.
   • Remote Logout URL : This is the URL that users will be redirected to after they log out from Sisense (that is, the participating application’s home page).
   • Shared Secret : The Shared Key is a JWT encryption public key used to encrypt the JWT payload. It's generated once the SSO configuration is saved. Include this key in the JWT payload after authenticating the user on your side when redirecting the user back to Sisense .

   

   • Enter the required information in the User Attributes and Groups sections.

5. Click Save.

Creating a JWT

Create a script that builds a JWT request which contains the user data.

The table below describes the attributes your JWT should contain.

Attribute	Mandatory?	Description
typ	Yes	Define the type of token with the attribute typ. You should also specify HS256 as the JWT algorithm in the header of your JWT payload. { "typ":"JWT", "alg":"HS256" }
iat	Yes	Issued at the time the token was generated. This is used to ensure that a given token gets used shortly after it's generated. The value must be the number of seconds since UNIX epoch. Sisense allows up to five minutes clock skew. Note: The date must be an integer and not a float.
sub	Yes	Email of the user being signed in, used to uniquely identify the user in Sisense. Users who don’t exist in Sisenseare handled according to the configurations set under User Attributes and Groups.
jti	Yes*	A unique string added to the token used to prevent replay attacks, by making sure the token is used only once.

• You can set this attribute as optional in the Sisense REST API v1.0 through the POST settings/SSO endpoint.

return_to URL

After users successfully authenticate, Sisense returns them to a URL defined as the return_to URL.

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

To define the return_to URL in Sisense , contact your Sisense Customer Service Manager or Sisense Support .

Troubleshooting SSO in iFrames on Internet Explorer and Safari

If you embedded Sisense in an iFrame and implemented SSO, in some cases when using Internet Explorer or Safari, you might see the following error: "An error occurred while trying to authenticate you using Single-Sign-On. Please ask your administrator for assistance."

This error is caused by Explorer and Safari blocking third-party cookies by default, rendering the JWT invalid. You can solve this by changing the default configuration of the browser.

Internet Explorer:

Open Internet Options > Privacy > Advanced, and change Third-party cookies to Accept.

Safari:

Follow the instructions here: https://clearcode.cc/blog/browsers-first-third-party-cookies/ .

The Sisense SAML authentication process is based on the SAML 2.0 protocol, and is explained below.

Phase 1

The first phase of this process begins when a user requests a resource from Sisense via their browser (1). The browser generates a resource request to the Sisense server. The server processes this request (2), and for unauthenticated users, returns a special save-hash page to save the requested hash data.

After the browser loads the save-hash page from the Sisense server, it runs a script, which loads the requested resource hash from the URL and sends it to the Sisense Server (3).

At the end of this phase, the Sisense Server converts the requested resource URL and sends it to the browser as a part of the redirect to IdP Server command (4).

Phase 2

The second phase of the authentication process starts after the browser retrieves the redirect command from the Sisense Server, and sends the authentication request to the IdP Server (1) as described in the diagram below.

The base URL for this request is taken from the Remote Login URL field in the Single Sign On section of the Admin tab in Sisense .

The requested resource address is passed to this request as a RelayState parameter. All other data is provided as a SAMLRequest parameter.

The next step of this phase depends on the user authentication state and the IdP implementation.

If the current user isn’t logged in as an IdP user, the IdP server redirects the browser to your Login page (2), where the user enters their IdP credentials. After logging in, the IdP Server sends the browser the Auto-Sign-In page with encoded data about the currently logged-in user (4).

After this document is loaded in the user’s browser, it runs a script which creates the POST-query to the Sisense Server API, and passes the SAML response to this query (1). The third phase of the authentication process begins.

Phase 3

The Sisense Server handles the POST-query (2), decrypts it with the certificate specified in the Public X.509 Certificate field defined in the Single Sign On section of the Admin page. The Sisense Server uses the decrypted User ID as a key to locate the Sisense user in the internal database.

If a user isn't found in the system, Sisense creates a new user (3).

Associating SSO Users with Sisense Groups

When Sisense creates a new user, Sisense analyzes the “memberOf” field to locate one or more groups related to the logged-in user.

If the “memberOf” field is empty, the user is handled according to the configuration set under Groups . If the “memberOf” field contains one or more groups, and the groups were previously defined in Sisense , the newly created user’s Role is taken from the group’s default role. When multiple Sisense groups are found, the user is assigned the role with the maximum privileges.

After a user is created in the system, an Administrator can modify the user role, if needed.

Below, is an example of an SAML XML where the “Test” group is specified:

<saml:Attribute
  NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic
  Name="memberOf">
  <saml:AttributeValue
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:type="xs:string">
    Test
  </saml:AttributeValue>
</saml:Attribute>

After the user is located or created, a new session is initialized, and the Sisense Server redirects the user browser to the requested resource (4).

Enabling SSO via SAML in Sisense

After you have configured your SAML server, sign in to Sisense as an Administrator and follow the instructions, below.

To enable SAML in Sisense :

1. In Sisense , click the Admin tab.

2. Select Single Sign On and then SAML 2.0.

   

3. Fill in the following configuration details:

   • Remote Login URL : The SAML Login endpoint. Sisense redirects the user to this field when they sign in. This value should be provided by the IdP Service.
   • Remote Logout URL : The SAML Logout endpoint. Sisense redirects the user to this field when they sign out. This value should be provided by the IdP Service.
   • Public X.509 Certificate : Your public key for your SAML configuration. This value should be provided by the IdP Service.

4. Enter the required information in the User Attributes and Groups sections.

5. Click Save.

Sisense Default Role Set-Up

When an authenticated user isn't found in the Sisense database, a new account is created. The user role is specified based on the user group/groups default role. To define a group’s role, see Managing User Groups .

Related Topics

For instructions on setting up Sisense with some third-party providers, see:

Setting Up SSO SAML 2.0 with Okta

Setting Up SSO SAML 2.0 with OneLogin

Setting Up SSO SAML 2.0 with Auth0

Setting Up SSO SAML 2.0 With Salesforce

Setting Up SSO SAML 2.0 With ADFS

Setting Up SSO SAML 2.0 With G Suite

Setting Up SSO SAML 2.0 With Keycloak

You can configure Sisense to support OpenID Connect for single sign on. OpenID Connect (OIDC) is an authentication protocol, based on the OAuth 2.0 family of specifications. In the OpenID Connect authentication flow, Sisense , the Replying Party (RP), interacts with your OpenID Connect provider (OP) to authenticate your user. Sisense relies on this authentication to provide your users access to Sisense .

How OpenID Connect Works

Sisense enables you to authenticate your users with the following authorization code flow:

1. Authentication Redirect : A user attempts to access your dashboard.

2. Authentication : Sisense recognizes that the user isn't signed in, and that you have enabled OpenID Connect in your Admin settings. Sisense redirects the user to the provider's Authorization URL that you also define in the Admin settings in Sisense .

3. Redirect to RP : The user authenticates through the OpenID provider’s site and is redirected back to Sisense with an authorization code.

4. Redirect to Token URL : Sisense responds with a request to the Token URL with the Client ID and Client Secret, all of which you define in the Admin settings. Your OpenID provider responds with an ID token, access token, and refresh token.

5. Redirect to User Info URL : Sisense uses the access token to retrieve additional information from the UserInfo URL. Once the OpenID provider responds, Sisense locates the user and signs them in. If they don't exist, Sisense creates a new user.

Configuring Your OpenID Provider

Before you can use SSO with OpenID in Sisense , you must have an account with an OpenID provider. Once you have configured your OpenID provider, in Sisense , you must provide the following details in the OpenID settings in the Admin page:

• Client ID : This is the identifier that the IdP assigned to your application.
• Client Secret : This is a token that is used by Sisense to verify the authenticity of the response from your OpenID provider.
• Issuer : This is the server identifier. Typically, this is the base URL with the HTTPS scheme. For example, https://sisense.com.
• Authorization URL : This is the URL at the provider's site that Sisense redirects your user when they try to authenticate.

Configuring OpenID in Sisense

After you have obtained the necessary details from your OpenID provider, you need to configure OpenID SSO in Sisense , and then enable it.

To configure OpenID in Sisense :

1. In Sisense , click the Admin tab.

2. In the left menu, click Single Sign On .

3. Select OpenID Connect .

4. In the OpenID configuration settings, enter the following details:

• Scope : Enter the scope. The scope is a comma-separated list of identifiers used to specify what privileges should be granted to the user. ‘openid’ is a required scope that is automatically appended by Sisense . However, you can append additional comma-separated values as needed. Typical values include name and family_name.
• Client ID : The Client ID, provided to you by your provider.
• Client Secret : Your Client Secret provided to you by your provider.
• Issuer : Your server identifier. Typically, this is the base URL with the HTTPS scheme. For example, https://sisense.com.
• Authentication URL : The URL to the login page of your OpenID provider where Sisense redirects the user when they try to access a dashboard.
• Token URL : URL that returns access tokens, ID tokens, and refresh tokens. For example: https://[base-server-url]/token.
• User Info : The URL that returns information about the currently signed-in user. For example: https://[base-server-url]/userinfo.
• Logout URL : The URL where users are redirected to when they log out of Sisense .

5. Enter the required information in the User Attributes and Groups sections.
6. Click Save.