mirror of
https://github.com/hashicorp/vault.git
synced 2025-08-23 07:31:09 +02:00
Terraform secret engine docs - support multiple team tokens (#30477)
* 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
GitHub
parent
1d317af395
commit
6e67294f4f
@ -58,7 +58,7 @@ management tool.
|
||||
desired User ID.
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
@ -81,21 +81,21 @@ token TJFDSIFDSKFEKZX.FKFKA.akjlfdiouajlkdakadfiowe
|
||||
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,
|
||||
Teams, 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.
|
||||
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.
|
||||
|
||||
### Organization and team roles
|
||||
### Organization roles
|
||||
|
||||
Generating a new Organization or 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 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
|
||||
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:
|
||||
|
||||
```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
|
||||
|
||||
$ vault write -f terraform/rotate-role/testing
|
||||
@ -152,18 +152,78 @@ token <example token>
|
||||
token_id at-fqvtdTQ5kQWcjUfG
|
||||
```
|
||||
|
||||
Please see the [HCP Terraform API
|
||||
Token documentation for more
|
||||
information](/terraform/cloud-docs/users-teams-organizations/api-tokens).
|
||||
### Team roles
|
||||
|
||||
## 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
|
||||
Engine](/vault/tutorials/secrets-management/terraform-secrets-engine)
|
||||
for a step-by-step tutorial.
|
||||
In HCP Terraform, team tokens cannot have matching descriptions. In order to avoid
|
||||
collisions, the secret engine generates a random string as a suffix to the description. It is
|
||||
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
|
||||
[HCP Terraform secrets engine API](/vault/api-docs/secret/terraform) for more
|
||||
details.
|
||||
```shell-session
|
||||
$ vault write terraform/role/team-testing team_id="${TF_TEAM_ID}" credential_type=team description="testing token" ttl=200 max_ttl=600
|
||||
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
|
||||
```
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user