{"id":15686979,"url":"https://github.com/moritzheiber/terraform-aws-oidc-github-actions-module","last_synced_at":"2025-05-07T03:24:19.672Z","repository":{"id":37745116,"uuid":"436190470","full_name":"moritzheiber/terraform-aws-oidc-github-actions-module","owner":"moritzheiber","description":"A Terraform module for dynamically authenticating and authorizing GitHub Actions on AWS using OIDC","archived":false,"fork":false,"pushed_at":"2025-04-16T23:28:42.000Z","size":703,"stargazers_count":9,"open_issues_count":1,"forks_count":2,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-04-19T17:58:09.072Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/moritzheiber.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2021-12-08T09:33:36.000Z","updated_at":"2025-03-13T08:31:57.000Z","dependencies_parsed_at":"2023-10-04T15:49:39.631Z","dependency_job_id":"69c7ba86-4f93-468d-80e0-2a5f421c7202","html_url":"https://github.com/moritzheiber/terraform-aws-oidc-github-actions-module","commit_stats":{"total_commits":240,"total_committers":2,"mean_commits":120.0,"dds":"0.17083333333333328","last_synced_commit":"134457e70ec1f27f989fe223bd5b7eac2dc0f0cb"},"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moritzheiber%2Fterraform-aws-oidc-github-actions-module","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moritzheiber%2Fterraform-aws-oidc-github-actions-module/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moritzheiber%2Fterraform-aws-oidc-github-actions-module/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moritzheiber%2Fterraform-aws-oidc-github-actions-module/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/moritzheiber","download_url":"https://codeload.github.com/moritzheiber/terraform-aws-oidc-github-actions-module/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252805144,"owners_count":21806934,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-03T17:42:14.800Z","updated_at":"2025-05-07T03:24:19.653Z","avatar_url":"https://github.com/moritzheiber.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!-- BEGIN_TF_DOCS --\u003e\n[![Module Releases](https://img.shields.io/badge/dynamic/json?color=%237b42bc\u0026label=Release\u0026query=version\u0026url=https%3A%2F%2Fregistry.terraform.io%2Fv1%2Fmodules%2Fmoritzheiber%2Foidc-github-actions-module%2Faws\u0026logo=terraform\u0026style=for-the-badge)](https://registry.terraform.io/modules/moritzheiber/oidc-github-actions-module/aws/latest) ![Module Downloads](https://img.shields.io/badge/dynamic/json?color=%237b42bc\u0026label=Downloads\u0026query=data.attributes.total\u0026url=https%3A%2F%2Fregistry.terraform.io%2Fv2%2Fmodules%2Fmoritzheiber%2Foidc-github-actions-module%2Faws%2Fdownloads%2Fsummary\u0026logo=terraform\u0026style=for-the-badge)\n\n# Terraform AWS OIDC GitHub Actions Module\n\nA module for creating a federated OIDC provider on AWS for dynamically authenticating and authorizing GitHub Actions workflow runs.\n\n## Setting up the OIDC AWS provider\n\nAdd the module to one of your Terraform configurations to create an OIDC provider and one or more roles that can be assumed via the provider. The names and ARNs of the created roles will be provided in the `roles` output of the module. You will need one or more names for GitHub repositories that GitHub Actions should be allowed to assume the roles from in order to configure the module:\n\n```hcl\nmodule \"oidc_auth\" {\n  source = \"github.com/moritzheiber/terraform-aws-oidc-github-actions-module\"\n\n  github_repositories = toset([\"my-org/my-repository\"])\n  role_names          = toset([\"some-role\"])\n}\n\noutput \"github_actions_roles\" {\n    value = module.oidc_auth.roles\n}\n```\n\n*Note: Usually you will want to use a specific version of the module by using the `version` attribute.*\n\nContinue with assigning permissions to these roles:\n\n```hcl\nresource \"aws_iam_policy\" \"policy\" {\n  name        = \"some_policy\"\n  path        = \"/\"\n  description = \"Some policy\"\n\n  policy = jsonencode({\n    Version = \"2012-10-17\"\n    Statement = [\n      {\n        Action = [\n          \"ec2:Describe*\",\n        ]\n        Effect   = \"Allow\"\n        Resource = \"*\"\n      },\n    ]\n  })\n}\n\nresource \"aws_iam_role_policy_attachment\" \"attachment\" {\n  for_each = module.oidc_auth.roles\n  role       = each.key\n  policy_arn = aws_iam_policy.policy.arn\n}\n```\n\n## Setting up GitHub Actions\n\n[AWS provides a \"native\" GitHub Actions action](https://github.com/aws-actions/configure-aws-credentials) to enable you to use the configured OIDC provider. Just add the following two bits to any job for a GitHub repository you passed under `github_repository` to the module previously and you should be good to go:\n\n```yaml\njobs:\n    some-job:\n        # [...]\n        permissions:\n          id-token: write\n          contents: read\n        # [...]\n        steps:\n            # [...]\n            - uses: aws-actions/configure-aws-credentials@v1\n                with:\n                  role-to-assume: \u003cARN-of-the-one-or-any-of-the-roles-created-by-the-module\u003e\n                  aws-region: \u003csome-region\u003e\n            # [...]\n            # Any step beyond the last one now has access to your AWS account with the permissions\n            # you assigned via the policy associated with the role you want to assume\n```\n\nYou can get the ARN of any of the roles created via the `roles` output of the OIDC module. In keeping with our previous example, the ARN for the `some-role` role would be accessible via `module.oidc_auth.roles[\"some-role\"]`. Be sure that `\u003csome-region\u003e` matches the region you used earlier to provision your Terraform code or otherwise you'll run into authentication issues.\n\nYou will probably want to add the ARN for `role-to-assume` as [a GitHub Actions secret](https://docs.github.com/en/actions/security-guides/encrypted-secrets) instead of writing it directly into the workflow YAML.\n\n## Troubleshooting\n\n#### \"OpenIDConnect provider's HTTPS certificate doesn't match configured thumbprint\"\n\nThe AWS OIDC provider _requires_ you to store the HTTP TLS thumbprint of any and all OIDC endpoints it is going to use to identify providers. In this case that's the endpoint for GitHub Actions, with its default URL at `https://token.actions.githubusercontent.com` (see `variables.tf`).\n\nTLS certificates change all the time, which is why, occasionally, you will have workflows fail because the thumbprint you stored in the AWS OIDC provider when running this module initially doesn't match \"the reality\" anymore (i.e. the endpoints HTTP TLS certificate has changed and therefore also its thumbprint). AWS will refuse to operate against an OIDC provider for which it doesn't have a correct thumbprint stored to prevent malicious actors from spoofing a seemingly valid HTTP TLS certificate to gain access to your AWS Account.\n\nYou will have to _manually verify that the new TLS certificate for the GitHub Actions endpoint is valid and can be trusted_ and then re-run this module afterwards.\n\nFor convenience, the module automatically fetches the latest thumbprint, and it will explicitely tell you that it's going to change the OIDC provider's thumbprint. After having re-run the module the newer thumbprint should be stored in the OIDC provider's definitions and your workflows should run again.\n\n##### Steps to resolve this error\n\n1. Fetch the current thumbprint from the module's output:\n\n```console\n$ terraform output [potential-module-prefix].github_actions_thumbprint\n```\n\nThe thumbprint will look something like this: `15e29108718111e59b3dad31954647e3c344a231` (it's the `sha1` thumbprint, for the curious)\n\n2. Make sure you are on a trusted network (e.g. no suspicious actors between you and GitHub's infrastructure) and run the following command:\n\n```console\n$ openssl s_client -connect token.actions.githubusercontent.com:443 | openssl x509 -noout -fingerprint -sha1\ndepth=2 C = US, O = DigiCert Inc, OU = www.digicert.com, CN = DigiCert Global Root CA\nverify return:1\ndepth=1 C = US, O = DigiCert Inc, CN = DigiCert TLS RSA SHA256 2020 CA1\nverify return:1\ndepth=0 C = US, ST = California, L = San Francisco, O = \"GitHub, Inc.\", CN = *.actions.githubusercontent.com\nverify return:1\nsha1 Fingerprint=15:E2:91:08:71:81:11:E5:9B:3D:AD:31:95:46:47:E3:C3:44:A2:31\n```\n\nThis is important: If the string from the first step doesn't match the string under `sha1 Fingerprint` (separated by colons) there are two scenarios: either the certificate was rotated (likely) or somebody is trying to highjack your connection to GitHub Actions.\n\nShould the thumbprints match it could've been [a temporary issue on AWS](https://health.aws.amazon.com/health/status) (it's the cloud after all) or [GitHub might be having problems](https://www.githubstatus.com/). It's unlikely to be something else, especially not this module. I would try to re-run the workflow(s), either now or at a later point in time.\n\n3. Verify that you're dealing with a newer certificate:\n\n```console\n$ openssl s_client -connect token.actions.githubusercontent.com:443 | openssl x509 -noout -dates\ndepth=2 C = US, O = DigiCert Inc, OU = www.digicert.com, CN = DigiCert Global Root CA\nverify return:1\ndepth=1 C = US, O = DigiCert Inc, CN = DigiCert TLS RSA SHA256 2020 CA1\nverify return:1\ndepth=0 C = US, ST = California, L = San Francisco, O = \"GitHub, Inc.\", CN = *.actions.githubusercontent.com\nverify return:1\nnotBefore=Jan 11 00:00:00 2022 GMT\nnotAfter=Jan 11 23:59:59 2023 GMT\n```\n\nAs you can see, under `notBefore` and `notAfter` are two dates. It is likely that the `notBefore` date is somewhere in the not too distant past (a day to a week), which would indicate that it was recently rotated.\n\n4. This is where you have to ask yourself whether you trust the newer certificate the endpoint is presenting to you. Because a newer certificate could also mean somebody generated a \"fake\" certificate recently and is trying to use a [MITM](https://en.wikipedia.org/wiki/Man-in-the-middle_attack) attack to harvest your (temporary) AWS credentials. There are other methods to verify an endpoints authenticity (checking on [OCSP revocations](https://www.certificatetools.com/ocsp-checker), [SSLLabs](https://www.ssllabs.com/ssltest/index.html)), but a more in-depth defense against TLS-based attacks is beyond the scope of this document.\n\n5. Adjust the thumbprint in the AWS OIDC provider configuration\n\nIf you're sure that the newer certificate was issued by a trusted authority (GitHub, DigiCert or some other trusted source) you can simply re-run the Terraform code this module is used from to replace the old thumbprint with the newer version. Terraform will automatically fetch the latest thumbprint and add it to your configuration\n\nAfterwards your workflows should run without authentication issues again.\n\n# Terraform module documentation\n\n## Requirements\n\n| Name | Version |\n|------|---------|\n| \u003ca name=\"requirement_terraform\"\u003e\u003c/a\u003e [terraform](#requirement\\_terraform) | \u003e= 1 |\n| \u003ca name=\"requirement_aws\"\u003e\u003c/a\u003e [aws](#requirement\\_aws) | ~\u003e 5 |\n| \u003ca name=\"requirement_tls\"\u003e\u003c/a\u003e [tls](#requirement\\_tls) | ~\u003e 4.0.1 |\n\n## Modules\n\nNo modules.\n\n## Resources\n\n| Name | Type |\n|------|------|\n| [aws_iam_openid_connect_provider.github](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/iam_openid_connect_provider) | resource |\n| [aws_iam_role.federated_auth_role](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/iam_role) | resource |\n| [aws_iam_policy_document.federated_assume_policy](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/iam_policy_document) | data source |\n| [tls_certificate.github_actions_oidc_endpoint](https://registry.terraform.io/providers/hashicorp/tls/latest/docs/data-sources/certificate) | data source |\n\n## Inputs\n\n| Name | Description | Type | Default | Required |\n|------|-------------|------|---------|:--------:|\n| \u003ca name=\"input_github_actions_oidc_url\"\u003e\u003c/a\u003e [github\\_actions\\_oidc\\_url](#input\\_github\\_actions\\_oidc\\_url) | The URL to use for the OIDC handshake | `string` | `\"https://token.actions.githubusercontent.com\"` | no |\n| \u003ca name=\"input_github_repositories\"\u003e\u003c/a\u003e [github\\_repositories](#input\\_github\\_repositories) | A list of GitHub repositories the OIDC provider should authenticate against. The format is org/user/repository-name | `set(string)` | `[]` | no |\n| \u003ca name=\"input_role_names\"\u003e\u003c/a\u003e [role\\_names](#input\\_role\\_names) | The set of names for roles that GitHub Actions will be able to assume | `set(string)` | `[]` | no |\n| \u003ca name=\"input_role_path\"\u003e\u003c/a\u003e [role\\_path](#input\\_role\\_path) | The path the created roles are going to live under | `string` | `\"/\"` | no |\n| \u003ca name=\"input_tags\"\u003e\u003c/a\u003e [tags](#input\\_tags) | A key \u003e value map of tags to associate with the resources that are being created | `map(string)` | `{}` | no |\n\n## Outputs\n\n| Name | Description |\n|------|-------------|\n| \u003ca name=\"output_github_actions_thumbprint\"\u003e\u003c/a\u003e [github\\_actions\\_thumbprint](#output\\_github\\_actions\\_thumbprint) | The thumbprint of the TLS certificate used for the OIDC endpoint at GitHub Actions |\n| \u003ca name=\"output_roles\"\u003e\u003c/a\u003e [roles](#output\\_roles) | The names and ARNs of the roles that were created |\n\u003c!-- END_TF_DOCS --\u003e","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmoritzheiber%2Fterraform-aws-oidc-github-actions-module","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmoritzheiber%2Fterraform-aws-oidc-github-actions-module","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmoritzheiber%2Fterraform-aws-oidc-github-actions-module/lists"}