Introducing the StackRox “central-login” GitHub Action

With the recent packed release of StackRox 4.3, the StackRox team wanted to highlight the a major improvement to your CI/CD pipelines with the release of a new GitHub Action called “central-login”.

Setting up credentials in a CI/CD pipeline can be annoying, time-consuming, and insecure if improperly configured. To fix this issue, the “central-login” GitHub action will configure access to your StackRox Central instance by leveraging GitHub’s OIDC provider and enabling short-lived credentials to your Central instance.

Before you set up the new “central-login” action, let’s review the basics of GitHub Actions.

GitHub Actions

When setting up StackRox CLI or ‘roxctl’ in GitHub Actions, you will typically need to reach out to a third-party service. These other resources could be a cloud provider, secrets management application or StackRox to scan your images and configuration.

To access those services, you need to supply your workflow with credentials, such as a password or token. However, using those long-living credentials requires you first to create the credentials within StackRox Central (i.e. an API token) and duplicate them in GitHub as a secret. This creates an additional overhead of maintenance. Additionally, long-lived secrets provide a higher risk during exposure. At the current time, the default lifetime of a Central API token is a year.

Thanks to GitHub, we have an easier solution: GitHub’s built-in OIDC provider.

Each action, or workflow run, can obtain an ID token from the OIDC provider, which contains multiple claims, creating a verifiable identity for each workflow. The ID token and the underlying identity will then be presented to the third-party service, which will validate the token provided claims, and provide a short-lived access token in return. (for more information on the OIDC token’s claims, see this documentation).

Now it’s time for the fun part. Let’s look at an example of leveraging this with StackRox Central Service and the new “central-login” action!

How to use the action

Step 1: Enable the Feature Flag

At the time of writing this blog, this functionality is guarded behind a feature flag within StackRox. You must set the environment variable ROX_AUTH_MACHINE_TO_MACHINE=true for your Central instance. For example, run the following on the command line

export ROX_AUTH_MACHINE_TO_MACHINE=true

This will allow you to configure the StackRox central in the next step.

Step 2: Configure StackRox Central to trust the GitHub OIDC ID tokens

The first step is configuring StackRox to trust tokens issued by the GitHub OIDC provider and mapping claims to specific roles within Central.

This is as easy as executing the below API call:

curl -u “admin:<password>” https://<CENTRAL-ENDPOINT>/v1/auth/m2m -d  @- << EOF
{
 "config": {
   "type": "GITHUB_ACTIONS",
   "tokenExpirationDuration": "5m",
   "mappings": [
     {
       "key": "sub",
       "valueExpression": "repo:octo-org/octo-repo.*", // This supports https://github.com/google/re2/wiki/Syntax expressions.
       "role": "Continuous Integration"
     }
   ],
 }
}
EOF

Let’s walk through the different parts within the request:

"type": "GITHUB_ACTIONS":

The type of the configuration, i.e. which OIDC provider we want to establish trust with. This will be “GITHUB_ACTIONS” for our example.

"tokenExpirationDuration": "5m":

The expiration duration for the short-lived access token. The duration must be less than 24 hours but can be adjusted. We recommend the lifespan to be tailored to your pipelines needs and no more.

"Mappings":

Each mapping looks at the presented OIDC token’s claims and maps a claim key-value pair to a StackRox role. The claim value can be a RE2 regular expression. Please read the documentation for more information on the GitHub OIDC claims and their structure.

NOTE: we recommend using the “sub” claim as a mapping as it is immutable. Using claims such as the “aud” claim can have unwanted consequences since it can be customized.

After creating the configuration above, we have established the following: Central will now trust tokens issued by GitHub’s OIDC provider. If a mapping matches a specific claim key-value pair, a specific role will be assigned to the access token.

Step 3: Use the central-login action within your workflow

Now that we’ve configured Central to trust the identities from GitHub’s OIDC provider, we can start using the central-login GitHub action.

This is as simple as adding the following to your workflow:

   - name: Retrieve Central credentials
      uses: stackrox/central-login@v1
      with:
        endpoint: https://sample.endpoint.com:443

    - name: roxctl central whoami
      image: quay.io/stackrox-io/roxctl:4.3.0
      script: central whoami

And that’s it! No additional configuration is required in the form of credentials or any other secrets!

Let’s look at the output for the central-login step:

Attempting to obtain an access token for Central https://<endpoint>...
Received status 200 from endpoint 

https://<endpoint>/v1/auth/m2m/exchange: {"accessToken":"***"}
Successfully obtained an access token for central https://localhost:8000!

Successfully set the variable *** and ROX_ENDPOINT to the access token and Central API endpoint!

We see the outgoing API call to the v1/auth/m2m/exchange API, exchanging the GitHub OIDC ID token for a Central access token.

Also, the environment variables ROX_API_TOKEN and ROX_ENDPOINT will be set for the following jobs.

This way, no additional configuration is required for the “roxctl central whoami” job, which will use the API token as well as the endpoint configured via environment variables.

Step 4: Enjoy the central-login GitHub Action and use it in your other workflows!

That’s all there is to the new central-login GitHub Action!

If you have any questions, run into issues, or would like to contribute, reach out in the CNCF StackRox Slack Channel or create an issue within directly within the StackRox GitHub repository!