Configure Okta as the SCIM identity provider

This topic describes how to configure Okta as the SCIM identity provider for Terraform Enterprise. In Terraform Enterprise, SAML handles authentication and SCIM handles provisioning.

After completing this configuration, Terraform Enterprise can accept SCIM provisioning requests from Okta for users and groups.

Overview

Complete the following steps to configure Okta for SCIM provisioning:

Enable SCIM provisioning in Terraform Enterprise and create a SCIM token.
Configure the SCIM API integration in Okta.
Enable the provisioning actions that Okta should perform.
Configure group push for any groups that you want Okta to provision.
Assign test users or groups and verify the resulting behavior in Terraform Enterprise.

Prerequisites

Before configuring SCIM provisioning with Okta, verify that you meet the following requirements:

Terraform Enterprise with SAML SSO configured for Okta: SCIM provisioning requires SAML single sign-on to be enabled first. If you have not configured SAML, refer to Configure Okta as the SAML identity provider for instructions.
Okta administrator access: You must have administrator permissions in Okta to configure SCIM provisioning for the Terraform Enterprise application.
Non-SSO admin account: We strongly recommend creating a non-SSO admin account for recovery before enabling SCIM. This account allows you to log in and troubleshoot if there are issues with your SCIM or SAML configuration.

Before broad rollout, validate your Okta user identifier and attribute mappings with a small set of test users. During SCIM user creation, Terraform Enterprise links an existing Terraform Enterprise user by email address when the email matches.

Enable SCIM provisioning in Terraform Enterprise

To start the synchronization process, enable SCIM provisioning in Terraform Enterprise so that you can obtain the base URL and token required for Okta.

Log in to Terraform Enterprise as a site administrator.
Open your user icon menu and click Site Admin, or go directly to https://<TFE_HOSTNAME>/app/admin/scim.
Click SCIM in the left navigation.
Click Enable SCIM provisioning if SCIM is not already enabled.
Click Create Token in the SCIM Tokens section.
Enter a description for the token, such as Okta SCIM Integration.
Optionally, configure the token expiration.
Click Create Token.
Copy and save the token value.
Note the SCIM base URL displayed on the settings page. The URL format is:
```
https://<TFE_HOSTNAME>/scim/v2
```

For configuration in Okta, you need:

The SCIM base URL.
The token value from the SCIM token you created.

Terraform Enterprise only displays the token value once. If you lose the token, you must create a new one.

For more information about enabling SCIM and managing tokens, refer to Configure SCIM provisioning and Tokens.

Configure API integration in Okta

After SCIM is enabled in Terraform Enterprise, configure the SCIM connection in Okta.

Log in to the Okta Admin Console.
Navigate to Applications > Applications.
Open your existing Terraform Enterprise application.
Click the Provisioning tab.
Click Configure API Integration.
Select the Enable API integration checkbox.
In the SCIM connector base URL field, enter the SCIM base URL from Terraform Enterprise:
```
https://<TFE_HOSTNAME>/scim/v2
```
In the Authentication Mode section, select HTTP Header.
In the Authorization field, enter the SCIM token you created in Terraform Enterprise without the Bearer prefix. Okta automatically adds the Bearer prefix when making requests to Terraform Enterprise.
Configure the Unique identifier field for users according to your validated Okta provisioning setup.
Click Test API Credentials to verify the connection.
If the test succeeds, click Save.

The following table summarizes the required SCIM connection settings:

Setting	Value
SCIM connector base URL	`https://<TFE_HOSTNAME>/scim/v2`
Unique identifier field for users	Your validated Okta provisioning configuration
Authentication Mode	HTTP Header
Authorization	Your SCIM token value

Configure provisioning actions in Okta

After the API integration is verified, new settings appear under the Provisioning tab.

On the Provisioning tab, click To App in the left sidebar.
Click Edit.
Enable the following options:
- Create Users: Allows Okta to create new users in Terraform Enterprise.
- Update User Attributes: Allows Okta to update user attributes in Terraform Enterprise.
- Deactivate Users: Allows Okta to deactivate users in Terraform Enterprise when they are unassigned or suspended in Okta.
Click Save.

Configure group push

To synchronize Okta groups with Terraform Enterprise:

Click the Push Groups tab.
Click Push Groups and select Find groups by name or Find groups by rule.
Search for and select the groups you want to push to Terraform Enterprise.
Click Save.

Okta creates corresponding SCIM groups in Terraform Enterprise for each pushed group. You can then link these SCIM groups to Terraform Enterprise teams. Refer to Link SCIM groups to teams for instructions.

Start provisioning

After the Okta provisioning configuration is complete, start with a small rollout to verify provisioning before broader adoption:

Click the Assignments tab in your Terraform Enterprise application.
Click Assign and select either Assign to People or Assign to Groups.
Select a test user or group to provision to Terraform Enterprise.
Click Assign for each selection, then click Done.

