OIDC token claims

To see all the claims supported by GitHub's OIDC provider, review theclaims_supported entries athttps://token.actions.githubusercontent.com/.well-known/openid-configuration.

The OIDC token includes the following claims.

Standard audience, issuer, and subject claims

Additional standard JOSE header parameters and claims

Custom claims provided by GitHub

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 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 GitHub organization, repository, branch, or associatedjob environment. SeeExample subject claims to see how the subject claim is assembled from concatenated metadata.

If you need more granular trust conditions, you can customize the subject (sub) claim that's included with the JWT. For more information, seeCustomizing the token claims.

There are also many additional claims supported in the OIDC token that can be used for setting these conditions. In addition, your cloud provider could allow you to assign a role to the access tokens, letting you specify even more granular permissions.

Example subject claims

The following examples demonstrate how to use "Subject" as a condition, and explain how the "Subject" is assembled from concatenated metadata. Thesubject uses information from thejob 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

The subject claim includes the environment name when the job references an environment.

You can configure a subject that filters for a specificenvironment name. In this example, the workflow run must have originated from a job that has an environment namedProduction, in a repository namedocto-repo that is owned by theocto-org organization:

• Syntax:repo:ORG-NAME/REPO-NAME:environment:ENVIRONMENT-NAME
• Example:repo:octo-org/octo-repo:environment:Production

Filtering forpull_request events

The subject claim includes thepull_request string when the workflow is triggered by a pull request event, but only if the job doesn't reference an environment.

You can configure a subject that filters for thepull_request event. In this example, the workflow run must have been triggered by apull_request event in a repository namedocto-repo that is owned by theocto-org organization:

• Syntax:repo:ORG-NAME/REPO-NAME:pull_request
• Example:repo:octo-org/octo-repo:pull_request

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.

You can configure a subject that filters for a specific branch name. In this example, the workflow run must have originated from a branch nameddemo-branch, in a repository namedocto-repo that is owned by theocto-org organization:

• 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

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.

You can create a subject that filters for specific tag. In this example, the workflow run must have originated with a tag nameddemo-tag, in a repository namedocto-repo that is owned by theocto-org organization:

• Syntax:repo:ORG-NAME/REPO-NAME:ref:refs/tags/TAG-NAME
• Example:repo:octo-org/octo-repo:ref:refs/tags/demo-tag

Filtering for metadata containing:

Any: within the metadata values will be replaced with%3A in the subject claim.

You can configure a subject that includes metadata containing colons. In this example, the workflow run must have originated from a job that has an environment namedProduction:V1, in a repository namedocto-repo that is owned by theocto-org organization:

• Syntax:repo:ORG-NAME/REPO-NAME:environment:ENVIRONMENT-NAME
• Example:repo:octo-org/octo-repo:environment:Production%3AV1

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 samerepo:octo-org/octo-repo:ref:refs/heads/demo-branch subject in different ways:

For more information about configuring specific cloud providers, see the guides listed inSecurity hardening your deployments.

Customizing the token claims

You can security harden your OIDC configuration by customizing the claims that are included with the JWT. These customizations allow you to define more granular trust conditions on your cloud roles when allowing your workflows to access resources hosted in the cloud:

• You can customize values foraudience claims. SeeCustomizing theaudience 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 asrepository_id andrepository_visibility. SeeOpenID Connect.

Customizing theaudience value

When you use custom actions in your workflows, those actions may use the GitHub Actions Toolkit to enable you to supply a custom value for theaudience claim. Some cloud providers also use this in their official login actions to enforce a default value for theaudience claim. For example, theGitHub Action for Azure Login provides a defaultaud value ofapi://AzureADTokenExchange, or it allows you to set a customaud value in your workflows. For more information on the GitHub Actions Toolkit, see theOIDC token section in the documentation.

If you do not want to use the defaultaud value offered by an action, you can provide a custom value for theaudience claim. This allows you to set a condition that only workflows in a specific repository or organization can access the cloud role. If the action you are using supports this, you can use thewith keyword in your workflow to pass a customaud value to the action. For more information, seeMetadata syntax reference.

Customizing the subject claims for an organization or repository

To help improve security, compliance, and standardization, you can customize the standard claims to suit your required access conditions. If your cloud provider supports conditions on subject claims, you can create a condition that checks whether thesub value matches the path of the reusable workflow, such as"job_workflow_ref:octo-org/octo-automation/.github/workflows/oidc.yml@refs/heads/main". The exact format will vary depending on your cloud provider's OIDC configuration. To configure the matching condition on GitHub, you can use the REST API to require that thesub claim must always include a specific custom claim, such asjob_workflow_ref. You can use the REST API to apply a customization template for the OIDC subject claim; for example, you can require that thesub claim within the OIDC token must always include a specific custom claim, such asjob_workflow_ref. For more information, seeREST API endpoints for GitHub Actions OIDC.

Customizing the claims results in a new format for the entiresub claim, which replaces the default predefinedsub format in the token described inExample subject claims.

The following example templates demonstrate various ways to customize the subject claim. To configure these settings on GitHub, admins use the REST API to specify a list of claims that must be included in the subject (sub) claim.

To apply this configuration, submit a request to the API endpoint and include the required configuration in the request body. For organizations, seeREST API endpoints for GitHub Actions OIDC, and for repositories, seeREST API endpoints for GitHub Actions OIDC.

To customize your subject claims, you should first create a matching condition in your cloud provider's OIDC configuration, before customizing the configuration using the REST API. Once the configuration is completed, each time a new job runs, the OIDC token generated during that job will follow the new customization template. If the matching condition doesn't exist in the cloud provider's OIDC configuration before the job runs, the generated token might not be accepted by the cloud provider, since the cloud conditions may not be synchronized.

Example: Allowing repository based on visibility and owner

This example template allows thesub claim to have a new format, usingrepository_owner andrepository_visibility:

{"include_claim_keys":["repository_owner","repository_visibility"]}

In your cloud provider's OIDC configuration, configure thesub condition to require that claims must include specific values forrepository_owner andrepository_visibility. For example:"sub": "repository_owner:monalisa:repository_visibility:private". The approach lets you restrict cloud role access to only private repositories within an organization or enterprise.

Example: Allowing access to all repositories with a specific owner

This example template enables thesub claim to have a new format with only the value ofrepository_owner.

To apply this configuration, submit a request to the API endpoint and include the required configuration in the request body. For organizations, seeREST API endpoints for GitHub Actions OIDC, and for repositories, seeREST API endpoints for GitHub Actions OIDC.

{"include_claim_keys":["repository_owner"]}

In your cloud provider's OIDC configuration, configure thesub condition to require that claims must include a specific value forrepository_owner. For example:"sub": "repository_owner:monalisa"

Example: Requiring a reusable workflow

This example template allows thesub claim to have a new format that contains the value of thejob_workflow_ref claim. This enables an enterprise to use reusable workflows to enforce consistent deployments across its organizations and repositories.

To apply this configuration, submit a request to the API endpoint and include the required configuration in the request body. For organizations, seeREST API endpoints for GitHub Actions OIDC, and for repositories, seeREST API endpoints for GitHub Actions OIDC.

{"include_claim_keys":["job_workflow_ref"]}

In your cloud provider's OIDC configuration, configure thesub condition to require that claims must include a specific value forjob_workflow_ref. For example:"sub": "job_workflow_ref:octo-org/octo-automation/.github/workflows/oidc.yml@refs/heads/main".

Example: Requiring a reusable workflow and other claims

The following example template combines the requirement of a specific reusable workflow with additional claims.

To apply this configuration, submit a request to the API endpoint and include the required configuration in the request body. For organizations, seeREST API endpoints for GitHub Actions OIDC, and for repositories, seeREST API endpoints for GitHub Actions OIDC.

This example also demonstrates how to use"context" to define your conditions. This is the part that follows the repository in the defaultsub format. For example, when the job references an environment, the context contains:environment:ENVIRONMENT-NAME.

{"include_claim_keys":["repo","context","job_workflow_ref"]}

In your cloud provider's OIDC configuration, configure thesub condition to require that claims must include specific values forrepo,context, andjob_workflow_ref.

This customization template requires that thesub uses the following format:repo:ORG-NAME/REPO-NAME:environment:ENVIRONMENT-NAME:job_workflow_ref:REUSABLE-WORKFLOW-PATH.For example:"sub": "repo:octo-org/octo-repo:environment:prod:job_workflow_ref:octo-org/octo-automation/.github/workflows/oidc.yml@refs/heads/main"

Example: Granting access to a specific repository

This example template lets you grant cloud access to all the workflows in a specific repository, across all branches/tags and environments.

