Secure AWS deploys from GitHub Actions with OIDC

Long gone are the days when you had to keep long-lived access keys in your CI/CD pipelines to deploy to AWS. Learn how to use OIDC (OpenID Connect) to securely deploy to AWS from Github Actions, and how to use GitHub Environments to secure deployments to specific AWS environments.

Introduction

Managing access from your CI/CD systems to your cloud environments in a secure manner can often be a tedious challenge. For a long time, one common way to do so for AWS was to set up an IAM user for this purpose and then store the access keys for that user in e.g. GitHub secrets for use with GitHub Actions. This required a lot of manual work, such as setting up different users for different projects, rotating keys after a certain period, etc.

By utilizing OIDC you can configure AWS to trust GitHub as a federated identity provider, and then use ID tokens in Github Actions workflows to authenticate to AWS and access resources. You can create separate IAM roles for different purposes and allow workflows to assume those roles in a granular way.

Each job in a GitHub Actions workflow can request an OIDC token from GitHub’s OIDC provider. The contents of the token are described well in the GitHub documentation. Depending on the job’s configuration, as well as what event triggered the workflow, the token will contain a different set of claims. One important claim is the sub claim, which will be used in our IAM Role trust policies to grant permission for workflows to use a role.

For example, if a workflow is triggered by a push to the main branch of a repository named repo-org/repo-name, the subject claim will be set to repo:repo-org/repo-name:ref:refs/heads/main. If a job references a GitHub environment named Production, the subject claim will be set to repo:repo-org/repo-name:environment:Production. For a full list of possible subject claims, check the GitHub documentation.

Example setup

In this example, we will use two different S3 buckets to mimic two different AWS environments. We will create two different workflows, one that will be triggered by pushes to the main branch, and another that will be triggered by pull requests.

On pull requests, we want to be able to read our environments. In a real example, this could perhaps be a terraform plan job that could visualize any proposed changes to the environment. We will also deploy to the development environment from pull requests, to speed up the feedback loop. We do, however, NOT want to deploy to the production environment from pull requests. We also need to make sure that contributors cannot update the workflow as part of the pull request to include a deployment to the production environment.

For pushes to main, we want to be able to read and deploy to both environments. We will also require manual approval from a repository admin to deploy to the production environment.

In the example workflows, read and deploy operations will be demonstrated by download and upload operations to the respective S3 buckets.

1. Create buckets

Start by creating two buckets in your account. I will refer to these below as YOUR_DEV_BUCKET and YOUR_PROD_BUCKET.

2. Add GitHub as an identity provider

To be able to authenticate with OIDC from GitHub you will first need to set up GitHub as a federated identity provider in your AWS account. To do that, navigate to the AWS IAM console and click on Identity Providers on the left-hand side. Then, click on the Add provider button.

1. For Provider type, select OpenID Connect.
2. For Provider URL, enter https://token.actions.githubusercontent.com
3. Click on Get thumbprint to get the thumbprint of the provider
4. For Audience, enter sts.amazonaws.com

3. Create roles and policies

Now that GitHub is set up as an identity provider, it is time to create the roles and policies that will be assumed by the respective workflows. You will create three roles:

• Reader role: Will have read permissions on both the buckets. This role will be available both for pull_request events as well as push events to the main branch.
• Dev Deploy role: Will have both read and write permissions to the dev bucket. This role will require a workflow to use the Development GitHub environment.
• Prod Deploy role: Will have both read and write permissions to the prod bucket. This role will require a workflow to use the Production GitHub environment.

Reader role

Start by creating a new role that will be used to read from the buckets. The role should be able to be assumed by both workflows triggered by the pull_request and push events. To allow this, the role will need to have the following trust policy:

1
{
2
  "Version": "2012-10-17",
3
  "Statement": [
4
    {
5
      "Effect": "Allow",
6
      "Principal": {
7
        "Federated": "arn:aws:iam::0123456789:oidc-provider/token.actions.githubusercontent.com"
8
      },
9
      "Action": "sts:AssumeRoleWithWebIdentity",
10
      "Condition": {
11
        "StringEquals": {
12
          "token.actions.githubusercontent.com:sub": [
13
            "repo:ORG_OR_USER_NAME/REPOSITORY:pull_request",
14
            "repo:ORG_OR_USER_NAME/REPOSITORY:ref:refs/heads/main"
15
          ],
16
          "token.actions.githubusercontent.com:aud": "sts.amazonaws.com"
17
        }
18
      }
19
    }
20
  ]
21
}

