Home Administration Popular SCIM Provisioning: Okta

Table of Contents

Was this article helpful?

Yes No

Thank you for your feedback!

SCIM Provisioning: Okta

In this article you'll learn:

  • Complete steps for setting up Okta SCIM provisioning for Heap
This doc is for: Admins

Overview

This feature is only available to customers on the Premier plan. To upgrade, contact your Customer Success Manager or sales@heap.io.

Features

SCIM provisioning allows you to:

  • Create users in Heap
  • Update users in Heap
  • Remove users in Heap
  • Create teams and add users to teams in Heap via Okta’s Group Push

All from Okta’s UI.

Okta offers ease of access, the ability to quickly block credentials for departed team members, multi-factor authentication, and more.

Prerequisites

To set up SCIM provisioning with Okta, you’ll need to have the following:

  • An existing Okta SSO configuration
  • Admin access to your organization’s Heap account
  • Administrator rights in your organization’s Okta account

If you set up your Heap application in Okta prior to April 2022 you will need to delete your existing Okta configuration and then create a new application using the instructions above in order to enable SCIM in your account.

Setup

Note that once SCIM provisioning is enabled, you’ll be unable to add or remove teammates in Heap and can only add or remove them via Okta.

To set up SCIM provisioning via Okta, complete these steps:

1. Login to your Okta account

2. Click Admin

3. Click the Heap application

4. In the Sign On tab, ensure that Application username format is set to Email

5. Go to the Provisioning tab and click Configure API Integration

6. In Heap, go to Account > Manage > Account settings

7. Click Enable SCIM Provisioning in the Single Sign-On section

8. Select the role you would like new users to be given by default. This can be edited later and individual users can be given different roles after they have been added to Heap.

9. Copy the Bearer Token

10. In Okta, toggle Enable API Integration and paste the Bearer Token into the API Token field, then click Save

11. In the Provisioning Section, click on the To App tab and click Edit. Then enable the SCIM functionality you’d like to support. It’s recommended that you toggle all three options. Then click Save.

SCIM provisioning has now been enabled. Assigning new users to Heap in Okta will automatically create their account and revoking access will automatically delete their account.

Tips and Troublehsooting

  • Deactivating a user in Okta will result in the user being removed from Heap. When the user is reactivated their account will be recreated in Heap.
  • If a user already has a Heap account outside your organization, they’ll need to delete their account and have their account re-made in the correct organization.
  • We don’t currently support updating a user’s email or Okta userName once it’s been set. Trying to update a user’s email will result in a new, separate account being created for the new email.

Managing teams from Okta

To link a team in Heap with a group in Okta, complete these steps:

1. If you do not already have a group in Okta you’d like to link with a team in Heap, navigate to the Groups pane, click Add Group, and fill out the form to create your group.

2. In your Heap application in Okta, select Push Groups and click Refresh App Groups.

3. Click Push Group and enter the name of the group.

4. Click Create Group. If you have an existing team in Heap you would like to link this group to, select Link Group and enter the name of the team in Heap. If you would like to create a new team, select Create Group.

5. Click Save.

Your group in Okta and your team in Heap are now linked. Any users you add to the group in Okta who are also assigned to your Heap application will be added to the team in Heap.

You can add users to the group from the Groups section by clicking on a group and clicking Assign People in the People tab. You can also assign the whole group the have access to Heap in the Applications tab if you would like everyone added to the group to be provisioned automatically in Heap as well.

Managing user roles from Okta

By default all users will be assigned to the default role you selected when setting up SCIM provisioning. However, you can also assign roles to users using the Heap Role parameter in the Provisioning -> To App tab in Okta.

If a user has a value for this parameter, then their account will be given that role in Heap. If they don’t have a value for this parameter or this parameter is disabled, then they’ll be given the default role.

The Heap Role should exactly match the name of the role in Heap that you want to assign to the user. If this value is updated in Okta, the user’s role will also be updated in Heap. However, the user’s role may also be changed in the Heap app and this won’t be reflected in the Okta parameter.