Using OIDC with Jenkins and Cloudsmith

This guide provides a setup process for configuring Jenkins to authenticate with Cloudsmith using OpenID Connect (OIDC). By using OIDC, Jenkins can issue short-lived tokens for secure access to Cloudsmith resources.

Prerequisites

1. Jenkins OIDC Plugins
   Install the following plugins in Jenkins:

   • OpenID Connect Provider Plugin - The OIDC Provider plugin allows Jenkins to act as an OpenID Connect Provider, issuing tokens that can be consumed by Cloudsmith for authentication.
   • Credentials Binding Plugin - Allows secure injection of credentials (e.g., OIDC tokens) into Jenkins jobs.

2. Service Account in Cloudsmith
   Create a Service Account in Cloudsmith for OIDC access. This will act as a proxy identity for Jenkins jobs.

Step-by-Step Setup

1. Install Required Plugins

1. Go to Manage Jenkins → Manage Plugins.
2. Under the Available tab, search for:
   • OIDC Connect Provider https://plugins.jenkins.io/oidc-provider/
   • Credentials Binding https://plugins.jenkins.io/credentials-binding/
3. Install both plugins and restart Jenkins if prompted.

2. Create OIDC Credential in Jenkins

1. Go to "Manage Jenkins" → "Credentials" → "System" → "Global credentials"
2. Click "Add Credentials"
3. Select "Kind" → "OpenID Connect ID Token"
4. Fill in:
   1. Scope: "Global"
   2. ID: "oidc-token-cred"
   3. Audience: jenkins
   4. Description: "OIDC Token for Jenkins"
   5. Issuer URL: Your publically assessible URL
5. Click "OK"

3. Host OIDC Configuration Files

After creating the credential, Jenkins will show you two URLs where you can get the configuration files:

1. OpenID Configuration URL:

   http://your-jenkins-instance/manage/descriptorByName/io.jenkins.plugins.oidc_provider.IdTokenStringCredentials/wellKnownOpenidConfiguration?issuer=your-public-url
   

2. JWKS URL:

http://your-jenkins-instance/manage/descriptorByName/io.jenkins.plugins.oidc_provider.IdTokenStringCredentials/jwks?id=oidc-token-cred&issuer=your-public-url

Requirements for hosting these files:

• Put the OpenID configuration at /.well-known/openid-configuration
• Put the JWKS at /jwks
• Host domain must match the issuer URL in Jenkins

4. Create a Service Account in Cloudsmith

1. Navigate to your Cloudsmith Organization.
2. Go to Services under Account Settings and click Create Service.
3. Provide:
   • A name and optional description.
   • Select any teams for access control if needed.
4. Save your service account.
5. Assign the service account appropriate permissions for your repository..

5. Configure OIDC Provider in Cloudsmith

1. Go to OIDC Provider Settings at:
   https://cloudsmith.io/orgs/{ACCOUNT}/settings/openid-connect/
2. Click Create to open the provider form and configure:
   • Provider Name: Enter a unique name for Jenkins.
   • Provider URL: Enter the Jenkins OIDC endpoint- this should match the URL in Step 2, Issuer.
   • Required OpenID Token Claims:Configure at least one claim, such as aud: jenkins.
   • Service Accounts: Select the Cloudsmith service accounts to authenticate with the provider.
3. Save the configuration.

6. Configure a Jenkins Job

1. Create a new Freestyle Project in Jenkins.

2. In the project configuration::

   1. Under "Build Environment" → "Use secret text(s) or file(s)"
   2. Add → "Secret text"
   3. Variable: "OIDC_TOKEN"
   4. Credentials: Select your OIDC token

3. Add build step "Shell":

   # Get Cloudsmith token
   response=$(curl -X POST -H "Content-Type: application/json" \
       -d "{\"oidc_token\":$OIDC_TOKEN, \"service_slug\": $CLOUDSMITH_SERVICE_ACCOUNT_SLUG}" \
       https://api.cloudsmith.io/openid/${CLOUDSMITH_ORG}/)
   
   # Get token from response
   token=$(echo "$response" | jq -r ".token")
   
   # Install packages using token
   python -m venv jenkins
   source ./jenkins/bin/activate
   PIP_INDEX_URL="https://token:[email protected]/basic/${CLOUDSMITH_ORG}/${CLOUDSMITH_REPO}/python/simple/"
   pip install package-name --index-url $PIP_INDEX_URL
   

7. Test the Setup

1. Trigger the Jenkins job.
2. Monitor the console output:
   1. Ensure the OIDC token is successfully retrieved.
   2. Verify the Cloudsmith token is exchanged and used for authentication.
3. Confirm packages are pushed/pulled to/from the specified Cloudsmith repository.

Example Jenkins Pipeline

You can find an example Jenkins Pipeline that integrates with Cloudsmith via OIDC here: https://github.com/cloudsmith-iduffy/jenkins-oidc-poc

Troubleshooting

• Make sure the Cloudsmith service account has permissions to access the Cloudsmith repository.
• Invalid Claims or Tokens: Ensure the claims in Jenkins and Cloudsmith match.
• Plugin or Credential Issues: Verify plugin installations and credential configurations.
• Network Errors: Confirm Jenkins can reach Cloudsmith APIs and vice versa.

4. Handle Errors

If the job fails, common errors might include:

• Invalid Claims or OIDC Token: Ensure your Jenkins OIDC provider claims match Cloudsmith’s settings.
• Missing Plugins or Credentials: Double-check plugin installation and credential configuration.
• Network Issues: Verify connectivity between Jenkins and Cloudsmith.