OpenID Connect

OpenID Connect (OIDC) overview

You can use Cloudsmith's support for OpenID Connect to enable short-lived authentication tokens, helping to secure your pipelines against the exposure of credentials.

πŸ“˜

OpenID Connect support is currently an Early Access feature, please Contact Us if you would like this feature enabled on your Cloudsmith account.

Glossary

TermDescription
OpenID TokenA JWT token with a specified format that Cloudsmith receives from an OIDC provider which we use to enable users to authenticate as a service account
OpenID Connect (OIDC) ProviderThe OIDC Token provider (GitHub Actions, CircleCI, etc)
ClaimsContained within the payload of the OpenID Token, used to verify the authenticity and restrict access of specific Provider requests to specific service accounts
ACCOUNTYour Cloudsmith Organization slug/identifier.

​

OIDC Settings

​

OIDC Provider Settings for your organization are configured at:

https://cloudsmith.io/orgs/{ACCOUNT}/settings/openid-connect/

You must have the Manager or Owner role in your Cloudsmith Organization to configure OIDC Provider Settings.

πŸ“˜

OIDC Provider Settings can only be configured if there's at least one Service Account in your organization

Click "Create" to open the Create Provider Settings form:

To configure a provider, you must provide:

FieldDescription
Provider NameA Unique name for the provider
Provider URLA Provider URL. This is unique to each provider, for example for Github Actions it is: https://token.actions.githubusercontent.com
Note: this needs to be the root URL
i.e. it has the .well-known/openid-configuration portion of the URL removed


This provides the configuration for the chosen provider, we use this to verify the OpenID Token we received was signed by the provider
Required OpenID Token ClaimsThe required claims that must be present in the received OpenID Token's payload to successfully authenticate.

For example, tokens from CircleCI could specify the oidc.circleci.com/vcs-origin value which would allow users to limit requests from a specific version control source repository to allow access to specified Cloudsmith Service Account(s)

We strongly encourage people to set at least one claim, as some providers share signing keys across all orgs, meaning that without any configured claims any OIDC request from that provider could authenticate if they knew the service account(s) to target.
Service AccountsThe service accounts that the user wants to be able to authenticate as with the configured provider & claims combination

Changes will be applied immediately.
​

Provider Documentation

CircleCI

  • Provider URLs are unique per organization, the format is:
    https://oidc.circleci.com/org/<organization_id>

GitHub Actions

  • There is an extra step to generate an OpenID Token compared to CircleCI - this needs to be done before sending the token to us.
  • Because the keys used to verify the token are shared across all GitHub Actions for all organizations, at least one claim verification is strongly encouraged so that only jobs from your GitHub organization can authenticate. If only one claim is being configure then the audience claim (aud) is probably best for this as that scopes it to requests from the your GitHub organization.
    ​

OIDC requests

With the settings configured, you can now have requests from your provider use your Cloudsmith organization's OIDC endpoint to exchange the OpenID Token for a JWT token to authenticate with all Cloudsmith API endpoints.
​

Token exchange

To receive the Cloudsmith JWT token, you need to make a POST request to our OpenID endpoint. This POST request must have a body of oidc_token, with the OpenID Token as it's value and service_slug as the slug of the service account the request wants to attempt to authenticate as.

The OIDC Endpoint for your Cloudsmith organization will be:
https://api.cloudsmith.io/openid/{ACCOUNT}/

Examples:

GitHub Actions

name: OpenID Connect Demo
run-name: ${{ github.actor }} is testing out GitHub Actions with OpenID Connect πŸš€
on: [push]

permissions:
  id-token: write

jobs:
  test-openid-connect:
    runs-on: ubuntu-latest
    steps:
      - run: echo "Testing out OpenID Connect in GitHub Actions."
      - run: |
          value=$(curl -H "Authorization: bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" "$ACTIONS_ID_TOKEN_REQUEST_URL&audience=api://AzureADTokenExchange" | jq '.value')
          echo "$value"
          curl -X POST -H "Content-Type: application/json" -d "{\"oidc_token\":$value, \"service_slug\":\"github-service\"}" https://api.cloudsmith.io/openid/{ACCOUNT}/

CircleCI

version: 2.1


commands:
  make_oidc_request:
    steps:
      - run: |
          echo "Testing CircleCI OIDC!"
          curl -X POST -H "Content-Type: application/json" -d "{\"oidc_token\":\"$CIRCLE_OIDC_TOKEN_V2\", \"service_slug\":\"{SERVICE_SLUG}"}" https://api.cloudsmith.io/openid/{ACCOUNT}/

jobs:
  build:
    docker:
      - image: cimg/base:current
    steps:
      - make_oidc_request
         
workflows:
  test-workflow:
    jobs:
      - build:
          context:
            - circle-oidc-test

If successful, this will give a JWT token that can be used as an API key

If unsuccessful, you will receive an error message that is intentionally quite generic - This is by design, so that we do not leak any information (such as if OIDC is configured, which claim failed, whether a service account is associated with the provider, etc).
​

Using the JWT

The JWT token generated by the OIDC endpoint can be used like an API key:
X-Api-Key header: "X-Api-Key:Bearer OIDC_TOKEN"

This token is active for 2 hours from the time of creation.

This token works with all Cloudsmith API endpoints to manage resources, as well as format-specific endpoints, e.g. The Ruby endpoint to get all available packages
​
This token will also, work with the Command-Line Interface when specified as CLOUDSMITH_API_KEY


Cloudsmith is the new standard in Package / Artifact Management and Software Distribution

With support for all major package formats, you can trust us to manage your software supply chain.


Start My Free Trial Now
Cookie Declaration (Manage Cookies)