Skip to main content
waffle.svg
Domo Knowledge Base

Troubleshooting Single Sign-On Using SAML

Version 3

 

Common issues with Single Sign-On Using SAML and how to solve them.

Intro

Use the following information to troubleshoot Single Sign-On Using SAML (Okta, ADFS, PingIdentity, etc.)

 

Items to Consider

Troubleshooting failed SAML-SSO logins can begin with the following considerations:

  • If a user does not see the "Sign In" button while trying to login, double-check that they did not mistype the instance URL (e.g. moodcrop.domo.com in place of modocorp.domo.com) Typing the URL incorrectly will still bring you to a normal sign-in page, even if no real Domo instance exists at that address

    • Check if the "mixed-mode sign-in" option is enabled in the SSO Settings; if it is, the product is working as designed. Mixed-mode sign-in causes the regular login page to be presented for normal instance logins but allows for SSO logins to be initiated from within an IdP system (this feature is most typically utilized for SSO-powered embedding of cards in external systems where SSO is not desired for regular sign-ins.)

  • If a user receives an error while signing in, and the error is NOT displayed on a Domo-branded webpage, the issue may be:

    • The SAML Endpoint URL or Entity ID is incorrect in the Domo SSO settings.

    • The IdP is expecting a signed SAML Request and the option to "Sign Authentication Requests" has not been enabled in the Domo SSO Settings, or perhaps that the digital certificate loaded into the IdP does not match the certificate provided by Domo near where this setting is enabled.

    • The user does not have permissions within the IdP to use Domo. Typically, IdP systems will have a permission system built into them to allow different users to be granted access to different tools; make sure the user trying to sign in to Domo has access to use Domo in the IdP settings.

  • If a user receives an error while signing in, and the error is displayed on a Domo-branded webpage, the issue may be:

    • The IdP redirected the user to the wrong Domo login URL.

    • The digital certificate sent by the IdP in the SAML Response does not match the certificate that was uploaded to Domo for validating the origin of the SAML Response.

    • The user's email attribute is not properly defined in the SAML Response.

    • The user's email attribute IS properly defined in the SAML Response, but the email is not assigned to any existing users, and the "only invited people can access Domo" option has been selected in the Domo SSO Settings. When this option is enabled, users must be created manually and cannot be auto-generated when logging in via SSO.

If the above overview of general items to consider does not reveal the cause of your login failures, please continue with the advanced troubleshooting below.

What are SAML Requests and Responses?

SSO logins use a special communication protocol called SAML which stands for Security Assertion Markup Language.

The SAML Request is a message that is sent from Domo to your IdP during login which contains identifying information about your Domo instance so that your IdP knows what system you are trying to sign in to. Depending on settings you choose in Domo, it may also contain a digital certificate to further confirm that the login request originated from Domo.

The SAML Response is a message that is sent from your IdP to Domo during login. This message contains identifying information about the person who is signing in so that Domo knows which Domo user they belong to. It also contains a digital certificate to confirm that the login response originated from your IdP.

The lifecycle of a SAML-Protocol sign-in is typical as follows:

  1. User navigates to their Domo Instance URL.
  2. User clicks "Sign In".

  3. Domo redirects the user to the IdP and includes a SAML Request packet.

  4. IdP performs some method of authentication and confirmation that the user has permission to login to Domo from that system.

  5. IdP redirects the user back to Domo and includes a SAML Response packet.

  6. Domo reviews the SAML response packet to confirm that it contains the correct authorization information from the IdP and allows the user to login.

 

If the "skip to identity provider" option is selected in the Domo SSO settings, the user will not have to click the "sign in" button, they will simply be automatically directed straight to the IdP sign in page.

If the user has already logged into the IdP recently, for Domo or even another service, the IdP may skip the process of asking for username and password and immediately redirect back to Domo.

If both of the above scenarios occur together, the whole login process may be invisible to the user, aside from a possible 1-5 second delay while all of the redirects and other steps occur in the background.

