Troubleshooting SSO Using OpenID Connect

Authentication Logical Flow

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

Authentication Redirect - A user attempts to access your dashboard.
Authentication - Sisense recognizes that the user is not 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.
Redirect to RP - The user authenticates through the OpenID provider's site and is redirected back to Sisense with an authorization code.
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.
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 do not exist, Sisense creates a new user.

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

The HTTP Archive Format (HAR) file cannot be used to analyze SSO issues when the OIDC protocol is used because the communication occurs directly between Sisense and the Identity Provider site.

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 from off to on, and save, the combined log will be added with the additional logs.

This is described in the following table:

#	HAR Entries	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	Sisense server communicates with the OIDC Identity Provider. There is no communication routed via the browser, and therefore no HAR entry.	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.
3	Sisense server communicates with the OIDC Identity Provider. There is no communication routed via the browser, and therefore no HAR entry.	API-gateway.log and Identity log do not include a log entry for this step. 2021-06-29T01:37:12.580, sisense, api-gateway, [4743.341944461] [[34mINFO[39m] [2021-6-29 08:37:12.579] [undefined] [41]:[] [/usr/src/app/node_modules/@sisense/sisense-logger/index.js:174] [X-request:342ee528-4b11-4abc-a263-db81ddf9399f] [Start handling request => GET /openid?return_to=http%3A%2F%2F10.50.11.117%3A30845%2F] 2021-06-29T01:37:12.600, sisense, api-gateway, [4743.361269058] [[34mINFO[39m] [2021-6-29 08:37:12.599] [undefined] [41]:[] [/usr/src/app/node_modules/@sisense/sisense-logger/index.js:179] [X-request:342ee528-4b11-4abc-a263-db81ddf9399f] [Finished handling request => GET /openid?return_to=http%3A%2F%2F10.50.11.117%3A30845%2F 302] 2021-06-29T01:37:18.118, sisense, api-gateway, [4748.880378683] [[34mINFO[39m] [2021-6-29 08:37:18.118] [undefined] [41]:[] [/usr/src/app/node_modules/@sisense/sisense-logger/index.js:174] [X-request:d20baf21-a471-4753-9eae-22fdd532d24b] [Start handling request => GET /openid_callback?state=UTOlut%2FwmZMLyPL%2F%2FiQwgnoR&session_state=90acee91-79bb-4a37-a6a4-8c51e60ba684&code=ac7611ad-60bc-4800-bc51-dd35f0eec608.90acee91-79bb-4a37-a6a4-8c51e60ba684.4e2b1b4c-b52e-4e47-9634-ae9eb6fd1aae] 2021-06-29T01:37:18.206, sisense, api-gateway, [4748.968722582] [[34mINFO[39m] [2021-6-29 08:37:18.206] [undefined] [41]:[] [/usr/src/app/node_modules/@sisense/sisense-logger/index.js:179] [X-request:d20baf21-a471-4753-9eae-22fdd532d24b] [Finished handling request => GET /openid_callback?state=UTOlut%2FwmZMLyPL%2F%2FiQwgnoR&session_state=90acee91-79bb-4a37-a6a4-8c51e60ba684&code=ac7611ad-60bc-4800-bc51-dd35f0eec608.90acee91-79bb-4a37-a6a4-8c51e60ba684.4e2b1b4c-b52e-4e47-9634-ae9eb6fd1aae 302]
4	Sisense server communicates with the OIDC Identity Provider. There is no communication routed via the browser, and therefore no HAR entry.
Log Out
	n/a	n/a

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., such as 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 always remains "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
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 in SSO Using OpenID Connect 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 Cause
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.
2	When the Sisense page is accessed, it redirects to the OpenID login, but after login an error is displayed and the Sisense site does not load.	The message failed to obtain access token appears.	1
3	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	3

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

#	Issue Category	Probable Cause	Diagnostic Procedure	HAR File	API Gateway.log (Only in DEBUG level)	Resolution
1	Certificate	The SSL certificate of the OIDC Identity Provider is not a trusted certificateThis can occur when OpenID is used in a private network or behind a corporate proxy server.	This issue results in an error on Sisense site "failed to obtain access token	In HAR file entry: openid_callback GET 400 Bad Request	n/a	The certificate needs to be set up to be trusted.
2	Infrastructure	A proxy URL is used in the setup because the customer is using a reverse proxy, and 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).	Check if a Relay State in the HAR file is showing a value of a correct 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.
3	Admin	The group assigned to the user in the Identity Provider does not match what is set up in Sisense Admin.	Check that the values match in the Identity Provider and Sisense Admin setup.	n/a	n/a	Correct the admin/mapping in Identity Provider or Sisense Admin setup.

Issue Category

Probable Cause

Diagnostic Procedure

HAR File

API Gateway.log

(Only in DEBUG level)

Resolution

Certificate

The SSL certificate of the OIDC Identity Provider is not a trusted certificateThis can occur when OpenID is used in a private network or behind a corporate proxy server.

This issue results in an error on Sisense site "failed to obtain access token

In HAR file entry:

openid_callback

GET 400

Bad Request

n/a

The certificate needs to be set up to be trusted.

Infrastructure

A proxy URL is used in the setup because the customer is using a reverse proxy, and 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).

Check if a Relay State in the HAR file is showing a value of a correct 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.

Admin

The group assigned to the user in the Identity Provider does not match what is set up in Sisense Admin.

Check that the values match in the Identity Provider and Sisense Admin setup.

n/a

Correct the admin/mapping in Identity Provider or Sisense Admin setup.