Access Authress through GitHub Actions
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 JWT tokens. 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.
To enable GitHub OIDC JWT tokens access to your Authress account, we'll review the steps here.
Add GitHub as a trusted provider
- Log into your Authress account and navigate Connections
- Scroll down to
OIDC Trusted identitiesand click Add trusted provider.
- 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:
- Provider's Audience:
- 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.
- Navigate to Access Records.
- Click Create access record.
- 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
subclaim of the incoming JWT. Depending on where your job is running will decide what the
User IDshould be. We'll assume for this example that you want to update Authress from your
mainbranch 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:
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.
- 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
Ownerrole. 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
Rolesas well as all
✶resources. Normally you would not need this second one, but depending on your use case, you may decide this is necessary.
- 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.
- In your GitHub Action workflow.yml, add the following top level permissions. This allows your job to use JWTs
- Then tell GitHub to actually generate a JWT for your workflow, by adding this step to your job:
- name: Install OIDC Client from Core Package
run: npm install @firstname.lastname@example.org @actions/http-client
- name: Get Id Token
const githubAction = require('@actions/core');
const token = await githubAction.getIDToken('https://api.authress.io');
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.