HCP Terraform - Login via SSO to HCP Terraform returns 422 error

Problem

When a user accepts an invitation to an HCP Terraform organization with SSO enabled, the login fails with a 422 Unprocessable Entity error. This prevents the user from linking their Identity Provider (IdP) email with their HCP Terraform account.

Cause

This issue can occur when an HCP Terraform organization has a manually created team named SSO.

The team name sso (lowercase) is reserved for internal use by HCP Terraform. HCP Terraform automatically creates the sso team during the first successful SSO login to manage user permissions. If a team named SSO already exists, it creates a conflict that blocks the authentication process, resulting in the 422 error.

Solution

To resolve the conflict, you must either rename or delete the existing SSO team in your HCP Terraform organization.

1. Navigate to your organization's settings.
2. Select Teams from the sidebar.
3. Locate the team named SSO.
4. Either rename the team to something else (e.g., SSO-Users) or delete it if it is not in use.

After you rename or delete the conflicting team, the affected user should be able to complete the SSO login process successfully.