Access Authress through GitHub Actions

Background

To access Authress securely--updating roles, access records, connections, etc--requires a valid access token. Access tokens can be generated by one of a few different mechanisms. In this guide we'll review how to use the trusted OIDC provider. The Trusted OIDC provider is the correct option to use when you have an existing system that generates JWTs. If you have an existing Auth provider that your software already trusts, this is the right solution, such as Cognito, Firebase, Auth0, Terraform, GitLab, etc...

Because GitHub can generate its own JWTs, Authress can use those tokens. In this guide we will set up a Trusted OIDC Provider from the Instructions in the Connections section of the Authress Management Portal.

Setup

To enable GitHub OIDC JWTs access to your Authress account, we'll review the steps here.

Add GitHub as a trusted provider

1. Log into your Authress account and navigate Connections
2. Scroll down to OIDC Trusted identities and click Add trusted provider.

3. Click the button for I don't have access to a token. (Normally, you would want to verify your configuration with an actual JWT, however obtaining one from GitHub is a challenge). And then enter the following values:

• Provider's Issuer URL: https://token.actions.githubusercontent.com
• Provider's Audience: https://api.authress.io

4. Click Link provider to complete the setup

Enable permissions for your org

At this point Authress enables verifying tokens from GitHub, but to prevent unauthorized access, these tokens won't have permissions to change any of your Authress resources. In other words, just because we can prove that a user or entity is who they say they are, that doesn't automatically give them access to protected resources.

1. Navigate to Access Records.
2. Click Create access record.
3. Under Users & Groups, enter the following User ID that matches your github organization. We want to give your organization (or specifically a single repo access to your Authress account). This user will match. Authress matches the sub claim of the incoming JWT. Depending on where your job is running will decide what the User ID should be. We'll assume for this example that you want to update Authress from your main branch of your git repository. If your GitHub org is called my-org, and the repo in that org is called authress-configuration, then configuration you want is

• User ID: repo:my-org/authress-configuration:ref:refs/heads/main

If you are calling out to Authress from GitHub from a different branch, a specific tag, a configured environment, then review the GitHub subject claim configuration options.

4. Click on Statements and add the permissions you want to assign to the GitHub Runner. The recommendation here would be to restrict access to only the Authress resources that are necessary. In most cases you'll want to limit the configuration to Authress Roles. For the example here we give it the Authress defined Owner role. This specifically grants the capability to create, edit, update, and delete any of the Resources. And we specify that it will have access to your Authress account Roles as well as all ✶ resources. Normally you would not need this second one, but depending on your use case, you may decide this is necessary.

5. Click Create record.

Your GitHub action now has access to your Authress account. If you have already configured your GitHub Action to generate a token and call Authress, you are done. If this is the first step you have done, see the next section for setting up your GitHub Action.

Log into Authress in a GitHub Action

Now that your GitHub Action has access to your Authress account, we can go and generate the temporary JWT access token your action will use to update your Authress resources.

1. In your GitHub Action workflow.yml, add the following top level permissions. This allows your job to use JWTs

Grant GitHub action permission to generate JWTs

permissions:
  contents: read
  id-token: write

2. Then tell GitHub to actually generate a JWT for your workflow, by adding this step to your job:

jobs:
  job:
    runs-on: ubuntu-latest
    steps:
    - name: Install OIDC Client from Core Package
      run: npm install @actions/core@1.6.0 @actions/http-client
    - name: Get Id Token
      uses: actions/github-script@v6
      id: authress_credentials
      with:
        script: |
          const githubAction = require('@actions/core');
          const token = await githubAction.getIDToken('https://api.authress.io');
          githubAction.setSecret(token);
          githubAction.setOutput('authress-key', token);
          githubAction.exportVariable('AUTHRESS_KEY', token);

And now the AUTHRESS_KEY environment variable is now available for use in other toolkits, such as Terraform or directly in one of the Authress SDKs.