aripalo/aws-cdk-github-oidc

CDK constructs to use OpenID Connect for authenticating your Github Action workflow with AWS IAM

AWS CDK Github OpenID Connect

---

AWS CDK constructs that define:

• Github Actions as OpenID Connect Identity Provider into AWS IAM
• IAM Roles that can be assumed by Github Actions workflows

These constructs allows you to harden your AWS deployment security by removing the need to create long-term access keys for Github Actions and instead use OpenID Connect to Authenticate your Github Action workflow with AWS IAM.

Background information

• GitHub Actions: Secure cloud deployments with OpenID Connect on Github Changelog Blog.
• Security hardening your deployments on Github Docs.
• Assuming a role with aws-actions/configure-aws-credentials.
• Shout-out to Richard H. Boyd for helping me to debug Github OIDC setup with AWS IAM and his Deploying to AWS with Github Actions-talk.
• Shout-out to Aidan W Steele and his blog post AWS federation comes to GitHub Actions for being the original inspiration for this.

Getting started

npm i -D aws-cdk-github-oidc

OpenID Connect Identity Provider trust for AWS IAM

To create a new Github OIDC provider configuration into AWS IAM:

import { GithubActionsIdentityProvider } from "aws-cdk-github-oidc";

const provider = new GithubActionsIdentityProvider(scope, "GithubProvider");

In the background this creates an OIDC provider trust configuration into AWS IAM with an issuer URL of https://token.actions.githubusercontent.com and audiences (client IDs) configured as ['sts.amazonaws.com'] (which matches the aws-actions/configure-aws-credentials implementation).

Retrieving a reference to an existing Github OIDC provider configuration

Remember, there can be only one (Github OIDC provider per AWS Account), so to retrieve a reference to existing Github OIDC provider use fromAccount static method:

import { GithubActionsIdentityProvider } from "aws-cdk-github-oidc";

const provider = GithubActionsIdentityProvider.fromAccount(
  scope,
  "GithubProvider"
);

Defining a role for Github Actions workflow to assume

import { GithubActionsRole } from "aws-cdk-github-oidc";

const uploadRole = new GithubActionsRole(scope, "UploadRole", {
  provider: provider, // reference into the OIDC provider
  owner: "octo-org", // your repository owner (organization or user) name
  repo: "octo-repo", // your repository name (without the owner name)
  filter: "ref:refs/tags/v*", // JWT sub suffix filter, defaults to '*'
});

// use it like any other role, for example grant S3 bucket write access:
myBucket.grantWrite(uploadRole);

You may pass in any iam.RoleProps into the construct's props, except assumedBy which will be defined by this construct (CDK will fail if you do):

const deployRole = new GithubActionsRole(scope, "DeployRole", {
  provider: provider,
  owner: "octo-org",
  repo: "octo-repo",
  roleName: "MyDeployRole",
  description: "This role deploys stuff to AWS",
  maxSessionDuration: cdk.Duration.hours(2),
});

// You may also use various "add*" policy methods!
// "AdministratorAccess" not really a good idea, just for an example here:
deployRole.addManagedPolicy(
  iam.ManagedPolicy.fromAwsManagedPolicyName("AdministratorAccess")
);

Subject Filter

By default the value of filter property will be '*' which means any workflow (from given repository) from any branch, tag, environment or pull request can assume this role. To further stricten the OIDC trust policy on the role, you may adjust the subject filter as seen on the examples in Github Docs; For example:

filter value	Descrition
'ref:refs/tags/v*'	Allow only tags with prefix of v
'ref:refs/heads/demo-branch'	Allow only from branch demo-branch
'pull_request'	Allow only from pull request
'environment:Production'	Allow only from Production environment

Github Actions Workflow

To actually utilize this in your Github Actions workflow, use aws-actions/configure-aws-credentials to assume a role.

At the moment you must use the master version (until AWS releases a new tag):

jobs:
  deploy:
    name: Upload to Amazon S3
    runs-on: ubuntu-latest
    permissions:
      id-token: write # needed to interact with GitHub's OIDC Token endpoint.
      contents: read
    steps:
      - name: Checkout
        uses: actions/checkout@v2

      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@master
        with:
          role-to-assume: arn:aws:iam::123456789012:role/MyUploadRole
          #role-session-name: MySessionName # Optional
          aws-region: us-east-1

      - name: Sync files to S3
        run: |
          aws s3 sync . s3://my-example-bucket

aws-cdk-github-oidc's Issues

Constructs are not taggable

Looks like the custom constructs in this library are not taggable. Therefore tags added on the stack or app level don't propagate to resources created by custom constructs in this library.

Deprecate support for CDK v1

CDK v1 entered maintenance mode a year ago. There should be no need to support it anymore, so we should deprecate the release branch for v1 compatible construct (as it has not even been updated at all).

