A deployment workflow needs to authenticate to a cloud provider or artifact registry, but storing a service-user password or API key creates another secret to protect. OpenID Connect (OIDC), a standard built on OAuth 2.0, lets supported services connect without sharing those long-lived credentials. It is particularly useful for infrastructure-as-code pipelines and tests. section 8.5.1 section 9.2.6
Authentication identifies the requesting workflow; authorization determines what that identity may access. Setting up OIDC therefore involves both registering an identity provider and granting the resulting identity appropriate access. Vendor-specific instructions matter, but the basic setup is consistent. section 8.5.1
For a GitHub Actions workflow accessing AWS:
- Find the platform’s provider URL. GitHub Actions uses https://token.actions.githubusercontent.com; register that URL with AWS, typically once per account and URL. section 8.5.1
- Configure the workflow to request an OIDC token with `id-token: write`, then use `aws-actions/configure-aws-credentials@v4` with the AWS role to assume. section 8.5.1
- For a different platform, follow its provider and vendor documentation rather than copying GitHub-specific settings. section 8.5.1
Listing 8.13 Registering an OIDC provider with AWS
locals {
gh_actions_token_url = "https://token.actions.githubusercontent.com" #1
}
data "tls_certificate" "gh_actions" {
url = local.gh_actions_token_url #2
}
resource "aws_iam_openid_connect_provider" "github" { #3
url = local.gh_actions_token_url #4
thumbprint_list = data.tls_certificate.gh_actions.certificates[*].
sha1_fingerprint #5
client_id_list = ["sts.amazonaws.com"] #6
}
#1 This is the URL for the GitHub Actions OIDC token service.
#2 OIDC uses the TLS certificate to verify the identity of the service.
#3 This resource should only be called once per account per url.
#4 These values comes from the GitHub Actions documentation.
#5 This is the SHA1 fingerprint of the certificates attached to the GitHub OIDC service.
#6 For AWS, you will almost always use the security token service as the client.
The Terraform example registers GitHub Actions as an AWS OIDC provider using its token URL, a TLS certificate fingerprint, and `sts.amazonaws.com` as the client ID. section 8.5.1
Listing 8.14 Allowing a GitHub Actions workflow to assume a role
jobs:
terraform:
name: Run Terraform against AWS
runs-on: ubuntu-latest
permissions: #1
id-token: write #1
contents: read #1
steps:
- name: Checkout #2
uses: actions/checkout@v4
- name: Configure AWS credentials
uses: aws-actions/configure-aws-credentials@v4 #3
with:
role-to-assume: arn:aws:iam::999999999999:role/github-actions-${{
github.repository }} #4
region: us-west-2 #5
#1 The AWS action needs the OIDC token to be accessible.
#2 Checkout our repository.
#3 This action is published by AWS and converts the OIDC token into AWS credentials.
#4 When using OIDC you have to tell AWS what role you want to assume.
#5 AWS requires a region when logging in.
The workflow example shows the other side of the connection: token permission and an AWS credentials action configured with a role to assume. section 8.5.1
The same approach can authorize a GitHub release workflow to publish a Terraform module to Artifactory, or let a supported test workflow authenticate to its vendors. OIDC is not available for every service: use a secret manager for remaining keys, and treat orchestrator-stored secrets as a last option. Retrieving secrets through Terraform data sources can still place sensitive values in state. section 8.1.5 section 8.5.2 section 8.5.3 section 9.2.6
