Configure OIDC authentication

Set up OpenID Connect (OIDC) authentication between CloudBees Unify and AWS for secure, credential-free workflow authentication. Before you begin, ensure you have administrative access to your AWS account and your CloudBees Unify organization.

Follow the principle of least privilege when granting AWS permissions. Only assign the minimum permissions necessary for your workflows to function.

Add CloudBees Unify as a trusted identity provider in AWS

In AWS IAM, add CloudBees as an OIDC identity provider:

Navigate to Identity providers > Add provider.
Select OIDC with provider URL https://api.cloudbees.io and audience sts.amazonaws.com.
Select Get thumbprint and Add provider.

Your AWS account now accepts CloudBees Unify as a trusted identity provider.

Create a trust policy

Create a trust policy that defines which CloudBees Unify workflows can assume your AWS role.

AWS uses specific condition keys to check JWT claims:

aud matches the azp claim (set to sts.amazonaws.com)
oaud matches the aud claim (set to your organization ID in format cbp://<org_id>@sts.amazonaws.com)
sub matches the repository and branch information

CloudBees Unify strongly recommends using the oaud key with a StringEquals condition to ensure only tokens from your CloudBees Unify organization are trusted.

Example trust policies

Here are trust policy examples for different access scenarios:

Restrict to specific branches

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::012345678901:oidc-provider/api.cloudbees.io"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "api.cloudbees.io:oaud": "cbp://1234abcd-56ef78gh-90ij-klmn1234opqr@sts.amazonaws.com",
          "api.cloudbees.io:sub": [
            "provider:github:repo:my-org/my-repo:ref:/refs/head/main",
            "provider:github:repo:my-org/my-repo:ref:/refs/head/qc"
          ]
        }
      }
    }
  ]
}▼

Allow any branch in specific repository

"Condition": {
  "StringEquals": {
    "api.cloudbees.io:oaud": "cbp://1234abcd-56ef78gh-90ij-klmn1234opqr@sts.amazonaws.com"
  },
  "StringLike": {
    "api.cloudbees.io:sub": "provider:github:repo:my-org/my-repo:ref:*"
  }
}▼

Allow branches with specific tag pattern

"Condition": {
  "StringEquals": {
    "api.cloudbees.io:oaud": "cbp://1234abcd-56ef78gh-90ij-klmn1234opqr@sts.amazonaws.com"
  },
  "StringLike": {
    "api.cloudbees.io:sub": "provider:github:repo:my-org/*:ref:/refs/tag/v1.*"
  }
}▼

Replace 012345678901 with your AWS account ID and 1234abcd-56ef78gh-90ij-klmn1234opqr with your CloudBees Unify organization ID.

Create an AWS IAM role

Create an IAM role that CloudBees Unify workflows can assume:

Navigate to Roles > Create role.
Select Custom trust policy, enter your trust policy, and assign necessary permissions.

Assign role permissions

Add permissions based on your workflow requirements:

For Amazon ECR access: AmazonEC2ContainerRegistryReadOnly or custom ECR permissions
For S3 access: AmazonS3ReadOnlyAccess or custom S3 permissions
For EC2 deployment: Custom permissions for EC2 instance management

Avoid granting broad or administrative permissions. Use the minimum permissions required for your specific use case.

Configure CloudBees Unify workflows

Configure your workflows to use OIDC tokens for AWS authentication:

apiVersion: automation.cloudbees.io/v1alpha1
kind: workflow
name: aws-deployment
on:
  push:
    branches:
      - "main"

permissions:
  scm-token-own: read
  scm-token-org: read
  id-token: read

jobs:
  deploy:
    permissions:
      scm-token-own: read
      scm-token-org: read
      id-token: write
    steps:
      - name: Check out
        uses: https://github.com/cloudbees-io/checkout@v1
        with:
          repository: my-org/my-repo
      - name: Deploy to AWS
        uses: https://github.com/cloudbees-io/ec2-deploy-binary@v1
        with:
          source-location: workspace/build/*
          destination-ec2-location: /home/ubuntu/deployments/
          aws-ssh-key-data: ${{ secrets.AWS_DEPLOY_KEY }}
          aws-user: ubuntu
          aws-host: ${{ secrets.AWS_HOST }}
          deploy-script: deploy.sh▼

Important workflow considerations

Job-level permissions: When using id-token: write at the job level, you must also specify any other required permissions even if they’re set at the workflow level.
Required permissions: Include scm-token-own: read if your job checks out code.
Scope principle: Grant the narrowest permissions necessary for each job.

JWT claims reference

CloudBees Unify OIDC tokens include JWT claims that provide context about the workflow execution:

sub: Repository and branch/environment information
aud: Organization ID and audience
repository: Repository name
ref: Branch or tag reference
environment: Deployment environment name
workflow: Workflow name

Use these claims in your trust policies for fine-grained access control.