Collecting, decoding, interpreting, and troubleshooting a SAML Request

Note: The following instructions are specific to the Google Chrome browser.

Collecting a SAML Request

  1. Open a new Incognito window in Google Chrome.
  2. Right-click anywhere in the main window and choose "Inspect"; this will open the Chrome Dev Tools pane.

  3. In the Dev Tools pane, select the "Network" tab, then check the box that says "preserve log." 

    Chrome Dev Tools Network Tab.jpg

  4. Leaving the Developer Tools window open, navigate to the URL for your Domo instance in the Incognito window. Click "Sign In" to proceed to your IdP's login page.

  5. Once you have landed on your IdP's login page, the SAML Request will have already been sent from Domo to the IdP. To find it, go back to the Chrome Dev Tools pane, find the "Filter" field in the Network tab, and enter the word: SAML

    Chrome Dev Tools Network Filter.jpg

  6. You will see a network communication record in the list below the Filter field. Click on it and navigate to the "Headers" tab of that record.

    Chrome Developer Tools SAML Headers.jpg

  7. In the Headers tab, scroll down to the "Form Data" section. The block of text following under this section is the SAML Request in encoded form.

Note: Encoding data is not done to protect the data, but rather to protect communication systems from misinterpreting the data as commands to be run. As you'll see, the process to decode your SAML Request is fairly trivial.

 

Important: Do not use an online website to decode your SAML Request as it may contain sensitive data. It is best to follow the steps below to decode the SAML Request using the Chrome browser on your machine.

  Decoding a SAML Request

  1. After you have followed the steps to obtain the encoded SAML Request, copy the full encoded SAML Request value.

  2. In the Chrome Dev Tools, navigate to the "Console" tab.

  3. In the Console tab, type ATOB('SAMLRequestValue'). Be sure to keep the single-quotes and replace SAMLRequestValue with the encoded SAML value you previously copied.
     

    Note: If the pasted value has line-breaks in it, remove them.
  4. Hit enter and Chrome will decide the SAML Request into its original XML format.

Important: Do not use an online website to format your decoded SAML Request as it may contain sensitive data.

Interpreting a SAML Request

The decoded, formatted SAML Request can still be daunting to try and interpret, but rest assured, there are only a couple items here to be reviewed:

  1. First, in this SAML Request, there will be an entry similar to this: <saml2:Issuer xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">some_text</saml2:Issuer>


    The text that is present in place of some_text in the example above is the Entity ID for Domo or the identifier that tells your IdP that Domo is the application your user is trying to log into. In most cases, it is simply your Domo instance URL, but some IdPs require a special identifier to be used. This value corresponds to the value that was entered into the Entity ID field in your Domo SSO Settings.
     
  2.  Next, in this SAML Request, there may be an entry similar to this: <ds:X509Certificate>some_certificate</ds:X509Certificate>

    The text that is present in place of some_certificate in the example above is the x.509 digital certificate which helps your IdP confirm that this login request originated from Domo. It is only present if you enabled the option "Sign Authentication Requests" in the SSO Settings.

Troubleshooting a SAML Request

Once you have collected, decoded, and interpreted the SAML Request, there are only a few things to review to determine if any issues exist here.

  1. The Entity ID is a value which you specify in the SSO Settings for Domo to include in the SAML Request. Your IdP must be able to recognize this Entity ID before it can know that Domo is the system your user is trying to sign into.

    Typically, Domo will be set up in your IdP system as an Application or App with an Entity ID specified in the App settings. Review this App in your IdP and make sure that the Entity IDs match up between the two systems. You may need to contact your IdP's support team for help finding the Entity ID for the App in their system.
  2. The x.509 digital certificate is a value provided by Domo which should be uploaded in connection with the Domo App in your IdP system so that it knows what value to expect in the SAML Request. You can download a copy of the certificate from the SSO Settings page in Domo under "Information your IdP may need."

    Review that the certificate from the SAML Request and the certificate uploaded for the Domo app in your IdP system match. If you have a certificate file, you can open it in a text editor to view the certificate. 

