[Terraform] SAML User API token 401 Unauthorized – HashiCorp Help Center

Problem

When attempting to use a user API token generated after authenticating to Terraform Enterprise via SAML, operations fail with a 401 Unauthorized error. This can occur when running Terraform operations from the command line or interacting with the API directly.

Prerequisites

Administrative access to the Terraform Enterprise instance (SSH or console).
A Terraform Enterprise instance configured with SAML authentication.

Cause

This error typically occurs when the SAML user's API token has expired or has not been correctly refreshed by the Identity Provider (IdP). The token's validity is tied to the SAML session, and if the session is invalid, the token will be rejected.

Solutions

The first step is to diagnose the token's status by checking its last update timestamp within the Terraform Enterprise Rails console. Based on the result, you can proceed with the appropriate solution.

Step 1: Verify the Token Timestamp

Access the Rails console to inspect the details of the user's authentication token.

Connect to the Terraform Enterprise instance via SSH.

Execute the appropriate command for your TFE version to access the Rails console.

## For TFE versions before v202205-1:
$ sudo docker exec -it ptfe_atlas /usr/bin/init.sh /app/scripts/wait-for-token -- bash -i -c 'cd /app && ./bin/rails c'

## For TFE v202205-1 and above:
$ sudo docker exec -it tfe-atlas /usr/bin/init.sh /app/scripts/wait-for-token -- bash -i -c 'cd /app && ./bin/rails c'

## For Flexible Deployment Options (FDO) instances:
$ docker exec -it terraform-enterprise-tfe-1 tfectl support console

Once in the Rails console, use the following command to look up the token, replacing <token-value> with the problematic API token.
```
token = AuthenticationToken.lookup_by_token("<token-value>")
```
Retrieve the details associated with the token.
```
token.authenticatable_resource
```
Inspect the output and note the value of the updated_at timestamp. This timestamp indicates the last time the user's authentication details were refreshed.
```
=> #<User id: 1, email: "admin@example.com", username: "admin", ..., updated_at: "2023-10-16 10:27:59.664059000 +0000", ...>
```

After checking the timestamp, proceed to the solution that matches your findings.

Solution 1: Re-authenticate to Refresh the Token

This solution applies if the updated_at timestamp is not updating after you attempt to re-authenticate. This indicates the SAML session needs to be completely reset.

Log out of the Terraform Enterprise UI.
Log out of your SAML Identity Provider (e.g., Okta, Azure AD).
Log back into your SAML IdP.
Log back into Terraform Enterprise, which will trigger a new SAML authentication flow.
Generate a new user API token and verify that it works.

This process forces a new session and should update the token's validity.

Solution 2: Investigate Further

This solution applies if the updated_at timestamp is updating correctly, but the token still results in a 401 Unauthorized error.

If the token timestamp is updating but authentication still fails, this may indicate a different underlying issue, such as a misconfiguration in network proxies, load balancers, or SAML settings. Review the Terraform Enterprise application logs for more detailed error messages related to the authentication attempt to diagnose the problem further.

Outcome

After following the appropriate solution, the user API token should authenticate successfully, allowing Terraform operations and API calls to proceed without authorization errors.

Additional Information