Configure SCIM for Okta

Permissions: Site Admin who can manage and configure SSO and SCIM

Product tier: Available for Advanced and Expert subscription tiers

SCIM (System for Cross-domain Identity Management) is an open standard that allows you to create, update and deactivate users in Greenhouse Recruiting more efficiently.

Updates made via SCIM are instantaneous. Provisioning with SCIM allows syncing to happen immediately in Greenhouse as soon as a user is assigned to the Greenhouse Recruiting application in Okta.

Note: Users that were deactivated in Okta prior to SCIM set up will not automatically be deactivated in Greenhouse Recruiting.

Configure Okta SSO

Before configuring SCIM, you need to configure Okta SSO in Greenhouse Recruiting.

Copy the base URL and token in Greenhouse Recruiting

Go to the SCIM Configuration page. (Configure icon > Dev Center > SCIM Configuration)

Note: This link will only appear for Site Admins who can manage and configure SSO and SCIM.

Click the toggle next to Enable SCIM for Okta.

Screenshot of the enable SCIM for okta toggle

Paste the base URL and token in Okta

Open another tab in your browser and log in to your Okta account.

Note: You must be an Okta Admin to configure SCIM.

Go to the Greenhouse Recruiting app. Keep this tab open as you navigate between Okta and Greenhouse Recruiting.

Screenshot of the greenhouse app in okta

In Greenhouse Recruiting, copy the link from the Base URL box by clicking Copy.

Screenshot of the copy base URL button

Go to the Provisioning page in Okta, then click Integration. Paste the URL in the Base URL field in Okta.

Note: If you don't see the Provisioning page, follow the steps below:

Re-add the Greenhouse Recruiting application to your Okta account.
Configure SSO.
Enable SCIM.

Screenshot of the base URL field in okta

Go back to Greenhouse Recruiting. In the SCIM token section, click Generate token. Then, click Copy.

Go to the Okta Integration page. Paste the token in the API Token field.

Screenshot of the API token field in okta

Note: If you lose or forget your token, click Generate new token to create another. This will replace your existing token, and you will need to add the new token to your Identity Provider. SCIM will stop working until the new token is added to Okta.

Click Test API Credentials. If you receive an error, check that your credentials are entered correctly. Then, click Save.

Screenshot of the test API credentials and save buttons in okta

Note: You may receive the following error: "User was assigned this application before Provisioning was enabled and not provisioned in the downstream application." This is expected behavior. Click Provision User to continue.

Add attributes to the Okta user profile

Go to the Profile Editor in Okta, then click on the profile labeled User (default).

Screenshot of the user default profile in okta

On the Attributes page, click +Add Attribute.

There are several attributes you can configure.

Note: Fields not listed in this document are optional. For the most comprehensive documentation on all potential information that can be included in an SSO request, visit Okta’s Help Center.

Username attribute

Display name	`Username`
Variable name	`userName`
Data type	`string`

First name attribute

Display name	First name
Variable name	`firstName`
Data type	`string`

Last name attribute

Display name	`Last name`
Variable name	`lastName`
Data type	`string`

Employee number attribute

Display name	`Employee number`
Variable name	`employeeNumber`
Data type	`string`

Department attribute

Tip: Setting up the department attribute allows you to sync a user's department automatically from Okta to Greenhouse Recruiting. For example, if you assigned a user to the Marketing department in Okta, the Department in their Greenhouse Recruiting profile would automatically update to Marketing.

Department attributes are defined by internal IDs, which are automatically assigned by Greenhouse Recruiting, and external IDs, which are optional and can be configured by your organization.

Before adding a department attribute, decide whether you want to use internal IDs or external IDs. Using internal IDs and external IDs together will cause an error.

Locate a department ID

To locate your office IDs, go to Configure > Organization > Departments > Download department ID report.

Open the downloaded .csv file and copy the values from either the External ID column or the Department ID (Internal ID) column.

If you want to use an external ID but don’t currently have one configured for each department, you’ll have to do so before you continue. On the Organization page, find the Department section. Hover over a department until the Edit icon appears on the right side of the page. Click the Edit icon , then enter an External ID and click Save.

Department attribute (internal)

Display name	You can choose anything, but we recommend something like `Department`
Variable name	You can choose anything, but we recommend something like `department_ids`
Data type	`string array` or `number array` Note: Unless you already have a number array set up in Okta, we recommend using a string array for this attribute.

Department attribute (external)

Display name	You can choose anything, but we recommend something like `Department`
Variable name	You can choose anything, but we recommend something like `external_department_ids`
Data type	`string array` or `number array` Note: Unless you already have a number array set up in Okta, we recommend using a string array for this attribute.

Office attribute

Tip: Setting up the office attribute allows you to sync a user's office automatically from Okta to Greenhouse Recruiting. For example, if you assigned a user to the New York office in Okta, the Office in their Greenhouse Recruiting profile would automatically update to New York.

Office attributes are defined by internal IDs, which are automatically assigned by Greenhouse Recruiting, and external IDs, which are optional and can be configured by your organization.

Choose either internal IDs or external IDs to set up your Office attribute in Okta. Using internal IDs and external IDs together will cause an error.

Locate an office ID

To locate your office IDs, go to Configure > Organization > Offices > Download office ID report.

Open the downloaded .csv file and copy the values from either the External ID column or the Office ID (Internal ID) column.

If you want to use an external ID but don’t currently have one configured for each office, you’ll have to do so before you continue. On the Organization page, find the Offices section. Hover over an office until the Edit icon appears on the right side of the page. Click the Edit icon , then enter an External ID and click Save.

Office attribute (internal)

