diff --git a/website/content/api-docs/secret/terraform.mdx b/website/content/api-docs/secret/terraform.mdx index 62dd5e29c9..4b4facb54e 100644 --- a/website/content/api-docs/secret/terraform.mdx +++ b/website/content/api-docs/secret/terraform.mdx @@ -84,19 +84,22 @@ This endpoint creates or updates the Terraform Cloud role definition in Vault. If the role does not exist, it will be created. If the role already exists, it will receive updated attributes. -Terraform Cloud offers three distinct types of API tokens with varying level of -access: Organizations, Teams, and Users. A Vault Role can manage a single type -of API token at a time, determined by how it is configured: +Terraform Cloud offers four distinct types of API tokens with varying level of +access: Organizations, Teams, Legacy Teams (deprecated in HCP Terraform) and Users. +A Vault Role can manage a single type of API token at a time, determined by how it is configured: - To manage an Organization API token, provide the organization name with the `organization` parameter -- To manage a Team API token, provide the `team_id` parameter +- To manage a Team API token, provide the `team_id` parameter and set the + `credential_type` parameter to `team` +- To manage a Legacy Team API token, provide the `team_id` parameter and set the + `credential_type` parameter to `team_legacy` - To manage a User API token, provide a `user_id` parameter -~> **Special Note:** both Organizations and Teams can only have a single active API -token at any given time. Generating a new token for a team or organization will +~> **Special Note:** Organizations and Legacy Teams can only have a single active API +token at any given time. Generating a new token for an organization or legacy team will effectively revoke any existing tokens, regardless if those tokens were -originally created by Vault. As such, requesting an Organization or Team token +originally created by Vault. As such, requesting an Organization or Legacy Team token from Vault will return the same token indefinitely until that token is rotated with the `/rotate-role` endpoint. @@ -124,21 +127,31 @@ information](/terraform/cloud-docs/users-teams-organizations/api-tokens). - `user_id` `(string: "")` – User ID to manage dynamic tokens. Conflicts with `organization` and `team_id`. +- `credential_type` `(string: "")` – Specifies the type of credential to generate. + If unspecified, Vault sets it automatically based on the type of id (defaults to + `team_legacy` if setting `team_id`). Valid values are `team`, `team_legacy`, + `user`, or `organization`. + +- `description` `(string: "")` - Description of the role. Applies to User and + Team API tokens. Used as a prefix to help identify the token in the HCP Terraform UI. + - `ttl` `(duration: "")` – Specifies the TTL for this role. If not - provided, the default Vault TTL is used. Only applies to User API tokens. + provided, the default Vault TTL is used. Applies to User and Team API tokens. Uses [duration format strings](/vault/docs/concepts/duration-format). - `max_ttl` `(duration: "")` – Specifies the max TTL for this role. If not - provided, the default Vault Max TTL is used. Only applies to User API tokens. + provided, the default Vault Max TTL is used. Applies to User and Team API tokens. Uses [duration format strings](/vault/docs/concepts/duration-format). ### Sample payload -To create a Vault role to manage a Terraform Cloud User tokens +To create a Vault role to manage Terraform Cloud User tokens ```json { "user_id": "user-glhf1234", + "credential_type": "user", + "description": "description", "ttl": "1h", "max_ttl": "24h" } @@ -181,6 +194,8 @@ $ curl \ ```json { "data": { + "credential_type": "user", + "description": "description", "max_ttl": 86400, "name": "tfuser", "ttl": 3600, @@ -243,8 +258,8 @@ $ curl \ ## Rotate role This endpoint rotates the credentials for a Terraform Cloud role that manages an -Organization or Team. This endpoint is only valid for those roles; attempting to -rotate a role that manages user tokens will result in an error. +Organization or Legacy Team. This endpoint is only valid for those roles; +attempting to rotate a role that manages User or Team tokens will result in an error. | Method | Path | | :----- | :----------------------------- | @@ -267,8 +282,8 @@ $ curl \ ## Generate credential This endpoint returns a Terraform Cloud token based on the given role -definition. For Organization and Team roles, the same API token is returned -until the token is rotated with `rotate-role`. For User roles, a new token is +definition. For Organization and Legacy Team roles, the same API token is returned +until the token is rotated with `rotate-role`. For User and Team roles, a new token is generated with each request. | Method | Path | diff --git a/website/content/docs/secrets/terraform.mdx b/website/content/docs/secrets/terraform.mdx index bff612db3d..fca9c76b7b 100644 --- a/website/content/docs/secrets/terraform.mdx +++ b/website/content/docs/secrets/terraform.mdx @@ -86,14 +86,14 @@ token_id at-123acbdfask HCP Terraform supports four distinct types of API tokens; Organizations, Teams, Legacy Team Tokens and Users. Each token type has distinct access levels and generation workflows. A given Vault role can manage any one of the -three types at a time, however there are important differences to be aware of. +supported types at a time, however there are important differences to be aware of. ### Organization roles -Generating a new Organization or Team API token by reading the credentials in +Generating a new Organization API token by reading the credentials in Vault or otherwise generating them on [app.terraform.io](https://app.terraform.io/session) will effectively revoke -**any** existing API token for that Organization or Team. +**any** existing API token for that Organization. Due to this behavior, Organization API tokens created by Vault will be stored and returned on future requests, until the credentials get rotated. This @@ -168,7 +168,7 @@ In HCP Terraform, team tokens cannot have matching descriptions. In order to avo collisions, the secret engine generates a random string as a suffix to the description. It is highly recommended you set an additional description. -Below is an example of creating a Vault role to manage manage User API tokens: +Below is an example of creating a Vault role to manage manage Team API tokens: ```shell-session $ vault write terraform/role/team-testing team_id="${TF_TEAM_ID}" credential_type=team description="testing token" ttl=200 max_ttl=600 @@ -199,7 +199,7 @@ reading the credentials in Vault or otherwise generating them on [app.terraform.io](https://app.terraform.io/session) will effectively revoke **any** existing API token for that Team. -Due to this behavior, Team API tokens created by Vault will be stored and +Due to this behavior, Legacy Team API tokens created by Vault will be stored and returned on future requests, until the credentials get rotated. This is to prevent unintentional revocation of tokens that are currently in-use. diff --git a/website/content/docs/updates/release-notes.mdx b/website/content/docs/updates/release-notes.mdx index e6a48e3bea..c6fe872c9a 100644 --- a/website/content/docs/updates/release-notes.mdx +++ b/website/content/docs/updates/release-notes.mdx @@ -336,6 +336,18 @@ Deprecated in 1.20.x | Retired in 1.20.x Learn more: Snowflake overview + + + Terraform support for dynamic team tokens + + GA + Community + + Implement dynamic team token generation in the Terraform Cloud secrets engine. +

+ Learn more: Terraform Cloud overview + +