Collecting, decoding, interpreting, and troubleshooting a SAML Response

Note: These instructions are specific to the Google Chrome browser.

Collecting a SAML Response

  1. Open a new Incognito window in Google Chrome and navigate to the URL for your Domo Instance. Click "Sign In" to proceed to your IdP's login page. Do not yet enter your credentials.
     
    Note: If the option 'Skip to Identity Provider' is selected in the Domo SSO settings, you will not have to click "Sign In."
  2. Right-click anywhere in the main window and choose "Inspect"; this will open the Chrome Dev Tools pane.

  3. In the Dev Tools pane, select the "Network" tab, then check the box that says "preserve log." 

    Chrome Dev Tools Network Tab.jpg

  4. Leaving the Developer Tools pane open, enter your credentials for your IdP and continue until you reach the error message saying that you are not allowed to login to Domo, assuming you do see that message because you're reading this troubleshooting documentation.

  5. Once you have landed on the Domo Error page, the SAML Response will have already ben sent from the IdP to Domo. To find it, go back into the Chrome Dev Tools pane, find the "Filter" field in the Network tab, and enter the word SAML.

    Chrome Dev Tools Network Filter.jpg

  6. You will see a network communication record in the list below the Filter field, click on it, and navigate to the "Headers" tab of that record.

    Chrome Developer Tools SAML Headers.jpg

  7. In the Headers tab, scroll down to the "Form Data" section. The block of text following under this section is the SAML Response in encoded form.

Decoding a SAML Response

  1. After you have followed the steps above and found the encoded SAML Response, copy the full encoded SAML Response value to your clipboard.
  2.  In the Chrome Dev Tools, navigate to the "Console" tab.

  3. In the Console tab, type ATOB('SAMLResponseValue'). Be sure to keep the single-quotes and replace SAMLResponseValue with the encoded SAML value you previously copied.
     

    Note: If the pasted value has line-breaks in it, remove them.
  4. Hit enter and Chrome will decode the SAML Response into its original XML format.
     

    Important: Do not use an online website to format your decode SAML Response as it contains sensitive data.

Interpreting a SAML Response

  1. First, in this SAML Response, there should be an entry similar to this: <ds:X509Certificate>some_certificate</ds:X509Certificate>

    The text that is present in place of some_certificate in the example above is the x.509 digital certificate which helps Domo confirm that this login response originated from your IdP.
  2. Next, in this SAML Response, there should be an entry similar to this: <saml2:Attribute Name="email"><saml2:AttributeValue>some_email</saml2:AttributeValue></saml2:Attribute>

    The text that is present in place of some_email in the example above is the user email address for the user trying to sign in to Domo which is how Domo identifies who exactly is signing in. The <saml2:Attribute> and <saml2:AttributeValue> tags may include more information within them than what is shown in the example above, but it's important for the Name="email" piece to exist within the <saml2:Attribute> tag.

Troubleshooting a SAML Response

Once you have collected, decoded, and interpreted your SAML Response, there are only a few things to review to determine if any issues exist here:

  1. The x.509 digital certificate is a value provided by your IdP which should be uploaded into the SSO Settings in your Domo instance so that we know what value to expect in the SAML Response. You may need to work with your IdP's support team to learn where to retrieve the certificate on their side. This is typically a .pem, .cer, or .cert file. 

    Review that the certificate from the SAML Response and the certificate uploaded to the SSO Settings in Domo match.

    This certificate is mandatory to be included in the SAML Response.
  2. The user email address is a value from the user's profile within the IdP. The SAML settings in the IdP should be configured to include this Attribute with the SAML Response. You may need to work with your IdP's support team to learn how to set up that configuration in their system.

    Review that the email address from the SAML Response matches the Primary Email Address of the User in Domo that is trying to sign in.

    This email attribute is mandatory to be included in the SAML Response.