You need to replace the ORG_OR_USER_NAME and REPOSITORY with your own values. For my example repository eliasbrange/aws-github-actions-oidc it would be "repo:eliasbrange/aws-github-actions-oidc:pull_request"

Next, add an IAM policy to this role that grants the role permission to read from the buckets.

1
{
2
  "Statement": [
3
    {
4
      "Action": ["s3:ListBucket"],
5
      "Effect": "Allow",
6
      "Resource": [
7
        "arn:aws:s3:::YOUR_DEV_BUCKET",
8
        "arn:aws:s3:::YOUR_PROD_BUCKET"
9
      ]
10
    },
11
    {
12
      "Action": ["s3:GetObject"],
13
      "Effect": "Allow",
14
      "Resource": [
15
        "arn:aws:s3:::YOUR_DEV_BUCKET/*",
16
        "arn:aws:s3:::YOUR_PROD_BUCKET/*"
17
      ]
18
    }
19
  ],
20
  "Version": "2012-10-17"
21
}

Development Deploy Role

Create another role that will be used to “deploy” to the development environment, in this case by uploading a file to the development bucket. This role should require the workflow to use a GitHub Environment named Development, so it will require the following trust policy:

1
{
2
  "Version": "2012-10-17",
3
  "Statement": [
4
    {
5
      "Effect": "Allow",
6
      "Principal": {
7
        "Federated": "arn:aws:iam::0123456789:oidc-provider/token.actions.githubusercontent.com"
8
      },
9
      "Action": "sts:AssumeRoleWithWebIdentity",
10
      "Condition": {
11
        "StringEquals": {
12
          "token.actions.githubusercontent.com:sub": "repo:ORG_OR_USER_NAME/REPOSITORY:environment:Development",
13
          "token.actions.githubusercontent.com:aud": "sts.amazonaws.com"
14
        }
15
      }
16
    }
17
  ]
18
}

Give it the following IAM policy:

1
{
2
  "Statement": [
3
    {
4
      "Action": ["s3:ListBucket"],
5
      "Effect": "Allow",
6
      "Resource": ["arn:aws:s3:::YOUR_DEV_BUCKET"]
7
    },
8
    {
9
      "Action": ["s3:GetObject", "s3:PutObject"],
10
      "Effect": "Allow",
11
      "Resource": ["arn:aws:s3:::YOUR_DEV_BUCKET/*"]
12
    }
13
  ],
14
  "Version": "2012-10-17"
15
}

Production Deploy Role

Create the final role, which will be used for production deploys. It should look similar to the development role, but with some changes to the permissions.

Add the following trust policy:

1
{
2
  "Version": "2012-10-17",
3
  "Statement": [
4
    {
5
      "Effect": "Allow",
6
      "Principal": {
7
        "Federated": "arn:aws:iam::0123456789:oidc-provider/token.actions.githubusercontent.com"
8
      },
9
      "Action": "sts:AssumeRoleWithWebIdentity",
10
      "Condition": {
11
        "StringEquals": {
12
          "token.actions.githubusercontent.com:sub": "repo:ORG_OR_USER_NAME/REPOSITORY:environment:Production",
13
          "token.actions.githubusercontent.com:aud": "sts.amazonaws.com"
14
        }
15
      }
16
    }
17
  ]
18
}

Give it the following IAM policy:

1
{
2
  "Statement": [
3
    {
4
      "Action": ["s3:ListBucket"],
5
      "Effect": "Allow",
6
      "Resource": ["arn:aws:s3:::YOUR_PROD_BUCKET"]
7
    },
8
    {
9
      "Action": ["s3:GetObject", "s3:PutObject"],
10
      "Effect": "Allow",
11
      "Resource": ["arn:aws:s3:::YOUR_PROD_BUCKET/*"]
12
    }
13
  ],
14
  "Version": "2012-10-17"
15
}

4. Create GitHub Environments

In your GitHub repository, create two environments, Development and Production. For Development, we will not add any safeguards so that we can deploy to it directly from pull requests. However, for the Production environment, we will add a few protection rules.

1. In the environment configuration under Environment protection rules, tick the Required reviewers box and add your own GitHub username.
2. In the environment configuration under Deployment branches, pick Selected branches in the dropdown and add main as an allowed branch.

