Configure Okta as the SCIM identity provider

This topic describes how to configure Okta as the SCIM identity provider for HCP Terraform. After completing this configuration, HCP Terraform can accept SCIM provisioning requests from Okta for users and groups.

Background

Okta provisions users and groups to HCP Terraform using the SCIM protocol. Okta acts as the source of truth for user identities and group membership. When you assign a user or group to your custom HCP Terraform application in Okta, Okta pushes those changes to HCP Terraform automatically.

HCP Terraform matches incoming SCIM users to existing accounts by email address. When a match is found, the existing account becomes SCIM-managed. When no match is found, HCP Terraform creates a new organization-owned account. Okta group names become team names in HCP Terraform directly. There is no separate name mapping.

You cannot use the Terraform Cloud application from the Okta Integration Network gallery for SCIM. You must create a custom application to complete this configuration.

To configure Okta as the SCIM identity provider for HCP Terraform:

1. Create a custom application in Okta and configure SAML SSO on it.
2. Configure the API integration and configure the SCIM base URL and token.
3. Configure provisioning actions.
4. Start provisioning.
5. Configure group push and verify the setup.

Requirements

Before you configure Okta as the SCIM identity provider, enable SCIM in HCP Terraform and generate a SCIM token. You must also create a custom SAML application in Okta and have administrator permissions to configure SCIM provisioning. Refer to Configure SCIM provisioning for instructions.

Before broad rollout, validate your Okta user identifier and attribute mappings with a small set of test users.

Create a custom application

You must create a custom SAML application. You cannot use the existing Terraform Cloud application from the Okta Integration Network gallery.

1. From the Okta Admin Dashboard, navigate to Applications > Applications.
2. Click Create App Integration.
3. Select SAML 2.0.
4. Name the app and click Next.
5. Under Configure SAML, set the following values. The Single sign-on URL and Audience URI are temporary and will be replaced in a later step:
   • Single sign-on URL: https://app.terraform.io/sso/saml/placeholder
   • Audience URI (SP Entity ID): placeholder
   • Name ID format: EmailAddress
   • Application username: Okta username
   • Update application username on: Create and update
6. Under Feedback, select This is an internal app that we have created.
7. Click Finish.
8. Copy the Metadata URL to use in the HCP Terraform configuration.
9. Configure SAML SSO in HCP Terraform for this new custom application by providing the Metadata URL you copied in the previous step. Follow the instructions in Use single sign-on with Okta for HCP Terraform, up to and including the step to click Enable.
10. In the Okta application, update the following with the values from the HCP Terraform SSO configuration:
    • Single sign-on URL: use the Assertion Consumer URL from HCP Terraform
    • Audience URI (SP Entity ID): use the Entity ID (Audience) from HCP Terraform
11. Verify the SSO configuration by clicking Test. If the test is successful, click Enable.

Configure API integration

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

1. Sign in to the Okta Admin Console.
2. Navigate to Applications and open your custom HCP Terraform application.
3. On the General tab under App Settings, click Edit and select SCIM as Provisioning. After saving, a new Provisioning tab appears.
4. Click the Provisioning tab.
5. Click Edit for the SCIM Connection and complete the following fields:
   • SCIM connector base URL: Enter the base URL you copied from HCP Terraform. Refer to Enable SCIM for more information.
   • Unique identifier field for users: Set to email.
   • Supported provisioning actions: Enable Push New Users, Push Profile Updates, and Push Groups.
   • Authentication Mode: Select HTTP Header.
   • Authorization: Enter the SCIM token you copied from HCP Terraform. Refer to Enable SCIM for more information.
6. Click Test Connector Configuration to verify the configuration.
7. Click Save.

Configure provisioning actions

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

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

Configure group push

Complete the following steps to synchronize Okta groups:

1. Click the Push Groups tab.
2. Click Push Groups and select Find groups by name or Find groups by rule.
3. Search for and select the groups you want to push to HCP Terraform.
4. Click Save.

Okta creates corresponding teams in HCP Terraform for each pushed group. Okta group names become team names in HCP Terraform directly. When assigning groups, note the following factors:

• IdP group names become team names in HCP Terraform directly. There is no separate name mapping step.
• Group names must be fewer than 90 characters.
• Nested group membership is not supported.
• HCP Terraform supports a maximum of 3,000 IdP groups and 1,000 members per group.

Refer to Group lifecycle for more information about groups.

Before enabling SCIM, review existing team memberships. When an Okta group name matches an existing HCP Terraform team name, SCIM takes over that team and replaces its membership with the Okta group membership.

We recommend using separate groups for SSO access, which controls who can sign in, and SCIM team membership, which controls team assignments within HCP Terraform.

Start provisioning

Start with a small rollout to verify provisioning before broader adoption:

1. Click the Assignments tab in your HCP Terraform application.
2. Click Assign and select either Assign to People or Assign to Groups.
3. Select a test user or group to provision.
4. 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. Users can log in using SAML SSO after provisioning.
• Groups: If you configured group push, Okta creates the groups. Group membership is synchronized automatically.

When HCP Terraform receives a SCIM user deactivation request, it removes the user's access to HCP Terraform.

Refer to User lifecycle for more information.

Attribute mappings

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

Users

HCP Terraform requires userName and at least one email value for each user. Set the Unique identifier field for users to email. During user creation, HCP Terraform links existing users by email address when the email matches.

Groups

Test provisioning

After completing the configuration, verify that provisioning works correctly.

Verify user provisioning

1. Assign a test user to the HCP Terraform application in Okta.
2. Wait a few moments for Okta to provision the user.
3. Navigate to your organization in HCP Terraform.
4. Verify that the test user appears with a status of Synced.
5. Test that the user can log in using SSO.

Verify group provisioning

1. Push a test group from Okta.
2. Navigate to Teams in your HCP Terraform organization settings.
3. Verify that the group appears as a team.
4. Confirm team membership reflects the Okta group membership.

Verify user deactivation

1. Unassign a test user from the application in Okta.
2. Wait a few moments for Okta to deactivate the user.
3. Log in to HCP Terraform 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

User provisioning failures

Group provisioning failures

Rate limiting

Okta may encounter rate limits when provisioning large numbers of users or groups. If you see 429 Too Many Requests errors, it's because HCP Terraform 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:

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

For additional troubleshooting guidance, refer to Troubleshoot SCIM provisioning.

Next steps

Review the following topics for more information about managing users and groups:

• User lifecycle describes how SCIM-managed users work in HCP Terraform.
• SCIM group management describes how SCIM groups integrate with HCP Terraform teams.