Skip to main content

​
Intro

Domo supports single sign-on (SSO) using two protocols: Security Assertion Markup Language 2.0 (SAML) and OpenID Connect (OIDC). Both SAML and OIDC can operate concurrently. This article describes how to choose the best protocol—SAML or OIDC—for your use case and how to configure SSO with your chosen protocol. Depending on your configuration, SSO can also auto-provision Domo users and assign them their user role, attributes, and group membership.
SCIM: In addition to SSO, Domo also supports user and group management via SCIM. Learn more.

​
Required Grants

You must have the Admin system role or a custom role with the Manage All Company Settings grant enabled to set up SSO. Learn more about system and custom roles.

​
Access SSO Configuration Settings

You can find Domo SSO configuration settings by navigating to Admin > Authentication > Single Sign-On (SSO).

​
SAML vs. OIDC: Choose a Protocol

Domo supports both SAML and OIDC. Choosing which one to use depends on a few considerations. All other things being equal, OIDC is the more modern standard and a good choice. For Domo setup, management, and functionality, consider these differences:
  • OIDC may be easier to configure, especially if your IdP provides a well-known config.
  • SAML requires certificate exchange and management, which introduces some overhead.
Additionally, you may want to ask the following:
  • Does your organization dictate which you should use?
  • Is your team more familiar with one or the other?
Use SAML and OIDC concurrently: You may have a case for using both SAML and OIDC concurrently. For example, your employees may use one IdP, and contractors may use another. In this case, you can integrate using SAML for one IdP and OIDC for the other.You may also want to use one protocol as the default for logging into Domo and the other protocol as the default for accessing embedded content.

​
Configure Your IdP

Refer to your IdP’s documentation for instructions on configuring the IdP side of SAML and OIDC SSO integrations. You may be asked for information from Domo. That information can be found in the SSO configuration user interface, and descriptions of that information for SAML and OIDC appear below.

​
Configure SSO with SAML

After configuring your IdP, access the Domo SSO configuration settings as described above.
  • If SAML SSO hasn’t been configured previously, select Configure for the SAML item. You can then choose Upload Metadata or Manual Entry. Learn more about each option below.
  • If SAML was previously configured, you can edit the configuration by selecting More (three vertical dots icon) > Edit OR Upload metadata. Note that uploading metadata will overwrite previously configured values.

​
Metadata Upload or Manual Entry

  • To upload metadata from your IdP, choose More (three vertical dots icon) > Upload Metadata in the configuration menu.
    In the modal that appears, enter the metadata URL from your IdP and select Upload.
    The full SAML configuration screen displays. Uploading the metadata URL automatically sets configuration values in the Information from your IdP section and overwrites any values that may have been previously set.
  • If your IdP doesn’t provide a metadata URL or if you don’t want to use it, choose Manual Entry in the configuration menu. With this option, you must manually enter the necessary information.

​
Information From Your IdP

As you configure your Domo SSO integration via SAML, you must provide some key pieces of information to define how Domo integrates with your IdP.
Note: If you uploaded metadata from your IdP, these fields are already populated and only require verification.
These values are defined in your IdP, which may use different terminology. Each field is described below to help you understand the purpose of the information and to help you find it in your IdP, no matter what it’s called.

Field

Description

Identity provider endpoint URL The URL where Domo will send authentication requests.
Entity ID The unique identifier for your SAML application (for SSO into this Domo instance, for example) in your IdP. This is also known as the Issuer. Some IdPs may set a default value; others may ask you to specify this value when creating your SAML app in your IdP.
Upload x.509 certificate The certificate provided by your IdP. This establishes trust between Domo and your IdP and allows Domo to verify that SAML assertions are legitimate.

​
Information Your IdP May Need

You may need to give the SAML app in your IdP some information about how it should integrate with Domo. This will depend on your IdP and how you’ve configured your SAML app. These values are defined in Domo, and your IdP may use different terminology. Each field is described below to help you understand the purpose of the information and how to identify the corresponding parameters to set in your IdP. For more details, refer to your IdP’s documentation.

