SCIM user lifecycle

When you enable SCIM, your identity provider (IdP) becomes the source of truth for user management, automatically synchronizing user creation, updates, and deactivation with HCP Terraform.

Overview

SCIM lets your IdP automatically manage the complete user lifecycle:

• When a new employee is assigned to your organization, SCIM automatically creates their account. No manual account creation is required.

• When user attributes change in your IdP, such as email or username, SCIM synchronizes those changes to HCP Terraform in real-time.

• When an employee leaves or is removed from the application in your IdP, SCIM immediately revokes their access by either removing them from the organization or by deleting their account depending on how the user was created. Refer to Deactivate user for more information.

This automation eliminates manual user management overhead and ensures that terminated employees cannot retain access to the platform.

User lifecycle operations

All operations use the /scim/v2/Users endpoint.

Create user

When your IdP provisions a new user, HCP Terraform performs the following actions:

1. Creates a user record or links an existing user with the same email address.
2. Creates a SCIM identity record that links the user to your IdP.
3. Returns a unique SCIM id that your IdP uses for all subsequent operations on this user.

HCP Terraform adds new users to the organization automatically without requiring an invitation or email verification.

Update user

When user attributes change in your IdP, HCP Terraform updates the corresponding user record. Supported updates include:

• Email address changes
• SCIM userName changes
• External ID changes
• Active status changes

Updates apply synchronously and take effect immediately. HCP Terraform supports the following PATCH behaviors for users:

• Replace on supported user attributes, either as a targeted operation with a path or without a path when value is an object.
• Add on single-valued supported user attributes, which HCP Terraform treats the same as Replace.
• Remove for externalId.

You must include the path to perform a Remove operation. HCP Terraform ignores attempts to clear required user attributes such as userName, emails, or active.

Deactivate user

When your IdP sets active=false for a user or removes them from the organization, HCP Terraform changes the user's team membership status to inactive. Inactive users are still members of the organization. You can reactivate users by provisioning them again in your IdP with active=true.

Delete user

When your IdP sends a delete request, HCP Terraform performs the following actions:

• Deletes the SCIM identity record that links the user to the IdP
• Removes the user from the organization
• For SCIM-managed users, deletes the user account
• For manually-managed users, HCP Terraform removes them from the organization but preserves their account for access to other organizations

SCIM attribute mapping

The following table describes how SCIM attributes map to user fields in HCP Terraform:

When creating the user record, the SCIM userName does not become the HCP Terraform username. Instead, HCP Terraform generates the internal HCP Terraform username value. HCP Terraform also uses the userName attribute to automatically map users to their single sign-on nameids. Refer to Team Names and SSO Team ID for more information.

HCP Terraform does not store SCIM name fields, such as givenName, familyName, middleName. These attributes are accepted in requests but not persisted.

Existing users

If an incoming SCIM user has the same email address as an existing system user, HCP Terraform links that existing user to SCIM management as long as the incoming userName is not already owned by a different SCIM identity.

After HCP Terraform creates the SCIM identity link, the IdP initiates any future updates to that user. HCP Terraform keeps a single underlying user record.

If HCP Terraform does not find a matching email address that is a member of the organization, it creates a new user record and generates the local username separately from the SCIM userName. HCP Terraform ignores users that are not members of the organization, even if the email address matches.

HCP Terraform stores the original userName sent by the IdP in the scim_username field. This enables the IdP to query by its original username even when the HCP Terraform username differs.

When an existing user's email address that has been linked to an IdP identity, you must use the HCP Terraform UI to update their email address. HCP Terraform ingores updates to the emails[primary=true].value attribute because it represents global objects that can be associated with multiple organizations.

SCIM-managed versus manually-managed users

Users in HCP Terraform are either SCIM-managed or manually-managed. The management type affects what operations are allowed.

SCIM-managed users

A user is SCIM-managed if they have an associated SCIM identity record. You can identify SCIM-managed users through the following indicators in the HCP Terraform UI:

• User status shows Synced - Provisioned for users created by SCIM
• User status shows Synced - Claimed for existing users linked to SCIM
• The user was created or linked through SCIM provisioning

The HCP Terraform UI refers to SCIM-managed users as organization-owned and refers to manually-managed users as user-owned.

Behavior when SCIM is enabled

Users provisioned through SCIM become SCIM-managed. Existing users that were created manually are manually-managed until provisioned through SCIM.

