search

terraform-module / terraform-aws-github-oidc-provider

Fully configurable terraform module to access AWS APIs from Github Actions through OpenID Connect.
MIT License
12 stars 11 forks source link

readme

AWS Github OIDC Provider Terraform Module

This module allows you to create a GitHub OIDC provider and the associated IAM roles, that will help Github Actions to securely authenticate against the AWS API using an IAM role.

We recommend using GitHub's OIDC provider to get short-lived credentials needed for your actions. Specifying role-to-assume without providing an aws-access-key-id or a web-identity-token-file will signal to the action that you wish to use the OIDC provider. The default session duration is 1 hour when using the OIDC provider to directly assume an IAM Role. The default session duration is 6 hours when using an IAM User to assume an IAM Role (by providing an aws-access-key-id, aws-secret-access-key, and a role-to-assume) . If you would like to adjust this you can pass a duration to role-duration-seconds, but the duration cannot exceed the maximum that was defined when the IAM Role was created. The default session name is GitHubActions, and you can modify it by specifying the desired name in role-session-name.

Features

  1. Create an AWS OIDC provider for GitHub Actions
  2. Create one or more IAM role that can be assumed by GitHub Actions
  3. IAM roles can be scoped to :
    • One or more GitHub organisations
    • One or more GitHub repository
    • One or more branches in a repository
Feature Status
Create a role for all repositories in a specific Github organisation ✅
Create a role specific to a repository for a specific organisation ✅
Create a role specific to a branch in a repository ✅
Create a role for multiple organisations/repositories/branches ✅
Create a role for organisations/repositories/branches selected by wildcard (e.g. feature/* branches) ✅

linter release.draft

Maintenance GitHub forks

Documentation

Usage example

IMPORTANT: The master branch is used in source just as an example. In your code, do not pin to master because there may be breaking changes between releases. Instead pin to the release tag (e.g. ?ref=tags/x.y.z) of one of our latest releases.

module "github-oidc" {
  source  = "terraform-module/github-oidc-provider/aws"
  version = "~> 1"

  create_oidc_provider = true
  create_oidc_role     = true

  repositories              = ["terraform-module/module-blueprint"]
  oidc_role_attach_policies = ["arn:aws:iam::aws:policy/AmazonEC2ContainerRegistryReadOnly"]
}

Examples

See examples directory for working examples to reference

Assumptions

Available features

AWS Github OIDC Provider Terraform Module

Purpose

This module allows you to create a Github OIDC provider for your AWS account, that will help Github Actions to securely authenticate against the AWS API using an IAM role

Requirements

Name Version
terraform >= 1

Providers

Name Version
aws n/a

Modules

No modules.

Resources

Name Type
aws_iam_openid_connect_provider.this resource
aws_iam_role.this resource
aws_iam_role_policy_attachment.attach resource
aws_iam_policy_document.this data source

Inputs

Name Description Type Default Required
create_oidc_provider Whether or not to create the associated oidc provider. If false, variable 'oidc_provider_arn' is required bool true no
oidc_provider_arn ARN of the OIDC provider to use. Required if 'create_oidc_provider' is false string null no
create_oidc_role Whether or not to create the OIDC attached role bool true no
github_thumbprint GitHub OpenID TLS certificate thumbprint. string "6938fd4d98bab03faadb97b34396831e3780aea1" no
max_session_duration Maximum session duration in seconds. number 3600 no
oidc_role_attach_policies Attach policies to OIDC role. list(string) [] no
repositories List of GitHub organization/repository names authorized to assume the role. list(string) [] no
role_description (Optional) Description of the role. string "Role assumed by the GitHub OIDC provider." no
role_name (Optional, Forces new resource) Friendly name of the role. string "github-oidc-provider-aws" no
tags A mapping of tags to assign to all resources map(string) {} no

Outputs

Name Description
oidc_provider_arn OIDC provider ARN
oidc_role CICD GitHub role.

:memo: Guidelines

License

Copyright 2022 Ivan Katliarhcuk

MIT Licensed. See LICENSE for full details.

How to Contribute

Submit a pull request

Authors

Currently maintained by Ivan Katliarchuk and these awesome contributors.

ForTheBadge uses-git

Terraform Registry

Resources

Clone Me

Create a repository using this template →