Skip to content

Commit 9f93acf

Browse files
emlanctotemlanctot
authored
Add documentation for new organization level user-token-enabled setting (#952)
This PR adds documentation for our Organization Control for User Tokens project, that will go GA on September 30. Original PR: #862 **Relevant Links:** [JIRA](https://hashicorp.atlassian.net/browse/TF-28425) [RFC](https://go.hashi.co/rfc/tf-1125) [PRD](https://docs.google.com/document/d/13sXhJ6S6-1NU4emMZUWXk01ChSEBpyR8T6HpwaLg_Sk/edit?tab=t.0)
2 parents 5421318 + 75a269f commit 9f93acf

File tree

3 files changed

+36
-5
lines changed

3 files changed

+36
-5
lines changed

‎content/terraform-docs-common/docs/cloud-docs/api-docs/organizations.mdx‎

Lines changed: 12 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -134,7 +134,8 @@ curl \
134134
"owners-team-saml-role-id": null,
135135
"two-factor-conformant": false,
136136
"assessments-enforced": false,
137-
"default-execution-mode": "remote"
137+
"default-execution-mode": "remote",
138+
"user-tokens-enabled": true
138139
},
139140
"relationships": {
140141
"default-agent-pool": {
@@ -223,7 +224,8 @@ curl \
223224
"owners-team-saml-role-id": null,
224225
"two-factor-conformant": false,
225226
"assessments-enforced": false,
226-
"default-execution-mode": "remote"
227+
"default-execution-mode": "remote",
228+
"user-tokens-enabled": true
227229
},
228230
"relationships": {
229231
"default-agent-pool": {
@@ -358,7 +360,8 @@ curl \
358360
"owners-team-saml-role-id": null,
359361
"two-factor-conformant": false,
360362
"assessments-enforced": false,
361-
"default-execution-mode": "remote"
363+
"default-execution-mode": "remote",
364+
"user-tokens-enabled": true
362365
},
363366
"relationships": {
364367
"default-agent-pool": {
@@ -430,6 +433,7 @@ Properties without a default value are required.
430433
| `data.attributes.default-execution-mode` | string | `remote` | Which [execution mode](/terraform/cloud-docs/workspaces/settings#execution-mode) to use by default. Valid values are `remote`, `local`, and `agent`. |
431434
| `data.attributes.default-agent-pool-id` | string | (previous value) | Required when `default-execution-mode` is set to `agent`. The ID of the agent pool belonging to the organization. Do _not_ specify this value if you set `execution-mode` to `remote` or `local`. |
432435
| `data.attributes.enforce-hyok` | boolean | false | Whether or not new workspaces within the organization are created with hold your own key enabled. Your organization must have a primary HYOK configuration before enabling `enforce-hyok`. Hold your own key is only available in HCP Terraform, [learn more](/terraform/cloud-docs/hold-your-own-key). |
436+
| `data.attributes.user-tokens-enabled` | boolean | true | Whether or not user tokens can access an organization's resources through the API. Defaults to `true`. |
433437

434438
### Sample Payload
435439

@@ -512,7 +516,8 @@ curl \
512516
"owners-team-saml-role-id": null,
513517
"two-factor-conformant": false,
514518
"assessments-enforced": false,
515-
"default-execution-mode": "remote"
519+
"default-execution-mode": "remote",
520+
"user-tokens-enabled": true
516521
},
517522
"relationships": {
518523
"default-agent-pool": {
@@ -622,6 +627,7 @@ This PATCH endpoint requires a JSON object with the following properties as a re
622627
| `data.attributes.default-execution-mode` | string | `remote` | Which [execution mode](/terraform/cloud-docs/workspaces/settings#execution-mode) to use by default. Valid values are `remote`, `local`, and `agent`. |
623628
| `data.attributes.default-agent-pool-id` | string | (previous value) | Required when `default-execution-mode` is set to `agent`. The ID of the agent pool belonging to the organization. Do _not_ specify this value if you set `execution-mode` to `remote` or `local`. |
624629
| `data.attributes.enforce-hyok` | boolean | false | Whether or not new workspaces within the organization are created with hold your own key (HYOK) enabled. Your organization must have a primary HYOK configuration before enabling `enforce-hyok`. Hold your own key is only available in HCP Terraform, [learn more](/terraform/cloud-docs/hold-your-own-key). |
630+
| `data.attributes.user-tokens-enabled` | boolean | true | Whether or not user tokens can access an organization's resources through the API. Defaults to `true`. |
625631

626632
### Sample Payload
627633

@@ -702,7 +708,8 @@ curl \
702708
"owners-team-saml-role-id": null,
703709
"two-factor-conformant": false,
704710
"assessments-enforced": false,
705-
"default-execution-mode": "remote"
711+
"default-execution-mode": "remote",
712+
"user-tokens-enabled": true
706713
},
707714
"relationships": {
708715
"default-agent-pool": {

‎content/terraform-docs-common/docs/cloud-docs/users-teams-organizations/api-tokens.mdx‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,26 @@ Refer to [Team Token API](/terraform/cloud-docs/api-docs/team-tokens) and [Organ
1616

1717
API tokens may belong directly to a user. User tokens are the most flexible token type because they inherit permissions from the user they are associated with. For more information on user tokens and how to generate them, see the [Users](/terraform/cloud-docs/users-teams-organizations/users#tokens) documentation.
1818

19+
### Disable user tokens for organizations
20+
21+
By default, user tokens are enabled for organizations. When your organization disables user tokens, the HCP Terraform API blocks user tokens from accessing organization resources.
22+
23+
To disable user tokens for your organization, perform the following steps:
24+
1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise, then navigate to the organization where you want to disable user tokens.
25+
1. Choose **Settings** from the sidebar, then **API tokens**.
26+
1. From the **User Tokens** tab, uncheck the **Allow members to access organization resources with their user tokens** setting.
27+
1. Click **Update settings**.
28+
1. In the confirmation modal, select **Disable**.
29+
1. User tokens are now disabled for this organization.
30+
31+
If your organization has automations that authenticate using user tokens, disabling user tokens can cause those automations to fail.
32+
33+
<Note>
34+
35+
An organization that disables user tokens cannot connect to VCS using the [Github (App)](/terraform/cloud-docs/vcs/github-app), because it relies on user tokens to authenticate. Your organization can use [Github (OAuth) to configure their VCS connections](/terraform/cloud-docs/vcs/github) instead.
36+
37+
</Note>
38+
1939
## Team API Tokens
2040

2141

‎content/terraform-docs-common/docs/cloud-docs/users-teams-organizations/users.mdx‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -202,6 +202,10 @@ To revoke a token, click the **trash can** next to it. That token will no longer
202202

203203
~> **Note**: HCP Terraform does not revoke a user API token's access to an organization when you remove the user from an SSO Identity Provider as 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](https://registry.terraform.io/providers/hashicorp/tfe/latest).
204204

205+
#### Tokens disabled
206+
207+
User tokens can be disabled at the organization level, for more information refer to [User API tokens](/terraform/cloud-docs/users-teams-organizations/api-tokens#user-api-tokens).
208+
205209
### GitHub app OAuth token
206210

207211
Click **Tokens** in the sidebar to manage your GitHub App token. This token lets you connect a workspaces to an available GitHub App installation.

0 commit comments

Comments
 (0)