mirror of
https://github.com/hashicorp/vault.git
synced 2026-02-03 20:40:45 -05:00
Add documentation and release notes entry for the Terraform support for dynamic team tokens feature (#31260)
* Add TFC Dynamic Team Credentials feature to Vault 1.20 release notes * Update website/content/docs/secrets/terraform.mdx * Update website/content/api-docs/secret/terraform.mdx * Remove todo in release notes * Amend Legacy Team section in docs * Add description field to api-docs
This commit is contained in:
Constantin Biguet
GitHub
parent
3611b8b709
commit
e845a467aa
3 changed files with 46 additions and 19 deletions
|
|
@ -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 |
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
|
|
@ -336,6 +336,18 @@ Deprecated in 1.20.x | Retired in 1.20.x
|
|||
Learn more: <a href="/vault/docs/secrets/databases/snowflake">Snowflake</a> overview
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td style={{verticalAlign: 'middle'}}>
|
||||
Terraform support for dynamic team tokens
|
||||
</td>
|
||||
<td style={{verticalAlign: 'middle', textAlign: 'center'}}>GA</td>
|
||||
<td style={{verticalAlign: 'middle', textAlign: 'center'}}>Community</td>
|
||||
<td style={{verticalAlign: 'middle'}}>
|
||||
Implement dynamic team token generation in the Terraform Cloud secrets engine.
|
||||
<br /><br />
|
||||
Learn more: <a href="/vault/docs/secrets/terraform">Terraform Cloud</a> overview
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue