> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hightouch.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SSO and SCIM

> Hightouch helps customers manage access control for large organizations via a third-party identity provider.

> [!NOTE]
>
> SAML single sign-on and SCIM are only available on [Business tier plans](https://hightouch.com/pricing).

## 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 (JIT) provisioning during login.
* **SCIM** automates user management tasks such as group assignments and deactivations based on changes in the identity provider.

> [!TIP]
>
> 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.

### Identity model and trust boundaries

* SSO is configured at the **organization level** in Hightouch. This means all workspaces in that organization inherit the same SAML trust and access model.
* Hightouch supports one SAML IdP trust per organization at a time. Updating IdP metadata (like issuer, certificate, or IdP SSO URL) updates that trust for the entire organization.

## Configuring SAML SSO

SAML single sign-on (SSO) enables just-in-time (JIT) 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](https://app.hightouch.com/login?from=docs) 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](#okta) and [Microsoft Entra ID](#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](https://www.youtube.com/watch?v=O1cRJWYF-g4).

> [!WARNING]
>
> Keep your SAML NameID stable over time, especially during IdP migrations or
> tenant changes. If the NameID format or source value changes (for example,
> from `email` to an employee ID or UUID), users may be created as duplicate
> identities in Hightouch.

### Okta

The first step is to create a new SAML application in Okta. You can follow [this guide](https://help.okta.com/oag/en-us/Content/Topics/Access-Gateway/add-app-saml-pass-thru-add-okta.htm) or the steps outlined below:

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

![App creation in Okta](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/security/security-sso-okta-create-application.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=fa27bc8b599c4ccaa879f5dffdefcf41)

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

![App creation in Okta](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/security/security-sso-okta-saml-selection.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=95d56fbed46bda8a06e87ae422d2df49)

3. Give the application a descriptive **App Name**, such as "Hightouch." You can also add the [Hightouch logo](https://cdn.sanity.io/images/pwmfmi47/production/acbc037f008ebc7c51a8ba6ca32db440aec03ee2-1600x1600.jpg) if you'd like. Then, click **Next**.

![Okta SAML integration general settings](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/security/security-sso-okta-name-app.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=d908c1905371245b0d6ff5a705b894c0)

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

![Hightouch SSO Connection settings](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/security/security-sso-modal.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=d2b3f50d46ce22c5606b112cf1a51571)

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.

![Okta SAML settings](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/security/security-sso-okta-settings.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=8b0ec5c4da2f19a81a2d585e08c014b8)

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](https://developer.okta.com/docs/reference/api/users/#default-profile-properties) if needed. Click **Next** to continue.

![Okta attribute statements](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/security/security-sso-okta-attr-mappings.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=b411766a64e5146f610ec9d08d008368)

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.

![Okta IdP SSO URL and certificate](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/security/security-sso-url-and-certificate.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=2f52a469f3c394414a73fc9ff12c78c3)

9. 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](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/security/security-sso-modal-2.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=4af0ecb4aac226eadd2f19305d077bb3)

10. 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](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/security/security-sso-okta-assignments.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=13dd5912f327c754b01781a0fce3fb97)

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.

> [!WARNING]
>
> 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.

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.

![Edit settings in the Okta UI](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/security/security-okta-edit-saml.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=42456a71dd92f5c91798ff13f921fadb)

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

![Setting the group attribute name to "groups" in the Okta UI](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/workspace-management/permissions/okta-group-attribute.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=f4f58698593b698d5f5de59441bd6e11)

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](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/workspace-management/permissions/okta-group-attribute-2.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=a0a947e6e439af1555af83feb2ff100f)

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

![Group mappings](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/workspace-management/permissions/sso-group-mappings.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=d37e84c0acfe10d96a7077ca379419d0)

