README.md

Browse the Repo

.circleci

.github

.patcher

_ci

_docs

codegen

examples

modules

_deprecated

auto-update

aws-auth

aws-config-bucket

aws-config-multi-region

aws-config-rules

aws-config

aws-organizations

cloudtrail-bucket

cloudtrail

cross-account-iam-roles

custom-iam-entity

ebs-encryption-multi-region

ebs-encryption

fail2ban

github-actions-iam-role

README.md

main.tf

outputs.tf

variables.tf

guardduty-multi-region

guardduty

iam-access-analyzer-multi-region

iam-groups

iam-policies

iam-user-password-policy

iam-users

ip-lockdown

kms-cmk-replica

kms-grant-multi-region

kms-master-key-multi-region

kms-master-key

ntp

os-hardening

private-s3-bucket

saml-iam-roles

secrets-manager-resource-policies

ssh-grunt-selinux-policy

ssh-grunt

ssh-iam

ssm-healthchecks-iam-permissions

tls-cert-private

test

.editorconfig

.gitignore

.pre-commit-config.yaml

CODEOWNERS

LICENSE.txt

README.adoc

terraform-cloud-enterprise-private-module-...

Browse the Repo

.circleci

.github

.patcher

_ci

_docs

codegen

examples

modules

_deprecated

auto-update

aws-auth

aws-config-bucket

aws-config-multi-region

aws-config-rules

aws-config

aws-organizations

cloudtrail-bucket

cloudtrail

cross-account-iam-roles

custom-iam-entity

ebs-encryption-multi-region

ebs-encryption

fail2ban

github-actions-iam-role

README.md

main.tf

outputs.tf

variables.tf

guardduty-multi-region

guardduty

iam-access-analyzer-multi-region

iam-groups

iam-policies

iam-user-password-policy

iam-users

ip-lockdown

kms-cmk-replica

kms-grant-multi-region

kms-master-key-multi-region

kms-master-key

ntp

os-hardening

private-s3-bucket

saml-iam-roles

secrets-manager-resource-policies

ssh-grunt-selinux-policy

ssh-grunt

ssh-iam

ssm-healthchecks-iam-permissions

tls-cert-private

test

.editorconfig

.gitignore

.pre-commit-config.yaml

CODEOWNERS

LICENSE.txt

README.adoc

terraform-cloud-enterprise-private-module-...

ssh-grunt

Manage SSH access to EC2 Instances using groups in AWS IAM or your Identity Provider (e.g., ADFS, Google, Okta, etc).

IAM Role for GitHub Actions

This Terraform module can be used to create Assume Role policies and IAM Roles such that they can be used with GitHub Actions. This requires you to provision an IAM OpenID Connect Provider for GitHub Actions in your account. By using OpenID Connect, GitHub Actions can directly exchange credentials to access AWS without having to store and provide GitHub with permanent AWS access credentials. This is useful to prevent credential leaks from progressing undetected.

You can either use the account-baseline-app or account-baseline-security modules (setting enable_github_actions_access = true) or by adding the following resource to your Terraform module:

resource "aws_iam_openid_connect_provider" "github_actions" {
  url             = "https://token.actions.githubusercontent.com"
  client_id_list  = ["sts.amazonaws.com"]
  thumbprint_list = [data.tls_certificate.oidc_thumbprint.certificates[0].sha1_fingerprint]
}

data "tls_certificate" "oidc_thumbprint" {
  url = "https://token.actions.githubusercontent.com"
}

How do you use this module?

See the root README for instructions on using Terraform modules.
See variables.tf for all the variables you can set on this module.
See outputs.tf for all the variables that are outputed by this module.

Creating the IAM Role

module "iam_role" {
  # Update <VERSION> with latest version of the module
  source = "git::git@github.com:gruntwork-io/terraform-aws-security.git//modules/github-actions-iam-role?ref=<VERSION>"

  github_actions_openid_connect_provider_arn = aws_iam_openid_connect_provider.github_actions.arn
  github_actions_openid_connect_provider_url = aws_iam_openid_connect_provider.github_actions.url

  allowed_sources = {
    "gruntwork-io/terraform-aws-security" = ["main"]
  }

  iam_role_name                  = "example-iam-role"
  permitted_full_access_services = ["ec2"]
}

The above example will configure the IAM role example-iam-role such that it is available to be assumed by GitHub Actions if it is run from the main branch of the gruntwork-io/terraform-aws-security repository. The IAM role would then have the ability to call any API in the ec2 namespace.

You can further customize the IAM role using the following variables:

permitted_full_access_services: List of AWS services that the IAM role will have full access to (set to SERVICE_NAME:*).
iam_policy: IAM policy statements that should be directly attached (inline) to the IAM role.
iam_policy_arns: List of IAM Policy ARNs that should be attached to the IAM role.
iam_customer_managed_policy_names: List of customer managed IAM policies that should be attached to the IAM role.
iam_aws_managed_policy_names: List of AWS managed IAM policies that should be attached to the IAM role.

