Create and manage users
This topic provides reference information about creating and managing users in HCP Terraform. You can also connect to an identity provider (IdP), such as Okta and Microsoft Entra ID, and automate user provisiong and management. Refer to SCIM provisioning for more information.
Introduction
User accounts belong to individual people. Each user can be part of one or more teams, which are granted permissions on projects and projects and workspaces within an organization. A user can be a member of multiple organizations.
There are several ways to add users and manage their access:
- Organization owners can invite people to the platform. Refer to Create an account for more information.
- People with an existing HashiCorp Cloud Platform (HCP) account can log into HCP Terraform through the HCP portal. Refer to Log in with a HashiCorp Cloud Platform account for more information.
- Enable single sign-on (SSO), which offloads access verification to your identitfy provider (IdP). When a user logs in for the first time, the platform redirects to the IdP, which prompts the user to either create an HCP Terraform or Terraform Enterprise account or link their SSO identities to an existing account. Refer to Single sign-on for more information.
- Enable SCIM provisioning to completely offload user management to your IdP. Refer to SCIM provisioning for more information.
- Users already in the system can call the
/accountAPI endpoints to get account details, update account information, and change their password.
Log in with a HashiCorp Cloud Platform account
We recommend using a HashiCorp Cloud Platform (HCP) account to log in to HCP Terraform. Your HCP account grants access to all HashiCorp products and the Terraform Registry. Linking your HCP account to HCP Terraform lets you manage multi-factor authentication, password resets, and other user management functionality from HCP instead of the HCP Terraform UI.
To log in with your HCP account, navigate to HCP Terraform and login with your HCP credentials.
Link HCP and HCP Terraform accounts
The first time you log in with your HCP credentials, HCP Terraform searches for an existing HCP Terraform account with the same email address. If you have an unlinked account, HCP Terraform asks if you want to link it to your HCP account. Otherwise, if no account matches your HCP account's email address, HCP Terraform creates and automatically links a new HCP Terraform account to your HCP account.
You can only log in with your HCP credentials after linking your HCP and HCP Terraform accounts. We do not recommend linking your account if you use an SSO provider to log in to HCP Terraform because linking your account may conflict with your existing SSO configuration.
The only way to log in with your old HCP Terraform credentials is to unlink your HCP Terraform and HCP accounts. If HCP Terraform generated an account for you, you cannot unlink that account from your HCP account. You can unlink a pre-existing HCP Terraform account on the HCP Account Linking page in your Account settings.
Create an account
You can manually create an account using one of the following methods:
- Accept the invitation from another user sends to join an existing organization. The invitation email includes a link for creating an account. After creating your account, you can automatically join that organization and can begin using HCP Terraform.
- Create an account from the sign up page. You must specify a username, email address, and a password.
After you create an account, you do not belong to any organizations. To begin using HCP Terraform, you can either create an organization or ask an organization owner to send you an invitation email to join their organization.
Some platform APIs take your username as a query parameter. If you change your username, update any integrations that rely on your username in their API calls.
You can create either a standalone HCP Terraform account or an HCP Terraform account linked to an HCP account.
We recommend logging into HCP Terraform with your HCP account instead of creating a separate HCP Terraform account.
Join organizations and teams
An organization owner or a user with Manage Membership permissions enabled must invite you to join their organization and add you to one or more teams.
The platform emails user invitations. If the invitation email address matches an existing account, the invitee can join the organization with that account. Otherwise, they must create a new account and then join the organization.
Account settings
To view your settings page, click your user icon and select Account settings. Your Profile page appears, showing your username, email address, and avatar.
Profile
Click Profile in the sidebar to view and edit the username and email address associated with your account. HCP Terraform uses Gravatar to display a user icon if you have associated one with your email address. Refer to the Gravatar documentation for details about changing your user icon.
Sessions
Click Sessions in the sidebar to view a list of sessions associated with your account. You can revoke any sessions you do not recognize.
Depending on the organization's authentication settings, you may be required to regularly re-authenticate. The following settings determine how often and under what conditions you are required to re-authenticate.
Idle session timeout
HCP Terraform automatically terminates user sessions if there has been no end-user activity for a certain time period. This is a security measure to prevent unauthorized access to unmonitored devices. By default, HCP Terraform implements the following schedule for idle session timeouts:
- Standalone HCP Terraform accounts can stay idle and valid for up to 14 days
- HCP Terraform accounts linked to an HCP account follow the HCP defaults and can stay idle for one hour
HCP Terraform organization owners can reduce the idle session timeout for an organization in the authentication settings for standalone HCP Terraform accounts, but they can not modify settings for HCP Terraform accounts linked to HCP accounts.
After HCP Terraform terminates a session, you can resume it by logging back in through the HCP Terraform portal.
Forced re-authentication
HCP Terraform forces users to re-authenticate regardless of activity after the specified amount of time has elapsed. This security feature is intended to enforce new identity verifications to access sensitive IT and data managed by HCP Terraform. When the specified amount of time elapses, the you must re-authenticate your credentials and potentially re-verify through 2FA or MFA.
- By default, standalone HCP Terraform accounts are forced to re-authenticate every 14 days
- By default, HCP Terraform accounts linked to an HCP account follow the HCP defaults and are forced to re-authenticate every 48 hours
For standalone HCP Terraform accounts, organization owners can reduce the idle session timeout. Refer to the authentication settings reference for more information. Owners can't modify settings for HCP Terraform accounts linked to HCP accounts.
Other re-authentication triggers
By default, users must re-authenticate when they log in at start of the week, which begins on Mondays, but several actions immediately terminate active sessions, including:
- Manually logging out of the HCP or HCP Terraform portals
- Clearing the browser session or cookies
- Closing all active browser windows
Any of these actions requires you to re-authenticate regardless of session timeout settings.
Organizations
Click Organizations in the sidebar to view a list of the organizations where you are a member. If you are on the owners team, the organization is marked with an OWNER badge.
To leave an organization, choose Leave organization from the ellipses menu for the organization. No additional permissions are required, but you cannot leave if you are the last member of the owners team. Either add a new owner and then leave, or delete the organization.
Password
Click Password in the sidebar to change your password. You cannot manage your HCP Terraform password directly if you linked your account to GitHub or HashiCorp Cloud Platform (HCP). Instead, manage your password through the linked service.
Passwords must be at least eight characters long, and contain at least three of the following:
- Lowercase letters (a-z)
- Uppercase letters (A-Z)
- Numbers (0-9)
- Special characters (!@#$%^&*)
Password management is not available if your Terraform Enterprise instance uses SAML single sign on.
Two-factor authentication
Click Two Factor Authentication in the sidebar to enable two-factor authentication. Two-factor authentication requires a TOTP-compliant application or an SMS-capable phone number. An organization can set policies that require two-factor authentication.
Refer to Two-Factor Authentication for details.
HCP account linking
Click HCP Account Linking in the sidebar to unlink your HCP Terraform from your HCP Account. You cannot unlink an account that HCP Terraform autogenerated during the linking process. Refer to Linked HCP and HCP Terraform Accounts for more details.
After you unlink, you can begin using your HCP Terraform credentials to log in. You cannot log in with your HCP account again unless you re-link it to your HCP Terraform account.
SSO identities
Click SSO Identities in the sidebar to review and remove SSO identity links associated with your account.
You have an SSO identity for every SSO-enabled HCP Terraform organization. HCP Terraform links each SSO identity to a single HCP Terraform user account. This link determines which account you can use to access each organization.
Tokens
Click Tokens in the sidebar to create, manage, and revoke API tokens. You can pass user, team, and organization tokens to interact with the platform. Users can be members of multiple organizations, so user tokens work with any organization where the associated user is a member. Refer to API Tokens for details.
API tokens are required for the following tasks:
- Authenticating with the API. API calls require an
Authorization: Bearer <TOKEN>HTTP header. - Authenticating with the CLI integration or the
remotebackend. These require a token in the CLI configuration file or in the backend configuration. - Using private modules in command-line runs on local machines. This requires a token in the CLI configuration file.
Protect your tokens carefully because they contain the same permissions as your user account. For example, if you belong to a team with permission to read and write variables for a workspace, another user could use your API token to authenticate as your user account and also edit variables in that workspace. Refer to permissions for more details.
We recommend creating tokens that are valid for the shortest duration possible. Refer to API Token Expiration for details.
Create a token
To create a new token:
- Click Create an API token. The Create API token box appears.
- Enter a Description that explains what the token is for and click Create API token.
- Choose the token's expiration date or time. The UI displays a token's expiration date and time in your current time zone.
- Copy your token from the box and save it in a secure location. HCP Terraform only displays the token once, right after you create it. If you lose it, you must revoke the old token and create a new one.
Revoke a token
To revoke a token, click the trash can next to it. That token will no longer be able to authenticate as your user account.
When you remove the user from an SSO identity provider, the user API token continues to allow platform access. This is because the user may still be a member of the organization. To remove access to a user's API token, remove the user from the organization in the UI or with the Terraform Enterprise provider.
Tokens disabled
You can disable user tokens at the organization level. For more information, refer to User API tokens.
GitHub app OAuth token
Click Tokens in the sidebar to manage your GitHub App token. This token lets you connect a workspaces to an available GitHub App installation.
Only an HCP Terraform user can own a GitHub App token. Team and organization API tokens can't own a GitHub App token.
A GitHub App token lets you perform the following actions:
- Connect workspaces, policy sets, and registry modules to a GitHub App installation with the HCP Terraform API and UI.
- View available GitHub App installations with the HCP Terraform API and UI.
After generating this token, you can use it to view information about your available installations for the Terraform Cloud GitHub App.
Create a GitHub app token
To create a GitHub App token, click Create a GitHub App token. The GitHub App authorization pop-up window appears requesting authorization of the Terraform Cloud GitHub App. This does not grant HCP Terraform access to repositories.
Revoke a GitHub app token
To revoke the GitHub App token, click the ellipses button (...). The dropdown menu appears. Click the Delete Token option. This triggers a confirmation window to appear, which asks you to confirm that you want to revoke the token. Once confirmed, the token is revoked and you can no longer view GitHub App installations.