SSO via JWT
JWT is a technique that can be used for single sign-on (SSO) between your site and Sisense. JWT is a token that represents your users credentials wrapped in a single query string. In addition, 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, thus preventing attacks on the system (also known as replay attacks).
The Sisense SSO via JWT authentication flow is explained in the following diagram.Note: See the Developers Community for a tutorial that shows how to implement SSO via JWT.
SSO Authentication Flow
The following is a diagram of the SSO authentication flow from your site or application to Sisense.
- Your user requests a resource from Sisense, typically a dashboard.
- 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 the Sisense Web Application.
- Your user is challenged to authenticate their account.
- Your Remote Login application authenticates your user and generates a JWT (JSON Web Token).
- 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 you log them out via the Sisense REST API. For more information see Logging Users Out.
- Sisense provides the authenticated user with the request resource.
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 then grants the user a session.
Configuring SSO in Sisense
While SSO is highly customizable, there are generally four steps you should complete when configuring SSO:Note: Configuring SSO requires technical expertise and should be conducted by an administrator or developer with SSO experience.
- Enabling SSO in Sisense: Through the Sisense Web Application, an administrator can enable SSO in Sisense and define the relevant Login and Logout URLs.
- Creating a JWT: After you authenticate a user, you generate a JWT with the user’s credentials to Sisense, so Sisense knows this user is allowed to access resources from Sisense through your site.
- Configure Sisense as a sub-domain: When authenticating users, you should configure SSO as a sub-domain.
- Logging Users Out: A user can access Sisense so 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 in Sisense
For Sisense to recognize that your users should be authenticated through SSO, you must enable SSO in the Sisense Web Application. In the SSO menu of the Admin page of the Sisense Web Application, you define the URL where Sisense redirects users to authenticate on your side and where Sisense redirects users after they log out from Sisense.
When you access the SSO menu of the Admin page, Sisense displays the Shared Secret key. The Shared Key is a JWT encryption public key used to encrypt the JWT payload. It is generated once when the SSO configuration is saved. You include this key in the JWT payload when redirecting the user back to Sisense after authenticating them on your side.
To access and set up SSO:
- Log into Sisense.
- Select Admin screen and click Single Sign On in the left menu.
- 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 (i.e. the participating application’s home page).
- Click Save.
Creating a JWT
Your script builds a JWT request that contains the user data.
The table below provides a list and descriptions of the attributes your JWT should contain.
In addition, several samples are provided below in various languages.
Issued at the time the token was generated. This is used to help ensure that a given token gets used shortly after it is 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. If the user does not exist in Sisense, it will be created with default viewer privileges.|
|jti||Yes*||A unique string added to the token that is 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.
SSO Code Samples
When Sisense redirects a user to your login script, Sisense passes a return_to parameter in the URL. This parameter contains the page that Sisense will return the user to after the authentication succeeds. For example:
A customer visits your site opens a dashboard embedded through an iFrame.
Sisense recognizes that the user is not authenticated.
Sisense redirects the user to:
All your script needs to do, is take the return_to value from the invoked URL and pass it back to Sisense when submitting the JWT token. In other words, upon authentication on your side, your script redirects the user to:
Configuring Sisense as a Sub-Domain with SSO
To authenticate your users locally and allow them to access Sisense, your first step should be to configure Sisense as a sub-domain of your web application and embed Sisense into your web application with SSO.Note: Sisense also works when embedded in cross-domain iFrames.
To configure Sisense as a Sub-Domain:
- In IIS Management Console, add your website to IIS.
- In the Add Website window, in the field Site Name, enter the site name.
Note: You can not leverage SSO when you enter a DNS address with an underscore “_” with Internet Explorer.
- In Physical path, enter the subdomain directory.
- Under the Binding area, in Host name, change the existing SisenseWeb site binding to use sisense.example.website.com as host name on port 80.
- Open the file C:\Windows\System32\drivers\etc\hosts and add mapping for the sites:
- Sign in to the Sisense Web Application at sisense.examplewebsite.com and configure the SSO as pictured below:
- Place the following SSO script in the server location corresponding to the Remote Login URL in the server’s root directory. The SSO script can be implemented in any server-side language. This example uses Python. Example code has been attached for C# and Python.
Python script example
C# script example
- In index.html from examplewebsite.com, the IFrame source is the Sisense dashboard URL.
- index.html from examplewebsite.com:
<p><b>examplewebsite.com</b> - <b>SSO</b> login with embedded dashboard from <b>sisense.examplewebsite.com</b></p>
<iframe width="100%" height="100%" src='http://sisense.examplewebsite.com/app/main#/dashboards/53b29843751b655443000018?embed=true' />
Navigate to examplewebsite.com and you should see the specific dashboard you embedded.
Logging Users Out
When a user is logged in, anyone using that browser can access the session, or users may encounter an issue where they remain logged in until the Sisense cookie is cleared.
Users are logged out when the session ends. A session ends when the user closes their browser or according to the value of the attribute exp you send in the JWT payload.
You can log the user out through the Sisense REST API.
To manually log a user out, access version .9 of the REST API. Through the Auth method, you can issue a get request to log out specific users.
While the logout REST API can delete the SSO authentication cookie, it can only delete it when the call is made from within the Sisense domain. Scripts on different pages can access each other only if the pages that executed them are at locations with the same protocol.
If you have embedded Sisense in an iFrame and you want to log out the user from your application and Sisense, you can use the window.postMessage method to call the logout when the users asks to logout from your application. This method overcomes any cross-origin communication limitations. Sisense has created a plugin that implements a listener, which calls the Logout API when the postMessage method() is called. For more information, click here.