OIDC setup and examples

OpenID Connect (OIDC) offers a secure and standardized way to authenticate users across platforms. To enable CloudBees platform workflows to assume roles in AWS, you need to establish an Identity Trust Relationship (IdP) between AWS and CloudBees platform using OIDC. This setup ensures secure and seamless authentication, allowing your CloudBees pipelines to interact with AWS resources efficiently and securely.

Establish an IdP between AWS and CloudBees

To add CloudBees platform as a Trusted Identity Provider in AWS:

Sign in to your AWS account and go to Identity and Access Management (IAM) Identity providers Add provider.
Select the OpenID Connect option.
Set the Provider URL to api.cloudbees.io.
Set Audience to sts.amazonaws.com.
Select [Get Thumbprint] to validate the provider URL and certificate.
Select [Add provider] to complete the setup.

Create an AWS IAM role for CloudBees platform workflows

To create AWS roles that can be assumed by CloudBees platform workflows using trusted CloudBees platform identity tokens:

Sign in to your AWS account and go to Identity and Access Management (IAM) Roles Create role.
Select Custom trust policy as the trusted entity type.

Enter the following trust policy, replacing the placeholders, "YOUR_AWS_ACCOUNT_ID" and "YOUR_GITHUB_ORG_ID/YOUR_GITHUB_REPO" in the code below with your actual AWS account ID and GitHub organization/repository details.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::YOUR_AWS_ACCOUNT_ID:oidc-provider/api.cloudbees.io"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "api.cloudbees.io:aud": "sts.amazonaws.com" (1)
        },
        "StringEquals": {
          "api.cloudbees.io:event_name":"PUSH" (2)
        },
        "StringEquals": {
          "api.cloudbees.io:sub": "provider:github:repo:YOUR_GITHUB_ORG_ID/YOUR_GITHUB_REPO" (3)
        },
        "StringLike": {
          "api.cloudbees.io:ref":"refs/heads/example-*" (4)
        }
      }
    }
  ]
}▼

"api.cloudbees.io:aud": "sts.amazonaws.com"

Explanation: This ensures that only tokens issued by CloudBees platform and specifically intended for AWS are accepted when attempting to assume the role. This requirement is always necessary for security.
Alternative configuration: Not applicable; this is always required when issuing an OIDC token for AWS.

"api.cloudbees.io:event_name":"PUSH"

Explanation: This condition restricts the role assumption to workflows triggered by a PUSH event in the repository. It ensures that only users with push permissions can create workflows that generate tokens capable of assuming roles in AWS.
Alternative configuration: You could modify this to another event type, such as "WORKFLOW_DISPATCH" for manually triggered workflows, or remove the condition if you want to allow multiple event types.

To prevent accidentally enabling a drive-by pull-request attack target on any of your public repos, "PULL_REQUEST" cannot use OIDC tokens and does not support the id-token:write permission.

"api.cloudbees.io:sub"
"provider:github:repo:YOUR_GITHUB_ORG_ID/YOUR_GITHUB_REPO"

Explanation: This condition restricts role assumption to workflows from a specific GitHub repository by matching the token subject (sub) to the repository and organization. While you can limit access to the organization, CloudBees recommends creating a unique role for each repository as a more secure approach.

Alternative configuration: To broaden the scope, you can include multiple repositories or organizations by following AWS guidelines on multivalued context keys.

When using StringEquals conditions, you can either include multiple key-value pairs within a single StringEquals block or use separate StringEquals blocks for each key. While both approaches are functionally the same, using multiple keys in a single StringEquals block is more concise and efficient, improving readability and performance.

"api.cloudbees.io:ref":"refs/heads/example-*"

Explanation: This condition limits role assumption to branches matching a specific pattern, such as those starting with example-. By using StringLike, you create a wildcard matching rule. For tighter security, CloudBees recommends using StringEquals to restrict access to the default branch (for example, main), ensuring that branch protections in the repository also safeguard AWS interactions.
Alternative configuration: Adjust the pattern to match different branch naming conventions, such as release- for release branches or simply use "refs/heads/" to match all branches.

Select Next and assign the necessary permissions to the role. The permissions can vary depending on the required AWS operations.

Assign permissions to the role

Add additional permissions to the role to allow specific AWS operations. These permissions should be based on your workflow requirements. For example, accessing ECR, and S3.

CloudBees strongly recommends that you avoid granting broad or unnecessary permissions, particularly administrative access, to your environments. In the event of a security breach, having limited permissions can help mitigate potential damage and demonstrate that appropriate security measures were advised.

Configure workflows to use OIDC tokens

To set up platform workflows to use OIDC tokens:

Use the cloudbees-io/configure-aws-credentials action to configure the workflow to use OIDC tokens for AWS operations.

apiVersion: automation.cloudbees.io/v1alpha1
kind: workflow
name: workflow
on:
  push:
    branches:
      - "example-*"

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

jobs:
  build:
    steps:
      - name: Log in to AWS
        uses: cloudbees-io/configure-aws-credentials@v1
        id: aws-login
        with:
          aws-region: us-east-1
          # Replace YOUR_AWS_ACCOUNT_ID with your AWS account ID
          role-to-assume: arn:aws:iam::YOUR_AWS_ACCOUNT_ID:role/cloudbees-infra-mgmt
          role-duration-seconds: "3600"

      - name: Run AWS CLI commands
        uses: docker://public.ecr.aws/aws-cli/aws-cli
        run: |
          aws sts get-caller-identity▼

Use JWT Claims for fine-grained access control.

CloudBees OIDC tokens include JSON Web Token (JWT) claims that can be used to filter trust policies. Example token claims include repository, branch, and workflow context information.

An Example of OIDC JWT token claims is below:

{
  "iss": "https://api.cloudbees.io",
  "sub": "provider:github:repo:acme/quickstart-app-deploy",
  "aud": ["sts.amazonaws.com"],
  "exp": 1708033784,
  "iat": 1708004989,
  "environment": "",
  "event_name": "PUSH",
  "event_source": "github",
  "ref": "refs/heads/main",
  "ref_type": "branch",
  "repository": "quickstart-app-deploy",
  "repository_owner": "acme",
  "repository_provider": "github",
  "run_attempt": "1",
  "run_id": "d29cc443-593d-4dd3-84e7-49c60234563d6",
  "run_number": "10",
  "workflow": "Workflow",
  "workflow_ref": "acme/quickstart-app-deploy/.cloudbees/workflows/Workflow@refs/heads/main",
  "workflow_sha": "aa0cbc4a9fdb2c3cf7d4cc6d0ad63f27272727757"
}▼

AWS references

The following AWS documentation links provide guidance for setting up and managing OIDC identity providers and IAM roles in AWS.