Access Authress through GitLab

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 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, GitHub, etc...

Because GitLab 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 GitLab OIDC JWT tokens access to your Authress account, we'll review the steps here.

Add GitLab 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 GitLab is a challenge). And then enter the following values:

• Provider's Issuer URL: https://gitlab.com
• Provider's Audience: https://api.authress.io

4. Click Link provider to complete the setup

Enable permissions for your org group

At this point Authress enables verifying tokens from GitLab, 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 GitLab group. We want to give your group (or specifically a single repo in GitLab) 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 GitLab group is called my-org, and the repo in that org is called authress-configuration, then configuration you want is

• User ID: project_path:my-org/authress-configuration:ref_type:branch:ref:main

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

4. Click on Statements and add the permissions you want to assign to the GitLab 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 GitLab pipeline now has access to your Authress account. If you have already configured your GitLab 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 GitLab Pipeline.

Log into Authress in a GitLab Pipeline

Now that your GitLab Pipeline 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. Then tell GitLab to actually generate a JWT for your workflow, by adding this step to your job:

Dynamically generate the Authress access token

job_to_configure_authress:
  id_tokens:
    AUTHRESS_KEY:
      aud: https://api.authress.io
  script:
    - terraform apply

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.

Additional GitLab documentation:

• GitLab id_token workflow parameter
• GitLab OIDC authentication