is there an example of how to use it? to deploy to my aws?

CDK v2 support

Release a new v2 major with CDK v2 support

Remove hardcoded (and now obsolete) GitHub thumbprints

As stated in issue #24, AWS is now handling the GitHub connection verification via trusted root CA and IAM ignores the provided thumbprints.

So the deprecated thumbprints should be now removed.

Github Thumbprints can be ommited

Hi there,

Just wanted to let you know, that you can omit the github certificates thumbprints and cdk/aws will fetch them on its own.

I am referring to this lines:
https://github.com/aripalo/aws-cdk-github-oidc/blob/main/src/provider.ts#L20-L23

See also the docs to the thumbprints parameter in the official docs

Type: string[] (optional, default: If no thumbprints are specified (an empty array or undefined), the thumbprint of the root certificate authority will be obtained from the provider's server as described in https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc_verify-thumbprint.html)

Its probably easier if you stick with that solution as a Constructs Library Maintainer, in case github change its certificate you dont need to maintain thumbprints at all.

Deprecate NodeJS v14 LTS and upgrade to v16 LTS

NodeJS v14 LTS has reached its end-of-life. Latest Projen requires active LTS version of NodeJS:

In some ways, this could be a major version release (for this construct), but as fixing current vulnerabilities requires updating Projen as well, using NodeJS v14 results in a build error (for this construct):

So, doing this in non-major version bump isn't optimal (and apologies for anyone this may cause trouble) but requiring NodeJS v16 is reasonable requirement (in my mind at least) because:

• the security patched version (of this construct) should actually work
• NodeJS v14 has been end-of-life since April 2023

On that note, I will be enabling DependaBot security update Pull Requests for this repo (I dunno why I've disabled them at some point - probably accident), to hopefully avoid this kind of mess in the future where a lot of depedency updates are required at one go.

Stale GitHub thumbprints

GitHub has updated their certificates:
https://github.blog/changelog/2023-06-27-github-actions-update-on-oidc-integration-with-aws/
You can see the thread of challenges for people here:
aws-actions/configure-aws-credentials#357

For temporary workaround:

    (GithubActionsIdentityProvider as any).thumbprints = [
      '1c58a3a8518e8759bf075b76b750d4f2df264fcd', // 2023-06-27
      '6938fd4d98bab03faadb97b34396831e3780aea1',
    ];
    const provider = new GithubActionsIdentityProvider(this, 'GithubProvider');

I cannot make a PR against origin, but essentially here is the fix:
pmoghaddam#1
I extended the code to more natively support overriding going forward.

Feature: support partitions

It seems that the library does not support other partitions than the different one.
I have an implementation for this and I will open a PR soon.

Reporting a vulnerability

Hello!

I hope you are doing well!

We are a security research team. Our tool automatically detected a vulnerability in this repository. We want to disclose it responsibly. GitHub has a feature called Private vulnerability reporting, which enables security research to privately disclose a vulnerability. Unfortunately, it is not enabled for this repository.

Can you enable it, so that we can report it?

Thanks in advance!

PS: you can read about how to enable private vulnerability reporting here: https://docs.github.com/en/code-security/security-advisories/repository-security-advisories/configuring-private-vulnerability-reporting-for-a-repository

Fix Go deployment

Currently Go deployment fails: https://github.com/aripalo/aws-cdk-github-oidc/actions/runs/5744594271/job/15571212677

Might be an issue with expired token or something. Need to investigate later.

Use jsii-struct-builder to produce iam-role-props.ts

You can use https://github.com/mrgrain/jsii-struct-builder to produce your Partial based on RoleProps: https://github.com/aripalo/aws-cdk-github-oidc/blob/main/src/iam-role-props.ts

You can see an example here: https://github.com/blimmer/cdk-static-wordpress/blob/372b42e9c9c3eb1bfde8c61afbded0188ca08d6c/.projenrc.ts#L66-L92

Patch vulnerable dependencies

Fix current vulnerable dependencies:

Feature: allow setting an array of filters (subjects)

Currently, it is only possible to set one filter per role.

aws-cdk-github-oidc/src/role.ts

Lines 163 to 166 in 53de62a

	StringLike: {
	// Only allow specified subjects to assume this role
	[`${GithubActionsIdentityProvider.issuer}:sub`]: subject,
	},

However I believe it is possible to support an array of filters, like so:

      "Condition": {
        "ForAnyValue:StringLike": {
          "token.actions.githubusercontent.com:sub": [
            "repo:myorg/myrepo:ref:refs/heads/test-branch-1",
            "repo:myorg/myrepo:ref:refs/heads/test-branch-2"
          ]
        }

(not actually tested, source)

Fix the NodeJS version in projenrc/nvmrc

I already upgraded to NodeJS v16 locally but forgot to update the NodeJS version in projenrc & nvmrc etc.