Search documentation...

K
ChangelogBook a demoSign up

SSO setup guide

SAML single sign-on and SCIM are only available on Business tier plans.

Overview

Hightouch integrates with identity providers like Okta and Microsoft Entra ID to simplify user management and authentication.

  • SAML SSO enables users to authenticate through their organization’s identity provider, supporting just-in-time provisioning during login.
  • SCIM automates user management tasks such as group assignments and deactivations based on changes in the identity provider.
Need help with SSO or SCIM setup? Share this page with your IT team.

Required permissions

To configure these integrations, you'll need the following:

  • Admin access to your company's identity provider, which is typically managed by your IT team.
  • User membership in the Organization admins group within your Hightouch organization.

Configuring SAML SSO

SAML single sign-on (SSO) enables just-in-time provisioning so that Hightouch users are automatically created upon first login. Once SSO is set up, users in your organization can navigate to the Hightouch login page and select Log in with SSO to authenticate with your identity provider.

When a user attempts to log in, Hightouch sends a SAML authentication request to your identity provider. If the identity provider validates the user’s credentials and confirms that the user is authorized to access Hightouch, the user is logged in. For first-time users, an account is automatically provisioned based on the information returned from the identity provider, such as name and email address. SSO also ensures that user attributes (like email addresses) are updated during login when changes are detected.

Configuration steps for SAML SSO may vary depending on the identity provider used. Below are detailed instructions for setting up SAML with Okta and Microsoft Entra ID (formerly known as Azure Active Directory). For other identity providers, similar configuration will apply.

For an overview of SSO and SAML concepts, refer to this introductory video.

Okta

The first step is to create a new SAML application in Okta. You can follow this guide or the steps outlined below:

  1. In your Okta dashboard, navigate to Applications and select Create App Integration.

App creation in Okta

  1. Choose SAML 2.0 as the sign-in method and click Next.

App creation in Okta

  1. Give the application a descriptive App Name, such as "Hightouch." You can also add the Hightouch logo if you'd like. Then, click Next.

Okta SAML integration general settings

  1. In Hightouch, visit the Single sign-on tab on the Organization settings page. Click Configure SAML SSO to display a modal that provides the Hightouch SSO URL and Audience URI.

Hightouch SSO Connection settings

  1. In Okta, configure the SAML settings by entering the Hightouch SSO URL from the Hightouch modal as the Single sign on URL, and the Audience URI as the Audience URI (SP Entity ID). You can leave the remaining fields at their default settings.

Okta SAML settings

  1. Under Attribute Statements, map the name and email attributes. For instance, you might map name using String.join(" ", user.firstName, user.lastName) and email as user.email. Ensure that these match the properties defined in your Okta instance. You can refer to the Okta user profile properties if needed. Click Next to continue.

Okta attribute statements

  1. For the prompt Help Okta Support understand how you configured this application, select I'm an Okta customer adding an internal app. Click Finish.

  2. Then, you’ll be taken to the application overview page in Okta. Under Metadata details, click More details, then copy the Sign on URL and download the Signing Certificate. These will be needed for Hightouch.

Okta IdP SSO URL and certificate

  1. In the Hightouch modal from step 4, paste the Identity provider SSO URL and upload the certificate. Click Save to finalize the connection.

Hightouch SSO Connection settings

  1. In Okta, go to the Assignments tab of the application you just created. Assign users or groups to grant them access to Hightouch.

Okta Assignments

  1. At this point, you've completed the basic SAML SSO setup, allowing your users to log in to Hightouch through Okta. However, you'll still need to manually assign permissions for each user after they join your Hightouch organization. To streamline this process, we highly recommend setting up automatic group assignments in Okta. This ensures users have the right access to workspaces and resources as soon as they log in for the first time.

If SSO group mappings are not configured, new users won't be automatically assigned to any group, which may result in limited access until group assignments are manually set up.

  1. To configure group mappings, navigate to the General tab for your Hightouch application in Okta and click the Edit button in the SAML Settings section.