Field

Description

Domo Entity ID The unique identifier of your Domo instance. This is sometimes known as the Issuer.
SAML assertion endpoint URL The URL where your IdP will send SAML assertions after authenticating a user. This is also known as the Assertion Consumer Service (ACS) URL.
Domo x.509 certificate download Your IdP can use this certificate to verify requests coming from Domo. If your SAML app is configured to verify authentication requests from Domo, you’ll need to upload this certificate to your SAML app in your IdP AND configure Domo to sign authentication requests. See Sign authentication requests below.
Metadata Domo provides a metadata file that contains the above information, including Domo’s current x.509 signing certificate. You can download this metadata and upload it to your IdP—if metadata upload is supported—to simplify the configuration of your SAML app.

​
Additional Settings

Configure the other SSO settings as necessary. These are discussed below.

​
Save the Configuration

After entering the required information and configuring the settings, save the configuration. If SAML isn’t already enabled, you can choose to save and enable it or save without enabling it. Learn how to enable SSO below.

​
Configure SSO with OIDC

After configuring your IdP, access the Domo SSO configuration settings as described above.
  • If OIDC SSO hasn’t been configured previously, select Configure for the OIDC item.
  • If OIDC was previously configured, you can edit the configuration by selecting More (three vertical dots icon) > Edit.

​
Information From Your IdP

As you configure your Domo SSO integration via OIDC, you must provide some key pieces of information to define how Domo integrates with your IdP. Most IdPs have a well-known config endpoint to make sharing this information easy, but if yours doesn’t, you’ll need to configure OIDC manually by providing the information that would otherwise be provided by the well-known config.

​
Configure with Well-Known Config

  1. After selecting Configure to open the configuration modal, select Well-Known Config if it isn’t already selected.
  2. Enter the following information associated with your Domo SSO app in your IdP. These values are defined in your IdP, which may use different terminology. Each field is described below to help you understand the purpose of the information and to help you find each value in your IdP, no matter what it’s called.

    Field

    Description

    Well-known config URL

    An endpoint where your IdP publishes key pieces of information instructing Domo how to configure the OIDC integration. The well-known config URL is typically in this format:

    https:/ //.well-known/openid-configuration

    Client ID The client identifier assigned to your Domo OIDC app in your IdP. The client ID should be provided by your IdP.
    Client Secret Used in conjunction with the client ID, the secret allows Domo to make OIDC requests of your IdP. The client secret is highly sensitive and should be treated in compliance with your company’s policies for passwords, secrets, and other sensitive information. The client secret should be provided by your IdP.

​
Configure Manually

If your IdP doesn’t provide a well-known config, you’ll need to manually enter the information that would otherwise be provided by the well-known config.
  1. After selecting Configure to open the configuration modal, select Manual Entry if it isn’t already selected.
  2. Enter the following information associated with your Domo SSO app in your IdP. These values are defined in your IdP, which may use different terminology. Each field is described below to help you understand the purpose of the information and to help you find each value in your IdP, no matter what it’s called.

    Field

    Description

    Authentication request endpoint URL The URL to which Domo will send requests for authentication of the Domo user.
    Token endpoint URL Domo sends token requests to this endpoint.
    Userinfo endpoint URL Domo sends requests for user attributes (claims) to this endpoint.
    Public key The JSON Web Key Set (JWKS), or the URL where it is hosted, Domo uses this key to verify and trust only legitimate tokens from your IdP.
    Client ID The identifier assigned to your Domo OIDC app in your IdP. The client ID should be provided by your IdP.
    Client Secret Used in conjunction with the client ID, the secret allows Domo to make OIDC requests of your IdP. The client secret is highly sensitive and should be treated in compliance with your company’s policies for passwords, secrets, and other sensitive information. The client secret should be provided by your IdP.

​
Information Your IdP May Need

Your IdP may need to know the OpenID Callback URL for your Domo environment. That URL is listed in the section of the configuration modal labeled Information your IdP may need. Open the modal from the SSO configuration settings by selecting Configure / More (three vertical dots icon) > Edit.

​
Additional Settings

Configure the other SSO settings as necessary. These are discussed below.

​
Save the Configuration

After entering the required information and configuring the settings, save the configuration. If OIDC isn’t already enabled, you can choose to save and enable it or save without enabling it.

​
Configure SSO Settings

These settings govern SSO behavior within the Domo instance. They are configured in the OIDC and SAML settings and setting values are independent between SAML and OIDC—that is, configuring a setting in SAML doesn’t affect the equivalent setting in OIDC and vice versa.

Field

Options

Description

Just-in-time user provisioning

Allowed (all domains)

Allowed (authorized domains only)

Disallowed

This setting governs the behavior when a user who does not exist in Domo attempts to log in via SSO. The behavior you choose should be influenced by your use case and the configuration of your IdP.

For example, if your IdP is configured to allow any IdP user to log into Domo, you may want to disallow users from being automatically created in Domo.

On the other hand, if you have a large and dynamic user base and your IdP controls user access to Domo, you may want to allow users to be automatically created in Domo. Learn how to specify authorized domains for invited users.

Important: Particularly important if you allow just-in-time user provisioning, we strongly recommend that your default user role in Domo be a low-privilege role, such as Participant, in alignment with the principle of least privilege. Learn about assigning roles below .
User login experience

Domo Credentials

SSO (Domo auth screen)

SSO (skip to IdP)

This setting governs the user’s experience when navigating directly to Domo. If all Domo users are expected to log in via SSO, you’ll likely want to configure this setting for SSO login (optionally presenting the Domo login screen or skipping the Domo login screen and immediately redirecting to your IdP).

  • Domo Credentials — Choosing this option displays the Domo auth screen, prompting for Domo (not IdP) credentials. Logging in via SSO is still supported, but the SSO flow must be initiated from the IdP. You may want to consider this option if some Domo users aren’t users in your IdP.
  • SSO (Domo auth screen) — Choosing this option displays the Domo login screen with a button to initiate SSO login. If at least one user is on the Direct Sign-on List , the auth screen will also present a link for logging in with Domo (not IdP) credentials.
  • SSO (skip to IdP) — Choosing this option automatically redirects a user to your IdP for SSO login.
Note: If SAML is enabled and SAML “User login experience” is set to “SSO (Domo auth screen)” or “SSO (skip to IdP)”, the Direct Sign-on List is enforced, meaning only users on the Direct Sign-on List (and users with the Admin system role) can log into Domo with their Domo credentials; other users must log in via SSO.

The “User login experience” setting in the OIDC configuration has no effect on enforcement of the Direct Sign-on List.

Even if the login experience doesn’t present the option, users on the Direct Sign-on List and users with the Admin system role can log into Domo with their Domo credentials by navigating to:
https:/ /.domo. com/auth/index?domoManualLogin=true
Logout URL (optional) — The URL users are redirected to when they log out of Domo.
Import groups from identity provider — This setting determines whether Domo directory groups will be created and their membership maintained by the SSO integration. If enabled, users are added to and/or removed from Domo directory groups as required when users log in via SSO. Learn about groups in Domo.
Enable custom attribute ingestion — If enabled, Domo will inherit values for custom Domo user attributes as users log in via SSO. Learn about setting attributes below.
(SAML only) Sign authentication requests —

This setting governs whether Domo signs SAML authentication requests it sends to your IdP.

If your SSO app in your IdP is configured to require authentication request signature verification, you’ll need to enable this AND load Domo’s x.509 signing certificate into your SSO app in your IdP. Domo’s certificate can be downloaded in the section of the SAML configuration modal labeled Information your IdP may need .

(SAML only) Use SAML relay state to redirect — If enabled, Domo will redirect users to the location (such as a specific Domo dashboard or app) specified in the SAML relay state.