To apply this configuration, submit a request to the API endpoint and include the required configuration in the request body. For organizations, seeREST API endpoints for GitHub Actions OIDC, and for repositories, seeREST API endpoints for GitHub Actions OIDC.

{"include_claim_keys":["repo"]}

In your cloud provider's OIDC configuration, configure thesub condition to require arepo claim that matches the required value.

Example: Using system-generated GUIDs

This example template enables predictable OIDC claims with system-generated GUIDs that do not change between renames of entities (such as renaming a repository).

To apply this configuration, submit a request to the API endpoint and include the required configuration in the request body. For organizations, seeREST API endpoints for GitHub Actions OIDC, and for repositories, seeREST API endpoints for GitHub Actions OIDC.

{"include_claim_keys":["repository_id"]}

In your cloud provider's OIDC configuration, configure thesub condition to require arepository_id claim that matches the required value.

or:

{"include_claim_keys":["repository_owner_id"]}

In your cloud provider's OIDC configuration, configure thesub condition to require arepository_owner_id claim that matches the required value.

Example: Context value with:

This example demonstrates how to handle context value with:. For example, when the job references an environment namedproduction:eastus.

To apply this configuration, submit a request to the API endpoint and include the required configuration in the request body. For organizations, seeREST API endpoints for GitHub Actions OIDC, and for repositories, seeREST API endpoints for GitHub Actions OIDC.

{"include_claim_keys":["environment","repository_owner"]}

In your cloud provider's OIDC configuration, configure thesub condition to require that claims must include a specific value forenvironment andrepository_owner. For example:"sub": "environment:production%3Aeastus:repository_owner:octo-org".

Resetting organization template customizations

This example template resets the subject claims to the default format. This template effectively opts out of any organization-level customization policy.

To apply this configuration, submit a request to the API endpoint and include the required configuration in the request body. For organizations, seeREST API endpoints for GitHub Actions OIDC, and for repositories, seeREST API endpoints for GitHub Actions OIDC.

{"include_claim_keys":["repo","context"]}

In your cloud provider's OIDC configuration, configure thesub condition to require that claims must include specific values forrepo andcontext.

Resetting repository template customizations

All repositories in an organization have the ability to opt in or opt out of (organization and repository-level) customizedsub claim templates.

To opt out a repository and reset back to the defaultsub claim format, a repository administrator must use the REST API endpoint atREST API endpoints for GitHub Actions OIDC.

To configure repositories to use the defaultsub claim format, use thePUT /repos/{owner}/{repo}/actions/oidc/customization/sub REST API endpoint at with the following request body.

{"use_default":true}

Example: Configuring a repository to use an organization template

Once an organization has created a customizedsub claim template, the REST API can be used to programmatically apply the template to repositories within the organization. A repository administrator can configure their repository to use the template created by the administrator of their organization.

To configure the repository to use the organization's template, a repository admin must use thePUT /repos/{owner}/{repo}/actions/oidc/customization/sub REST API endpoint at with the following request body. For more information, seeREST API endpoints for GitHub Actions OIDC.

{"use_default":false}

Debugging your OIDC claims

You can use thegithub/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 GitHub Actions.

Workflow permissions for the requesting the OIDC token

Required permission

• The job or workflow must grant theid-token: write permission to allow GitHub's OIDC provider to create a JSON Web Token (JWT):

  permissions:id-token:write

• Withoutid-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.

Setting permissions

• To fetch an OIDC token for a workflow, set the permission at the workflow level:

  permissions:id-token:write# This is required for requesting the JWTcontents:read# This is required for actions/checkout

• To fetch an OIDC token for a single job, set the permission within that job:

  permissions:id-token:write# This is required for requesting the JWT

• Additional permissions may be required depending on workflow needs.

Reusable workflows

• 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 thepermissions setting forid-token towrite explicitly at the caller workflow or job level. This ensures the OIDC token is only available to intended caller workflows.

Methods for requesting the OIDC token

Custom actions can request the OIDC token using:

• ThegetIDToken() method from the Actions toolkit. For more information, seeOIDC Token in the npm package documentation.

• The following environment variables on the runner.

  Variable	Description
  ACTIONS_ID_TOKEN_REQUEST_URL	The URL for GitHub's OIDC provider.
  ACTIONS_ID_TOKEN_REQUEST_TOKEN	Bearer token for the request to the OIDC provider.

  For example:

  Shell

  curl -H "Authorization: bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" "$ACTIONS_ID_TOKEN_REQUEST_URL&audience=api://AzureADTokenExchange"