Edit settings in the Okta UI

  1. Scroll down to the Group Attribute Statements section. Set the attribute name to groups and apply the appropriate filter. For instance, to make all Okta groups available in Hightouch, select the Matches regex filter and enter .*.

Setting the group attribute name to "groups" in the Okta UI

If you want to send only specific groups, you can either map them individually or use a filter like Starts with Hightouch.

Setting group filters in the Okta UI

  1. Next, you'll want to go back to Hightouch and create mappings between the groups from your identity provider and the corresponding user groups in Hightouch. Navigate to Organization settings and click on the Single sign-on tab.

  2. Scroll to the bottom section called Group mappings. In this table, each group from your identity provider can be mapped to any number of user groups in Hightouch. (Users can belong to multiple groups, and when they do, they inherit the combined access from all of their assigned groups.)

Group mappings

Group assignments are refreshed only when a user logs in. This means that new SSO groups will not appear for mapping until after a member belonging to that group has logged into Hightouch. If you need to synchronize users and groups without requiring login, consider enabling SCIM.

  1. All done! Members of your organization can access Hightouch by selecting Log in with SSO. You can also share your workspace's direct Hightouch login URL, which is available in the Single sign-on tab on the Organization settings page.

Single sign-on link

Microsoft Entra ID

  1. In the Microsoft Entra admin center, go to the Enterprise applications screen and select New application, then click Create your own application.

Azure AD App creation

  1. In your newly created app, select Set up single sign on.

Azure single sign-on setup

  1. Choose SAML as the sign-on method.

Azure single sign-on methods

  1. In Hightouch, open the Single sign-on tab in the Organization settings page. Click Configure SAML SSO to display a modal with the Hightouch SSO URL and Audience URI.

Hightouch SSO Connection settings

  1. Configure the SAML settings in Microsoft Entra ID by entering the Hightouch SSO URL as the Reply URL (Assertion Consumer Service URL) and the Audience URI as the Identifier (Entity ID).

Leave the Sign on URL field empty if you plan to use IdP-initiated sign-on.

Azure basic SAML configuration

  1. Set attribute mappings for name and email in Microsoft Entra ID, if they aren't already configured.

Azure required claims and values

  1. In the Hightouch modal from step 4, enter Microsoft Entra ID's Login URL as the Identity provider SSO URL, and upload the Certificate Base64 as the x.509 certificate in Hightouch. Then, click Save.

Azure AD certificate

  1. At this point, you've completed the basic SAML SSO setup, allowing your users to log in to Hightouch through your identity provider. However, you'll still need to manually assign permissions for each user after they join your Hightouch organization. To streamline this process, we highly recommend setting up automatic group assignments. This ensures users have the right access to workspaces and resources as soon as they log in for the first time.

If SSO group mappings are not configured, new users won't be automatically assigned to any group, which may result in limited access until group assignments are manually set up.

  1. In the Microsoft Entra admin center, go to Enterprise applications and select the Hightouch application you created earlier. Navigate to Single Sign On configuration and then click on Attributes & Claims.

  2. Select Add a group claim.

  3. Choose Groups assigned to the application and set Group ID as the Source attribute.

If you want the group to include the group display name for cloud-only groups, select Cloud-only group display names as the Source attribute.

  1. Next, you'll want to go back to Hightouch and create mappings between the groups from Microsoft Entra and the corresponding user groups in Hightouch. Navigate to Organization settings and click on the Single sign-on tab.

  2. Scroll to the bottom section called Group mappings. In this table, each group from your identity provider can be mapped to any number of user groups in Hightouch. (Users can belong to multiple groups, and when they do, they inherit the combined access from all of their assigned groups.)

Group mappings

Group assignments are refreshed only when a user logs in. This means that new SSO groups will not appear for mapping until after a member belonging to that group has logged into Hightouch. If you need to synchronize users and groups without requiring login, consider enabling SCIM.

  1. All done! Members of your organization can access Hightouch by selecting Log in with SSO. You can also share your workspace's direct Hightouch login URL, which is available in the Single sign-on tab on the Organization settings page.

Single sign-on link

Other identity providers

Hightouch supports all major identity providers, including OneLogin, Rippling, Google, Ping, and more.

