unfunco/terraform-aws-oidc-github

Terraform module to configure GitHub Actions as an IAM OIDC identity provider in AWS.

OpenID Connect for AWS and GitHub Actions

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

• 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.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

• 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 Apache License 2.0.

terraform-aws-oidc-github's Issues

Changes in every plan/apply

Hi,
I just added this simple module in my project

module "oidc-github" {
  source                  = "unfunco/oidc-github/aws"
  version                 = "1.3.1"
  attach_admin_policy     = true
  attach_read_only_policy = false
  github_repositories     = ["ORG/*"]
  iam_role_name           = "GithubAssumeRole"
}

With the name of my organization instead of ORG.

It's ok, but every time I launch plan & apply I have this:

Plan: 1 to add, 1 to change, 1 to destroy.

Terraform will perform the following actions:

  # module.github_openid_connect.module.oidc-github.data.aws_iam_policy_document.assume_role[0] will be read during apply
  # (config refers to values not yet known)
 <= data "aws_iam_policy_document" "assume_role" {
      + id      = (known after apply)
      + json    = (known after apply)
      + version = "2012-10-17"

      + statement {
          + actions = [
              + "sts:AssumeRoleWithWebIdentity",
            ]
          + effect  = "Allow"

          + condition {
              + test     = "StringEquals"
              + values   = [
                  + "sts.amazonaws.com",
                ]
              + variable = "token.actions.githubusercontent.com:aud"
            }
          + condition {
              + test     = "StringLike"
              + values   = [
                  + "repo:ORG/*:*",
                ]
              + variable = "token.actions.githubusercontent.com:sub"
            }

          + principals {
              + identifiers = [
                  + (known after apply),
                ]
              + type        = "Federated"
            }
        }
    }

  # module.github_openid_connect.module.oidc-github.aws_iam_openid_connect_provider.github[0] must be replaced
-/+ resource "aws_iam_openid_connect_provider" "github" {
      ~ arn             = "arn:aws:iam::XXXXXXXXXX:oidc-provider/token.actions.githubusercontent.com" -> (known after apply)
      ~ client_id_list  = [ # forces replacement
          - "sts.amazonaws.com",
            "https://github.com/ORG",
          + "sts.amazonaws.com",
        ]
      ~ id              = "arn:aws:iam::XXXXXXXXXXX:oidc-provider/token.actions.githubusercontent.com" -> (known after apply)
        tags            = {
            "BuildBy"     = "ORG/Terraform"
            "Environment" = "sbx"
            "Project"     = "ORG"
        }
      ~ url             = "token.actions.githubusercontent.com" -> "https://token.actions.githubusercontent.com"
        # (2 unchanged attributes hidden)
    }

  # module.github_openid_connect.module.oidc-github.aws_iam_role.github[0] will be updated in-place
  ~ resource "aws_iam_role" "github" {
      ~ assume_role_policy    = jsonencode(
            {
              - Statement = [
                  - {
                      - Action    = "sts:AssumeRoleWithWebIdentity"
                      - Condition = {
                          - StringEquals = {
                              - "token.actions.githubusercontent.com:aud" = "sts.amazonaws.com"
                            }
                          - StringLike   = {
                              - "token.actions.githubusercontent.com:sub" = "repo:ORG/*:*"
                            }
                        }
                      - Effect    = "Allow"
                      - Principal = {
                          - Federated = "arn:aws:iam::XXXXXXXXXXX:oidc-provider/token.actions.githubusercontent.com"
                        }
                      - Sid       = ""
                    },
                ]
              - Version   = "2012-10-17"
            }
        ) -> (known after apply)
        id                    = "GithubAssumeRole"
        name                  = "GithubAssumeRole"
        tags                  = {
            "BuildBy"     = "ORG/Terraform"
            "Environment" = "sbx"
            "Project"     = "ORG"
        }
        # (9 unchanged attributes hidden)
    }

Plan: 1 to add, 1 to change, 1 to destroy.

Why? Where do you think I'm wrong?
Thanks

Thumbprint mismatch

I'm trying this module, and I see it obtains the thumbprint f879abce0008e4eb126e0097e46620f5aaae26ad instead of 6938fd4d98bab03faadb97b34396831e3780aea1. This value is the one in https://github.blog/changelog/2023-06-27-github-actions-update-on-oidc-integration-with-aws/ and the same value obtained when manually replicating https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc_verify-thumbprint.html.

Do you have any suggestions?

Two instances of this module in one account conflict due to the same name

It's related to this resource. The name seems auto-generated and we can't override it as far as I can tell.

Review the enhanced OIDC support with the subject claim

https://github.blog/changelog/2022-10-18-github-actionsopenid-connect-support-enhanced-to-enable-secure-cloud-deployments-at-scale/

output role_arn is incompatible with aws_iam_role_policy_attachment resource

Issue

aws_iam_role_policy_attachment requires role name, not arn.
in order to attach a policy to the created role "github", either arn string manipulation is needed or hard-coding "github"

Example

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

github_repositories = ["org/repo"]
}

resource "aws_iam_role_policy_attachment" "github_role_ecr_policy_attachement" {
role = "github"
policy_arn = aws_iam_policy.ecr_push_policy.arn
}`

Proposed solution:

add role_name output which will consist only of role name

[Bug] 1.7.0 errors when create_oidc_provider = false

When create_oidc_provider = false is set, 1.7.0 errors with

Error: Invalid index
on .terraform/modules/<module_name>/outputs.tf line 30, in output "oidc_provider_arn":
  value       = var.enabled ? aws_iam_openid_connect_provider.github[0].arn : ""
aws_iam_openid_connect_provider.github is empty tuple
The given key does not identify an element in this collection value: the collection has no elements.

Failed to query available provider packages

Hi there!

Thanks for great module!
One small thing, currently when I'm trying to use that module I'm getting this error:

I guess this is because I'm using older version of hashicorp/aws than you:

aws = {
  source  = "hashicorp/aws"
  version = "~> 3.74"
}

Could you support also version 3.74?

New intermediary certificate

GitHub has published a blog post that says there's a new intermediary certificate:
https://github.blog/changelog/2023-06-27-github-actions-update-on-oidc-integration-with-aws/

The module should automatically pull this certificate information when applied but this will need to be checked. The number of allowed additional_thumbprints should be reduced from 4 to 3.

GitHub renewed its SSL cert, thumbprint changed

validation.condition of additional_thumbprints has not been completed (v1.3.0)

If additional_thumbprints is not required, it should not be an error to not include it in the code.

module "aws_oidc_github" {
  source = "unfunco/oidc-github/aws"
<ommit>
  # no additional_thumbprints variable
}

has error

│ Error: Invalid function argument
│
│   on .terraform/modules/aws_oidc_github/variables.tf line 21, in variable "additional_thumbprints":
│   21:     condition     = length(var.additional_thumbprints) <= 4
│     ├────────────────
│     │ while calling length(value)
│     │ var.additional_thumbprints is null
│
│ Invalid value for "value" parameter: argument must not be null.

workaround(and If additional_thumbprints is required, then)

module "aws_oidc_github" {
  source = "unfunco/oidc-github/aws"
<ommit>

  additional_thumbprints = []

}

Additional checks on condition would be nice.

like https://stackoverflow.com/questions/66912991/terraform-custom-validation-for-variable-that-can-be-null

Known thumbprints are no longer required

This email has been sent out by Amazon Web Services to the email addresses of accounts which have configured OIDC/GitHub Actions.

No action is required for users of this module.

Hello,

We are sending this notification because you have configured a GitHub OpenID Connect (OIDC) identity provider (IdP) in your AWS account. GitHub uses a cross-signed TLS server certificate for GitHub’s OIDC servers which can have two intermediate certificates. Each of these intermediate certificates has a unique thumbprint. If you configured the GitHub IdP in your account using only one thumbprint, you may have encountered “Error: OpenIDConnect provider's HTTPS certificate doesn't match configured thumbprint” when attempting to access AWS resources using GitHub as the identity provider. This would occur when the certificate thumbprint configured in AWS does not match the one presented by the GitHub server.

No action is required from you.

Starting July 6, 2023, AWS began securing communication with GitHub’s OIDC identity provider (IdP) using our library of trusted root Certificate Authorities instead of using a certificate thumbprint to verify the IdP’s server certificate. This approach ensures that your GitHub OIDC configuration behaves correctly without disruption during future certificate rotations and changes. With this new validation approach in place, your legacy thumbprint(s) will remain in your configuration but will no longer be needed for validation purposes.

This change means the known thumbprints can be removed from the module and the additional_thumbprints variable can accept 5 thumbprints instead of 3.

Using module with var.enabled=false throws an error

Firstly thank you for this module - I got up and running with GHA way quicker and way easier than was reasonable to expect thanks to this module!

I'm struggling to use it my environment though when I try to set the enabled variable to false the module errors out. I have reproduced the error using the examples/complete directory. This is on 0.7.0.

I tried tweaking the create_oidc_provider variable to false as well, but that hasn't helped.

$ cd examples/complete
$ terraform init -reconfigure 
$ terraform plan -var=region=us-east-1 -var='github_repositories=["invalid/example"]' -var=enabled=true

<snip>
Plan: 3 to add, 0 to change, 0 to destroy.
<snip>

$ terraform plan -var=region=us-east-1 -var='github_repositories=["invalid/example"]' -var=enabled=false
╷
│ Error: Invalid index
│
│   on ../../main.tf line 17, in locals:
│   17:   oidc_provider_arn    = var.create_oidc_provider ? aws_iam_openid_connect_provider.github[0].arn : data.aws_iam_openid_connect_provider.github[0].arn
│     ├────────────────
│     │ aws_iam_openid_connect_provider.github is empty tuple
│
│ The given key does not identify an element in this collection value: the collection has no elements.
╵

Missing token.actions.githubusercontent.com:aud condition in iam role

The IAM role misses a condition as recommended by AWS [Documentation]
(https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-idp_oidc.html)
currently failing our security sentinel policy because of this

"Condition": {
  "StringLike": {
    "token.actions.githubusercontent.com:aud": "sts.amazonaws.com", <- missing
    "token.actions.githubusercontent.com:sub": "repo:GitHubOrg/*"
  }
}

support organization wide (all repos)

At the moment you have github_repositories which is list(string) that supports defining which repos you want the IAM policy for. In some organizations you might want to allowlist all repos by having:

    condition {
      test     = "StringLike"
      variable = "token.actions.githubusercontent.com:sub"
      values   = ["repo:myorg/*"]
    }

I am happy to submit a PR, but if you think it might be quick, I'll leave it to you.

Enhancement - Optional variable to define allowed branch/environment?

Hey @unfunco, thanks again for maintaining this. It's been real helpful.

I've been working to set up one of my developers with this to allow a series of public runners to access some internal resources - namely an S3 bucket. The engineer brought up a security concern around the fact that we define in the IAM role something like:

...
                "StringLike": {
                    "token.actions.githubusercontent.com:sub": "repo:my-org/my-repo:*"
                }
...

This is defined here as I'm sure you know: https://github.com/unfunco/terraform-aws-oidc-github/blob/main/data.tf#L28

Now, Github's own docs state that we are able to further limit what branches are allowed.

We can use specific refs or environments. I'd like to work on a PR to allow users optionally to specific this field instead of just a *. Wanted to get your take before I began the work in earnest to make sure you're interested.

I intend to make * continue to be the default, so this will be a minor/non-breaking change to end users. Purely an option/best practice.

Let me know what you think. Maybe there's some more simple way to accomplish improved security here that I'm overlooking.