{"meta":{"title":"OpenID Connect","intro":"OpenID Connect allows your workflows to exchange short-lived tokens directly from your cloud provider.","product":"GitHub Actions","breadcrumbs":[{"href":"/en/actions","title":"GitHub Actions"},{"href":"/en/actions/concepts","title":"Concepts"},{"href":"/en/actions/concepts/security","title":"Security"},{"href":"/en/actions/concepts/security/openid-connect","title":"OpenID Connect"}],"documentType":"article"},"body":"# OpenID Connect\n\nOpenID Connect allows your workflows to exchange short-lived tokens directly from your cloud provider.\n\n## Overview of OpenID Connect (OIDC)\n\nGitHub 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 GitHub, and the workflow presents this secret to the cloud provider every time it runs.\n\nHowever, using hardcoded secrets requires you to create credentials in the cloud provider and then duplicate them in GitHub as a secret.\n\nAfter you have established a trust connection with a cloud provider that supports OIDC, you can configure your workflow to request a short-lived access token directly from the cloud provider.\n\n## Benefits of using OIDC\n\nBy updating your workflows to use OIDC tokens, you can adopt the following good security practices:\n\n* **No cloud secrets:** You won't need to duplicate your cloud credentials as long-lived 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.\n* **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.\n* **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.\n\n## How OIDC integrates with GitHub Actions\n\nThe following diagram gives an overview of how GitHub's OIDC provider integrates with your workflows and cloud provider:\n\n![Diagram of how a cloud provider integrates with GitHub Actions through access tokens and JSON web token cloud role IDs.](/assets/images/help/actions/oidc-architecture.png)\n\n1. You establish an OIDC trust relationship in the cloud provider, allowing specific GitHub workflows to request cloud access tokens on behalf of a defined cloud role.\n2. Every time your job runs, GitHub'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.\n3. A step or action in the workflow job can request a token from GitHub’s OIDC provider, which can then be presented to the cloud provider as proof of the workflow’s identity.\n4. 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.\n\n## Understanding the OIDC token\n\nEach job requests an OIDC token from GitHub'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.\n\nThe following example OIDC token uses a subject (`sub`) that references a job environment named `prod` in the `octo-org/octo-repo` repository.\n\n```yaml\n{\n  \"typ\": \"JWT\",\n  \"alg\": \"RS256\",\n  \"x5t\": \"example-thumbprint\",\n  \"kid\": \"example-key-id\"\n}\n{\n  \"jti\": \"example-id\",\n  \"sub\": \"repo:octo-org/octo-repo:environment:prod\",\n  \"environment\": \"prod\",\n  \"aud\": \"https://github.com/octo-org\",\n  \"ref\": \"refs/heads/main\",\n  \"sha\": \"example-sha\",\n  \"repository\": \"octo-org/octo-repo\",\n  \"repository_owner\": \"octo-org\",\n  \"actor_id\": \"12\",\n  \"repository_visibility\": \"private\",\n  \"repository_id\": \"74\",\n  \"repository_owner_id\": \"65\",\n  \"run_id\": \"example-run-id\",\n  \"run_number\": \"10\",\n  \"run_attempt\": \"2\",\n  \"runner_environment\": \"github-hosted\",\n  \"actor\": \"octocat\",\n  \"workflow\": \"example-workflow\",\n  \"head_ref\": \"\",\n  \"base_ref\": \"\",\n  \"event_name\": \"workflow_dispatch\",\n  \"repo_property_workspace_id\": \"ws-abc123\",\n  \"ref_type\": \"branch\",\n  \"job_workflow_ref\": \"octo-org/octo-automation/.github/workflows/oidc.yml@refs/heads/main\",\n  \"iss\": \"https://token.actions.githubusercontent.com\",\n  \"nbf\": 1632492967,\n  \"exp\": 1632493867,\n  \"iat\": 1632493567\n}\n```\n\n## Authenticating custom actions using OIDC\n\nCustom actions use the `getIDToken()` method from the Actions toolkit or a `curl` command to authenticate using OIDC.\n\nFor more information, see [OpenID Connect reference](/en/actions/reference/openid-connect-reference#methods-for-requesting-the-oidc-token).\n\n## Updating your workflows for OIDC\n\nGitHub 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 [Security hardening your deployments](/en/actions/how-tos/security-for-github-actions/security-hardening-your-deployments).\n\n## Using repository custom properties as OIDC claims\n\nOrganization and enterprise admins can include repository custom properties as claims in OIDC tokens. This enables attribute-based access control (ABAC) policies in your cloud provider, artifact registry, or secrets manager that are driven by repository metadata rather than hard-coded allow lists.\n\n### How custom property claims work\n\nThe end-to-end flow for using custom properties as OIDC claims is as follows:\n\n1. **Define custom properties.** An organization or enterprise admin creates custom properties (for example, `business_unit`, `data_classification`, or `environment_tier`) and assigns values to repositories. For more information, see [Managing custom properties for repositories in your organization](/en/organizations/managing-organization-settings/managing-custom-properties-for-repositories-in-your-organization) and [OpenID Connect reference](/en/actions/reference/security/oidc#including-repository-custom-properties-in-oidc-tokens).\n2. **Enable properties in OIDC tokens.** An organization or enterprise admin selects which custom properties should be included in OIDC tokens, using the settings UI or the REST API.\n3. **Claims appear automatically.** Every workflow run in a repository that has a value set for an enabled property will include that value in its OIDC token, prefixed with `repo_property_`. No workflow-level configuration changes are required.\n4. **Update cloud trust policies.** You update your cloud provider's trust conditions to evaluate the new `repo_property_*` claims, enabling fine-grained, attribute-based access decisions.\n\nBecause this builds on GitHub's existing OIDC short-lived credential model, no long-lived secrets are required, and every token is scoped, auditable, and automatically rotated per workflow run.\n\n### Prerequisites\n\n* Custom properties must already be defined at the organization or enterprise level. For more information, see [Managing custom properties for repositories in your organization](/en/organizations/managing-organization-settings/managing-custom-properties-for-repositories-in-your-organization).\n* You must be an organization admin or enterprise admin.\n\n### Adding a custom property to OIDC token claims\n\nTo include a custom property in OIDC tokens, use the REST API or the settings UI for your organization or enterprise.\n\n* **Using the settings UI:** Navigate to your organization or enterprise's Actions OIDC settings page to view and manage which custom properties are included in OIDC tokens.\n\n* **Using the REST API:** Send a `POST` request to the `/orgs/{org}/actions/oidc/customization/properties/repo` endpoint to add a custom property to the OIDC token claims for your organization. For request parameters and full details, see the REST API documentation for managing OIDC custom properties: [REST API endpoints for GitHub Actions OIDC](/en/rest/actions/oidc).\n\n### Example OIDC token with custom properties\n\nThe following example shows an OIDC token that includes two custom properties: a single-select property `business_unit` and a string property `workspace_id`. Each custom property appears in the token with the `repo_property_` prefix.\n\n```json\n{\n  \"sub\": \"repo:my-org/my-repo:ref:refs/heads/main\",\n  \"aud\": \"https://github.com/my-org\",\n  \"repository\": \"my-org/my-repo\",\n  \"repository_owner\": \"my-org\",\n  \"ref\": \"refs/heads/main\",\n  \"repo_property_business_unit\": \"payments\",\n  \"repo_property_workspace_id\": \"ws-abc123\"\n}\n```\n\nYou can use the `repo_property_*` claims in your cloud provider's trust conditions to create flexible, attribute-based access control policies. For more information about the claim format, supported property types, and limits, see [OpenID Connect reference](/en/actions/reference/openid-connect-reference#including-repository-custom-properties-in-oidc-tokens).\n\n## OIDC support for Dependabot\n\nDependabot can use OIDC to authenticate with private registries, eliminating the need to store long-lived credentials as repository secrets. With OIDC-based authentication, Dependabot update jobs can dynamically obtain short-lived credentials from your cloud identity provider.\n\nDependabot supports OIDC authentication for any registry type that uses `username` and `password` authentication, when the registry is hosted on AWS CodeArtifact, Azure DevOps Artifacts, or JFrog Artifactory.\n\nThe benefits of OIDC authentication for Dependabot are:\n\n* **Enhanced security:** Eliminates static, long-lived credentials from your repositories.\n* **Simpler management:** Enables secure, policy-compliant access to private registries.\n* **Avoid rate limiting:** Dynamic credentials help you avoid hitting rate limits associated with static tokens.\n\nFor more information, see [Configuring access to private registries for Dependabot](/en/code-security/dependabot/working-with-dependabot/configuring-access-to-private-registries-for-dependabot#using-oidc-for-authentication).\n\n## Next steps\n\nFor more information about configuring OIDC, see [Security hardening your deployments](/en/actions/how-tos/security-for-github-actions/security-hardening-your-deployments).\n\nFor reference information about OIDC, see [OpenID Connect reference](/en/actions/reference/openid-connect-reference)."}