Initial provisioning may take longer than later updates, especially when provisioning many users or groups. Later provisioning runs only process subsequent changes.

When you assign users or groups:

Users: Okta immediately provisions assigned users to Terraform Enterprise. Users can log in using SAML SSO after provisioning.
Groups: If you configured group push, Okta creates the groups in Terraform Enterprise. Group membership is synchronized automatically.

When Terraform Enterprise receives a SCIM user deactivation request, it suspends the user.

Assigning groups to the application does not automatically create team memberships in Terraform Enterprise. You must link SCIM groups to Terraform Enterprise teams after the groups are provisioned. Refer to Link SCIM groups to teams.

Attribute mappings

The following tables show the Okta-to-SCIM mappings relevant to Terraform Enterprise. The Required column reflects what Terraform Enterprise requires on incoming SCIM requests.

Users

Okta attribute	SCIM attribute	Required
`userName`	`userName`	Yes
`emails`	`emails`	Yes

Terraform Enterprise requires userName and at least one email value for each user. During user creation, Terraform Enterprise links existing users by email address when the email matches.

Groups

Okta attribute	SCIM attribute	Required
`displayName`	`displayName`	Yes
`members`	`members`	No
`externalId`	`externalId`	No

Test provisioning

After completing the configuration, verify that provisioning works correctly.

Verify user provisioning

Assign a test user to the Terraform Enterprise application in Okta.
Wait a few moments for Okta to provision the user.
Log in to Terraform Enterprise as a site administrator.
Navigate to Site Admin > Users.
Verify that the test user appears in the user list.
Check that the user's email address matches the Okta user.

Verify group provisioning

Push a test group from Okta to Terraform Enterprise.
Log in to Terraform Enterprise as a site administrator.
Navigate to Site Admin > SCIM.
Verify that the group appears in the SCIM groups list.
Link the group to a Terraform Enterprise team and verify membership synchronization.

Verify user deactivation

Unassign a test user from the Terraform Enterprise application in Okta.
Wait a few moments for Okta to deactivate the user.
Log in to Terraform Enterprise and verify that the user is deactivated.

Troubleshooting

If you encounter issues with Okta SCIM provisioning, use the following guidance to diagnose and resolve common problems.

Authentication failures

Issue	Cause	Solution
`401 Unauthorized` error	Invalid or expired SCIM token	Create a new SCIM token in Terraform Enterprise and update the Okta configuration.
Test API Credentials fails	Incorrect base URL or token	Verify the SCIM base URL format and ensure the token value is correct.
Connection timeout	Network or firewall issues	Verify that Okta can reach your Terraform Enterprise instance. Check firewall rules and network connectivity.

User provisioning failures

Issue	Cause	Solution
Users not created	Incorrect user identifier or attribute mapping	Review the Okta user identifier and attribute mappings, then test with a single user before broad rollout.
Duplicate user errors	Existing Terraform Enterprise user or SCIM identity conflicts with the incoming Okta user	If the email matches an existing Terraform Enterprise user, Terraform Enterprise links that user to SCIM. If the conflict is with an existing SCIM identity or another unique attribute, review the Terraform Enterprise-side conflict guidance in Troubleshoot SCIM provisioning.
User attributes not updating	Update User Attributes not enabled	Enable Update User Attributes in the Okta provisioning settings.

Group provisioning failures

Issue	Cause	Solution
Groups not appearing in Terraform Enterprise	Push Groups not configured	Configure group push in Okta and select the groups to push.
Group membership not syncing	SCIM group not linked to a team	Link the SCIM group to a Terraform Enterprise team. Refer to Link SCIM groups to teams.
Large group operations timeout	Group exceeds size limits	Split large groups into smaller groups. Terraform Enterprise public SCIM group create and update requests support a maximum of 1,000 members per group.

Rate limiting

Okta may encounter rate limits when provisioning large numbers of users or groups. If you see 429 Too Many Requests errors:

Terraform Enterprise temporarily rate-limits SCIM requests when request volume is too high. Review the Okta provisioning logs, wait for provisioning to continue, and refer to Troubleshoot SCIM provisioning if the condition persists.

View provisioning logs in Okta

To view detailed provisioning logs and error messages:

In the Okta Admin Console, navigate to your Terraform Enterprise application.
Click the Provisioning tab.
Click View Logs to see recent provisioning events.
Filter by status to find failed operations.

For additional troubleshooting guidance, refer to Troubleshoot SCIM provisioning.

Next steps

After configuring Okta for SCIM provisioning, complete the following tasks:

Link SCIM groups to Terraform Enterprise teams to control team membership through your IdP.
Configure a site admin group to automatically provision site administrators.
Review SCIM user management to understand how SCIM-managed users behave in Terraform Enterprise.
Review SCIM group management to understand how SCIM groups integrate with Terraform Enterprise teams.