SSO setup guide

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.

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.

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

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

4. 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.

5. 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.

6. 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.

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

8. 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.

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

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

11. 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.

12. 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.

13. 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 .*.

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

14. 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.

15. 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.)

15. 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.

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.

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

3. Choose SAML as the sign-on method.

4. 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.

5. 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).

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

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

8. 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.

9. 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.

10. Select Add a group claim.

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

12. 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.

13. 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.)

14. 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.

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

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.

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.

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.)

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/.

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.

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