Skip to content
play

GitHub Action

AWS IAM assume role

v1 Latest version

AWS IAM assume role

play

AWS IAM assume role

Assume an AWS IAM role - either via an IAM user or OpenID Connect (OIDC)

Installation

Copy and paste the following snippet into your .yml file.

 
              
- name: AWS IAM assume role

              
  uses: magnetikonline/action-aws-iam-assume-role@v1
Learn more about this action in magnetikonline/action-aws-iam-assume-role

Choose a version

Action AWS IAM assume role

Action that allows for the sts:AssumeRole of an IAM role via the following methods:

  • An IAM user with permission to assume the target IAM role using static access ID key/secret access key credentials (the old way).
  • Via a GitHub OpenID Connect identity provider (OIDC), which avoids the need to handle static secrets (the new, preferred way 👌).

To keep things relatively simple, this composite action uses the AWS CLI for all AWS API operations and a little Python to handle execution/parsing responses and setting things up - all of which is pre-installed out of the box under GitHub-hosted runners.

Be aware: designed for use under Linux based runners only - doubtful this will get far under Windows. 😀

Usage

IAM user -> IAM role

Given the following IAM user permissions:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "sts:AssumeRole",
      "Resource": [
        "arn:aws:iam::ACCOUNT_ID:role/MY_TARGET_ROLE"
      ]
    }
  ]
}

...and the following IAM role trust relationship:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "sts:AssumeRole",
      "Principal": {
        "AWS": [
          "arn:aws:iam::ACCOUNT_ID:user/MY_IAM_USER"
        ]
      }
    }
  ]
}

the following GitHub Actions workflow example would provide IAM assume of arn:aws:iam::ACCOUNT_ID:role/MY_TARGET_ROLE:

jobs:
  main:
    name: IAM user -> IAM role
    runs-on: ubuntu-latest
    steps:
      - name: Assume role
        uses: magnetikonline/action-aws-iam-assume-role@v1
        with:
          user-access-key-id: ${{ secrets.IAM_USER_ACCESS_KEY_ID }}
          user-secret-access-key: ${{ secrets.IAM_USER_SECRET_ACCESS_KEY }}
          assume-role-arn: arn:aws:iam::ACCOUNT_ID:role/MY_TARGET_ROLE
          aws-region: ap-southeast-2
          # optional inputs
          # assume-role-duration-seconds: 6000
          # assume-role-session-name: GitHubActions

      # IAM role assumed via AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY/AWS_SESSION_TOKEN
      - name: whoami
        run: aws sts get-caller-identity

OpenID Connect (OIDC) IAM role

Note: assumes arn:aws:iam::ACCOUNT_ID:oidc-provider/token.actions.githubusercontent.com has been previously configured as an OpenID Connect AWS identity provider to GitHub with the following settings:

  • Provider: token.actions.githubusercontent.com
  • Audience: https://github.com/ORGANIZATION_OR_USERNAME

Given the following IAM role trust relationship:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Principal": {
        "Federated": "arn:aws:iam::ACCOUNT_ID:oidc-provider/token.actions.githubusercontent.com"
      },
      "Condition": {
        "StringLike": {
          "token.actions.githubusercontent.com:aud": "https://github.com/ORGANIZATION_OR_USERNAME",
          "token.actions.githubusercontent.com:sub": "repo:ORGANIZATION_OR_USERNAME/*"
        }
      }
    }
  ]
}

the following GitHub Actions workflow example would provide IAM assume of the OpenID Connect provider trusted IAM role:

jobs:
  main:
    name: OpenID Connect (OIDC) IAM role
    runs-on: ubuntu-latest
    # note: permissions required to fetch OpenID Connect token and allow actions/checkout
    permissions:
      contents: read
      id-token: write
    steps:
      - name: Assume role
        uses: magnetikonline/action-aws-iam-assume-role@v1
        with:
          web-identity-role-arn: arn:aws:iam::ACCOUNT_ID:role/MY_TARGET_ROLE_WITH_OIDC_TRUST_RELATIONSHIP
          aws-region: ap-southeast-2
          # optional inputs
          # assume-role-duration-seconds: 6000
          # assume-role-session-name: GitHubActions

      # IAM role assumed via AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY/AWS_SESSION_TOKEN
      - name: whoami
        run: aws sts get-caller-identity

OpenID Connect (OIDC) IAM role -> Another IAM role

A slight spin on above, performing the following:

  • First assume the OpenID Connect trusted IAM role.
  • Next, assume another IAM role via the OIDC trusted IAM role.

With the following another IAM role trust relationship:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "sts:AssumeRole",
      "Principal": {
        "AWS": [
          "arn:aws:iam::ACCOUNT_ID:role/MY_TARGET_ROLE_WITH_OIDC_TRUST_RELATIONSHIP"
        ]
      }
    }
  ]
}

the following GitHub Actions workflow example would provide IAM assume of OpenID Connect provider trusted IAM role -> final role. Note the use of both web-identity-role-arn and assume-role-arn input arguments:

jobs:
  main:
    name: OpenID Connect (OIDC) IAM role -> Another IAM role
    runs-on: ubuntu-latest
    # note: permissions required to fetch OpenID Connect token and allow actions/checkout
    permissions:
      contents: read
      id-token: write
    steps:
      - name: Assume role
        uses: magnetikonline/action-aws-iam-assume-role@v1
        with:
          web-identity-role-arn: arn:aws:iam::ACCOUNT_ID:role/MY_TARGET_ROLE_WITH_OIDC_TRUST_RELATIONSHIP
          assume-role-arn: arn:aws:iam::ACCOUNT_ID:role/MY_TARGET_ROLE_ASSUMED_FROM_OIDC_ROLE
          aws-region: ap-southeast-2
          # optional inputs
          # assume-role-duration-seconds: 6000
          # assume-role-session-name: GitHubActions

      # IAM role assumed via AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY/AWS_SESSION_TOKEN
      - name: whoami
        run: aws sts get-caller-identity

Reference