Setting up Workload Identity Federation for GitHub Actions

If you use the google-github-actions/auth GitHub action, it now recommends you authenticate via Workload Identity Federation. Buzzwords aside, this is a way to authenticate to Google Cloud Platform by trusting that GitHub is GitHub, therefore they can be granted a service account instead of needing a separate JSON key to authenticate the connection.

There are some guides around to set this up but I think it's easier to do it from the cloud console and we can explain what's going on instead of blindly copy/pasting gcloud commands everywhere.

Creating a new workload provider.

Head over to Google Cloud and create a new workload provider. Name your identity pool GitHub or whatever you'd like. This is meant to represent a given provider.

Next, create a new provider with the name GitHub, or also whatever you'd like, using OIDC and issuer URL https://token.actions.githubusercontent.com/.

Lastly, configure the following provider attributes. These map GitHub's information to Google Cloud, allowing Google Cloud to know who the token is for. The GitHub attributes can be found in OIDC documentation. I'm not sure where the Google Cloud documentation can be found or if the latter three attributes are even necessary. I know they're used if you want to further restrict the scope of the pool, but I'm not sure otherwise. If you know, please let me know too!

This step is functionally identical to the gcloud commands documented by Google.

Binding a Service Account

Now that we've created a workload pool and provider, we need to bind a service account to the provider. This is the service account that will be used to authenticate to Google Cloud Platform. Click Grant Access on the console.

Select the service account you'd like to use for your GitHub Action or create a new one.

Next, select the provider you created earlier, and for OIDC ID token path, put anything: it doesn't matter.

Download the file and it should look something like this

{
  "type": "external_account",
  "audience": "//iam.googleapis.com/projects/********/locations/global/workloadIdentityPools/github/providers/github",
  "subject_token_type": "urn:ietf:params:oauth:token-type:jwt",
  "token_url": "https://sts.googleapis.com/v1/token",
  "service_account_impersonation_url": "https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/github-action-******@********.iam.gserviceaccount.com:generateAccessToken",
  "credential_source": {
    "file": "asdfasdf",
    "format": {
      "type": "text"
    }
  }
}

Setting up GitHub Actions

For the last step, set up GitHub Actions to Identity Federation. In your google-github-actions/auth action, copy the workload_identity_provider and service_account from the JSON file's audience and service_account_impersonation_url respectively. Note that they have slightly different formats, so trim as necessary.

    - id: 'auth'
      name: 'Authenticate to Google Cloud'
      uses: 'google-github-actions/auth@v1'
      with:
        workload_identity_provider: 'projects/********/locations/global/workloadIdentityPools/github/providers/github'
        service_account: 'github-action-******@********.iam.gserviceaccount.com'

And you're done! Your GitHub action should now authenticate correctly.

Going back to the gcloud-based instructions, now the assorted commands should make more sense. Maybe I'm just a visual learner.