The above rules will prevent contributors to modify the actual workflow as part of a pull request to deploy to production. It will also force workflows that target the Production environment to require manual approval.

5. Add GitHub secrets

In your GitHub repository, add the following secrets:

1. DEV_DEPLOY_ROLE: The ARN of your development deploy role.
2. PROD_DEPLOY_ROLE: The ARN of your production deploy role.
3. READ_ROLE: The ARN of your reader role.

6. Create workflows

Time to create the deployment workflows. You will create a total of three workflows, one for pull requests, one for pushes to main, as well as a bonus workflow for visualizing which workflow event triggers that has access to which IAM roles.

Pull request workflow

Add the following workflow to your repository:

1
name: 'Pull Request'
2

3
# The workflow should only trigger on pull requests to the main branch
4
on:
5
  pull_request:
6
    branches:
7
      - main
8

9
# Required to get the ID Token that will be used for OIDC
10
permissions:
11
  id-token: write
12

13
jobs:
14
  read-dev:
15
    runs-on: ubuntu-latest
16
    steps:
17
      - name: Checkout
18
        uses: actions/checkout@v3
19

20
      - name: Configure AWS Credentials
21
        uses: aws-actions/configure-aws-credentials@v1
22
        with:
23
          aws-region: eu-west-1
24
          role-to-assume: ${{ secrets.READ_ROLE }}
25
          role-session-name: OIDCSession
26

27
      - run: aws s3 cp s3://YOUR_DEV_BUCKET/README.md README.md
28
        shell: bash
29

30
  write-dev:
31
    runs-on: ubuntu-latest
32
    needs: read-dev
33
    environment: Development
34
    steps:
35
      - name: Checkout
36
        uses: actions/checkout@v3
37

38
      - name: Configure AWS Credentials
39
        uses: aws-actions/configure-aws-credentials@v1
40
        with:
41
          aws-region: eu-west-1
42
          role-to-assume: ${{ secrets.DEV_DEPLOY_ROLE }}
43
          role-session-name: OIDCSession
44

45
      - run: aws s3 cp README.md s3://YOUR_DEV_BUCKET/README.md
46
        shell: bash
47

48
  read-prod:
49
    runs-on: ubuntu-latest
50
    steps:
51
      - name: Checkout
52
        uses: actions/checkout@v3
53

54
      - name: Configure AWS Credentials
55
        uses: aws-actions/configure-aws-credentials@v1
56
        with:
57
          aws-region: eu-west-1
58
          role-to-assume: ${{ secrets.READ_ROLE }}
59
          role-session-name: OIDCSession
60

61
      - run: aws s3 cp s3://YOUR_PROD_BUCKET/README.md README.md
62
        shell: bash

This is a very basic workflow that:

1. First downloads the README.md file from the Development bucket.
2. Then uploads the README.md from the repository to the Development bucket.
3. Finally downloads the README.md file from the Production bucket.

Not a very exciting, nor useful, workflow, but it demonstrates the usage of different roles and environments.

In both read-dev and read-prod there is no environment specified, so the ID token in these jobs will have a subject claim of repo:ORG_OR_USER_NAME/REPOSITORY:pull_request. They are also both using the READ_ROLE secret, which should point to the ARN of your reader IAM role.

In write-dev, there is environment: Development specified, which means that the ID token will have a subject claim of repo:ORG_OR_USER_NAME/REPOSITORY:environment:Development. The job uses the DEV_DEPLOY_ROLE secret instead of READ_ROLE.

Push to main workflow

Add the following workflow to your repository:

1
name: 'Push'
2

3
# The workflow should only trigger on push events to the main branch
4
on:
5
  push:
6
    branches:
7
      - main
8

9
# Required to get the ID Token that will be used for OIDC
10
permissions:
11
  id-token: write
12

13
jobs:
14
  read-dev:
15
    runs-on: ubuntu-latest
16
    steps:
17
      - name: Checkout
18
        uses: actions/checkout@v3
19

20
      - name: Configure AWS Credentials
21
        uses: aws-actions/configure-aws-credentials@v1
22
        with:
23
          aws-region: eu-west-1
24
          role-to-assume: ${{ secrets.READ_ROLE }}
25
          role-session-name: OIDCSession
26

27
      - run: aws s3 cp s3://YOUR_DEV_BUCKET/README.md README.md
