GitHub Actions AWS Authentication with OIDC for GitHub Enterprise

GitHub Actions AWS Authentication with OIDC for GitHub Enterprise

There are many blog posts about how to use GitHub Actions OIDC with AWS; however, they all refer to using Github.com and don't provide some easy steps if you are running your own GitHub Enterprise instance.

Today I spent far too long working this out and likely annoying my colleagues with email after email for failed builds!

Anyway, I made progress eventually, and hopefully, this will help some other poor lost soul hitting google for a simple answer!

Let's get into it.

What is OIDC?

I won't repeat the documentation simply put:-

OpenID Connect allows your workflows to exchange short-lived tokens directly from your cloud provider.

Since Aidens' post here, I've been eagerly waiting to have this in our GitHub Enterprise instance, which delivered this functionality in 3.5.

Configuring the OIDC Provider

Maybe it's just me, but the GitHub documentation didn't flow with the needed steps, and I went around in circles a bit.

Here are the steps I followed to get it up and running

Get Thumbprint

The thumbprint is a SHA1 hash of the public certificate of the host. To calculate it, you need to obtain the GitHub Enterprise instance certificate, and then calculate the hash using a tool like OpenSSL.

The GitHub Enterprise instance has the following URL available with the OIDC supported claims - https://mygithub.com/.well-known/openid-configuration.

Using this URL and the handy shell script provided via stackoverflow we can generate the SHA1 for my pretend instance mygithub.com.

$ HOST=$(curl https://mygithub.com/.well-known/openid-configuration \
| jq -r '.jwks_uri | split("/")[2]')

$ echo | openssl s_client -servername $HOST -showcerts -connect $HOST:443 2> /dev/null \
| sed -n -e '/BEGIN/h' -e '/BEGIN/,/END/H' -e '$x' -e '$p' | tail +2 \
| openssl x509 -fingerprint -noout \
| sed -e "s/.*=//" -e "s/://g" \
| tr "ABCDEF" "abcdef"
6938fd4d98bab03faadb97b34396831e3780aea1

Define the AWS::IAM::OIDCProvider

With this info, we can create our Cloudformation Stack to configure our OIDCProvider and the IAM Role our action will assume.

I've totally copied Adiens work and just added in the necessary updates to show how to configure the setting for GitHub Enterprise.

Key things to note are the StringLike conditions that had me a little stumped for a while as all the public examples are for GitHub.com!

---
AWSTemplateFormatVersion: 2010-09-09
Description: GitHub Actions AWS Authentication with OIDC for GitHub Enterprise

Parameters:
  GithubOrg: # can also be a regular user
    Type: String
    Default: mygithuborg
  FullRepoName:
    Type: String
    Default: mygithuborg/sjramblings

Resources:
  Role:
    Type: AWS::IAM::Role
    Properties:
      RoleName: ExampleGithubRole
      ManagedPolicyArns: [arn:aws:iam::aws:policy/ReadOnlyAccess]
      AssumeRolePolicyDocument:
        Statement:
          - Effect: Allow
            Action: sts:AssumeRoleWithWebIdentity
            Principal:
              Federated: !Ref GithubOidc
            Condition:
              StringLike:
                mygithub.com/_services/token:aud: !Sub https://mygithub.com/${GithubOrg}
                mygithub.com/_services/token:sub: !Sub repo:${FullRepoName}:*

  GithubOidc:
    Type: AWS::IAM::OIDCProvider
    Properties:
      Url: https://mygithub.com/_services/token
      ThumbprintList: [6938fd4d98bab03faadb97b34396831e3780aea1]
      ClientIdList:
        - !Sub https://mygithub.com/${GithubOrg}

Outputs:
  Role:
    Value: !GetAtt Role.Arn

References

https://stackoverflow.com/questions/69247498/how-can-i-calculate-the-thumbprint-of-an-openid-connect-server

https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect

https://docs.aws.amazon.com/IAM/latest/UserGuide/id\_roles\_create\_for-idp\_oidc.html

Summary

Using the above CloudFormation you can enable OIDC Authentication for your GitHub Enterprise instance workflows to perform actions within AWS without having to manage and rotate cloud credentials.

It will also enable you to use more fine-grained permissions granting only what is required.

I hope this helps someone else!

Cheers

Did you find this article valuable?

Support Stephen Jones by becoming a sponsor. Any amount is appreciated!