Update tokenless authentication to use GitHub OIDC

Tokenless authentication is CloudBees Smart Tests’s specialized authentication method for public repositories that use GitHub Actions for CI.

We are updating this method to use OpenID Connect (OIDC) to make it more scalable and secure.

This change requires action on your part.

OIDC implementation overview

GitHub now provides a short-lived signed token for each GitHub Actions run (About security hardening with OpenID Connect). This token is signed by GitHub’s private key, and we can verify its validity via its public key. This makes the token a security credential that major Cloud providers such as AWS, Azure, and Google Cloud can use as an authentication token. CloudBees Smart Tests implemented the same mechanism as these Cloud providers, allowing it to be accepted as a credential.

The new implementation of tokenless authentication provides the same benefit as the previous one: no API key is needed.

However, on top of that, the new implementation provides more security as it uses a verifiable short-lived token. Because the previous implementation involved calling GitHub APIs, the authentication process occasionally hit its API limit, resulting in request failures. With the new implementation, we no longer need to hit the GitHub API, which makes the service more stable.

Migration process

The new OIDC-based authentication is supported by CLI v1.52.0. If the latest CLI using pip3 install --upgrade has been installed, you will get the necessary version automatically. Otherwise, upgrade to the latest version.

Steps

To migrate to the new implementation, do the following:

Add/update the permissions section of your GitHub Actions YAML file. (Refer to GitHub actions permissions).
Add a new EXPERIMENTAL_GITHUB_OIDC_TOKEN_AUTH environment variable.
1. Set this to 1 to enable the new auth implementation.
Remove the GITHUB_PR_HEAD_SHA environment variable. It is no longer needed.
Keep the LAUNCHABLE_ORGANIZATION and LAUNCHABLE_WORKSPACE environment variables that were already set.

Environment variables summary

API implementation (original) OIDC implementation (new)

API implementation (original)	OIDC implementation (new)
`LAUNCHABLE_ORGANIZATION`: CloudBees Smart Tests organization name	`LAUNCHABLE_ORGANIZATION`: CloudBees Smart Tests organization name
`LAUNCHABLE_WORKSPACE`: CloudBees Smart Tests workspace name	`LAUNCHABLE_WORKSPACE`: CloudBees Smart Tests workspace name
`GITHUB_PR_HEAD_SHA`	`EXPERIMENTAL_GITHUB_OIDC_TOKEN_AUTH`: Set this to `1` to enable the new auth.

LAUNCHABLE_ORGANIZATION: CloudBees Smart Tests organization name

LAUNCHABLE_WORKSPACE: CloudBees Smart Tests workspace name

GITHUB_PR_HEAD_SHA

EXPERIMENTAL_GITHUB_OIDC_TOKEN_AUTH: Set this to 1 to enable the new auth.

GitHub Actions Permissions

To use the OIDC token in GitHub Actions, configure permissions to retrieve it. As described in the GitHub Help Article , id-token: write permission needs to be added.

This permission can be added per job or to the entire workflow.

Examples

name: Verify {PRODUCT} tokenless authentication

on:
  pull_request:
    paths:
      - gradle/**

env:
  LAUNCHABLE_ORGANIZATION: "examples"
  LAUNCHABLE_WORKSPACE: "gradle"
  EXPERIMENTAL_GITHUB_OIDC_TOKEN_AUTH: 1

permissions:
  id-token: write
  contents: read

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v2
        with:
          fetch-depth: 0
      - uses: actions/setup-python@v2
      - name: Set up JDK 1.8
        uses: actions/setup-java@v1
        with:
          java-version: 1.8

      - name: {PRODUCT}
        run: |
          pip3 install --user smart-tests~=1.0
          export PATH=~/.local/bin:$PATH
          smart-tests verify
        working-directory: ./gradle▼

Frequently Asked Questions

What is included in the OIDC token?

GitHub provides a detailed explanation and example of the OIDC token. For more information, refer to Understanding the OIDC token.

How does CloudBees Smart Tests verify the OIDC token?

When you apply for tokenless authentication, we associate your GitHub repository with your CloudBees Smart Tests workspace in our internal database.

When you run the CLI, the CloudBees Smart Tests API server verifies the OIDC token and checks that the repository claim in it matches the stored association.

Can I see how the CLI handles the OIDC token?

Yes. Review these commits in the public CLI repository: