Troubleshooting Single Sign-On using SAML

Authentication Logical Flow

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).

Note: Two-factor authentication for Sisense is supported for SSO providers that support it.

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).

Architecture Diagram

The following table describes the steps in Figure 2: SSO authentication flow, the configuration involved in the attributes/properties used in the process, the output of action/data and the technical requirements to successfully execute each step.

Figure 1. Authentication flow using SAML 2.0

Authentication flow

#	Action	Configuration source	Output	Requirements
1	End user accesses the Sisense site from within the browser.	n/a	URL request to Sisense site.	The user needs to have access to the Sisense site.
2	Sisense redirects the user with a SAML request containing the Sisense return URL and the request to the destination Identity Provider.	Based on the Admin configuration in Sisense.	Redirect request with SAML request.	n/a
3	User browser relays SAML request to Identity Provider.	n/a	SAML request	User has access to the Identity Provider Site.
4	User is authenticated and a SAML assertion is sent back to the browser containing the user’s credential details.	n/a	SAML response	n/a
5	Browser sends back SAML assertion to Sisense site.	n/a	SAML response	n/a
6	The user value set in the SAML message User.email or nameId is used to find the user in MongoDB. If the user does not exist, and SSO Create User is on, the user record is inserted as per values sent in the SAML message. (First Name, Last Name, Email, and the group associated with the user based on the value set in “memberOf”.)	syncGroupsFromSamlToken is located in REST API 1.0 >> Settings >> POST settings/sso.	n/a	n/a
7	The user is directed to the appropriate Sisense page.	n/a	Sisense page (e.g., dashboard)	n/a

Analyzing and Testing

The following are various tools and logs to use during an end-to-end investigation of an SSO issue.

HTTP Archive Format and Server Logs

HTTP Archive format (HAR) files are generated using your browser’s Developer Tools and can be exported for offline troubleshooting of browser communication. You can use the import option in Developer Tools to analyze and validate the flow of communication. The Network tab provides details about exchanges between Sisense, Customer Login Site/SSO Handler, and end user browser.

The following table describes the entries in both HAR files and server logs involved in each successful step in the authentication flow. This does not illustrate log entries of exceptions and failures that occurred. These are described in Troubleshooting Scenarios.

Not all information reflecting the SSO workflow is captured on the server-side logs of API gateway and/or identity.log. As a workaround, the combined.log captures additional log entries showing the SSO flow, and the entries can be invoked by switching on and off the given SSO protocol from the Sisense SSO Admin page. Once you switch off to on and save, the combined log is added with the additional logs. This is described in the following table:

#	HAR entry	Server logs
Login
1	Shows the first step in a user's access from the Browser to the Sisense site. Name > main Headers: Request URL: https://customer.sisense.com:port Request Method: GET Status Code: 302 Found Remote Address: 10.20.4.174:7000 Referrer Policy: strict-origin-when-cross-origin	API gateway.log and Identity log do not include a log entry for this step. The combined.log does not include an entry for this step of the flow.
2	When using SAML, a SAML redirect URL will be set. Name: saml? Headers: Request URL: Click here Request Method: GET Status Code: 302 Found Remote Address: 10.50.83.39:30845 Referrer Policy: strict-origin	API gateway.log and Identity log do not include a log entry for this step The combined.log file will include the following: 2021-06-29T01:36:36.991, sisense, api-gateway, [4707.753085854] [[34mINFO[39m] [2021-6-29 08:36:36.990] [undefined] [41]:[] [/usr/src/app/node_modules/@sisense/sisense-logger/index.js:174] [X-request:123d27b6-b418-4644-89e0-0ec8d0d59554] [Start handling request => GET /saml?address=http%3A%2F%2F10.50.11.117%3A30845%2F] 2021-06-29T01:36:37.001, sisense, api-gateway, [4707.762730565] [[34mINFO[39m] [2021-6-29 08:36:37.000] [undefined] [41]:[] [/usr/src/app/node_modules/@sisense/sisense-logger/index.js:179] [X-request:123d27b6-b418-4644-89e0-0ec8d0d59554] [Finished handling request => GET /saml?address=http%3A%2F%2F10.50.11.117%3A30845%2F 302] 2021-06-29T01:36:52.258, sisense, api-gateway, [4723.020631012] [[34mINFO[39m] [2021-6-29 08:36:52.258] [undefined] [41]:[] [/usr/src/app/node_modules/@sisense/sisense-logger/index.js:174] [X-request:05ca8933-a8e4-4746-be84-0c8e9a6d5f38] [Start handling request => POST /api/v1/authentication/login_saml_callback/] 2021-06-29T01:36:52.426, sisense, api-gateway, [4723.188351366] [[34mINFO[39m] [2021-6-29 08:36:52.426] [undefined] [41]:[] [/usr/src/app/node_modules/@sisense/sisense-logger/index.js:179] [X-request:05ca8933-a8e4-4746-be84-0c8e9a6d5f38] [Finished handling request => POST /api/v1/authentication/login_saml_callback/ 302] 2021-06-29T01:36:52.268, sisense, identity, [4418.533950038] [[34mINFO[39m] [2021-6-29 08:36:52.267] [] [identity-service] [44]:[] [/usr/src/app/node_modules/@sisense/sisense-logger/index.js:167] [X-request:05ca8933-a8e4-4746-be84-0c8e9a6d5f38] [Start handling request => POST /api/v1/authentication/login_saml_callback/] 2021-06-29T01:36:52.424, sisense, identity, [4418.690612371] [[34mINFO[39m] [2021-6-29 08:36:52.424] [] [identity-service] [44]:[] [/usr/src/app/node_modules/@sisense/sisense-logger/index.js:172] [X-request:05ca8933-a8e4-4746-be84-0c8e9a6d5f38] [Finished handling request => POST /api/v1/authentication/login_saml_callback/ 302]
3	The redirect will occur to the configured Login URL. Name: SAMLRequest Headers: Request URL: Click here Request Method: GET Status Code: 200 OK Remote Address: 18.216.23.72:443 Referrer Policy: strict-origin	API gateway.log and Identity log do not include a log entry for this step
4	After logging in, a redirect will occur to the Sisense site to the login SAML callback page. The message in this entry under section FormData contains the content of the message in SAML encrypted format. It can be converted to view the details passed back from the Identify Provider site. Name: login_saml_callback Headers: Request URL: https://customer.sisense.com:port /api/v1/authentication/login_saml_callback/ Request Method: POST Status Code: 302 Found Remote Address: 10.50.83.39:30845 Referrer Policy: strict-origin-when-cross-origin	API gateway.log and Identity log do not include a log entry for this step
5	Request URL: https://customer.sisense.com:port /app/main Request Method: GET Status Code: 200 OK Remote Address: 10.50.83.39:30845 Referrer Policy: strict-origin-when-cross-origin	API gateway.log and Identity log do not include a log entry for this step
Logout
1	Logout redirect occurs when a user logs out of the site. RequestURL: http://0.0.0.0:30845/api/auth/logout Request Method: GET Status Code: 200 OK Remote Address: 0.0.0.0:30845 Referrer Policy: strict-origin	API gateway.log and Identity log do not include a log entry for this step
2	Redirect to the logout page that was configured in the Sisense SSO setup. Request URL: Click here Request Method: GET Status Code: 302 Found Remote Address: 18.216.23.72:443 Referrer Policy: strict-origin	n/a

Useful Tools

To view the decoded SAML message, download: https://chrome.google.com/webstore/detail/saml-message-decoder/mpabchoaimgbdbbjjieoaeiibojelbhm

The following website also decodes the content of the SAML response message:

https://www.samltool.com/decode.php

Enter code in the Deflated and Encoded XML field and click Decode and Inflate XML.

SAML Call-Back Message

The SAML Identity Provider site in which the Sisense is integrated for SSO returns a message callback. When converted to XML using a SAML conversion tool (such as the one mentioned above), you can view the user details passed. These details are described in the following table:

SAML field	Contains
User.email or NameID	User email configured in the Identity Provider site.
User.LastName	User last name configured in the Identity Provider site.
User.FirstName	User first name configured in the Identity Provider site.
memberOf	Contains one or many groups the user is associated with in the Identity Provider Site.

MongoDB

MongoDB is the context of SSO (and for a regular login) used to store the last session of the logged-in user including the additional SSO parameters that are passed via the SSO handshake.

If a user has previously logged in successfully, a set of validations are performed between the passed-in parameter via SSO token and the data in the document. This validation is part of a security assessment of the user’s login attempt.

The following table describes the various scenarios available for a user that logs in via SSO, where the option to automate the creation of the user is used as part of the SSO process.

Allow creation of new users via SSO	User setup in Sisense	Action
Off	No	Deny user login
Off	Yes	Accept user and update MongoDB record for the user
On	No	Accept user login and insert a new MongoDB record for the user
On	Yes	Accept user and update MongoDB record for the user

The record for a given user contains values that pertain to the SSO handshake. The user record can be found in MongoDB prismWebD under Collections >> users.

The following table describes keys in the SSO process, and which validations are performed between the token set values and the previous user records in the MongoDB:

Key	Value
SSO	true/false
createdSSO	Contains the protocol used for SSO, (e.g.,JWT, SAML, or OIDC. The value set indicates which protocol was used to login via SSO. If a user once logged in via one protocol, and then the protocol changed, the value will not change with the new login of the user using a different protocol. For example, if a user logs in via “SAML” and then the protocol changes to “JWT”, this field will always remain “SAML” even though the protocol changed.
email	The user’s login email that is passed via SAML message.
userName	The user’s login name that is passed via SAML message.
lastName	The user’s last name that is being passed via SAML message.
firstName	The user’s first name that is being passed via SAML message.

Troubleshooting

Gathering Information

Attribute	General information
Sisense deployment	Which version of Sisense is installed? Is this an on-premises or hosted deployment? Which operating system is the customer using? Is the customer using the Windows or Linux version of Sisense? Is the customer directly accessing or embedding Sisense? If embedding: using SisenseJS, Frame SDK, or Iframe embedding? Which version are they using? Is the customer using Active Directory (AD), full SSO integration, or a combination? Is the customer using only AD for authentication and NOT SSO? ⇒ Not an SSO issue Is the customer using AD only for user import and using Sisense Direct signing? ⇒ Not an SSO issue Is the customer using AD for the purpose of importing the users and using SSO integration for authentication?
Customer project stage	Is it a new or an existing customer that is using SSO for the first time? What stage is the customer at? Development of the SSO handler (e.g., the customer is looking for development help.) Testing the handshake (e.g., the customer is looking for troubleshooting and configuration help.) Going live for the first time. In production. Going live for first time and SSO login is not working For everyone For unrelated users (e.g., same organization/same network) For related users or groups of users (e.g. same organization/same network) In production and SSO login stopped working Potential causes Has the customer just upgraded to a new version of Sisense which led to the issue? Same release and experiencing issues with a previously working SSO? Has the customer switched from Windows to Linux? Effects For all For unrelated users (e.g., same organization/same network) For related users or groups of users (e.g., same organization/same network)
Network and infrastructure	Is there a firewall, private network, or proxy between the SSO handler and Sisense server? Do the SSO handler and Sisense servers reside on different domains? Have any changes been made within the infrastructure of the customer organization? Has a certificate been updated recently?
Sisense configuration	Have there been any configuration changes made in the SSO settings in Sisense?
End user analysis	What browser is the user using to access the platform? Is the user experiencing a production issue with all users, a subset of users, or a particular user. What is unique about the user and the method in which they access Sisense? Has the user experiencing issues previously logged in successfully? The type of users having issues are: Internal within the organization of the customer External users Is the user accessing the platform over the Internet? Behind a firewall or proxy server? Is there a VPN software on the user’s workstation? Has the customer organization or individual user recently made any changes to their workstation or within their organizational infrastructure? Have there been any changes made to the browser configuration with regard to site security and cookies?

Gathering Assets

To troubleshoot and test SSO, gather the following logs and configuration data:

Asset	Notes
HAR files (or screen captures of the specific sections in the browser Developer Tools)	This enables the user experiencing issues with their SSO login to view communication between Sisense and the user’s browser. In some instances this information cannot be shared due to security issues. Direct the customer to use screen captures and/or provide text extracts of the values that are outlined in the HTTP Archive Format and Server Logs section of this document.
Sisense Server-side log/API Gateway.log	The version in this document requires you to have a log level for the service set to DEBUG to view valid SSO connectivity flow or errors in the process.
Sisense Server-side log/Identity.log	The version in this document requires you to have a log level for this service setup to DEBUG.
Sisense Server-side log/Combined.log	The log contains some entries written as a result of login performed via SSO. However, some of the information might be incomplete. As a workaround, more complete log details will be written by going to the Sisense Admin page for SSO and changing the protocol to a different protocol and back to the protocol being implemented. This action immediately creates log entries that can be used to analyze the full workflow for the SSO workflow implemented.
MongoDB	Under prismWebDB > users collection get access to the document in MongoDB that contains the user having issues with SSO access.
Sisense configuration	Refer to the Configuration and Enabling section pertaining to SSO and review the configuration.

Troubleshooting Scenarios

The following table describes potential end-user issues with SSO login. Each incident may have one or more possible causes:

#	Issue	Browser error	Possible causes
1	The user is logging in successfully on the customer login page (Identity Provider) however; when redirected to Sisense, the login fails.	An error occurred while trying to authenticate using SSO. Ask your administrator for assistance. Administrators may log in using the manual Login page.	1
2	User is unable to launch Sisense after login was successful.	Browser displays a certificate error.	2
3	User is unable to launch Sisense after login was successful.	Browser displays “SAML assertion not yet ready”.	3
4	The user is able to log in, but not to their intended Sisense account. The default value has been applied rather than the intended one.	n/a	4
5	User has been disabled in Identity Provider (e.g., deleted or deactivated), but is not kicked out of the session.	n/a	5
6	Customer is using a load balancer to access Sisense and after the SAML callback the site is not accessible.	n/a	6, 7

The following table describes the diagnostic procedure for the issues described in the table above. Each procedure starts with a possible cause, a suggested procedure, the files that provide you with the evidence, and a resolution.

#	Issue category	Probable cause	Diagnostic procedureI	HAR file	API Gateway.log (Only in DEBUG level)	Resolution
1	Sisense admin	The user has not been set up in Sisense and the Create User for SSO is disabled.	Check the settings for SSO in Sisene Admin configuration.	n/a	n/a	Set up the user manually in Sisense.
2	Sisense admin	Certificate has expired or was updated on the customer site and needs to be updated in Sisense admin.	n/a	Locate the certificate settings.	n/a	Copy the X.509 certificate in the SAML response located in the HAR entry, and paste it into the Sisense SSO configuration.
3	Other	There is a timing discrepancy between Sisense and the Identity Provider.	Check if the Identity Provider site and the Sisense clocks are synchronized.	n/a	n/a	The customer needs to ensure that clocks are synchronised (and deviate no more than 5 minutes).
4	Sisense admin	The memberOf attribute setting in Sisense and the setting in the Identity Provider do not match.	Check the message content and see if a memberOf value is being passed in the XML.	Copy the content of the SAML message.	n/a	Change the setting on the Identity Provider site or on the Sisense Admin for SSO.
5	Other	This is a limitation with SAML, as the user will continue to have access as long as the browser session is open.	n/a	n/a	n/a	Need to end the session for the user.
6	Other	When a load balancer is set up, it changes https 443 port to standard 8081. As a result, SAML callback /api/v1/authentication/login_saml_callback/ goes to incorrect URL (e.g. http://site:8081/api/v1/authentication/login_saml_callback/ instead of http://lsite:443/api/v1/authentication/login_saml_callback/).
7	Other	A proxy URL is used in the setup because the customer is using a reverse proxy. The URL setup in the proxy URL under the Admin>System>Config for Web Server is not a fully qualified URL (e.g., /Sisense was entered as opposed to a full URL).	Verify if a Relay State in the HAR file is showing a value of a full URL location.	n/a		Force Sisense to send a secure cookie by executing a REST API call to POST /api/system/security with the body: {“forceSecureCookies": true} by utilizing the Admin > Rest API post command for security.

.r.