If an IdP provisions a user whose email matches an existing manual user, that user becomes SCIM-managed. You can still create manually-managed users directly for emergency access.

Existing users who are not provisioned with SCIM can still access the organization. However, HCP Terraform cannot add them to a SCIM managed team and removes them from any SCIM managed teams.

Transition from manual to SCIM management

When you enable SCIM, existing users are not automatically converted. A user becomes SCIM-managed only when the IdP creates the user through SCIM and when the IdP provisions a user whose email matches an existing user.

Multi-organization access

SCIM-managed users are scoped to a single organization. When logging in, they must specify the organization name. To access a different organization, they must log out and log in again with the other organization name.

Manually-managed users can access multiple organizations with a single login session. After logging in, they see a list of all organizations they are members of, including non-SSO organizations, SSO organizations, and organizations with SCIM enabled.

Owners team and emergency access

You cannot manage membership of the owners team with SCIM. This ensures that accounts used for emergencies, also referred to as break-glass accounts, are available even when SCIM is misconfigured. This also provides access when IdP changes would otherwise prevent administrators from being able to access HCP Terraform. Users managed by SCIM don't have emergency access because they are scoped to the organization and deleted when removed from the IdP.

Although you can't manage owner membership through SCIM, you can still deprovision users on the owners team. If you need to use an owner account to remediate a potential issue, verify that the account is active in the IdP.

HCP Terraform requires at least one manually-managed account in the owners team to ensure break-glass access in case of SCIM misconfiguration. Your IdP can still manage team membership for users that are manually managed in HCP Terraform. These users appear in the UI as Synced - Claimed. Membership within the owners team, however, is outside of SCIM control.

We recommend maintaining at least two manually-managed accounts in the owners team for emergency access.

To maintain emergency access when SSO or SCIM are misconfigured or your IdP is unavailable:

• Ensure account is SCIM active
• Maintain separate manually-managed accounts with password authentication
• Place these accounts in the owners team
• Limit the number of accounts in the owners team to minimize security risk
• Document break-glass procedures for your team

Blocked operations for SCIM-managed users

To maintain the IdP as the single source of truth, certain operations are blocked for SCIM-managed users. Administrators must make changes through the IdP rather than directly in the UI or API.

The following actions are blocked for SCIM-managed users and teams:

• Editing user profile information. Note that you can still edit profile information for non-SCIM users.
• Adding or removing users from teams.
• Deleting users or teams.

Your IdP controls profile fields, such as name and email, for SCIM-managed users. Update these fields in your IdP. HCP Terraform may overwrite changes made directly in the UI.

Operations that remain available

SCIM controls the user identity attributes and whether the user is active, but it does not control how the user authenticates to APIs. Users can perform operations that control platform-specific functionality rather than identity, including:

• Creating, listing, and revoking their own API tokens for programmatic access
• Assigning team permissions to workspaces
• Managing workspace settings
• Creating and managing teams that are not managed by SCIM
• Managing organization settings

SAML and SCIM username

When SCIM is enabled, HCP Terraform stops synchronizing SCIM-managed user identity from SAML assertions. Updates to SCIM userName must come from the IdP through SCIM. This ensures that SCIM remains the single source of truth for SCIM-managed user identity attributes.

When a user authenticates with SAML SSO, the identity provider sends a nameID assertion to identify the user. HCP Terraform matches the nameID against the SCIM userName stored when SCIM provisioned the user.

You should configure your identity provider so that the SAML nameID and the SCIM userName use the same IdP attribute. When they do not match, the user can't log in after provisioning and HCP Terraform the SSO workflow for linking users begins, potentially resulting in duplicate accounts.

In Entra ID, for example, the attribute mapping for SAML and SCIM are inconsistent, which potentially increases the likelihood for issues related to username values. Refer to the Entra ID attribute mapping documentation for more information.

HCP Terraform maps users to the SAML single sign-on nameid based on the SCIM userName object. Neither the Username SAML assertion nor the the SCIM userName affect the HCP Terraform username object.

SCIM is authoritative for team membership. HCP Terraform ignores any membership information passed during SAML SSO login, even when it contains membership information for teams that are not managed by SCIM. This approach avoids conflicts and simplifies compliance auditing.

API reference

Refer to the following API references for more information about SCIM user provisioning:

• Refer to the SCIM provisioning API endpoints reference for authentication, discovery endpoints, pagination, supported filters, and shared rate limits.
• Refer to the SCIM Users API for /scim/v2/:scim_configuration_id/Users request and response details.