OpenID Connect

Setup GitHub Actions to authenticate to Cloudsmith using OIDC

Our workflow using GitHub Actions and Cloudsmith with OIDC will push a package to Cloudsmith from GitHub Actions using OIDC to authenticate.

How does OIDC work with GitHub Actions and Cloudsmith?

The following diagram gives an overview of how GitHub's OIDC provider integrates with your workflows and Cloudsmith:

OIDC flow overview

1. Request token: GitHub Actions Worker initiates the workflow by requesting a token from the GitHub OIDC service to authenticate with Cloudsmith.
2. Return token: GitHub OIDC service receives the token request. After verification and validation, it generates a JWT token. The GitHub OIDC service and the GitHub Actions Worker have implicit trust, allowing for this token exchange.
3. Present token: GitHub Actions Worker presents a JWT token to Cloudsmith for access to resources.
4. Verify token: Cloudsmith verifies the JWT token with the GitHub OIDC service to ensure its authenticity and validity. This step includes verifying claims.
5. Return new token: Upon successful validation, Cloudsmith issues a short-lived access token to the GitHub Actions Worker, granting access to Cloudsmith's resources for around 90 minutes to cover the duration of the job.

Step-by-step guide

Follow the steps below for the Cloudsmith and GitHub Actions OIDC Setup:

1. Create a service account in Cloudsmith and set access controls

1. Service accounts are a specific type of account that allows you to create a Cloudsmith API Key not tied to a specific user.
2. Navigate to the Services section on your Cloudsmith workspace's accounts page and click "Create Service".
3. In the form, give your Service a name and optionally add a description and choose any teams in your workspace that you wish to add the service to.
4. Configure the repository access controls to allow the Service Account to push packages to Cloudsmith.

2. Configure GitHub OIDC in Cloudsmith

Requirements

NOTE: Manager or Owner role required in your Cloudsmith workspace to configure OIDC Provider Settings.

1. Navigate to the OIDC Provider Settings at: https://app.cloudsmith.com/{WORKSPACE}/settings/authentication/openid

2. Click "Create" to open the Edit Provider Settings form.

3. Fill in the OIDC form:

   • Provider Name: Set a unique name for the provider.
   • Provider URL: This URL must precisely match the iss (issuer) claim from the OIDC token generated by your GitHub environment:
     • Standard GitHub.com: The URL is typically https://token.actions.githubusercontent.com.
     • GitHub Enterprise Cloud: The URL will include your enterprise name, like https://token.actions.githubusercontent.com/YOUR_ENTERPRISE_NAME.
   • Required OpenID Token Claims: To validate the token, the cloud provider checks if the OIDC token's subject and other claims are a match for the conditions that were preconfigured on the cloud role's OIDC trust definition.
   • Service Accounts: Select the service accounts that can be authenticated with this provider and claim combination.

   Claims

   We strongly encourage you to set at least one claim. Without claims, any GitHub Action that knows the service account slug could gain access. In the example, we use repository_owner.

   

3. Update your GitHub Actions for OIDC

Cloudsmith provides a native GitHub action integration, that avoids a manual exchange of tokens.

1. Add permissions: In your GitHub Actions YAML file, add the permissions block to allow the workflow to request an OIDC token.

permissions:
  id-token: write # Required for requesting the JWT
  contents: read  # Required for actions/checkout

2. Authenticate using the Cloudsmith Action: Add the following step to your job. It installs the standalone Cloudsmith CLI, adds it to PATH, and configures OIDC authentication for any subsequent steps.

- name: Set up Cloudsmith CLI with OIDC
  uses: cloudsmith-io/cloudsmith-cli-action@v3
  with:
    oidc-namespace: 'your-workspace' # Your Cloudsmith Workspace
    oidc-service-slug: 'your-service-account-slug' # Your Cloudsmith service account slug

The action exports the service account context (CLOUDSMITH_ORG and CLOUDSMITH_SERVICE_SLUG) for the rest of the job, and the CLI exchanges the GitHub OIDC token on its first authenticated command. Set verify-auth: 'true' on the action to run cloudsmith whoami during setup and fail early if authentication is not configured correctly. Finally, add any extra step for your workflow and trigger a build in GitHub Actions.

3. (Optional) Export the authentication token for other tools: Set export-auth-token: 'true' to export the authentication token for later workflow steps. When enabled, the action sets the CLOUDSMITH_API_KEY and CLOUDSMITH_USERNAME environment variables. The oidc-auth-only input is a deprecated alias for export-auth-token and sets the same environment variables.

Example GitHub Actions workflow

Below is a full example of pushing a package to Cloudsmith in GitHub Actions using the modern OIDC authentication method.

name: Push a Debian package to Cloudsmith with OIDC
on:
  push:
    branches: [ main ]

permissions:
  id-token: write # Required to request the OIDC token from GitHub
  contents: read  # Required for actions/checkout to read the repository

jobs:
  push:
    runs-on: ubuntu-latest
    name: Push a Debian package to Cloudsmith using OIDC
    steps:
      - name: Check out code
        uses: actions/checkout@v4

      # This step installs the standalone Cloudsmith CLI and configures OIDC.
      # The CLI exchanges the GitHub OIDC token on its first authenticated command.
      - name: Set up Cloudsmith CLI with OIDC
        uses: cloudsmith-io/cloudsmith-cli-action@v3
        with:
          oidc-namespace: 'WORKSPACE'             # Replace with your Cloudsmith workspace
          oidc-service-slug: 'SERVICE_ACCOUNT_SLUG' # Replace with your service account slug
      - name: Push package to Cloudsmith
        run: |
          cloudsmith push deb WORKSPACE/REPOSITORY/DISTRO/VERSION PACKAGE_NAME-PACKAGE_VERSION.PACKAGE_ARCH.deb

Updated 3 days ago