28
        shell: bash
29

30
  write-dev:
31
    runs-on: ubuntu-latest
32
    needs: read-dev
33
    environment: Development
34
    steps:
35
      - name: Checkout
36
        uses: actions/checkout@v3
37

38
      - name: Configure AWS Credentials
39
        uses: aws-actions/configure-aws-credentials@v1
40
        with:
41
          aws-region: eu-west-1
42
          role-to-assume: ${{ secrets.DEV_DEPLOY_ROLE }}
43
          role-session-name: OIDCSession
44

45
      - run: aws s3 cp README.md s3://YOUR_DEV_BUCKET/README.md
46
        shell: bash
47

48
  read-prod:
49
    runs-on: ubuntu-latest
50
    steps:
51
      - name: Checkout
52
        uses: actions/checkout@v3
53

54
      - name: Configure AWS Credentials
55
        uses: aws-actions/configure-aws-credentials@v1
56
        with:
57
          aws-region: eu-west-1
58
          role-to-assume: ${{ secrets.READ_ROLE }}
59
          role-session-name: OIDCSession
60

61
      - run: aws s3 cp s3://YOUR_PROD_BUCKET/README.md README.md
62
        shell: bash
63

64
  write-prod:
65
    needs: [read-prod, write-dev]
66
    runs-on: ubuntu-latest
67
    environment: Production
68
    steps:
69
      - name: Checkout
70
        uses: actions/checkout@v3
71

72
      - name: Configure AWS Credentials
73
        uses: aws-actions/configure-aws-credentials@v1
74
        with:
75
          aws-region: eu-west-1
76
          role-to-assume: ${{ secrets.PROD_DEPLOY_ROLE }}
77
          role-session-name: OIDCSession
78

79
      - run: aws s3 cp README.md s3://YOUR_PROD_BUCKET/README.md
80
        shell: bash

Almost the same as the previous workflow, but with the addition of a write-prod job.

1. Download README.md from the Development bucket.
2. Upload README.md from the repository to the Development bucket.
3. Download README.md from the Production bucket.
4. Upload README.md from the repository to the Production bucket.

read-prod uses the same setup as read-dev, i.e. no environment and both use the READ_ROLE secret. The write-prod job is similar to the write-dev job, but uses environment: Production and the PROD_DEPLOY_ROLE secret.

Bonus workflow

This workflow is a bonus workflow that uses a matrix strategy to show the result of different combinations of subject claim, environment and role.

Add the following workflow to your repository:

1
name: 'Bonus'
2

3
on:
4
  pull_request:
5
    branches:
6
      - main
7

8
  push:
9
    branches:
10
      - main
11

12
permissions:
13
  id-token: write
14

15
jobs:
16
  read-dev:
17
    strategy:
18
      fail-fast: false
19
      matrix:
20
        environment:
21
          - ''
22
          - Development
23
          - Production
24
        role_secret:
25
          - READ_ROLE
26
          - DEV_DEPLOY_ROLE
27
          - PROD_DEPLOY_ROLE
28
    runs-on: ubuntu-latest
29
    environment: ${{ matrix.environment }}
30
    steps:
31
      - name: Checkout
32
        uses: actions/checkout@v3
33

34
      - name: Configure AWS Credentials
35
        uses: aws-actions/configure-aws-credentials@v1
36
        with:
37
          aws-region: eu-west-1
38
          role-to-assume: ${{ secrets[matrix.role_secret] }}
39
          role-session-name: OIDCSession
40

41
      - run: aws s3 cp s3://YOUR_DEV_BUCKET/README.md README.md
42
        shell: bash
43

44
  write-dev:
45
    strategy:
46
      fail-fast: false
47
      matrix:
48
        environment:
49
          - ''
50
          - Development
51
          - Production
52
        role_secret:
53
          - READ_ROLE
54
          - DEV_DEPLOY_ROLE
55
          - PROD_DEPLOY_ROLE
56
    runs-on: ubuntu-latest
57
    environment: ${{ matrix.environment }}
58
    steps:
59
      - name: Checkout
60
        uses: actions/checkout@v3
61

62
      - name: Configure AWS Credentials
63
        uses: aws-actions/configure-aws-credentials@v1
64
        with:
65
          aws-region: eu-west-1
66
          role-to-assume: ${{ secrets[matrix.role_secret] }}