> [!WARNING]
>
> 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](#configuring-scim).

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.

![Single sign-on link](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/security/security-sso-hightouch-link.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=055083c28bd19d7da92f789a3fdf519e)

### 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](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/security/security-sso-azure-create-app.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=f59c0fe9a8acbf8f34b3edcbfe71d069)

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

![Azure single sign-on setup](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/security/security-sso-azure-set-app-sso.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=d282c8b8507db89a97a334756271d9ba)

3. Choose **SAML** as the sign-on method.

![Azure single sign-on methods](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/security/security-sso-azure-select-SAML-sso.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=60046910cc20eb2a9ea1565114c1b200)

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

![Hightouch SSO Connection settings](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/security/security-sso-modal.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=d2b3f50d46ce22c5606b112cf1a51571)

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

> [!NOTE]
>
> Leave the **Sign on URL** field empty if you plan to use IdP-initiated
> sign-on. Alternatively, grab the value from the **Hightouch login URL** field
> in Hightouch and enter it here.

![Azure basic SAML configuration](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/security/security-sso-azure-basic-SAML-config.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=5489c87a4814e587a5a5aea1c17d2439)

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:

![Azure required claims and values](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/security/entra_attributes_mappings_final.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=488f339aab1b15caf9128b466ab23672)

> [!NOTE]
>
> The **Source attributes** you choose for the `name` and `email` claims will
> depend on your Entra configuration; in the example above, the `displayname`
> attribute contains the user's **full name**, while the `mail` property
> contains their **work email**.

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

![Azure AD certificate](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/security/security-sso-azure-settings-to-ht.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=3cd8fd50d60a942d5723eefc46218830)

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.

> [!WARNING]
>
> 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.

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.

> [!WARNING]
>
> If you select a different option, you won’t be able to use `Cloud-only group
>     display names` as the **Source attribute** - this attribute is required to
> sync human-readable group names to Hightouch, as described in the [Entra
> documentation](https://learn.microsoft.com/en-us/entra/identity/hybrid/connect/how-to-connect-fed-group-claims#emit-cloud-only-group-display-name-in-token).

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

![Group SAML mapping](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/security/group_saml_attributes.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=8987444351a6bbf67ea4540e130345ce)

> [!NOTE]
>
> For on-premises or hybrid Entra setups, you can emit group claims in two ways.
> For on-premises groups, select an on-premises source attribute such as
> `sAMAccountName`, and enable **Emit group name for cloud-only groups** so
> cloud-only groups send their display name (see the screenshot below). You can
> also emit `Group ID` for both group types. Entra group object UUIDs then
> appear in the **SSO group from identity provider** section of **SSO
> mappings**. Learn more in the [Entra
> documentation](https://learn.microsoft.com/en-us/entra/identity/hybrid/connect/how-to-connect-fed-group-claims?WT.mc_id=AZ-MVP-5003833#emit-cloud-only-group-display-name-in-token).

![hybrid group mapping](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/security/onpremise_cloud_group_attributes.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=2214a568e1761e4e7f03a81dd73b8659)

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

![Group mappings](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/security/sso_mappings.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=f29666cc2d10ebba716852d9e3f425db)

> [!WARNING]
>
> 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](#configuring-scim).

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.

![Single sign-on link](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/security/ht_login_url.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=6678f1e48dab0141a7a8a377d3ee7e04)

> [!NOTE]
>
> Regardless of your exact Entra configuration, make sure that your Entra SAML
> user and group attribute mappings are aligned with your Entra SCIM user and
> group attribute mappings.

### Other identity providers

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

The setup instructions are generally similar to those for Okta. [Contact support](#pylon-chat) if you run into issues.

## Configuring SCIM

> [!NOTE]
>
> You must [configure SAML SSO](#saml-single-sign-on) 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.

> [!WARNING]
>
> 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](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/workspace-management/permissions/assignments-groups.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=83144949b4d9f1947a910e67c48201ce)

> [!NOTE]
>
> For additional information, or if your Okta admin panel differs from the steps
> above, please refer to [Okta's documentation on SCIM
> provisioning](https://help.okta.com/en-us/content/topics/apps/apps_app_integration_wizard_scim.htm?cshid=ext_Apps_App_Integration_Wizard-scim).

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

![Provisioning tab within SAML app](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/security/provisioning_tab_scim.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=26826b7bb62455526086a977435afb52)

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

![How to configure SCIM for your SAML app](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/security/configure_scim.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=947bde14026b4ff81fed9fa44a0afe28)

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.

![SCIM attribute provisioning](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/security/scim_attribute_provisioning.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=460bda727a4b3feb44c40b52ade05810)

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**:

![SCIM attribute provisioning](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/security/exampleUserMapping.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=90c36187139a894f95f3dac35de66f78)

> [!NOTE]
>
>  
>
> You can read more about SCIM with Entra - including the `active` / `IsSoftDeleted`
> behavior, and the meaning of **Match objects using this attribute**, **Matching
> precedence**, and **Primary Key** - in the [official Microsoft documentation](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/customize-application-attributes). 

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**:

![SCIM attribute provisioning](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/security/exampleGroupMapping.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=36fcdeb8dcf40d986a5e89c2cf0bfca0)

> [!NOTE]
>
> As with the earlier example of the SAML group attribute configuration, this
> example SCIM setup is also optimized for a cloud-only Entra group environment;
> for an on-premises or hybrid group setup that includes both **on-premises
> groups synced to Entra** and **cloud-only groups in Entra**, you need to
> ensure that the **Source attribute** selected during SCIM provisioning for the
> `displayname` **Target attribute** fits your Entra configuration and also
> **aligns with your SAML attribute mapping**.

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](https://docs.hightouch.com/workspace-management/sso.md#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 for Okta. [Contact support](#pylon-chat) if you run into issues.

## Rollout, migration, and diagnostics best practices

These recommendations help reduce lockouts and access regressions during new SSO deployments, IdP migrations, and certificate rotations.

### Before rollout

* Use the **exact** Hightouch values for **SSO URL** and **Audience URI** from the SSO modal. Even minor typos can cause login loops.
* Plan your IdP group taxonomy and mapping strategy before production rollout.
* During initial validation, keep default access minimal and temporary until group mappings are verified.

### During migration or cutover

1. Recreate your SAML app in the new IdP/tenant with the same **Audience URI**, **NameID format/source**, and required claim mappings.
2. Update Hightouch with the new IdP SSO URL and signing certificate.
3. Generate a new SCIM token and connect SCIM in the new IdP app before disabling SCIM in the old app.
4. Validate with a small pilot (2-3 users), then expand to a full rollout.

> [!TIP]
>
> Keep an admin validation path during cutovers, for example by testing in a
> separate browser session before organization-wide rollout.

### Diagnostics

* Test in an incognito/private window to avoid cached session effects.
* Use a SAML tracer tool to inspect incoming NameID and group claims.
* If users can authenticate in your IdP but have no workspaces, verify SSO group mappings and that expected groups have been sent to Hightouch.

> [!WARNING]
>
> SSO disable/rollback is not self-serve in the app. If you need emergency SSO disablement
> for recovery, contact [Hightouch support](#pylon-chat).

## 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](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/security/security-sso-hightouch-link.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=055083c28bd19d7da92f789a3fdf519e)

### 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](#saml-single-sign-on)).

### 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](#okta-saml-sso-configuration) for more detailed steps.
* Ensure you used the correct Hightouch SAML URL and audience URL provided in your [dashboard](https://app.hightouch.com/settings/sso?from=docs).

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](https://app.hightouch.com/settings/sso?from=docs).

### 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](#okta-saml-sso-configuration) 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 doesn't affect workspace-owned resources like syncs, models, sources, and destinations.

However, [API keys](https://docs.hightouch.com/developer-tools/api-guide.md) stop working when the user who created them is deleted or loses workspace access. Before deleting the original non-SSO user, check whether they created any API keys, create replacements as the new SSO user, and update any integrations that use the old keys.

### 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](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/security/okta-provisioning.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=f9680bc96936c77a096dc6a5186b3300)

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