Understanding and Configuring Domo Single Sign-On Using SAML

Intro

Users can sign in to Domo using either the built-in authentication system of Domo or using a Single Sign-On (SSO) solution from a supported provider.  Domo provides two such SSO solutions—Security Assertion Markup Language (SAML) authentication and OpenID Connect. Both SAML and OIDC Connect can run at the same time. This makes it easy to segment internal and external users. This is also useful for separating the SSO solutions you use for Domo access and Domo Embed. For example, you can use SAML for controlling employee access in Domo and OIDC for embedding cards into other websites and applications. This article discusses SAML authentication. For information about OpenID Connect, see Enabling SSO with OpenID Connect.   

Using SAML, administrators can enable Single Sign-On into Domo. Once Single Sign-On has been enabled, new users are automatically provisioned from LDAP, and LDAP groups can be imported from an existing identity provider.

To use SAML, you must have a cloud identity provider (IDP) or federation service in place that supports authentication via SAML 2.0. For more information about SAML 2.0, see http://en.m.wikipedia.org/wiki/SAML_2.0

You can add specific users to the Direct Sign-On List to enable them to bypass SSO and sign into Domo directly. These users can then toggle login modes (Direct or Single Sign-On) from the Domo login screen. This is especially useful in situations where you want to grant Domo access to contractors or non-employees who are not given accounts in the company’s email or directory system.

You must have an "Admin" default security role or a custom role with "Manage All Company Settings" enabled to set up SAML. For more information about default roles, see Default Security Role Reference. For more information about custom roles, see Managing Custom Roles.

Domo provides three methods of setting up SSO:

• Manual Setup. This is the "traditional" method for setting up SSO in Domo. 

• Metadata Upload. This method allows you to retrieve your configuration information and digital certificate just by entering the URL for your identity provider. Be aware that not all identity providers offer this service.

• Setup Wizard. This wizard guides you through the difficult jargon and details of SSO configuration. The wizard offers context-based instructions for a number of leading identity provider services, including Okta, Ping, Microsoft Azure, Salesforce, and more.

Of these methods, metadata upload is strongly recommended, as you only need to enter your identity provider URL—the rest of the work is done automatically. If this method is not supported by your identity provider, it is recommended you use the setup wizard. Manual setup is recommended only if neither of the other two methods meet your needs.  

This topic first explains the components of the Single Sign-On tab user interface in Domo. It then gives provides instructions for configuring SSO using the three available methods.

Video - SAML Single Sign On (SSO)

Parts of the Single Sign-On tab

The following table lists and describes the various components of the More > Admin > Authentication > SAML (SSO) tab in Domo:

Configuring Single Sign-On

You can configure Domo SSO using any of these methods:

• Metadata Upload. Recommended. Allows you to retrieve your configuration information and digital certificate just by entering the URL for your identity provider. Be aware that not all identity providers offer this service. 

• Setup Wizard. Recommended if metadata upload is not supported by your IdP. This wizard guides you through the difficult jargon and details of SSO configuration. The wizard offers context-based instructions for a number of leading identity provider services, including Okta, Ping, Microsoft Azure, Salesforce, and more.

• Manual Setup. This is the "traditional" method for setting up SSO in Domo. 

Metadata Upload

Metadata upload is highly recommended for setting up Domo SSO, as it allows you to pull in all necessary information simply by entering your IdP's URL. If your IdP does not support this option, it is recommended you use the Setup Wizard as a next resort. 

To set up SSO using Metadata Upload,

1. Select More > Admin > Authentication > SAML (SSO).
   If SSO has not yet been set up for your Domo, an intro screen appears listing the benefits of SSO. Otherwise, you are taken directly into the Single Sign-On (SSO) tab.

2. (Conditional) Do one of the following:

   • If the intro screen appears, scroll to the bottom, click Start Setup, then click the Metadata upload tile.

   • If you are taken directly to the Single Sign-On (SSO) tab, click Metadata upload (found in the "Information from your IdP" section).

3. In the Metadata URL field, enter the SAML metadata URL for your identity provider.   

Setup Wizard

The SSO setup wizard is recommended if your identity provider does not support Metadata Upload as described in the preceding section.

To set up SSO using the Setup Wizard,

1. Select More > Admin > Authentication > SAML (SSO).
   If SSO has not yet been set up for your Domo, an intro screen appears listing the benefits of SSO. Otherwise, you are taken directly into the Single Sign-On (SSO) tab.

2. (Conditional) Do one of the following:

   • If the intro screen appears, scroll to the bottom, click Start Setup, then click the Wizard tile.

   • If you are taken directly to the Single Sign-On (SSO) tab, click the bolded word "wizard" near the top of the tab.
     
     
     
     The Setup Wizard now opens.

3. Follow the steps of the wizard to set up SSO in Domo.

   Tip: If you need to close out of the wizard before you've completed your setup, don't worry—the wizard remembers the screen you ended on and will open that screen when you return.

Manual Setup

To properly implement Single Sign-On with SAML in Domo using manual setup, you must configure SSO in both your Identity Provider and in the More > Admin > Authentication > SAML (SSO) tab in Domo.

To configure Single Sign-On,

