Skip to content

unfunco/terraform-aws-oidc-github

Repository files navigation

OpenID Connect for AWS and GitHub Actions

CI Cron / Verify Security License: Apache 2.0

Terraform module to configure GitHub Actions as an IAM OIDC identity provider in AWS. OpenID Connect allows GitHub Actions workflows to access resources in AWS without requiring AWS credentials to be stored as long-lived GitHub secrets.

🔨 Getting started

Requirements

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.0"

  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/github
    - 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_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.current 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 List of additional thumbprints for the OIDC provider. list(string) [] no
attach_admin_policy Flag to enable/disable the attachment of the AdministratorAccess policy. bool false no
attach_read_only_policy Flag to enable/disable the attachment of the ReadOnly policy. bool true no
create_oidc_provider Flag to enable/disable the creation of the GitHub OIDC provider. bool true no
enabled Flag to enable/disable the creation of resources. bool true 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 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 Name of the IAM role to be created. This will be assumable by GitHub. string "github" no
iam_role_path Path under which to create IAM role. string "/" no
iam_role_permissions_boundary ARN of the permissions boundary to be used by the IAM role. string "" no
iam_role_policy_arns List of IAM policy ARNs to attach to the IAM role. list(string) [] no
max_session_duration Maximum session duration in seconds. number 3600 no
tags Map of tags to be applied to all resources. map(string) {} no

Outputs

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

References

License

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