The setup instructions are generally similar to those provided above for Okta. If you encounter any issues or need assistance, please don't hesitate to reach out to our support team—we're here to help!​

Configuring SCIM

You must configure SAML SSO before configuring SCIM.

Unlike SAML SSO, which creates and updates user accounts only when users log in, SCIM automatically synchronizes user account changes from your identity provider to Hightouch without requiring user login. This means that adding, updating, or deactivating user accounts in your identity provider happens in the background and is immediately reflected in Hightouch.

To get started, generate a SCIM API token by following these steps:

  1. Visit the Organization settings page in Hightouch and navigate to the Single sign-on tab.
  2. Click Generate SCIM token.
  3. Copy the generated bearer token and click Save to activate the token.

Hightouch displays the SCIM token only once, immediately after you generate it. Once you close the modal, you won't be able to access the same token again. If you don't copy it when it's first displayed, you'll need to generate a new token by clicking Refresh SCIM token.

Okta

After generating your SCIM token, follow these steps:

  1. Navigate to the Hightouch application within your Okta admin panel.
  2. On the General tab, locate the App Settings section and click the Edit button.
  3. Check the box labeled Enable SCIM provisioning, then click Save.
  4. Move to the Provisioning tab and click Edit in the SCIM Connection section.
  5. Enter https://api.hightouch.com/api/scim/v2 as the SCIM connector base URL.
  6. Enter userName as the Unique identifier field for users.
  7. Under Supported provisioning actions, ensure that the following options are selected:
    • Import New Users and Profile Updates
    • Push New Users
    • Push Profile Updates
    • Push Groups
  8. Set the Authentication Mode to HTTP Header.
  9. Paste the SCIM bearer token you generated in Hightouch into the authentication field, ensuring it includes the Bearer prefix.
  10. Click Save to complete the configuration.
  11. Finally, make sure to assign the relevant users and groups to the Hightouch application. In Okta, you must do this from both the Assignments tab and the Push Groups tab.

SCIM provisioning

For additional information, or if your Okta admin panel differs from the steps above, please refer to Okta's documentation on SCIM provisioning.

Microsoft Entra ID

After generating your SCIM token, follow these steps:

  1. Navigate to the Hightouch application within the Microsoft Entra admin center.
  2. Go to the Provisioning tab and click Get Started.
  3. For Provisioning Mode, set to Automatic.
  4. Enter https://api.hightouch.com/api/scim/v2 as the Tenant URL.
  5. Paste the SCIM bearer token you generated in Hightouch into the Secret Token field. Click Save.
  6. Configure mappings and assign user groups to the Hightouch application. (The exact steps steps may vary depending on how your organization uses Microsoft Entra ID.)

For additional information, or if your admin center differs from the steps above, please refer to Microsoft's documentation on SCIM provisioning and group assignment.

Other identity providers

Hightouch supports all major identity providers, including OneLogin, Rippling, Google, Ping, and more.

The setup instructions are generally similar to those provided above for Okta. If you encounter any issues or need assistance, please don't hesitate to reach out to our support team—we're here to help!

FAQ

Where can I find my organization identifier to log in with SSO?

After setting up SSO, you can share your workspace's direct Hightouch login URL, which is available in the Single sign-on tab on the Organization settings page.

The organization identifier is the part that appears after /sso/.

Single sign-on link

I've enabled SSO in my workspace—how do I invite the rest of my team?

Once SSO is enabled, users no longer need a direct invitation to join your Hightouch organization. When they log in through your identity provider for the first time, Hightouch will automatically create an account for them.

How do I allow or disallow non-SSO logins?

Go to the Single sign-on tab in the Organization settings screen. Here, you'll find a toggle labeled Enforce SSO login for everyone. We typically recommend enabling this setting to ensure that all users in your organization are managed through your central identity provider.

However, there may be situations where you'd want to allow non-SSO logins for external users, such as contractors or consultants. In these cases, you might choose to leave the setting off.

When trying to login, I get redirected to app.hightouch.com/login.

If you see the Log in to Hightouch page instead of your Hightouch workspace after logging in with SSO, you need to make sure your IT team has appropriately set the Audience URI when configuring SAML SSO for login).