Extend the allowed_sources map if you want to allow additional repositories or branches. For example, if you want to allow the dev branch on terraform-aws-security, as well as the main branch from terraform-aws-service-catalog:

module "iam_role" {
  # Update <VERSION> with latest version of the module
  source = "git::git@github.com:gruntwork-io/terraform-aws-security.git//modules/github-actions-iam-role?ref=<VERSION>"

  github_actions_openid_connect_provider_arn = aws_iam_openid_connect_provider.github_actions.arn
  github_actions_openid_connect_provider_url = aws_iam_openid_connect_provider.github_actions.url

  allowed_sources = {
    "gruntwork-io/terraform-aws-security"              = ["main", "dev"]
    "gruntwork-io/terraform-aws-service-catalog" = ["main"]
  }

  iam_role_name                  = "example-iam-role"
  permitted_full_access_services = ["ec2"]
}

You can also use the module to only manage the assume role policy. This is useful if you want more control over the IAM role creation. For example:

module "assume_role_policy" {
  # Update <VERSION> with latest version of the module
  source = "git::git@github.com:gruntwork-io/terraform-aws-security.git//modules/github-actions-iam-role?ref=<VERSION>"

  github_actions_openid_connect_provider_arn = aws_iam_openid_connect_provider.github_actions.arn
  github_actions_openid_connect_provider_url = aws_iam_openid_connect_provider.github_actions.url

  allowed_sources = {
    "gruntwork-io/terraform-aws-security"              = ["main", "dev"]
    "gruntwork-io/terraform-aws-service-catalog" = ["main"]
  }

  create_iam_role = false
}

resource "aws_iam_role" "example" {
  name               = "example-iam-role"
  assume_role_policy = module.assume_role_policy.assume_role_policy_json
}

Using created IAM Role in GitHub Actions Workflow

To use the created IAM role in your GitHub Actions Workflow, you need to configure the following:

Attach permissions to write id-token at the workflow or job level. To add this permission, add the following as a top level key, or under the job:

permissions: id-token: write

Add the aws-actions/configure-aws-credentials to your step. This retrieves a JWT from the GitHub OIDC provider, and then requests an access token from AWS. For more information, see the AWS documentation.

- name: configure aws credentials
  uses: aws-actions/configure-aws-credentials@master
  with:
    role-to-assume: IAM_ROLE_ARN_OUTPUT_OF_MODULE
    role-session-name: ANY_CUSTOM_SESSION_NAME
    aws-region: DEFAULT_REGION_TO_USE

With these two settings, your GitHub Action should now be able to assume the IAM role you created in this module. The following is a full GitHub Action Workflow example that lists EC2 instances on every push:

# Sample workflow to access AWS resources when workflow is tied to branch
name: AWS example workflow
on:
  push
permissions:
  id-token: write
jobs:
  ReadEC2Instances:
    runs-on: ubuntu-latest
    steps:
      - name: configure aws credentials
        uses: aws-actions/configure-aws-credentials@master
        with:
          role-to-assume: IAM_ROLE_ARN_OUTPUT_OF_MODULE
          role-session-name: ANY_CUSTOM_SESSION_NAME
          aws-region: us-east-1
      - name: Whoami?
        run: |
          aws sts get-caller-identity
      - name: Read EC2 Instances
        run: |
          aws ec2 describe-instances

Questions? Ask away.

We're here to talk about our services, answer any questions, give advice, or just to chat.

Ready to hand off the Gruntwork?

Buy Now

"https://cdn.gruntwork.io/gruntwork-website/"

{"index":{"js":"https://cdn.gruntwork.io/gruntwork-website/index.bundle.c7884255553b53fbca3a.js","map":"https://cdn.gruntwork.io/gruntwork-website/index.bundle.1b14c1b7d19f1f5eb35d6e118e838255.map"},"styles":{"css":"https://cdn.gruntwork.io/gruntwork-website/styles.bundle.f22938926651ddec7c49.css","js":"https://cdn.gruntwork.io/gruntwork-website/styles.bundle.e782420e74a20dcb8691.js","map":"https://cdn.gruntwork.io/gruntwork-website/styles.bundle.d5e2af49807c6ca33f8367d621ece507.map"},"vendors":{"css":"https://cdn.gruntwork.io/gruntwork-website/vendors.bundle.29f7d0366a0978763f96.css","js":"https://cdn.gruntwork.io/gruntwork-website/vendors.bundle.fa8174a130797d75d12c.js","map":"https://cdn.gruntwork.io/gruntwork-website/vendors.bundle.57243d94deeeb29d5061288a338b4eb6.map"}}

ssh-grunt

Code Preview

Preview the Code

IAM Role for GitHub Actions

How do you use this module?

Creating the IAM Role

Using created IAM Role in GitHub Actions Workflow

Questions? Ask away.

Ready to hand off the Gruntwork?