Provision HubSpot users with SCIM through Okta

Provisioning users through SCIM (the System for Cross-domain Identity Management) provides a secure and automated way to create and manage HubSpot users through Okta.

Below, learn how to set up user provisioning through Okta.

Prerequisites

• Single sign-on (SSO) must be enabled in your HubSpot account. 
• It's recommended to set up user permission sets in HubSpot based on your team's Okta Roles before setting up SCIM.
• To set user permissions, you must create permission sets in HubSpot. Okta can then assign permissions to a user if their Role in Okta matches the name of the HubSpot permission set. 
• To verify your domain, you will need to update your DNS records. Ensure you have the login details for your DNS provider and have access to the TXT records.
• Assigning seats will vary depending on whether or not you're on the seats-based pricing model:
  • If you are not on a seats-based pricing model: to assign paid seats for users set up with SCIM, purchase the seats in HubSpot and create a permission set with a paid seat. Navigate back to Okta and set the user's Role to be the same as the permission set.
  • If you are using the seats-based pricing model: you cannot assign seats such as core seats, Sales or Service Hub seats, or view-only seats, based on permission sets assigned in Okta. Before assigning permissions through Okta, you will need to update a user's seat in HubSpot. 

Set up SCIM provisioning

To set up SCIM user provisioning through Okta, you'll need to first add the HubSpot app in Okta, then assign users to the app:

• Log in to Okta.
• In the left sidebar menu, select Applications > Applications, then browse for and add the HubSpot application in your Okta account.
• In the HubSpot application screen, click the Provisioning tab, then click Configure API Integration. 
  
  
• Select the Enable API integration checkbox, then click Authenticate with HubSpot. A new window will open where you can give Okta access to your HubSpot account.
• In the HubSpot window, select which account you want to integrate Okta with, then click Choose account.
• Click Connect app. The window will close, and you'll be directed to the Okta admin console.
• Click Save.
• On the Provisioning tab, select how you want Okta to provision users to HubSpot by clicking Edit.
   
• Select the Enable checkboxes next to Create Users, Update User Attributes, and Deactivate Users to configure the integration.
• Click Save.
• Then, assign users to the HubSpot app.

Verify your domain

After adding the HubSpot app through Okta, you'll need to verify your domain in HubSpot by updating your DNS records. 

• In your HubSpot account, click the settings settings icon in the top navigation bar.
• In the left sidebar menu, navigate to Integrations > Connected Apps.
• Click Okta SCIM.

• In the Domain field, enter your users’ email sending domain.

• Click Save.
• Click Verify it now.

• In the dialog box, select Next.

• Copy the value in the Value column. You’ll then use this value when creating a new TXT record in your DNS provider
• Log in to your DNS provider account, then create a new TXT record for the domain you’re verifying. Paste the value copied from HubSpot into the Value/Points To/Target field. 
• After you've created the TXT record, navigate back to HubSpot, then click Next. Once the DNS changes propagate, the domain will be verified.

Please note: it can take up to 48 hours for the DNS changes to propagate and reflect in HubSpot.

Sync Okta roles with HubSpot permission sets

To set user permissions, you must create permission sets in HubSpot. Okta can then assign permissions to a user if their Role in Okta matches the exact name of the HubSpot permission set, including spaces and caps.

To give Okta access to assign permission sets to users:

• In your HubSpot account, click the settings settings icon in the top navigation bar.
• In the left sidebar menu, click Integrations > Connected Apps.
• Under All apps, click Okta SCIM.
• Toggle Permission Set Management on.

Disable SCIM provisioning

To disable SCIM provisioning in HubSpot, you must uninstall Okta SCIM in HubSpot before making any changes in your Okta account. 

• In your HubSpot account, click the settings settings icon in the top navigation bar.
• In the left sidebar menu, navigate to Integrations > Connected Apps.
• Under the Okta SCIM app, click the Actions dropdown menu, then click Uninstall.
• In your Okta account, users will become editable and will no longer be synced with SCIM.

FAQ

Can users created through SCIM be edited in HubSpot?

Only user permissions can be edited in HubSpot, and only if permission set management is not configured. All other user information, including user name and email address, can only be updated through your identity provider. 

Why is my assigned Okta role not showing up on my user permission set in HubSpot?

You must turn on Permission set management in HubSpot to have Okta roles sync with HubSpot permission sets. The permission set name in HubSpot must match the exact Role name in Okta, including all spaces and caps.

Can Okta assign users to teams?

No. However, after the user is added to HubSpot, you can update their team manually in HubSpot.

What happens if I delete a SCIM user in HubSpot or Okta?

Deleting a user in HubSpot will not delete the user in Okta. However, if you remove a user's access to HubSpot from Okta, or deactivate their account in Okta, the user will be deactivated in HubSpot as well. Adding a user to HubSpot will not add the user to Okta.

What happens to existing users in my HubSpot account when I connect Okta?

After setting up SCIM through Okta, any existing HubSpot users that match users in Okta will automatically be converted to SCIM users. HubSpot will attempt to assign the user a permission set based on their Role in Okta. If the user does not have a role in Okta that matches a permission set in HubSpot, the user will have only minimal permissions in HubSpot. 

I'm seeing the error "This domain couldn't be verified", how do I fix this?

If you are seeing this error, ensure your domain has been entered correctly with no spelling mistakes. Also, check that you have copied the correct value for the TXT record from the Configuration step in HubSpot into your DNS provider.