Configuring CDK with GitHub Actions and OIDC

OpenID Connect (OIDC) allows your GitHub Actions workflows to access resources in Amazon Web Services (AWS), without needing to store the AWS credentials as long-lived GitHub secrets.

AWS CDK helps you define your cloud application resources using familiar languages such as python, node, and more.

If you setup from the beginning using this guideline, you will have secured your connection between GitHub Actions and AWS without needing to expose the AWS credentials as GitHub Secrets.

Boostrap your infrastructure

CDK provides a way to boostrap all the necessary resources to start deploying using CDK in your aws account.

The next command assumes you have configured in your local machine the aws credentials and region configuration. If not, please refer to the official guideline on how to specify those credentials.

npx cdk bootstrap

After some minutes, you will see in your IAM > Roles a set of roles created by CDK to manage your infrastructure.

We will use them on the next steps to allow GitHub to deploy CloudFormation Stack changes assuming those roles.

Create a new role for github-actions to assume

I found more convinient to create a dedicated role for GitHub Actions to assume with the necessary trust relationship and permissions.

Go to IAM > Roles and Create Role. We will choose Custom trust policy

Trust relationship

We will copy the next code replacing the values of:

• <account_id> with your account id from AWS.

• <org>/<repo> with the repositories that should be able to change AWS resources.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "RoleForGitHub",
            "Effect": "Allow",
            "Principal": {
                "Federated": "arn:aws:iam::<account_id>:oidc-provider/token.actions.githubusercontent.com"
            },
            "Action": "sts:AssumeRoleWithWebIdentity",
            "Condition": {
                "StringEquals": {
                    "token.actions.githubusercontent.com:aud": "sts.amazonaws.com",
                    "token.actions.githubusercontent.com:sub": [
                        "repo:<org>/<repo>:ref:refs/heads/main",
                        "repo:<org>/<repo>:ref:refs/heads/main"
                    ]
                }
            }
        }
    ]
}

Policies

Next, it will ask us for the policies to add. We will click to the Create new policy button, and we will use the JSON format.

We will copy pase the next code replacing:

• <account> by your AWS account number

• <region> with the region you plan to deploy your resources. The same that cdk created during the `cdk boostrap` step. Copy paste those arn resources.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "assumerolecdk",
            "Effect": "Allow",
            "Action": [
                "sts:AssumeRole",
                "iam:PassRole"
            ],
            "Resource": [
                "arn:aws:iam::<account>:role/cdk-hnb659fds-lookup-role-<account>-<region>",
                "arn:aws:iam::<account>:role/cdk-hnb659fds-deploy-role-<account>-<region>",
                "arn:aws:iam::<account>:role/cdk-hnb659fds-file-publishing-role-<account>-<region>",
                "arn:aws:iam::<account>:role/cdk-hnb659fds-image-publishing-role-<account>-<region>"
            ]
        }
    ]
}

Verify that your role looks like

GitHub Action

Now, you can tell GitHub Action to deploy the resources assuming the new role replacing the <account> and <region> with your particular case.

The next code assumes you are using CDK with node, if you use CDK with python, you need to adapt the code to setup python.

name: Deployment

on:
  push:
    branches: [ "main" ]
  workflow_dispatch:

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: read
    steps:
    - uses: actions/checkout@v3
    - name: Set up node 18
      uses: actions/setup-node@v3
      with:
        node-version: 18
        cache: npm
    - name: npm install
      run: npm install
    - name: npm tests
      run: npm tests
    - name: Configure AWS Credentials
      uses: aws-actions/configure-aws-credentials@v2
      with:
        aws-region: <your region>
        role-to-assume: arn:aws:iam::<account>:role/github-role
        role-session-name: deployment-session
    - name: cdk synth
      run: npx --yes cdk synth
    - name: cdk deploy
      run: npx --yes cdk deploy --require-approval never