Terraform Enterprise with SSO and SAML Usernames

Problem

When a user attempts to log into a Terraform Enterprise instance configured with SAML SSO, the login fails with the following error:

An error occurred. Please contact your TFE Administrator for further information.
ERROR: Validation failed: Username has already been taken

This can occur even if the user's email address is unique in the Identity Provider (IdP).

Cause

By default, Terraform Enterprise generates a username from the user's email address by removing the domain and replacing periods (.) with underscores (_). For example, both john.doe@email.com and john.doe@example.com are converted to the username john_doe.

This error occurs when a new SAML user's generated username conflicts with an existing username in Terraform Enterprise, which must be unique.

Solution

To resolve this issue, you must configure the Usernameattribute in your IdP to map to a field that is guaranteed to be unique for every user.

Important Considerations

Before implementing this change, be aware of the following constraints and behaviors:

1. Usernames in Terraform Enterprise have specific constraints:
   • Must be unique.
   • Can only contain alphanumeric characters, hyphens (-), or underscores (_).
   • Cannot contain spaces.
2. If the Username attribute from the IdP contains spaces, Terraform Enterprise sets the username to the value before the first space. For example, a Username value of John Doe results in the username John.
3. If Terraform Enterprise fails to parse the Username attribute, it falls back to the default behavior of parsing the email address.

Warning: Changing an existing username can cause important operations to fail. This is because it is used in URL paths to various resources. If external systems make requests to these resources, you must update them before making a change.

Additional Information

• Terraform Enterprise SAML SSO configuration
• Terraform Enterprise SAML attributes