Use Case
When a user authenticated via SAML SSO performs automated tasks using Terraform API calls in Terraform Enterprise, their session may expire based on your organization's settings. This expiration invalidates the user's API tokens, causing API calls to fail with a 401: Unauthorized error until the user manually logs in again to create a new session.
To prevent the invalidation of API tokens for automation users, you can designate the user as a service account using the SAML SSO attribute IsServiceAccount.
Prerequisites
- Terraform Enterprise with SAML SSO enabled.
- Administrative access to your SAML Identity Provider (IdP).
Procedure
To configure a user as a service account, you must create and assign a specific attribute in your IdP.
- In your Identity Provider (IdP), create a new attribute mapping for the
IsServiceAccountattribute. - Configure the attribute with the following settings:
-
Name: The name must be exactly
IsServiceAccount(case-sensitive). -
Format: Set the format to
basic. -
Value: Map the value to a source that resolves to a boolean
true.
-
Name: The name must be exactly
- Assign this attribute mapping to the user or group that you want to designate as a service account.
Expected Outcome
After you assign the IsServiceAccount attribute to a user, that user's API tokens will no longer expire when their UI session ends. This allows the user to perform API calls continuously without needing an active browser session.
Important Considerations
- Persistent Tokens: User accounts designated as service accounts can have API tokens that do not expire. These tokens will remain active indefinitely unless manually revoked or the user is suspended in Terraform Enterprise.
-
Synchronization Delay: Revoking the
IsServiceAccountattribute in your IdP does not automatically sync to Terraform Enterprise. The change only takes effect the next time the user signs in. An administrator can manually suspend the user or revoke their tokens in Terraform Enterprise if immediate revocation is required. -
SAML SSO Only: This feature is only available for environments using SAML SSO for authentication. There is no API endpoint or UI option to enable the
IsServiceAccountsetting directly within Terraform Enterprise.