AWS GitHub Actions OIDC Terraform Module

Terraform module to configure GitHub Actions as an OpenID Connect (OIDC) identity provider in AWS, allowing GitHub Actions to obtain short-lived credentials by assuming IAM roles directly, and enabling secure authentication between GitHub Actions workflows and AWS resources.

🔨 Getting started

Requirements

• AWS Provider 4.0+
• TLS Provider 3.0+
• Terraform 1.0+

Installation and usage

Refer to the complete example to view all the available configuration options. The following snippet shows the minimum required configuration to create a working OIDC connection between GitHub Actions and AWS.

module "oidc_github" {
  source  = "unfunco/oidc-github/aws"
  version = "1.8.1"

  github_repositories = [
    "org/repo",
    "another-org/another-repo:ref:refs/heads/main",
  ]
}

The following demonstrates how to use GitHub Actions once the Terraform module has been applied to your AWS account. The action receives a JSON Web Token (JWT) from the GitHub OIDC provider and then requests an access token from AWS.

jobs:
  caller-identity:
    name: Check caller identity
    permissions:
      contents: read
      id-token: write
    runs-on: ubuntu-latest
    steps:
    - name: Configure AWS credentials
      uses: aws-actions/configure-aws-credentials@v4
      with:
        aws-region: ${{ env.AWS_REGION }}
        role-to-assume: arn:aws:iam::${{ env.AWS_ACCOUNT_ID }}:role/GitHubActions
    - run: aws sts get-caller-identity

Enterprise Cloud

Organisations using GitHub Enterprise Cloud can further improve their security posture by setting the enterprise_slug variable. This configuration ensures that the organisation will receive OIDC tokens from a unique URL, after this is applied, the JWT will contain an updated iss claim.

Resources

Name	Type
aws_iam_openid_connect_provider.github	resource
aws_iam_role.github	resource
aws_iam_role_policy.inline_policies	resource
aws_iam_role_policy_attachment.admin	resource
aws_iam_role_policy_attachment.custom	resource
aws_iam_role_policy_attachment.read_only	resource
aws_iam_openid_connect_provider.github	data source
aws_iam_policy_document.assume_role	data source
aws_partition.this	data source
tls_certificate.github	data source

Inputs

Name	Description	Type	Default	Required
additional_audiences	List of additional OIDC audiences allowed to assume the role.	list(string)	null	no
additional_thumbprints	A list of additional thumbprints for the OIDC provider.	list(string)	[]	no
attach_read_only_policy	Flag to enable/disable the attachment of the ReadOnly policy.	bool	false	no
create_oidc_provider	Flag to enable/disable the creation of the GitHub OIDC provider.	bool	true	no
dangerously_attach_admin_policy	Flag to enable/disable the attachment of the AdministratorAccess policy.	bool	false	no
enterprise_slug	Enterprise slug for GitHub Enterprise Cloud customers.	string	""	no
force_detach_policies	Flag to force detachment of policies attached to the IAM role.	bool	false	no
github_repositories	A list of GitHub organization/repository names authorized to assume the role.	list(string)	n/a	yes
iam_role_inline_policies	Inline policies map with policy name as key and json as value.	map(string)	{}	no
iam_role_name	The name of the IAM role to be created and made assumable by GitHub Actions.	string	"GitHubActions"	no
iam_role_path	The path under which to create IAM role.	string	"/"	no
iam_role_permissions_boundary	The ARN of the permissions boundary to be used by the IAM role.	string	""	no
iam_role_policy_arns	A list of IAM policy ARNs to attach to the IAM role.	list(string)	[]	no
max_session_duration	The maximum session duration in seconds.	number	3600	no
tags	A map of tags to be applied to all applicable resources.	map(string)	{}	no

Outputs

Name	Description
iam_role_arn	The ARN of the IAM role.
iam_role_name	The name of the IAM role.
oidc_provider_arn	The ARN of the OIDC provider.

References

• Configuring OpenID Connect in Amazon Web Services
• Creating OpenID Connect (OIDC) identity providers
• Obtaining the thumbprint for an OpenID Connect Identity Provider
• GitHub Actions – Update on OIDC integration with AWS

License

© 2021 Daniel Morris
Made available under the terms of the MIT License.