67
          role-session-name: OIDCSession
68

69
      - run: aws s3 cp README.md s3://YOUR_DEV_BUCKET/README.md
70
        shell: bash
71

72
  read-prod:
73
    strategy:
74
      fail-fast: false
75
      matrix:
76
        environment:
77
          - ''
78
          - Development
79
          - Production
80
        role_secret:
81
          - READ_ROLE
82
          - DEV_DEPLOY_ROLE
83
          - PROD_DEPLOY_ROLE
84
    runs-on: ubuntu-latest
85
    environment: ${{ matrix.environment }}
86
    steps:
87
      - name: Checkout
88
        uses: actions/checkout@v3
89

90
      - name: Configure AWS Credentials
91
        uses: aws-actions/configure-aws-credentials@v1
92
        with:
93
          aws-region: eu-west-1
94
          role-to-assume: ${{ secrets[matrix.role_secret] }}
95
          role-session-name: OIDCSession
96

97
      - run: aws s3 cp s3://YOUR_PROD_BUCKET/README.md README.md
98
        shell: bash
99

100
  write-prod:
101
    strategy:
102
      fail-fast: false
103
      matrix:
104
        environment:
105
          - ''
106
          - Development
107
          - Production
108
        role_secret:
109
          - READ_ROLE
110
          - DEV_DEPLOY_ROLE
111
          - PROD_DEPLOY_ROLE
112
    runs-on: ubuntu-latest
113
    environment: ${{ matrix.environment }}
114
    steps:
115
      - name: Checkout
116
        uses: actions/checkout@v3
117

118
      - name: Configure AWS Credentials
119
        uses: aws-actions/configure-aws-credentials@v1
120
        with:
121
          aws-region: eu-west-1
122
          role-to-assume: ${{ secrets[matrix.role_secret] }}
123
          role-session-name: OIDCSession
124

125
      - run: aws s3 cp README.md s3://YOUR_PROD_BUCKET/README.md
126
        shell: bash

This workflow will be triggered by both pushes to main and pull requests. It will then try to perform reads and writes on both buckets with different combinations of environment and role_secret.

Results

With all the workflows pushed to main in your repository, create a new branch and create a pull request. If everything works correctly, the workflow named Pull Request should execute successfully. The Bonus workflow should fail for a lot of combinations (and it might take some time to fail due to the back-off strategy of the configure AWS credentials action).

If you merge the pull request, the workflow named Push should execute successfully.

Workflow combinations

Looking at the Bonus workflow we should be able to see which combinations of workflow event, environment and role that is possible with the OIDC setup we have. The working combinations should also be different depending on whether the workflow started from a push to main or a pull request.

For each of the 4 jobs, we should have 9 different combinations. These combinations are:

Pull request

If we start by looking at a pull request, the workflow should have access to the READ_ROLE when the environment is NONE (which means that the subject claim will be repo:ORG_OR_USER_NAME/REPOSITORY:pull_request). This should allow the workflow to read both development and production buckets when using the combination of no environment and READ_ROLE.

It should also be able to use the Development environment since there are no protection rules for that environment. This should allow the workflow to both read and write to the development bucket when the environment is Development and role is DEV_DEPLOY_ROLE.

Due to the environment protection rule on Production, the workflow should not be able to use the Production environment at all when triggered by pull requests.

read-dev job

write-dev job

read-prod job

write-prod job

Push

Continuing to the workflow when triggered by a push to main, we should be able to again use the READ_ROLE when the environment is NONE. This should give read access to both buckets for that combination.

For writing to development, a combination of Development environment with DEV_DEPLOY_ROLE is required.

Finally, to deploy to production, a combination of Production environment with PROD_DEPLOY_ROLE is required. This should also trigger a manual approval step to continue the deployment.

read-dev job

write-dev job

read-prod job

write-prod job

Conclusions

Starting from this example, you should now be able to use GitHub OIDC as a federated identity in your own GitHub Actions workflows to get rid of long-lived credentials once and for all. You have learned how to:

• Enable federated identity for GitHub on the AWS side
• Define which repositories and workflow events are allowed to access your roles
• Keep your production environments secure by requiring additional steps

Hope you learned a thing or two. Now go build something awesome.

GitHub repository

I have a companion repository available on GitHub for this blog post, where you can find the workflows themselves, as well as terraform configuration for setting up the AWS side.