Skip to content

Commit 2047950

Browse files
committed
add some clarity around the different tokens
1 parent 2433c7e commit 2047950

File tree

1 file changed

+21
-18
lines changed

1 file changed

+21
-18
lines changed

docs/guides/modules/permissions-authentication/pages/openid-connect-tokens.adoc

Lines changed: 21 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -18,21 +18,12 @@ Some advantages to using OIDC over using static credentials:
1818

1919
CircleCI OpenID Connect ID tokens are available in the following environment variables:
2020

21-
[.table-scroll]
22-
--
23-
.Explaining the available OIDC tokens available in environment variables
24-
[cols="1,2", options="header"]
25-
|===
26-
| Environment variable
27-
| Description
21+
* `$CIRCLE_OIDC_TOKEN`
2822
29-
| `$CIRCLE_OIDC_TOKEN`
30-
| The default OIDC token. See <<format-of-the-openid-connect-id-token>> for full details.
23+
* `$CIRCLE_OIDC_TOKEN_V2` - This token includes a different `sub` claim format to include a reference to the source of the change that triggered the job.
24+
25+
See <<format-of-the-openid-connect-id-token>> for full details on the Claims used in each token.
3126

32-
| `$CIRCLE_OIDC_TOKEN_V2`
33-
| Includes a different format for the `sub` claim to include a reference to the repository and branch. See <<format-of-the-openid-connect-id-token>> for full details.
34-
|===
35-
--
3627

3728
CAUTION: **What about forks?** OIDC tokens will only be generated for forked builds if the **Pass secrets to builds from forked pull requests** setting is enabled. Find this option at **Project settings** > **Advanced**. See <<oidc-in-open-source-projects>>.
3829

@@ -514,15 +505,27 @@ CircleCI's OIDC tokens contain the following standard https://openid.net/specs/o
514505
| `sub`
515506
a| The subject. This identifies who is running the CircleCI job and where. `$CIRCLE_OIDC_TOKEN_V2` also includes information about the source of change.
516507

517-
For `$CIRCLE_OIDC_TOKEN` its value is: `"org/<organization_id>/project/<project_id>/user/<user_id>"`, a string, where `organization_id`, `project_id`, and `user_id` are UUIDs that identify the CircleCI organization, project, and user, respectively. The user is the CircleCI user that caused this job to run.
508+
---
518509

519-
For `$CIRCLE_OIDC_TOKEN_V2` its value depends on the trigger type:
510+
For `$CIRCLE_OIDC_TOKEN` its value is:
520511

521-
* If the trigger is an xref:orchestrate:triggers-overview.adoc#trigger-a-pipeline-from-a-custom-webhook[Custom Webhook] then:
522512
`"org/<organization_id>/project/<project_id>/user/<user_id>"`, a string, where `organization_id`, `project_id`, and `user_id` are UUIDs that identify the CircleCI organization, project, and user, respectively. The user is the CircleCI user that caused this job to run.
523513

524-
* Otherwise it will be:
525-
`"org/<organization_id>/project/<project_id>/user/<user_id>/vcs-origin/<vcs_origin>/vcs-ref/<vcs_ref>"`, a string, where `organization_id`, `project_id`, and `user_id` are UUIDs that identify the CircleCI organization, project, and user, respectively. The user is the CircleCI user that caused this job to run. `vcs_origin` and `vcs_ref` are strings that identify the repository URL and reference to the change that caused the job to run.
514+
---
515+
516+
For `$CIRCLE_OIDC_TOKEN_V2` its value depends on the trigger type:
517+
518+
*If the trigger is a* xref:orchestrate:triggers-overview.adoc#trigger-a-pipeline-from-a-custom-webhook[Custom Webhook]:
519+
520+
`"org/<organization_id>/project/<project_id>/user/<user_id>"`
521+
522+
A string in which `organization_id`, `project_id`, and `user_id` are UUIDs that identify the CircleCI organization, project, and user, respectively. The user is the CircleCI user that caused this job to run.
523+
524+
*All other trigger types*:
525+
526+
`"org/<organization_id>/project/<project_id>/user/<user_id>/vcs-origin/<vcs_origin>/vcs-ref/<vcs_ref>"`
527+
528+
A string in which `organization_id`, `project_id`, and `user_id` are UUIDs that identify the CircleCI organization, project, and user, respectively. The user is the CircleCI user that caused this job to run. `vcs_origin` and `vcs_ref` are strings that identify the repository URL and reference to the change that caused the job to run.
526529

527530
| `aud`
528531
| The audience. By default, this is `ORGANIZATION_ID`, a string containing a UUID that identifies the job's project's organization. To customize the audience you can generate an OIDC token with a custom audience. See xref:oidc-tokens-with-custom-claims.adoc[OIDC Tokens With Custom Claims] for more information.

0 commit comments

Comments
 (0)