​
Enable SSO and Set Defaults

After you’ve configured SAML and/or OIDC, you must enable SSO using the switches in the SSO Configuration tab.
Important: If only one protocol is enabled, it will automatically be the default. If both protocols are enabled, you must specify the default for these two scenarios:
  • Signing into the Domo instance — Select More (three vertical dots icon) > Make default for sign in.
  • Signing in for embed — Select More (three vertical dots icon) > Make default for embed.

​
Set User Role, Attributes, and Group Membership

You can configure SSO to set/update user role, attributes, and group membership based on IdP-specified values as users log into Domo. User attributes in your IdP must be mapped to corresponding ones (identified by their key) in Domo. The following attributes are supported:

Attribute

SAML assertion or OIDC claim

SAML

OIDC

Email

Note: In Domo, the user’s unique identifier is their email address. The value included in the email attribute overrides the SAML Subject value in the SAML assertion.

email email

User Name

Note: For SAML, if name.personal and/or name.family are specified, those values are combined and take precedent over any other value specified in name.

Note: For OIDC, several other claims are supported (preferred_username, given_name, family_name, middle_name, and nickname). However, if the name claim is present, it takes precedence.

name

name

name.personal

Others. See note.

name.family

Role

Note: Domo supports only one role per user. The role value passed to Domo from the IdP must exactly match a role defined in Domo. If just-in-time provisioning is allowed, and if no acceptable role is provided by the IdP, the user will receive the default role for the Domo instance.

Learn about managing roles and the default role .

role Not supported
Secondary Email email.secondary alternate_email
Employee ID employee. id sub

Employee Number

Note: employee. id maps to Employee Number if employee. id is numeric.

employee. id Not supported

Hire Date

Format: YYYY-MM-DD

hire.date hiredate
Title title title
Department department department
Location location location
Mobile Phone user.phone phone_number
Desk Phone desk.phone desk_phone_number

Locale

Valid values: de-DE, de-AT, de-CH, en-AU, en-CA, en-150, en-HK, en-IE, en-IN, en-IL, en-MO, en-NL, en-NZ, en-SG, en-GB, en-US, en-001, es-ES, es-US, es-419, es-MX, fr-BE, fr-CA, fr-FR, fr-CH, nl-BE, nl-NL, pt-BR, pt-PT, ja-JP, zh-CN, zh-Hans-HK,zh-Hans-MO, zh-Hans-SG

locale locale

Time Zone

Valid values: any TZ identifier as defined in the tz database .

timezone zoneinfo

Any custom attribute defined in Domo.

Note : Attributes must be defined in Domo before Domo will accept those attribute values from your IdP. See Attributes .

Key defined for the target attribute Key defined for the target attribute

Directory Groups

Note: The directory group(s) the user is a member of.

groups groups

​
Direct Sign-on List

When enforced, the Direct Sign-on List designates the Domo users who can log into Domo directly with Domo credentials; other users must log in via SSO. The Direct Sign-on List is enforced if SAML is enabled and the SAML “User login experience” is set to “SSO (Domo auth screen)” or “SSO (skip to IdP)”.
Note: Users with the Domo Admin system role can always log in to Domo with their Domo credentials, whether they appear on the Direct Sign-on List or not.
You can configure the Direct Sign-on List in Domo by navigating to Admin > Authentication > Single Sign-On (SSO) > Direct Sign-On List (tab).
Important Notes:
  • Depending on your SSO and Direct Sign-on List configuration, the Domo auth screen may not give the option to log into Domo using Domo credentials. In this state, users on the Direct Sign-on List and users with the Admin system role can log into Domo using Domo credentials by going to:
HTTP s:/ /{ YourSubdomain }.domo. com/auth/index?domoManualLogin=true
  • The Direct Sign-on List is only enforced if SAML SSO is enabled AND the SAML “User login experience” is set to either “SSO (Domo auth screen)” or “SSO (skip to IdP)”. Otherwise, all users can log into Domo with their Domo credentials.