Display name	You can choose anything, but we recommend something like `Office`
Variable name	You can choose anything, but we recommend something like `office_ids`
Data type	`string array` or `number array` Note: Unless you already have a number array set up in Okta, we recommend using a string array for this attribute.

Office attribute (external)

Display name	You can choose anything, but we recommend something like `Office`
Variable name	You can choose anything, but we recommend something like `external_office_ids`
Data type	`string array` or `number array` Note: Unless you already have a number array set up in Okta, we recommend using a string array for this attribute.

Custom field attributes

Tip: Custom user fields are a type of custom option that allows you to add your own unique labels to user profiles. Custom user fields give you more control over how you categorize your users and assign user permissions. Learn more.

Single select custom field attribute

Display name	You can choose anything, but we recommend using the Field Name from Greenhouse Recruiting
Variable name	You can choose anything, but we recommend using the Immutable Field Key from Greenhouse Recruiting
Data type	`string`

Multi-select custom field attribute

Display name	You can choose anything, but we recommend using the Field Name from Greenhouse Recruiting
Variable name	You can choose anything, but we recommend using the Immutable Field Key from Greenhouse Recruiting
Data type	`string array`

Yes/no custom field attribute

Display name	You can choose anything, but we recommend using the Field Name from Greenhouse Recruiting
Variable name	You can choose anything, but we recommend using the Immutable Field Key from Greenhouse Recruiting
Data type	`boolean`

User custom field

Note: Any changes made to this attribute after its initial setup will need to be manually synced to Greenhouse Recruiting. To do this, go to the Provisioning tab in the Greenhouse Recruiting application and click Force Sync.

Display name	You can choose anything, but we recommend using the Field Name from Greenhouse Recruiting
Variable name	You can choose anything, but we recommend using the Immutable Field Key from Greenhouse Recruiting
Data type	`linked object`

Note: When mapping a user custom field, use the expression user.getLinkedObject(“[attribute]”).login, replacing [attribute] with the attribute name you set up in the Okta user profile. For example, if you chose "manager" as the variable name of the attribute, the full expression would be user.getLinkedObject(“manager”).

When you finish, scroll down to the bottom of the Add Attribute window. Click Save or Save and Add Another. Repeat this process for each new attribute.

Add attributes to the Greenhouse Recruiting user profile

Go to the Profile Editor in Okta, then click on the profile labeled Greenhouse Recruiting.

Click + Add Attribute.

First name attribute

Display name	`First name`
Variable name	`firstName`
Data type	`string`
External namespace	`urn:ietf:params:scim:schemas:core:2.0:User`

Last name attribute

Display name	`Last name`
Variable name	`lastName`
Data type	`string`
External namespace	`urn:ietf:params:scim:schemas:core:2.0:User`

Employee number attribute

Display name	`Employee number`
Variable name	`employeeNumber`
Data type	`string`
External namespace	`urn:ietf:params:scim:schemas:core:2.0:User`

Department attribute

Department attribute (internal)

Display name	You can choose anything, but we recommend `Department`
Variable name	`department_ids`
Data type	`string array` or `number array`
External namespace	`urn:ietf:params:scim:schemas:core:2.0:User`

Department attribute (external)

Display name	You can choose anything, but we recommend `Department`
Variable name	`external_department_ids`
Data type	`string array` or `number array`
External namespace	`urn:ietf:params:scim:schemas:core:2.0:User`

Office attribute

Office attribute (internal)

Display name	You can choose anything, but we recommend `Office`
Variable name	`office_ids`
Data type	`string array` or `number array`
External namespace	`urn:ietf:params:scim:schemas:core:2.0:User`

Office attribute (external)

Display name	You can choose anything, but we recommend `Office`
Variable name	`external_office_ids`
Data type	`string array` or `number array`
External namespace	`urn:ietf:params:scim:schemas:core:2.0:User`

Custom field attributes

Note: To add your custom fields from Greenhouse Recruiting, you’ll need to locate each field’s immutable field key. This is a unique value assigned to every custom field that allows other systems to pull your custom option data.

Go to Configure > Custom Options > Users, then click on a field. Scroll to the bottom of the page and copy the value under Immutable Field Key.

Single select custom field attribute

Display name	You can choose anything, but we recommend using the Field Name from Greenhouse Recruiting
Variable name	Immutable field key
Data type	`string/code`
External namespace	`urn:ietf:params:scim:schemas:extension:greenhouse:2.0:CustomField`

Multi-select custom field attribute

Display name	You can choose anything, but we recommend using the Field Name from Greenhouse Recruiting
Variable name	Immutable field key
Data type	`string array`
External namespace	`urn:ietf:params:scim:schemas:extension:greenhouse:2.0:CustomField`

Yes/no custom field attribute

Display name	You can choose anything, but we recommend using the Field Name from Greenhouse Recruiting
Variable name	Immutable field key
Data type	`boolean`
External namespace	`urn:ietf:params:scim:schemas:extension:greenhouse:2.0:CustomField`

User custom field

Display name	You can choose anything, but we recommend using the Field Name from Greenhouse Recruiting
Variable name	Immutable field key
Data type	`string`
External namespace	`urn:ietf:params:scim:schemas:extension:greenhouse:2.0:CustomField`

When you finish, scroll down to the bottom of the Add Attribute window. Click Save or Save and Add Another. Repeat this process for each new attribute.

Set up attribute mapping

After you finish adding your attributes, click Mappings on the Profile Editor.

Select Okta User to Greenhouse Recruiting User.

Map your Okta variable to the appropriate Greenhouse Recruiting variable. When you finish, click Save Mappings.

In this article

Configure Okta SSO