mirrors/vault
1
0
Fork 0
mirror of https://github.com/hashicorp/vault.git synced 2025-08-23 07:31:09 +02:00
Code Issues Projects Releases Wiki Activity

Terraform secret engine docs - support multiple team tokens (#30477)

Browse Source 
* include docs for multi team tokens

* separate legacy team and org token docs

* update to reflect system max_ttl behavior

* Update website/content/docs/secrets/terraform.mdx

Co-authored-by: Yoko Hyakuna <yoko@hashicorp.com>

* Update website/content/docs/secrets/terraform.mdx

Co-authored-by: Yoko Hyakuna <yoko@hashicorp.com>

* Update website/content/docs/secrets/terraform.mdx

Co-authored-by: Yoko Hyakuna <yoko@hashicorp.com>

* Update website/content/docs/secrets/terraform.mdx

---------

Co-authored-by: Yoko Hyakuna <yoko@hashicorp.com>
This commit is contained in:
drewmullen 2025-05-20 11:11:12 -04:00 committed by GitHub
parent 1d317af395
commit 6e67294f4f
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 80 additions and 20 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

100
website/content/docs/secrets/terraform.mdx
View File

@ -58,7 +58,7 @@ management tool.
desired User ID. desired User ID.
```shell-session ```shell-session
$ vault write terraform/role/my-role user_id=user-12345abcde $ vault write terraform/role/my-role user_id=user-12345abcde credential_type=user
Success! Data written to: terraform/role/my-role Success! Data written to: terraform/role/my-role
``` ```
@ -81,21 +81,21 @@ token TJFDSIFDSKFEKZX.FKFKA.akjlfdiouajlkdakadfiowe
token_id at-123acbdfask token_id at-123acbdfask
``` ```
## Organization, team, and user roles ## Organization, legacy team, team, and user roles
HCP Terraform supports three distinct types of API tokens; Organizations, HCP Terraform supports four distinct types of API tokens; Organizations,
Teams, and Users. Each token type has distinct access levels and generation Teams, Legacy Team Tokens and Users. Each token type has distinct access levels
workflows. A given Vault role can manage any one of the three types at a time, and generation workflows. A given Vault role can manage any one of the
however there are important differences to be aware of. three types at a time, however there are important differences to be aware of.
### Organization and team roles ### Organization roles
Generating a new Organization or Team API token by reading the credentials in Generating a new Organization or Team API token by reading the credentials in
Vault or otherwise generating them on Vault or otherwise generating them on
[app.terraform.io](https://app.terraform.io/session) will effectively revoke [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 or Team.
Due to this behavior, Organization and Team API tokens created by Vault will be Due to this behavior, Organization API tokens created by Vault will be
stored and returned on future requests, until the credentials get rotated. This stored and returned on future requests, until the credentials get rotated. This
is to prevent unintentional revocation of tokens that are currently in-use. is to prevent unintentional revocation of tokens that are currently in-use.
@ -103,7 +103,7 @@ Below is an example of creating a Vault role to manage an Organization
API token and rotating the token: API token and rotating the token:
```shell-session ```shell-session
$ vault write terraform/role/testing organization="${TF_ORGANIZATION}" $ vault write terraform/role/testing organization="${TF_ORGANIZATION}" credential_type=organization
Success! Data written to: terraform/role/testing Success! Data written to: terraform/role/testing
$ vault write -f terraform/rotate-role/testing $ vault write -f terraform/rotate-role/testing
@ -152,18 +152,78 @@ token <example token>
token_id at-fqvtdTQ5kQWcjUfG token_id at-fqvtdTQ5kQWcjUfG
``` ```
Please see the [HCP Terraform API ### Team roles
Token documentation for more
information](/terraform/cloud-docs/users-teams-organizations/api-tokens).
## Tutorial The HCP Terraform secret engine creates dynamic Team API tokens by
configuring a Vault role to manage an existing HCP Terraform Team.
The lifecycle of these tokens is managed by Vault and/or HCP Terraform.
Generally, Vault aims to manage tokens in external APIs with revoke actions
taken according to `ttl` and `max_ttl` settings. In addition to that behavior,
using the `max_ttl` Vault will set an `ExpiredAt` date in HCP Terraform
which will ensure the token expires at the Max TTL time. This prevents
Team tokens living past their `max_ttl` if Vault is unable to revoke the token.
Omitting the `max_ttl` value will default to Vault's system `max_ttl`.
Refer to [HCP Terraform Secrets In HCP Terraform, team tokens cannot have matching descriptions. In order to avoid
Engine](/vault/tutorials/secrets-management/terraform-secrets-engine) collisions, the secret engine generates a random string as a suffix to the description. It is
for a step-by-step tutorial. highly recommended you set an additional description.
## API Below is an example of creating a Vault role to manage manage User API tokens:
The HCP Terraform secrets engine has a full HTTP API. Please see the ```shell-session
[HCP Terraform secrets engine API](/vault/api-docs/secret/terraform) for more $ vault write terraform/role/team-testing team_id="${TF_TEAM_ID}" credential_type=team description="testing token" ttl=200 max_ttl=600
details. Success! Data written to: terraform/role/team-testing
```
The API token is retrieved by reading the credentials for the role:
```shell-session
$ vault read terraform/creds/team-testing
Key Value
--- -----
lease_id terraform/creds/team-testing/4oNxB4X0x77IrP51lBMJBiJi
lease_duration 3m20s
lease_renewable true
description testing token(74)
expired_at 2025-05-01T20:10:55Z
token <example token>
token_id at-GDMeMTvn3NhUernt
```
### Legacy team roles (Deprecated)
The HCP Terraform API limits Legacy Team roles to **one active
token at any given time**. Generating a new Legacy Team 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 Team.
Due to this behavior, 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.
Below is an example of creating a Vault role to manage a Legacy Team API token and
rotating the token:
```shell-session
$ vault write terraform/role/legacy-team team_id="${TF_TEAM_ID}" credential_type=team_legacy
Success! Data written to: terraform/role/legacy-team
$ vault write -f terraform/rotate-role/legacy-team
Success! Data written to: terraform/rotate-role/legacy-team
```
The API token is retrieved by reading the credentials for the role:
```shell-session
$ vault read terraform/creds/legacy-team
Key Value
--- -----
organization n/a
role legacy-team
team_id team-<id>
token <example token>
token_id at-fqvtdTQ5kQWcjUfG
```