From 6bcfb30034f707e5e56810359b36b5e33a12f4e4 Mon Sep 17 00:00:00 2001 From: Joe Clark <31087804+jc-clark@users.noreply.github.com> Date: Thu, 10 Jul 2025 14:28:02 -0700 Subject: [PATCH 1/2] [EDI] Actions OIDC content (#56561) Co-authored-by: Sam Browning <106113886+sabrowning1@users.noreply.github.com> --- content/actions/concepts/security/index.md | 2 +- .../concepts/security/openid-connect.md | 123 ++++++++++ ...g-openid-connect-in-amazon-web-services.md | 2 +- content/actions/reference/index.md | 1 + .../openid-connect-reference.md} | 227 ++++++------------ .../actions/oidc-permissions-token.md | 30 +-- 6 files changed, 204 insertions(+), 181 deletions(-) create mode 100644 content/actions/concepts/security/openid-connect.md rename content/actions/{concepts/security/about-security-hardening-with-openid-connect.md => reference/openid-connect-reference.md} (67%) diff --git a/content/actions/concepts/security/index.md b/content/actions/concepts/security/index.md index 2964b697cad2..2fcb12d44ef7 100644 --- a/content/actions/concepts/security/index.md +++ b/content/actions/concepts/security/index.md @@ -9,6 +9,6 @@ versions: children: - /secrets - /github_token - - /about-security-hardening-with-openid-connect + - /openid-connect --- diff --git a/content/actions/concepts/security/openid-connect.md b/content/actions/concepts/security/openid-connect.md new file mode 100644 index 000000000000..3a36a847445f --- /dev/null +++ b/content/actions/concepts/security/openid-connect.md @@ -0,0 +1,123 @@ +--- +title: OpenID Connect +shortTitle: OpenID Connect +intro: OpenID Connect allows your workflows to exchange short-lived tokens directly from your cloud provider. +versions: + fpt: '*' + ghec: '*' + ghes: '*' +type: tutorial +topics: + - Security +redirect_from: + - /actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect + - /actions/security-for-github-actions/security-hardening-your-deployments/about-security-hardening-with-openid-connect + - /actions/concepts/security/about-security-hardening-with-openid-connect +--- + +## Overview of OpenID Connect (OIDC) + +{% data variables.product.prodname_actions %} workflows are often designed to access a cloud provider (such as AWS, Azure, GCP, HashiCorp Vault, and others) in order to deploy software or use the cloud's services. Before the workflow can access these resources, it will supply credentials, such as a password or token, to the cloud provider. These credentials are usually stored as a secret in {% data variables.product.prodname_dotcom %}, and the workflow presents this secret to the cloud provider every time it runs. + +However, using hardcoded secrets requires you to create credentials in the cloud provider and then duplicate them in {% data variables.product.prodname_dotcom %} as a secret. + +After you have established a trust connection with a cloud provider that supports OIDC, you can you can configure your workflow to request a short-lived access token directly from the cloud provider. + +## Benefits of using OIDC + +By updating your workflows to use OIDC tokens, you can adopt the following good security practices: + +* **No cloud secrets:** You won't need to duplicate your cloud credentials as long-lived {% data variables.product.github %} secrets. Instead, you can configure the OIDC trust on your cloud provider, and then update your workflows to request a short-lived access token from the cloud provider through OIDC. +* **Authentication and authorization management:** You have more granular control over how workflows can use credentials, using your cloud provider's authentication (authN) and authorization (authZ) tools to control access to cloud resources. +* **Rotating credentials:** With OIDC, your cloud provider issues a short-lived access token that is only valid for a single job, and then automatically expires. + +## How OIDC integrates with {% data variables.product.prodname_actions %} + +The following diagram gives an overview of how {% data variables.product.github %}'s OIDC provider integrates with your workflows and cloud provider: + +![Diagram of how a cloud provider integrates with {% data variables.product.prodname_actions %} through access tokens and JSON web token cloud role IDs.](/assets/images/help/actions/oidc-architecture.png) + +1. You establish an OIDC trust relationship in the cloud provider, allowing specific {% data variables.product.github %} workflows to request cloud access tokens on behalf of a defined cloud role. +1. Every time your job runs, {% data variables.product.prodname_dotcom %}'s OIDC provider auto-generates an OIDC token. This token contains multiple claims to establish a security-hardened and verifiable identity about the specific workflow that is trying to authenticate. +1. A step or action in the workflow job can request a token from {% data variables.product.github %}’s OIDC provider, which can then be presented to the cloud provider as proof of the workflow’s identity. +1. Once the cloud provider successfully validates the claims presented in the token, it then provides a short-lived cloud access token that is available only for the duration of the job. + +## Understanding the OIDC token + +Each job requests an OIDC token from {% data variables.product.prodname_dotcom %}'s OIDC provider, which responds with an automatically generated JSON web token (JWT) that is unique for each workflow job where it is generated. When the job runs, the OIDC token is presented to the cloud provider. To validate the token, the cloud provider checks if the OIDC token's subject and other claims are a match for the conditions that were preconfigured on the cloud role's OIDC trust definition. + +The following example OIDC token uses a subject (`sub`) that references a job environment named `prod` in the `octo-org/octo-repo` repository. + +```yaml +{ + "typ": "JWT", + "alg": "RS256", + "x5t": "example-thumbprint", + "kid": "example-key-id" +} +{ + "jti": "example-id", + "sub": "repo:octo-org/octo-repo:environment:prod", + "environment": "prod", + "aud": "{% ifversion ghes %}https://HOSTNAME{% else %}https://github.com{% endif %}/octo-org", + "ref": "refs/heads/main", + "sha": "example-sha", + "repository": "octo-org/octo-repo", + "repository_owner": "octo-org", + "actor_id": "12", + "repository_visibility": "private", + "repository_id": "74", + "repository_owner_id": "65", + "run_id": "example-run-id", + "run_number": "10", + "run_attempt": "2", + "runner_environment": "github-hosted", + "actor": "octocat", + "workflow": "example-workflow", + "head_ref": "", + "base_ref": "", + "event_name": "workflow_dispatch",{% ifversion actions-OIDC-custom-claim-enterprise %} + "enterprise": "avocado-corp",{% endif %}{% ifversion actions-OIDC-enterprise_id-claim %} + "enterprise_id": "2",{% endif %} + "ref_type": "branch", + "job_workflow_ref": "octo-org/octo-automation/.github/workflows/oidc.yml@refs/heads/main", + "iss": "{% ifversion ghes %}https://HOSTNAME/_services/token{% else %}https://token.actions.githubusercontent.com{% endif %}", + "nbf": 1632492967, + "exp": 1632493867, + "iat": 1632493567 +} +``` + +{% ifversion ghec %} + +## Establishing OIDC trust with your cloud provider + +To use OIDC in your workflows, you must establish a trust relationship between {% data variables.product.github %} and your cloud provider. This trust relationship ensures that only authorized workflows can request access tokens for your cloud resources. + +Before granting an access token, your cloud provider checks that the [`subject`](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims) and any other claims used to set conditions in its trust settings match those in the request's JSON Web Token (JWT). If the trust configuration matches, your cloud provider issues a temporary access token to the workflow. + +For steps and syntax for configuring OIDC trust and setting conditions for cloud providers, see [AUTOTITLE](/actions/reference/openid-connect-reference#oidc-claims-used-to-define-trust-conditions-on-cloud-roles). + +## Configuring OIDC on {% data variables.enterprise.data_residency_site %} + +If you are part of an enterprise that uses {% data variables.enterprise.data_residency %} and you're setting up OIDC on {% data variables.enterprise.data_residency_site %}, you must **substitute certain values** while configuring OIDC. + +For more information, see [AUTOTITLE](/enterprise-cloud@latest/actions/reference/openid-connect-reference#substituted-values-on-ghecom). + +{% endif %} + +## Authenticating custom actions using OIDC + +Custom actions use the `getIDToken()` method from the Actions toolkit or a `curl` command to authenticate using OIDC. + +For more information, see [AUTOTITLE](/actions/reference/openid-connect-reference#methods-for-requesting-the-oidc-token). + +## Updating your workflows for OIDC + +{% data variables.product.prodname_actions %} workflows can use OIDC tokens instead of secrets to authenticate with cloud providers. Many popular cloud providers offer official login actions that simplify the process of using OIDC in your workflows. For more information about updating your workflows with specific cloud providers, see [AUTOTITLE](/actions/how-tos/security-for-github-actions/security-hardening-your-deployments). + +## Next steps + +For more information about configuring OIDC, see [AUTOTITLE](/actions/how-tos/security-for-github-actions/security-hardening-your-deployments). + +For reference information about OIDC, see [AUTOTITLE](/actions/reference/openid-connect-reference). diff --git a/content/actions/how-tos/security-for-github-actions/security-hardening-your-deployments/configuring-openid-connect-in-amazon-web-services.md b/content/actions/how-tos/security-for-github-actions/security-hardening-your-deployments/configuring-openid-connect-in-amazon-web-services.md index a2d0361da4e0..88cbfe14ba5b 100644 --- a/content/actions/how-tos/security-for-github-actions/security-hardening-your-deployments/configuring-openid-connect-in-amazon-web-services.md +++ b/content/actions/how-tos/security-for-github-actions/security-hardening-your-deployments/configuring-openid-connect-in-amazon-web-services.md @@ -69,7 +69,7 @@ Edit the trust policy, adding the `sub` field to the validation conditions. For } ``` -If you use a workflow with an environment, the `sub` field must reference the environment name: `repo:ORG-NAME/REPO-NAME:environment:ENVIRONMENT-NAME`. For more information, see [AUTOTITLE](/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect#understanding-the-oidc-token). +If you use a workflow with an environment, the `sub` field must reference the environment name: `repo:ORG-NAME/REPO-NAME:environment:ENVIRONMENT-NAME`. For more information, see [AUTOTITLE](/actions/reference/openid-connect-reference#filtering-for-a-specific-environment). {% data reusables.actions.oidc-deployment-protection-rules %} diff --git a/content/actions/reference/index.md b/content/actions/reference/index.md index b68aa030d3b7..844eb80aba35 100644 --- a/content/actions/reference/index.md +++ b/content/actions/reference/index.md @@ -19,6 +19,7 @@ children: - /metadata-syntax-reference - /actions-limits - /reusable-workflows-reference + - /openid-connect-reference - /github_token-reference - /dockerfile-support-for-github-actions - /github-hosted-runners-reference diff --git a/content/actions/concepts/security/about-security-hardening-with-openid-connect.md b/content/actions/reference/openid-connect-reference.md similarity index 67% rename from content/actions/concepts/security/about-security-hardening-with-openid-connect.md rename to content/actions/reference/openid-connect-reference.md index 94181eba803d..79264d3e340f 100644 --- a/content/actions/concepts/security/about-security-hardening-with-openid-connect.md +++ b/content/actions/reference/openid-connect-reference.md @@ -1,105 +1,23 @@ --- -title: About security hardening with OpenID Connect -shortTitle: Security hardening with OpenID Connect -intro: OpenID Connect allows your workflows to exchange short-lived tokens directly from your cloud provider. +title: OpenID Connect reference +shortTitle: OpenID Connect reference +intro: Find information about using OpenID Connect (OIDC) to authenticate {% data variables.product.prodname_actions %} workflows with cloud providers. versions: fpt: '*' ghec: '*' ghes: '*' -type: tutorial topics: - Security -redirect_from: - - /actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect - - /actions/security-for-github-actions/security-hardening-your-deployments/about-security-hardening-with-openid-connect --- -{% data reusables.actions.enterprise-github-hosted-runners %} - -## Overview of OpenID Connect - -{% data variables.product.prodname_actions %} workflows are often designed to access a cloud provider (such as AWS, Azure, GCP, or HashiCorp Vault) in order to deploy software or use the cloud's services. Before the workflow can access these resources, it will supply credentials, such as a password or token, to the cloud provider. These credentials are usually stored as a secret in {% data variables.product.prodname_dotcom %}, and the workflow presents this secret to the cloud provider every time it runs. - -However, using hardcoded secrets requires you to create credentials in the cloud provider and then duplicate them in {% data variables.product.prodname_dotcom %} as a secret. - -With OpenID Connect (OIDC), you can take a different approach by configuring your workflow to request a short-lived access token directly from the cloud provider. Your cloud provider also needs to support OIDC on their end, and you must configure a trust relationship that controls which workflows are able to request the access tokens. Providers that currently support OIDC include Amazon Web Services, Azure, Google Cloud Platform, and HashiCorp Vault, among others. - -### Benefits of using OIDC - -By updating your workflows to use OIDC tokens, you can adopt the following good security practices: - -* **No cloud secrets:** You won't need to duplicate your cloud credentials as long-lived {% data variables.product.prodname_dotcom %} secrets. Instead, you can configure the OIDC trust on your cloud provider, and then update your workflows to request a short-lived access token from the cloud provider through OIDC. -* **Authentication and authorization management:** You have more granular control over how workflows can use credentials, using your cloud provider's authentication (authN) and authorization (authZ) tools to control access to cloud resources. -* **Rotating credentials:** With OIDC, your cloud provider issues a short-lived access token that is only valid for a single job, and then automatically expires. - -### Getting started with OIDC - -The following diagram gives an overview of how {% data variables.product.prodname_dotcom %}'s OIDC provider integrates with your workflows and cloud provider: - -![Diagram of how a cloud provider integrates with {% data variables.product.prodname_actions %} through access tokens and JSON web token cloud role IDs.](/assets/images/help/actions/oidc-architecture.png) - -1. In your cloud provider, create an OIDC trust between your cloud role and your {% data variables.product.prodname_dotcom %} workflow(s) that need access to the cloud. -1. Every time your job runs, {% data variables.product.prodname_dotcom %}'s OIDC Provider auto-generates an OIDC token. This token contains multiple claims to establish a security-hardened and verifiable identity about the specific workflow that is trying to authenticate. -1. You could include a step or action in your job to request this token from {% data variables.product.prodname_dotcom %}'s OIDC provider, and present it to the cloud provider. -1. Once the cloud provider successfully validates the claims presented in the token, it then provides a short-lived cloud access token that is available only for the duration of the job. - -## Configuring the OIDC trust with the cloud - -When you configure your cloud to trust {% data variables.product.prodname_dotcom %}'s OIDC provider, you **must** add conditions that filter incoming requests, so that untrusted repositories or workflows can’t request access tokens for your cloud resources: - -* Before granting an access token, your cloud provider checks that the [`subject`](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims) and other claims used to set conditions in its trust settings match those in the request's JSON Web Token (JWT). As a result, you must take care to correctly define the _subject_ and other conditions in your cloud provider. -* The OIDC trust configuration steps and the syntax to set conditions for cloud roles (using _Subject_ and other claims) will vary depending on which cloud provider you're using. For some examples, see [Example subject claims](#example-subject-claims). - -### Understanding the OIDC token - -Each job requests an OIDC token from {% data variables.product.prodname_dotcom %}'s OIDC provider, which responds with an automatically generated JSON web token (JWT) that is unique for each workflow job where it is generated. When the job runs, the OIDC token is presented to the cloud provider. To validate the token, the cloud provider checks if the OIDC token's subject and other claims are a match for the conditions that were preconfigured on the cloud role's OIDC trust definition. - -The following example OIDC token uses a subject (`sub`) that references a job environment named `prod` in the `octo-org/octo-repo` repository. - -```yaml -{ - "typ": "JWT", - "alg": "RS256", - "x5t": "example-thumbprint", - "kid": "example-key-id" -} -{ - "jti": "example-id", - "sub": "repo:octo-org/octo-repo:environment:prod", - "environment": "prod", - "aud": "{% ifversion ghes %}https://HOSTNAME{% else %}https://github.com{% endif %}/octo-org", - "ref": "refs/heads/main", - "sha": "example-sha", - "repository": "octo-org/octo-repo", - "repository_owner": "octo-org", - "actor_id": "12", - "repository_visibility": "private", - "repository_id": "74", - "repository_owner_id": "65", - "run_id": "example-run-id", - "run_number": "10", - "run_attempt": "2", - "runner_environment": "github-hosted", - "actor": "octocat", - "workflow": "example-workflow", - "head_ref": "", - "base_ref": "", - "event_name": "workflow_dispatch",{% ifversion actions-OIDC-custom-claim-enterprise %} - "enterprise": "avocado-corp",{% endif %}{% ifversion actions-OIDC-enterprise_id-claim %} - "enterprise_id": "2",{% endif %} - "ref_type": "branch", - "job_workflow_ref": "octo-org/octo-automation/.github/workflows/oidc.yml@refs/heads/main", - "iss": "{% ifversion ghes %}https://HOSTNAME/_services/token{% else %}https://token.actions.githubusercontent.com{% endif %}", - "nbf": 1632492967, - "exp": 1632493867, - "iat": 1632493567 -} -``` +## OIDC token claims To see all the claims supported by {% data variables.product.prodname_dotcom %}'s OIDC provider, review the `claims_supported` entries at {% ifversion ghes %}`https://HOSTNAME/_services/token/.well-known/openid-configuration`{% else %}https://token.actions.githubusercontent.com/.well-known/openid-configuration{% endif %}. -The token includes the standard audience, issuer, and subject claims. +The OIDC token includes the following claims. + +### Standard audience, issuer, and subject claims | Claim | Claim type | Description | | ----------- | -----| ---------------------- | @@ -107,7 +25,7 @@ The token includes the standard audience, issuer, and subject claims. | `iss`| Issuer | The issuer of the OIDC token: {% ifversion ghes %}`https://HOSTNAME/_services/token`{% else %}`https://token.actions.githubusercontent.com`{% endif %} | | `sub`| Subject | Defines the subject claim that is to be validated by the cloud provider. This setting is essential for making sure that access tokens are only allocated in a predictable way. | -The OIDC token also includes additional standard JOSE header parameters and claims. +### Additional standard JOSE header parameters and claims | Header Parameter | Parameter type | Description | | ----------- | -----| ---------------------- | @@ -122,7 +40,7 @@ The OIDC token also includes additional standard JOSE header parameters and clai | `jti`| JWT token identifier | Unique identifier for the OIDC token. | | `nbf`| Not before | JWT is not valid for use before this time. | -The token also includes custom claims provided by {% data variables.product.prodname_dotcom %}. +### Custom claims provided by {% data variables.product.prodname_dotcom %} | Claim | Description | | ----------- | ---------------------- | @@ -155,11 +73,24 @@ The token also includes custom claims provided by {% data variables.product.prod | `workflow_ref`| {% data reusables.actions.workflow-ref-description %} | | `workflow_sha`| {% data reusables.actions.workflow-sha-description %} | -### Defining trust conditions on cloud roles using OIDC claims +{% ifversion ghec %} + +## Substituted values on {% data variables.enterprise.data_residency_site %} -With OIDC, a {% data variables.product.prodname_actions %} workflow requires a token in order to access resources in your cloud provider. The workflow requests an access token from your cloud provider, which checks the details presented by the JWT. If the trust configuration in the JWT is a match, your cloud provider responds by issuing a temporary token to the workflow, which can then be used to access resources in your cloud provider. You can configure your cloud provider to only respond to requests that originate from a specific organization's repository. You can also specify additional conditions, described below. +* Your provider's expected claim must substitute `githubusercontent.com` with `{% data variables.enterprise.data_residency_domain %}`, where SUBDOMAIN is your enterprise's subdomain on {% data variables.enterprise.data_residency_site %}. +* For any URLs that include a route with your enterprise's name or slug, you must substitute your enterprise's subdomain on {% data variables.enterprise.data_residency_site %}. -Audience and Subject claims are typically used in combination while setting conditions on the cloud role/resources to scope its access to the GitHub workflows. +For example, if your subdomain is `octocorp`, the following substitutions apply: + +* The URL for seeing all the claims supported by {% data variables.product.company_short %}'s OIDC provider would be `https://token.actions.octocorp.ghe.com/.well-known/openid-configuration`. +* The value of `iss` in your OIDC token would be `https://token.actions.octocorp.ghe.com`. +* The enterprise can receive tokens at `https://token.actions.octocorp.ghe.com/octocorp`, and the REST API endpoint for customizing the `issuer` value would be `/enterprises/octocorp/actions/oidc/customization/issuer`. + +{% endif %} + +## OIDC claims used to define trust conditions on cloud roles + +Audience and subject claims are typically used in combination while setting conditions on the cloud role/resources to scope its access to the {% data variables.product.github %} workflows. * **Audience:** By default, this value uses the URL of the organization or repository owner. This can be used to set a condition that only the workflows in the specific organization can access the cloud role. * **Subject:** By default, has a predefined format and is a concatenation of some of the key metadata about the workflow, such as the {% data variables.product.prodname_dotcom %} organization, repository, branch, or associated [`job`](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idenvironment) environment. See [Example subject claims](#example-subject-claims) to see how the subject claim is assembled from concatenated metadata. @@ -170,11 +101,11 @@ There are also many additional claims supported in the OIDC token that can be us > [!NOTE] > To control how your cloud provider issues access tokens, you **must** define at least one condition, so that untrusted repositories can’t request access tokens for your cloud resources. -### Example subject claims +## Example subject claims The following examples demonstrate how to use "Subject" as a condition, and explain how the "Subject" is assembled from concatenated metadata. The [subject](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims) uses information from the [`job` context](/actions/learn-github-actions/contexts#job-context), and instructs your cloud provider that access token requests may only be granted for requests from workflows running in specific branches, environments. The following sections describe some common subjects you can use. -#### Filtering for a specific environment +### Filtering for a specific environment The subject claim includes the environment name when the job references an environment. @@ -183,7 +114,7 @@ You can configure a subject that filters for a specific [environment](/actions/d * Syntax: `repo:ORG-NAME/REPO-NAME:environment:ENVIRONMENT-NAME` * Example: `repo:octo-org/octo-repo:environment:Production` -#### Filtering for `pull_request` events +### Filtering for `pull_request` events The subject claim includes the `pull_request` string when the workflow is triggered by a pull request event, but only if the job doesn't reference an environment. @@ -192,7 +123,7 @@ You can configure a subject that filters for the [`pull_request`](/actions/using * Syntax: `repo:ORG-NAME/REPO-NAME:pull_request` * Example: `repo:octo-org/octo-repo:pull_request` -#### Filtering for a specific branch +### Filtering for a specific branch The subject claim includes the branch name of the workflow, but only if the job doesn't reference an environment, and if the workflow is not triggered by a pull request event. @@ -201,7 +132,7 @@ You can configure a subject that filters for a specific branch name. In this exa * Syntax: `repo:ORG-NAME/REPO-NAME:ref:refs/heads/BRANCH-NAME` * Example: `repo:octo-org/octo-repo:ref:refs/heads/demo-branch` -#### Filtering for a specific tag +### Filtering for a specific tag The subject claim includes the tag name of the workflow, but only if the job doesn't reference an environment, and if the workflow is not triggered by a pull request event. @@ -210,7 +141,7 @@ You can create a subject that filters for specific tag. In this example, the wor * Syntax: `repo:ORG-NAME/REPO-NAME:ref:refs/tags/TAG-NAME` * Example: `repo:octo-org/octo-repo:ref:refs/tags/demo-tag` -### Configuring the subject in your cloud provider +## Configuring the subject in your cloud provider To configure the subject in your cloud provider's trust relationship, you must add the subject string to its trust configuration. The following examples demonstrate how various cloud providers can accept the same `repo:octo-org/octo-repo:ref:refs/heads/demo-branch` subject in different ways: @@ -221,28 +152,7 @@ To configure the subject in your cloud provider's trust relationship, you must a | Google Cloud Platform| `(assertion.sub=='repo:octo-org/octo-repo:ref:refs/heads/demo-branch')` | | HashiCorp Vault| `bound_subject="repo:octo-org/octo-repo:ref:refs/heads/demo-branch"` | -For more information, see the guides listed in [Enabling OpenID Connect for your cloud provider](#enabling-openid-connect-for-your-cloud-provider). - -## Updating your actions for OIDC - -To update your custom actions to authenticate using OIDC, you can use `getIDToken()` from the Actions toolkit to request a JWT from {% data variables.product.prodname_dotcom %}'s OIDC provider. For more information, see "OIDC Token" in the [npm package documentation](https://www.npmjs.com/package/@actions/core/v/1.6.0). - -You could also use a `curl` command to request the JWT, using the following environment variables. - -| Variable | Description | -| ------ | ----------- | -| `ACTIONS_ID_TOKEN_REQUEST_URL` | The URL for {% data variables.product.prodname_dotcom %}'s OIDC provider. | -| `ACTIONS_ID_TOKEN_REQUEST_TOKEN` | Bearer token for the request to the OIDC provider. | - -For example: - -```shell copy -curl -H "Authorization: bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" "$ACTIONS_ID_TOKEN_REQUEST_URL&audience=api://AzureADTokenExchange" -``` - -### Adding permissions settings - -{% data reusables.actions.oidc-permissions-token %} +For more information about configuring specific cloud providers, see the guides listed in [AUTOTITLE](/actions/how-tos/security-for-github-actions/security-hardening-your-deployments). ## Customizing the token claims @@ -250,7 +160,7 @@ You can security harden your OIDC configuration by customizing the claims that a * You can customize values for {% ifversion ghec %}`issuer` or {% endif %}`audience` claims. See {% ifversion ghec %}[Customizing the `issuer` value for an enterprise](#customizing-the-issuer-value-for-an-enterprise) and {% endif %}[Customizing the `audience` value](#customizing-the-audience-value). * You can customize the format of your OIDC configuration by setting conditions on the subject (`sub`) claim that require JWT tokens to originate from a specific repository, reusable workflow, or other source. -* You can define granular OIDC policies by using additional OIDC token claims, such as `repository_id` and `repository_visibility`. See [Understanding the OIDC token](#understanding-the-oidc-token). +* You can define granular OIDC policies by using additional OIDC token claims, such as `repository_id` and `repository_visibility`. See [AUTOTITLE](/actions/concepts/security/openid-connect#understanding-the-oidc-token). ### Customizing the `audience` value @@ -295,7 +205,7 @@ To help improve security, compliance, and standardization, you can customize the > [!NOTE] > When the organization template is applied, it will not affect any workflows already using OIDC unless their repository has opted in to custom organization templates. For all repositories, existing and new, the repository owner will need to use the repository-level REST API to opt in to receive this configuration by setting `use_default` to `false`. Alternatively, the repository owner could use the REST API to apply a different configuration specific to the repository. For more information, see [AUTOTITLE](/rest/actions/oidc#set-the-customization-template-for-an-oidc-subject-claim-for-a-repository). -Customizing the claims results in a new format for the entire `sub` claim, which replaces the default predefined `sub` format in the token described in [AUTOTITLE](/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect#example-subject-claims). +Customizing the claims results in a new format for the entire `sub` claim, which replaces the default predefined `sub` format in the token described in [Example subject claims](#example-subject-claims). > [!NOTE] > The `sub` claim uses the shortened form `repo` (for example, `repo:ORG-NAME/REPO-NAME`) instead of `repository` to reference the repository. {% ifversion fpt or ghec or ghes > 3.15 %} @@ -341,7 +251,7 @@ In your cloud provider's OIDC configuration, configure the `sub` condition to re #### Example: Requiring a reusable workflow -This example template allows the `sub` claim to have a new format that contains the value of the `job_workflow_ref` claim. This enables an enterprise to use [reusable workflows](/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect#example-subject-claims) to enforce consistent deployments across its organizations and repositories. +This example template allows the `sub` claim to have a new format that contains the value of the `job_workflow_ref` claim. This enables an enterprise to use reusable workflows to enforce consistent deployments across its organizations and repositories. {% data reusables.actions.use-request-body-api %} @@ -361,7 +271,7 @@ The following example template combines the requirement of a specific reusable w {% data reusables.actions.use-request-body-api %} -This example also demonstrates how to use `"context"` to define your conditions. This is the part that follows the repository in the [default `sub` format](/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect#example-subject-claims). For example, when the job references an environment, the context contains: `environment:ENVIRONMENT-NAME`. +This example also demonstrates how to use `"context"` to define your conditions. This is the part that follows the repository in the default `sub` format. For example, when the job references an environment, the context contains: `environment:ENVIRONMENT-NAME`. ```json { @@ -485,48 +395,61 @@ To configure the repository to use the organization's template, a repository adm } ``` -## Updating your workflows for OIDC +## Debugging your OIDC claims -You can now update your YAML workflows to use OIDC access tokens instead of secrets. Popular cloud providers have published their official login actions that make it easy for you to get started with OIDC. For more information about updating your workflows, see the cloud-specific guides listed below in [Enabling OpenID Connect for your cloud provider](#enabling-openid-connect-for-your-cloud-provider). +You can use the [`github/actions-oidc-debugger`](https://github.com/github/actions-oidc-debugger) action to visualize the claims that would be sent, before integrating with a cloud provider. This action requests a JWT and prints the claims included within the JWT that were received from {% data variables.product.prodname_actions %}. -{% ifversion fpt or ghec %} +## Workflow permissions for the requesting the OIDC token -## Enabling OpenID Connect for Python package publishing +### Required permission -You can use a {% data variables.product.prodname_actions %} workflow in a repository as a trusted publisher for a PyPI project. Using a workflow as a trusted publisher allows OIDC access tokens to be exchanged for temporary PyPI API tokens. For more information, see [AUTOTITLE](/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-pypi) and [Publishing to PyPI with a Trusted Publisher](https://docs.pypi.org/trusted-publishers/) in the PyPI documentation. +* The job or workflow must grant the [`id-token: write`](/actions/reference/github_token-reference#permissions-for-the-github_token) permission to allow {% data variables.product.github %}'s OIDC provider to create a JSON Web Token (JWT): -{% endif %} + ```yaml + permissions: + id-token: write + ``` -## Enabling OpenID Connect for your cloud provider +* Without `id-token: write`, the OIDC JWT ID token cannot be requested. This setting only enables fetching and setting the OIDC token; it does not grant write access to other resources. -To enable and configure OIDC for your specific cloud provider, see the following guides: +### Setting permissions -* [AUTOTITLE](/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-amazon-web-services) -* [AUTOTITLE](/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-azure) -* [AUTOTITLE](/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-google-cloud-platform) -* [AUTOTITLE](/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-hashicorp-vault) +* To fetch an OIDC token for a workflow, set the permission at the workflow level: -To enable and configure OIDC for another cloud provider, see the following guide: + ```yaml + permissions: + id-token: write # This is required for requesting the JWT + contents: read # This is required for actions/checkout + ``` -* [AUTOTITLE](/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-cloud-providers) +* To fetch an OIDC token for a single job, set the permission within that job: -{% ifversion ghec %} + ```yaml + permissions: + id-token: write # This is required for requesting the JWT + ``` -### Following these guides on {% data variables.enterprise.data_residency_site %} +* Additional permissions may be required depending on workflow needs. -If you are part of an enterprise that uses {% data variables.enterprise.data_residency %} and you're setting up OIDC on {% data variables.enterprise.data_residency_site %}, you must **substitute certain values** in the linked articles. +### Reusable workflows -* Your provider's expected claim must substitute `githubusercontent.com` with `{% data variables.enterprise.data_residency_domain %}`, where SUBDOMAIN is your enterprise's subdomain on {% data variables.enterprise.data_residency_site %}. -* For any URLs that include a route with your enterprise's name or slug, you must substitute your enterprise's subdomain on {% data variables.enterprise.data_residency_site %}. +* For reusable workflows owned by the same user, organization, or enterprise as the caller, the OIDC token generated in the reusable workflow is accessible from the caller's context. +* For reusable workflows outside your enterprise or organization, set the `permissions` setting for `id-token` to `write` explicitly at the caller workflow or job level. This ensures the OIDC token is only available to intended caller workflows. -For example, if your subdomain is `octocorp`, the following substitutions apply: +## Methods for requesting the OIDC token -* The URL for seeing all the claims supported by {% data variables.product.company_short %}'s OIDC provider would be `https://token.actions.octocorp.ghe.com/.well-known/openid-configuration`. -* The value of `iss` in your OIDC token would be `https://token.actions.octocorp.ghe.com`. -* The enterprise can receive tokens at `https://token.actions.octocorp.ghe.com/octocorp`, and the REST API endpoint for customizing the `issuer` value would be `/enterprises/octocorp/actions/oidc/customization/issuer`. +Custom actions can request the OIDC token using: -{% endif %} +* The `getIDToken()` method from the Actions toolkit. For more information, see [OIDC Token](https://www.npmjs.com/package/@actions/core/v/1.6.0#oidc-token) in the npm package documentation. +* The following environment variables on the runner. -## Debugging your OIDC claims + | Variable | Description | + | ------ | ----------- | + | `ACTIONS_ID_TOKEN_REQUEST_URL` | The URL for {% data variables.product.prodname_dotcom %}'s OIDC provider. | + | `ACTIONS_ID_TOKEN_REQUEST_TOKEN` | Bearer token for the request to the OIDC provider. | -You can use the [`github/actions-oidc-debugger`](https://github.com/github/actions-oidc-debugger) action to visualize the claims that would be sent, before integrating with a cloud provider. This action requests a JWT and prints the claims included within the JWT that were received from {% data variables.product.prodname_actions %}. + For example: + + ```shell copy + curl -H "Authorization: bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" "$ACTIONS_ID_TOKEN_REQUEST_URL&audience=api://AzureADTokenExchange" + ``` diff --git a/data/reusables/actions/oidc-permissions-token.md b/data/reusables/actions/oidc-permissions-token.md index cbe483045715..3bd4d2b75cd3 100644 --- a/data/reusables/actions/oidc-permissions-token.md +++ b/data/reusables/actions/oidc-permissions-token.md @@ -1,29 +1,5 @@ -The job or workflow run requires a `permissions` setting with [`id-token: write`](/actions/security-guides/automatic-token-authentication#permissions-for-the-github_token) to allow {% data variables.product.prodname_dotcom %}'s OIDC provider to create a JSON Web Token for every run. You won't be able to request the OIDC JWT ID token if the `permissions` for `id-token` is not set to `write`, however this value doesn't imply granting write access to any resources, only being able to fetch and set the OIDC token for an action or step to enable authenticating with a short-lived access token. Any actual trust setting is defined using OIDC claims, for more information see [AUTOTITLE](/actions/security-for-github-actions/security-hardening-your-deployments/about-security-hardening-with-openid-connect#configuring-the-oidc-trust-with-the-cloud). +The job or workflow run requires a `permissions` setting with [`id-token: write`](/actions/security-guides/automatic-token-authentication#permissions-for-the-github_token) to allow {% data variables.product.github %}'s OIDC provider to create a JSON Web Token for every run. -The `id-token: write` setting allows the JWT to be requested from {% data variables.product.prodname_dotcom %}'s OIDC provider using one of these approaches: +> [!NOTE] Setting `id-token: write` in the workflow’s permissions does not give the workflow permission to modify or write to any resources. Instead, it only allows the workflow to request (fetch) and use (set) an OIDC token for an action or step. This token is then used to authenticate with external services using a short-lived access token. -* Using environment variables on the runner (`ACTIONS_ID_TOKEN_REQUEST_URL` and `ACTIONS_ID_TOKEN_REQUEST_TOKEN`). -* Using `getIDToken()` from the Actions toolkit. - -If you need to fetch an OIDC token for a workflow, then the permission can be set at the workflow level. For example: - -```yaml copy -permissions: - id-token: write # This is required for requesting the JWT - contents: read # This is required for actions/checkout -``` - -If you only need to fetch an OIDC token for a single job, then this permission can be set within that job. For example: - -```yaml copy -permissions: - id-token: write # This is required for requesting the JWT -``` - -You may need to specify additional permissions here, depending on your workflow's requirements. - -For reusable workflows that are owned by the same user, organization, or enterprise as the caller workflow, the OIDC token generated in the reusable workflow can be accessed from the caller's context. -For reusable workflows outside your enterprise or organization, the `permissions` setting for `id-token` should be explicitly set to `write` at the caller workflow level or in the specific job that calls the reusable workflow. -This ensures that the OIDC token generated in the reusable workflow is only allowed to be consumed in the caller workflows when intended. - -For more information, see [AUTOTITLE](/actions/using-workflows/reusing-workflows). +For detailed information on required permissions, configuration examples, and advanced scenarios, see [AUTOTITLE](/actions/reference/openid-connect-reference##workflow-permissions-for-the-requesting-the-oidc-token). From 25b182d562b2a8c16b5c376a33c9136ef39639d9 Mon Sep 17 00:00:00 2001 From: Sunbrye Ly <56200261+sunbrye@users.noreply.github.com> Date: Thu, 10 Jul 2025 14:42:44 -0700 Subject: [PATCH 2/2] [Improvement]: users can see Copilot premium usage on the Copilot settings page (#56557) Co-authored-by: hubwriter --- .../monitoring-your-copilot-usage-and-entitlements.md | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/content/copilot/how-tos/monitoring-your-copilot-usage-and-entitlements.md b/content/copilot/how-tos/monitoring-your-copilot-usage-and-entitlements.md index 44815ac25167..8891ce4db750 100644 --- a/content/copilot/how-tos/monitoring-your-copilot-usage-and-entitlements.md +++ b/content/copilot/how-tos/monitoring-your-copilot-usage-and-entitlements.md @@ -20,9 +20,10 @@ You can track your monthly usage of premium requests to help you get the most va ## Viewing premium request usage -There are two ways to view your premium request usage: +There are multiple ways to view your premium request usage: * [View current usage directly within your IDE](#viewing-usage-in-your-ide) +* [View current usage in your {% data variables.product.prodname_copilot_short %} settings](#viewing-usage-in-your-copilot-settings) * [Download a {% data variables.product.prodname_copilot_short %} premium request usage report](#downloading-a-copilot-premium-request-usage-report) If you reach your limit for premium requests, you will be notified with a message in each of the {% data variables.product.prodname_copilot_short %} interfaces you use. @@ -41,6 +42,14 @@ You can access usage information in the following IDEs. * **In Xcode**, click the {% data variables.product.prodname_copilot_short %} icon ({% octicon "copilot" aria-hidden="true" aria-label="copilot" %}) in the menu bar. * **In Eclipse**, click the {% data variables.product.prodname_copilot_short %} icon ({% octicon "copilot" aria-hidden="true" aria-label="copilot" %}) in the status bar at the bottom of Eclipse. +### Viewing usage in your {% data variables.product.prodname_copilot_short %} settings + +You can view your premium request usage at any time from your {% data variables.product.prodname_copilot_short %} settings page on {% data variables.product.prodname_dotcom_the_website %}. + +1. In the upper-right corner of any page on {% data variables.product.prodname_dotcom %}, click your profile photo. +1. Click **{% octicon "copilot" aria-hidden="true" aria-label="copilot" %} Your {% data variables.product.prodname_copilot_short %}**. +1. Under "Usage," view the "Premium requests" progress bar to see the percentage of your premium request quota used for the current month. + ### Downloading a {% data variables.product.prodname_copilot_short %} premium request usage report >[!NOTE]