1. Configure Single Sign-On for Domo in your IDP.
   Because different IDPs configure applications differently, it is best to consult the documentation for your particular IDP for setup. However, the following list explains how to configure certain SSO components that are common across most IDPs.

   Component	Instructions
   Integration Type	Select SAML 2.0 as the Integration Type.
   Application Logo	If asked to supply an application logo, you can use the following:
   Identity Provider SSO URL	The URL where Domo sends the SAMLRequest. Copy and paste this URL from the SAML Assertion Endpoint URL field in More > Admin > Authentication > SAML (SSO) in Domo.
   Audience URI (SP Entity ID)	Enter the URL for the intended audience.
   Default Relay State	Leave this field blank, as Domo does not use it in the app configuration.
   Application Username	Enter a user's email address as the username.
   SAML Attributes	When defining which attributes get passed to Domo, use the following names for each of the attributes. (All attribute names should be lowercase except for SAML_SUBJECT. The "email" attribute is required; all others are optional.) Attribute Name Description Format email Email someone@acme.com email.secondary Email someone@acme.com group Directory Groups CN = Some Group, OU = Some Org, DC = Acme, DC = com title Job Title Product Manager user.phone Personal Phone Number Any format desk.phone Desk Phone Number Any format name Full Name Jon Smith name.personal Personal Name (this field and the name.family field are concatenated into name)  Jon name.family Family Name (this field and the name.personal field are concatenated into name)  Smith employee.id Employee ID 521 hire.date Hire Date   role Role Instructional Designer department Department Engineering timezone Time Zone
   Certificate	Download the certificate provided by the IDP. You will upload this certificate to Domo when configuring SSO in Domo.

    

2. Ensure that appropriate users are given access to Domo in the IDP.

3. In Domo, select More > Admin.
   The Admin Settings opens.

4. Expand Authentication, then select SAML (SSO).

5. Click Enable Single Sign-On.

6. In the Identity Provider Endpoint URL field, enter the URL where the SAMLRequest is to be sent.

7. In the Entity ID field enter the identifier of the Domo instance making the SAML request. This should match the "Audience URI" you entered in your IDP.

8. Upload the X.509 certificate by clicking , browsing to the certificate on your hard drive, and clicking Open.

9. (Optional) If you want to automatically import groups from your IDP, check the box that reads Import groups from identity provider.

10. Copy the URL from the SAML Assertion Endpoint URL field into the Identity Provider SSO URL in your IDP if you have not already done so.

11. Click Test Connection to make sure everything is configured properly.

12. Clicking Test Connection simulates an actual login with your credentials and verifies that the SAML Assertion was returned as expected.

    Note: The connection test does not work if you have not given yourself access to Domo in the IDP.

13. (Optional) If you want to see the returned attributes, click View Details.

14. Click Save Changes to enable SSO.
    This verifies that the test connection was successful and turns on SSO for your environment.

15. Sign out of Domo, close your browser, and clear your browser cookies (or open a different browser).
    If you sign out and then sign back in without clearing cookies, a session token issue occurs that causes an error.

Adding Users to Direct Sign-On

You can add specific users to the Direct Sign-On List to enable them to bypass SSO and sign into Domo directly. These users can then toggle login modes (Direct or Single Sign-On) from the Domo login screen. This is especially useful in situations where you want to grant Domo access to contractors or non-employees who are not given accounts in the company’s email or directory system.

To add users to the Direct Sign-On List,

1. In More > Admin > Authentication > SAML (SSO), click the Direct Sign On List header then the Add Users to Direct Sign-On button.

2. Click in the Search Users field and locate the name of a user or group you want to add to the Direct Sign-on List.

3. Click the name of the user or group to add it to the field.

4. Repeat steps 2 and 3 as often as necessary to add the names of all desired users and groups to the field.

5. (Optional) Add notes to the Notes field indicating why these users were added to the Direct Sign-On List.

6. Click Add.

The names of all of the users and groups you added should now appear in a list in this tab. If you added any notes, these should appear as well. You can remove a user or group from the list by clicking the "X" next to it.

Transitioning to Single Sign-On

If you are transitioning from the built-in authentication system of Domo to Single Sign-On, consider the following:

• Before implementing Single Sign-On, ensure that the email addresses for accounts in Domo match the email addresses for accounts in your system.

• When users sign in, Domo can identify users based only on their existing email addresses.

• If a user logs in via Single Sign-On and the email address does not match the email address of an existing account, Domo creates a new account. For this account you must configure group memberships and content access.

Using Single Sign-On in Domo

When using Single Sign-On (SSO) in Domo, users sign in and sign out differently than when using the built-in authentication system of Domo.

Signing in to Domo when using Single Sign-On

• If authenticated to their system, users can connect to Domo using their existing credentials.
  Depending on the type of directory, operating system, and Web browser, users may not have to provide credentials but are seamlessly signed in.

• If not yet authenticated to their system when connecting to Domo, users are presented with a simple sign-in to their system before connecting in to Domo.

Signing in to Domo from Workbench when using Single Sign-On

Workbench now uses access tokens to authenticate. You can no longer authenticate Workbench instances using single sign-on. 

Signing out of Domo when using Single Sign-On

To completely sign out, you must sign out of Domo and close the Web browser.

To sign out of Domo when using Single Sign-On,

1. Mouse over your user menu , then select Sign Out.
   After signing out, a sign in page appears.

2. Close the Web browser.
   To complete the sign out process, close the Web browser.

Using Domo with Single Sign-On

When using Domo with Single Sign-On, you cannot

• be sent a forgotten password email

• change your password in your profile

• see the Security tab for setting password requirements

• see a user until the user has signed in to Domo