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. In Microsoft Entra ID, go to the Attributes & Claims section and add two claim mappings:

• Name: email
  Namespace (optional): http://schemas.xmlsoap.org/ws/2005/05/identity/claims/email

• Name: name
  Namespace (optional): http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name

As indicated above, the Namespace fields can be left blank.

The Unique User Identifier (Name ID) is the stable value the service provider uses to identify a user across login sessions. Set this to a unique, persistent value in Microsoft Entra (e.g.userprincipalname) to ensure consistent user recognition.

Example mapping section:

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

10. Select Add a group claim.

11. Make sure to choose Groups assigned to the application when defining your scope. That means only groups that are both assigned to the application and include the logging-in user as a member will be included in the SAML assertion.

12. Next, set Cloud-only group display names as the Source attribute. This will send the displayName for each group associated with both the application and the user.
13. Optionally, you can also configure custom settings, such as filtering for groups whose Display name starts with a specific prefix, e.g. Hightouch.

14. 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 SSO mappings tab.

15. On this page, 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.)

16. 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 in Hightouch, follow these steps:

1. Navigate to the SAML SSO application that you created for logging into Hightouch within the Microsoft Entra admin center.
2. Click on the Provisioning tab.

3. To configure SCIM for your application, click Connect your application.

4. Set the Tenant URL to https://api.hightouch.com/api/scim/v2.
5. Paste the SCIM bearer token you generated in Hightouch into the Secret Token field. Test the connection to ensure it's working, then click Save.
6. At this point, SCIM is configured for your application, but it isn't yet enabled. It's also recommended to set up user and group assignments.
7. Cick on the Provisioning tab under the Manage section. This will open a nested Provisioning section where you can configure Users and Groups attribute mappings.

8. Select Provision Microsoft Entra ID Users to configure SCIM attribute mappings for users.
9. A Hightouch user object has three key properties relevant to SCIM provisioning: email, name, and active. During provisioning, these fields should receive their values from the following SCIM Target Attributes:

• emails[type eq "work"].value
• displayName
• active

While it’s technically possible to use other Target Attributes (for example, sending a value for email under userName), doing so isn't recommended. Using the Target Attributes above ensures that user provisioning behaves as expected within Hightouch.

If your Entra configuration meets the following conditions:

• Emails are stored in the mail attribute and are unique.
• Full names are stored in the displayName attribute.
• You want to control user access by enabling or disabling accounts in Hightouch without immediately deleting them.

You should proceed with the following setup:

• First, uncheck the userName field as a required attribute in the Edit attribute list for customappsso section under Show advanced options, and save the change.
• For emails[type eq "work"].value as the Target attribute, use mail as the Source attribute. Set Match objects using this attribute to Yes and set Matching precedence to 1.
• For displayName as the Target attribute, use displayName as the Source attribute as well.
• Leave active as the Target attribute mapped to the Switch([IsSoftDeleted], , "False", "True", "True", "False") formula as the Source attribute.
• Leave the Primary Key settings unchanged.

Example of a valid user attribute mapping configuration:

10. As mentioned earlier, the exact Source attribute configuration depends on how your Entra directory is set up. Once this setup is complete, your User Attributes Mapping section is ready!
11. The Group provisioning section (Provision Microsoft Entra ID Groups) does not require any changes. The default configuration works out of the box. If you want to verify it, ensure that the displayName Target attribute is mapped to the displayName Source attribute, and that Match objects using this attribute is set to Yes with a Matching precedence of 1 for this mapping. Additionally, the members Target attribute should be mapped to the members Source attribute. Optionally, you can delete the externalId (Target attribute) to objectId (Source attribute) mapping.

Example of a valid group attribute mapping configuration:

12. When provisioning groups with members, keep in mind that users added with this process will not automatically receive the intended Hightouch group assignment, as the SSO group mapping between Entra and Hightouch cannot yet exist at provisioning time.

Let’s assume the corresponding Hightouch group already exists. In that case, to ensure the user is correctly assigned to that group in Hightouch:

1. After the initial group-with-members provisioning, set up the relevant Entra → Hightouch SSO group mapping inside Hightouch.
2. Then, have the user log in to Hightouch via Entra using SAML SSO. The group assignment will be applied at that time (assuming the SAML attribute mapping is correctly configured, as per our documentation).

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 Allow inviting users. We typically recommend disabling this when using SSO 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 on.

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.