You can configure Gtmhub to automatically create and deactivate users whenever they are provisioned and deprovisioned from the application in your Identity Provider. What's more, you can configure each user's first name, last name, manager, and team to be automated from the IdP.

Configure SCIM with Gtmhub

Issue a SCIM token

The Gtmhub SCIM server expects a Bearer token in the request header to authenticate and authorize the provisioning operations. You must issue a SCIM token from your Gtmhub account and use it when setting up provisioning in your IdP. Follow the below steps:

  1. Navigate to Settings, then go to API Tokens on the left-hand menu.

  2. Click on 'Issue token'.

    1. Give your token a name (so you can distinguish which app is integrated via it later)

    2. and then select SCIM from the dropdown.

Once ready with the token, click on the masked portion it to copy the value

Use the SCIM token when setting up SCIM authentication in your Identity Provider.

Provide your account-specific SCIM URL

When configuring provisioning in your IdP you will need to provide your Gtmhub account SCIM URL (also referred to as SCIM Connector Base URL). Its value is specific to your Gtmhub account and the Data center your account is located in. Follow these steps:

  1. Navigate to Settings, then go to API Tokens on the left-hand menu.

  2. Copy your Account ID

  3. Construct your account-specific SCIM URL by replacing {Account ID} below with the value you copied in step 1 above

    1. If your Gtmhub account is in EU (its URL follows the pattern https://accountDomain.gtmhub.com) your SCIM URL is https://app.gtmhub.com/api/v1/scim/azure/{Account ID}

    2. If your Gtmhub account is in US (its URL follows the pattern https://accountDomain.us.gtmhub.com) your SCIM URL is https://app.us.gtmhub.com/api/v1/scim/azure/{Account ID}

    3. If your Gtmhub account is in Asia (its URL follows the pattern https://accountDomain.as.gtmhub.com) your SCIM URL is https://app.as.gtmhub.com/api/v1/scim/azure/{Account ID}

    4. If your Gtmhub account is in South America (its URL follows the patternhttps://accountDomain.sa.gtmhub.com) your SCIM URL is https://app.sa.gtmhub.com/api/v1/scim/azure/{Account ID}

Configure SCIM mappings

Gtmhub SCIM server supports the following user fields:

Name

Map to

Description

userName

Your IdP user email

Required. User to identify or create a user in Gtmhub

active

A property of your IdP user indicating whether they are active

Optional. Activates/Deactivates a user in Gtmhub. Must be boolean value.

givenName

Your IdP user first name

Optional. Sets the given name in Gtmhub

familyName

Your IdP user last name

Optional. Sets the family name in Gtmhub

photos

Your IdP user profile picture URL

Optional. Sets the profile picture URL.

manager

Your IdP user linked manager

Optional. Used to set the teams hierarchy if org chart provisioning is enabled(see below)

department

Your IdP user department

Optional. Used to set the team name if org chart provisioning is enabled (see below)

You can see a full reference of the supported fields by the Gtmhub SCIM by navigating in your browser to your account-specific SCIM Schema URL. The SCIM schema URL for your account is your SCIM Tenant URL with /schemas appended at the end.

For example, if your SCIM Tenant URL is https://app.gtmhub.com/api/v1/scim/azure/{Account ID}, your SCIM Schema URL: is https://app.gtmhub.com/api/v1/scim/azure/{Account ID}/schemas

Configure org structure provisioning

You can specify whether when a new user is provisioned via SCIM in Gtmhub they are assigned to a team. Follow these steps:

  1. Navigate to the SCIM Provisioning tab in the left-hand navigation

  2. In Create teams, choose which field should the system use to do so.

    1. If you choose Department, Gtmhub will use the name of the department field configured in your IdP SCIM mappings and create a team with that name. So in practice, when that mode is enabled Department is equal to a Team in Gtmhub. Note that when Department mode is enabled, we're still using the Manager field value to create the team in hierarchy. We only use the Department name to name the team in Gtmhub.

    2. If in your Identity Provider org structure you have multiple people that have the same department, but there's a hierarchical relationship between them and they have teams on their own, it's better to select the Manager option. When this option is selected, Gtmhub will create (or map) a team with that same Department name and will then use the manager field to create sub-teams that will be called '{Department name} - {User Names}'. E.g. the final result would look like this: the parent team would be 'Sales', and then a sub-team would be 'Sales - John Harrison'.


Integrating with your HCM system

In practice, you can instrument your IdP to sync team names from your HCM system into the Department field, which will then sync to Gtmhub. Alternatively, you can create a custom attribute in your AD and sync team names from your HCM into it. You can then configure in the attribute mappings this field to map to teams in Gtmhub.

If you are using Workday as your HCM, you can integrate Gtmhub directly with it so that the team hierarchy in Gtmhub is managed directly from the source. For more information, please refer to How to Connect Workday.

Did this answer your question?