Study guide
9.3 OpenID Connect (OIDC) & Workload Identity Federation
GitHub Actions Certification GH-200
Track your progress as you read
Finished sections get a check mark.
1 Chapter 1: Introduction & Exam Overview
1.1 Exam Structure, Format & Scoring 1.2 GitHub Actions Architecture & Core Mental Model 1.3 Hands-On Preparation & Exam Day Strategy
2 Chapter 2: Workflow Triggers & Event Architecture
2.1 Webhook & Code Events: push, pull_request, and pull_request_target 2.2 Scheduled & Manual Triggers: schedule, workflow_dispatch, and repository_dispatch 2.3 Release, Issue, and Dynamic Lifecycle Events 2.4 Branch, Tag, and Path Filtering Patterns
3 Chapter 3: Jobs, Matrix Strategies & Execution Control
3.1 Job Anatomy, Step Execution & Job Dependencies (needs) 3.2 Contexts, Expressions & Functions 3.3 Environment Variables & Workflow Commands 3.4 Matrix Strategies & Multi-Platform Builds 3.5 YAML Anchors, Aliases & Merge Keys
4 Chapter 4: Reusable Workflows & Troubleshooting
4.1 Authoring & Calling Reusable Workflows (workflow_call) 4.2 Comparing Reusable Workflows, Composite Actions & Starter Workflows 4.3 Troubleshooting Workflow Runs & Debug Logging 4.4 Concurrency Controls & Status Check Functions
5 Chapter 5: Authoring Custom Actions
5.1 Action Architecture & action.yml Specification 5.2 Authoring Composite Actions 5.3 Building JavaScript Actions 5.4 Building Docker Container Actions
6 Chapter 6: Action Distribution, Marketplace & Advanced Action Types
6.1 Action Versioning, Semantic Releases & Tagging 6.2 Publishing Actions to GitHub Marketplace 6.3 Service Containers & Network Topology 6.4 actions/github-script & Workflow Tooling
7 Chapter 7: Runner Infrastructure & Self-Hosted Runners
7.1 GitHub-Hosted Runners & Larger Runners 7.2 Self-Hosted Runner Setup, Architecture & Communication 7.3 Self-Hosted Runner Security & Ephemeral Runners 7.4 Runner Groups, Labels & Organization Routing
8 Chapter 8: Enterprise Governance, Policies & Environments
8.1 Enterprise & Organization Action Policies 8.2 Environments, Protection Rules & Deployment Approvals 8.3 Repository Rulesets, Required Status Checks & Governance 8.4 Usage Limits, Billing Multipliers & Usage Metrics
9 Chapter 9: Secrets, Permissions & OIDC Cloud Authentication
9.1 Encrypted Secrets Architecture & Scopes 9.2 GITHUB_TOKEN & Least Privilege Configuration 9.3 OpenID Connect (OIDC) & Workload Identity Federation 9.4 Script Injection Prevention & Secure Workflow Patterns
10 Chapter 10: Supply Chain Hardening & Performance Optimization
10.1 Supply Chain Hardening: SHA Pinning, Dependabot & Artifact Attestations 10.2 Caching Dependencies with `actions/cache` 10.3 Artifacts Management & Job Handoff 10.4 Workflow Performance, Cost Optimization & Architecture Review
9.3 OpenID Connect (OIDC) & Workload Identity Federation
Key Takeaways Explain This Topic AI
OpenID Connect (OIDC) eliminates the need for long-lived, static cloud credentials (such as AWS access keys, Azure service principal client secrets, or GCP service account keys) by exchanging ephemeral GitHub-issued JSON Web Tokens (JWTs) for short-lived cloud IAM tokens.
To request an OIDC JWT, a workflow must explicitly declare the id-token: write permission in its permissions block; without this permission, the runner cannot communicate with GitHub's OIDC token service.
GitHub acts as the Identity Provider (IdP) with issuer URL https://token.actions.githubusercontent.com , minting digitally signed JWTs containing standard claims ( iss , aud , sub , repository , actor , workflow , environment , etc.).
The subject ( sub ) claim forms the core trust condition, formatted as repo:<org>/<repo>:ref:refs/heads/<branch> for branch triggers or repo:<org>/<repo>:environment:<env> for environment deployments.
Cloud platforms (AWS IAM Role trust policy, Azure Federated Credentials, GCP Workload Identity Federation) evaluate GitHub JWT claims against strict IAM trust policies before issuing temporary, scoped credentials.
Last updated: August 2026
OpenID Connect (OIDC) & Workload Identity Federation
Historically, continuous deployment pipelines authenticated to cloud infrastructure (such as Amazon Web Services, Microsoft Azure, and Google Cloud Platform) using long-lived static credentials —such as AWS IAM Access Key/Secret Key pairs, Azure Service Principal client secrets, or GCP Service Account private JSON keys. These static secrets introduce major security vulnerabilities: they are susceptible to accidental exfiltration, require complex rotation schedules, and present an expansive blast radius if leaked.
GitHub Actions solves this problem through OpenID Connect (OIDC) and Workload Identity Federation . With OIDC, GitHub Actions acts as a trusted Identity Provider (IdP), minting short-lived, digitally signed JSON Web Tokens (JWTs) that cloud providers validate directly to exchange for temporary, scoped cloud credentials. Configuring OIDC authentication is one of the most prominent enterprise topics on the GH-200 examination.
1. OIDC Architecture & Token Exchange Lifecycle
The OIDC handshake between GitHub Actions and a target cloud provider eliminates static secrets entirely from repository settings. +-----------------------------------------------------------------------------+
- | OIDC TOKEN EXCHANGE LIFECYCLE |
- | |
- | [RUNNER JOB] [GITHUB OIDC SERVICE] [CLOUD PROVIDER (AWS)]|
- | (id-token: write) |
- | | | | |
- | 1. Request OIDC Token -------->| | |
- | | (via $ACTIONS_ID_TOKEN_REQUEST_URL) | |
- | |<-- 2. Return Signed JWT Token | |
- | | (RS256 signature, claims: sub, aud, iss) | |
- | | | | |
- | 3. Present JWT to Cloud STS --------------------------------->| |
- | (AssumeRoleWithWebIdentity) | |
- | | | 4. Fetch JWKS |
- | | |<------------------- Public Keys |
- | | | 5. Verify Signature |
- | | | 6. Match 'sub' Claim |
- | |<-- 7. Return Temporary Cloud Credentials (1 Hour) ---| |
- | | (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, TOKEN) | |
- | | | | |
- | 8. Execute Cloud CLI / SDK Deployment | |
- +-----------------------------------------------------------------------------+
- Step-by-Step Authentication Handshake
Prerequisite Permission: The workflow job declares permissions: { id-token: write } . The runner agent exposes two internal environment variables: $ACTIONS_ID_TOKEN_REQUEST_URL and $ACTIONS_ID_TOKEN_REQUEST_TOKEN .
JWT Request: An action (or script) calls the local token endpoint. GitHub's OIDC service generates a JSON Web Token signed with GitHub's private RS256 key.
Cloud Exchange: The runner transmits the signed JWT to the cloud provider's Security Token Service (e.g., AWS STS AssumeRoleWithWebIdentity ).
Cryptographic Verification: The cloud provider fetches GitHub's public JSON Web Key Set (JWKS) from https://token.actions.githubusercontent.com/.well-known/jwks.json and verifies the token's cryptographic signature.
Trust Policy Validation: The cloud provider validates standard claims: that the issuer ( iss ) matches GitHub, the audience ( aud ) matches the expected client ID, and the subject ( sub ) satisfies the IAM trust policy condition.
Temporary Credential Issuance: Upon successful validation, the cloud provider returns short-lived session credentials (typically valid for 15 to 60 minutes) to the runner.
2. Anatomy of the GitHub Actions OIDC JWT Token
When GitHub mints an OIDC token, it populates the payload with rich metadata describing the exact workflow execution context. {
- "iss": "https://token.actions.githubusercontent.com",
- "aud": "https://github.com/my-enterprise-org",
- "sub": "repo:my-enterprise-org/payment-service:ref:refs/heads/main",
- "repository": "my-enterprise-org/payment-service",
- "repository_owner": "my-enterprise-org",
- "repository_id": "74829104",
- "repository_owner_id": "1928374",
- "actor": "octocat",
- "actor_id": "583202",
- "workflow": "Deploy Production",
- "workflow_ref": "my-enterprise-org/payment-service/.github/workflows/deploy.yml@refs/heads/main",
- "workflow_sha": "f8d3b847a61d1983c27e98a12bc902341234abcd",
- "ref": "refs/heads/main",
- "ref_type": "branch",
- "sha": "b4ffde65f46336ab851b4c731e846067756f7004",
- "environment": "production",
- "runner_environment": "github-hosted",
- "exp": 1723748400,
- "iat": 1723747800
- }
- Critical Claims Reference
iss (Issuer): Always https://token.actions.githubusercontent.com . Used by cloud providers to locate the OIDC discovery endpoint.
aud (Audience): Defaults to the URL of the repository owner (or sts.amazonaws.com for AWS). Workflows can specify custom audiences via core.getIDToken(audience) .
sub (Subject Identifier): The most crucial claim for security filtering. Formats include:
- Branch push: repo:<org>/<repo>:ref:refs/heads/<branch-name> (e.g., repo:acme-corp/api:ref:refs/heads/main )
- Tag push: repo:<org>/<repo>:ref:refs/tags/<tag-name> (e.g., repo:acme-corp/api:ref:refs/tags/v1.0.0 )
Environment deployment: repo:<org>/<repo>:environment:<environment-name> (e.g., repo:acme-corp/api:environment:production )
Pull request: repo:<org>/<repo>:pull_request
environment : Present only if the workflow job explicitly targets a GitHub deployment environment ( environment: production ).
3. Configuring Cloud Provider Trust Policies
To establish trust, cloud IAM roles must define trust policies that evaluate GitHub's OIDC claims.
1. Amazon Web Services (AWS IAM Role Trust Policy)
AWS IAM validates GitHub OIDC using an Identity Provider configured for token.actions.githubusercontent.com . {
- "Version": "2012-10-17",
- "Statement": [
- {
- "Effect": "Allow",
- "Principal": {
- "Federated": "arn:aws:iam::123456789012:oidc-provider/token.actions.githubusercontent.com"
- },
- "Action": "sts:AssumeRoleWithWebIdentity",
- "Condition": {
- "StringEquals": {
- "token.actions.githubusercontent.com:aud": "sts.amazonaws.com",
- "token.actions.githubusercontent.com:sub": "repo:acme-corp/payment-service:ref:refs/heads/main"
- }
- }
- }
- ]
- }
- AWS Workflow Implementation name: AWS OIDC Deployment
on:
push:
branches: [main]
permissions:
- id-token: write # Mandatory for requesting the OIDC JWT token
- contents: read # Required for repository checkout
jobs:
deploy-aws:
runs-on: ubuntu-latest
steps:
- name: Checkout Code
- uses: actions/checkout@v4
- name: Configure AWS Credentials via OIDC
- uses: aws-actions/configure-aws-credentials@v4
with:
- role-to-assume: arn:aws:iam::123456789012:role/GitHubActionsProductionRole
- aws-region: us-east-1
- audience: sts.amazonaws.com
- name: Deploy to S3
- run: aws s3 sync ./dist s3://my-prod-bucket
- 2. Microsoft Azure (Federated Identity Credentials)
Azure uses Federated Identity Credentials attached to an Azure Active Directory (Microsoft Entra ID) Application or User-Assigned Managed Identity.
- Issuer: https://token.actions.githubusercontent.com
- Subject Identifier: repo:acme-corp/payment-service:environment:production
- Audience: api://AzureADTokenExchange
- Azure Workflow Implementation name: Azure OIDC Deployment
on:
push:
branches: [main]
permissions:
- id-token: write
- contents: read
jobs:
deploy-azure:
- runs-on: ubuntu-latest
- environment: production
steps:
- uses: actions/checkout@v4
- name: Azure Login via OIDC
- uses: azure/login@v2
with:
- client-id: ${{ vars.AZURE_CLIENT_ID }}
- tenant-id: ${{ vars.AZURE_TENANT_ID }}
- subscription-id: ${{ vars.AZURE_SUBSCRIPTION_ID }}
- 3. Google Cloud Platform (Workload Identity Federation)
GCP utilizes a Workload Identity Pool and Workload Identity Provider that maps GitHub assertion claims to Google IAM attributes:
- Attribute Mapping: google.subject=assertion.sub , attribute.repository=assertion.repository
- Attribute Condition: assertion.repository == 'acme-corp/payment-service'
- GCP Workflow Implementation name: GCP OIDC Deployment
on:
push:
branches: [main]
permissions:
- id-token: write
- contents: read
jobs:
deploy-gcp:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Authenticate to Google Cloud
- uses: google-github-actions/auth@v2
with:
workload_identity_provider: 'projects/123456789/locations/global/workloadIdentityPools/github-pool/providers/github-provider'