I don't see any workspaces after accepting an invitation.

There are a few possible reasons for this:

  • If your workspace uses SSO, you shouldn't need to accept an invitation. Instead, use your organization's dedicated login link (shared with you directly or accessible through your identity provider). This ensures that you're logging in to the correct organization.
  • If you land on the Welcome to Hightouch page, you may have accidentally created a separate Hightouch account. Keep in mind that Log in with Google and Log in with Microsoft do not connect to your company's central identity provider. To access your company's organization, be sure to select Log in with SSO.
  • Confirm with your team that your account is mapped to at least one user group in Hightouch. Group assignments might be automatically inherited from your identity provider. Without being part of a user group, you won't have access to any workspaces.

When I log in to Hightouch after configuring SSO, I am shown an error on the log in page.

In your SAML configuration:

  • Check that you have mapped attributes for name and email. See the SSO setup instructions for more detailed steps.
  • Ensure you used the correct Hightouch SAML URL and audience URL provided in your dashboard.

If you made changes to the SAML app in your identity provider between uploading your self-serve SAML settings, you can try to re-generate a certification and upload the new app settings on the Hightouch SSO tab.

I see an error when logging into Hightouch after configuring SSO.

In your SAML configuration:

  • Verify that the attributes for name and email are correctly mapped. Refer to the SSO setup instructions for detailed guidance.
  • Make sure you are using the correct Hightouch SSO URL and Audience URI when configuring SAML SSO in your identity provider.

If you made changes to the SAML app in your identity provider after uploading your self-serve SAML settings, try re-generating a certificate and uploading it again.

I see a duplicate user in Hightouch after logging in for the first time with SSO.

This is expected. SSO users are treated as separate from non-SSO users, so it's possible to have two users with the same email address (but different login methods). If you no longer need the original non-SSO user, you can manually delete it. This will not affect existing syncs or other resources.

I don't see any groups on the SSO tab of my dashboard.

You will only see groups and their mapped roles on your SSO tab if your identity provider has been configured to send the groups attribute. Users may need to log out and log back in for changes to take effect.

My group was updated in my organization's identity provider, but I still belong to the same group in Hightouch.

You will need to log out and log back in for changes to take effect.

Why can't I remove certain group assignments in the Hightouch app?

Group assignments inherited from your identity provider cannot be overridden. However, you can still manually add additional users beyond those assigned by your identity provider.

I see a "Matching user not found" error when adding users after enabling SCIM.

When SCIM is enabled, your identity provider needs to be configured to create users in Hightouch. For example, in Okta, you must go to the Provisioning tab and ensure your Hightouch integration app has permissions to Create Users, Update User Attributes, and Deactivate Users.

Configure SCIM settings in the Okta UI

Once these settings are updated, delete any users showing the "Matching user not found" error and re-add them.

Ready to get started?

Jump right in or a book a demo. Your first destination is always free.

Book a demoSign upBook a demo

Need help?

Our team is relentlessly focused on your success. Don't hesitate to reach out!

Feature requests?

We'd love to hear your suggestions for integrations and other features.

Last updated: Oct 7, 2024

On this page

OverviewRequired permissionsConfiguring SAML SSOOktaMicrosoft Entra IDOther identity providersConfiguring SCIMOktaMicrosoft Entra IDOther identity providersFAQWhere can I find my organization identifier to log in with SSO?I've enabled SSO in my workspace—how do I invite the rest of my team?How do I allow or disallow non-SSO logins?When trying to login, I get redirected to app.hightouch.com/login.I don't see any workspaces after accepting an invitation.When I log in to Hightouch after configuring SSO, I am shown an error on the log in page.I see an error when logging into Hightouch after configuring SSO.I see a duplicate user in Hightouch after logging in for the first time with SSO.I don't see any groups on the SSO tab of my dashboard.My group was updated in my organization's identity provider, but I still belong to the same group in Hightouch.Why can't I remove certain group assignments in the Hightouch app?I see a "Matching user not found" error when adding users after enabling SCIM.

Was this page helpful?