# Troubleshooting SSO Using SAML

> Troubleshooting SSO Using SAML

*Source: https://docs.sisense.com/main/SisenseLinux/troubleshooting-single-sign-on-using-saml.htm*

---

Last updated: June 10, 2026

|  |  |
| --- | --- |
| [Tier](https://www.sisense.com/pricing/#pricing) | [Deployment](https://docs.sisense.com/main/SisenseLinux/introduction-to-sisense-cloud-managed-services.md#ComparisonofManagedCloudandSelfHosted) |
| Grow    Enterprise | Cloud     On-Prem |

## Authentication Logical Flow

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

### Phase 1

![Troubleshooting single sign on using saml image 7a8hkx3d](https://docs.sisense.com/main/Resources/Images/troubleshooting-single-sign-on-using-saml-image-7a8hkx3d1.png)

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.

![Troubleshooting single sign on using saml image lqkzzpss](https://docs.sisense.com/main/Resources/Images/troubleshooting-single-sign-on-using-saml-image-lqkzzpss1.png)

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 is not 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.

![Troubleshooting single sign on using saml image 04tmt9tm](https://docs.sisense.com/main/Resources/Images/troubleshooting-single-sign-on-using-saml-image-04tmt9tm1.png)

If a user is not found in the system, Sisense creates a new user (3).

## Architecture Diagram

This figure illustrates the authentication flow using SAML 2.0.

[![Click to view full size](https://docs.sisense.com/main/Resources/Images/troubleshooting-single-sign-on-using-saml-image-8z1k59t4_600x715.png "Click to view full size")](https://docs.sisense.com/main/Resources/Images/troubleshooting-single-sign-on-using-saml-image-8z1k59t4.png)

The following table describes the steps of the authentication flow based on the figure above. This includes 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.

| # | 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](#Troubles).

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**](https://docs.sisense.com/main/SisenseLinux/troubleshooting-single-sign-on-using-saml.htm?address=http%3A%2F%2F10.50.83.39%3A30845%2Fapp%2Fmain%23%2Fdashboards)  **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**: Example:     ``` https://configuredlogin%20site/trust/saml2/http- post/sso/615413?SAMLRequest=nVPBjpswEP0V5DsYAqTUSrJKE1WNt G1RQnvoJfKaya5VY1O%20PyaZ%2Fv4aEKoduDjkhz7x5M%2FPeMHs4 NSo4gkVp9JwkUUweFjPkjWrZsnMvegt%2FOkAXeJhGNiTmpLOaGY4Sm eYNIHOC7ZZfH9kkillrjTPCKBJs1nOyL%209Isn0zzLDvUMIVCZJBnJPg5 NvQVHojYwUaj49r5UDxJwjgPk6KKC5ZlLM%2BjD0X6iwTlhfqT1LXUz7fn eDqDkH2pqjIsv%2B8qEqz9JlJzN7R%2Bca5FRqkvB%2040Q1nCMjAZlnq WOhGmosx062q88oT04bE3%2FRkOnSZ4lKQmWiGB7tpXR2DVgd2CPU sCP7eOZ39MncZTHUZFG6UeWxkWWU95Kekwo9%2FKCdlIM%2089Ch 777vthdcqScuflNytoINAtkrD26vzsexyGJ3Xm5Gr3hGf7%2F5ws26NEqKv %2Ff4%2B9nYhrv30UmUDBFZh4cByqDhUi3r2gKiV08p87qywB3MiRcbCB %201Hu1wd1MMNenUdn66wZVpWm4l9obDiQs3SnpNvFJesS0c7hH4Jk ww0VP7cOk%2Fr8bW%2FQmD8ItVlmtsjXUXa%2F43z%2BKce0eOf9nr %2F3TxBg%20%3D%3D&RelayState;&=%2Fapp%2Fmain%23%2Fdashboards ```   **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](https://sisense-dev.onelogin.com/trust/saml2/http-redirect/slo/615413?SAMLRequest=nVFNS8MwGP4rJffmo9uqhK5zMITB9ODEgxfJ2rdbpM0786bDn2%2F WThiCHjzmyfOZFIvPrk1O4MmimzPFJVuUBZmuPeoN7rEPT%2FDRA4Uk8hzp4WbOeu80GrKknemAdKj0dvmw0RmX%2BugxYIUtu5L8rTBE4EMswJL1as7emlmzq%2BRUT nKza5rcyOxmx5KX75JREolEPawdBeNChGSmUjlLs8mzUlreaim5yvNXlqxid%2BtMGJSHEI6khYg1wBGkNZw4Omhxbx2vsBPB9xTEuXEmzuTUQ209VBFrUeRqNlUTNr6PHhr 4f4wst2N8Ia58LqaPUbdeJffoOxN%2BN1RcDYit02agauiMbZd17YGIle94cLxGuLssPY%2B7xI0J5Xj68cnlFw%3D%3D)  **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 that were 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, 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 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 [HTTP Archive Format and Server Logs](#HTTP). |
| 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 Procedure | 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 | [Click to view full size](https://docs.sisense.com/main/Resources/Images/troubleshooting-single-sign-on-using-saml-image-ihoapyt0.png) | 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. |