app

Introduction to `octo-sts`: A Security Token Service for GitHub

The octo-sts project introduces a GitHub App designed to operate as a Security Token Service (STS) for the GitHub API. This innovative app allows various workloads, which can generate OpenID Connect (OIDC) tokens, to connect with its STS API. The key feature of octo-sts is its ability to generate short-lived tokens specifically for GitHub interactions. The ultimate aim of this application is to completely eliminate the reliance on GitHub Personal Access Tokens (PATs).

For more insights on the project's vision, you can explore the original blog post.

Setting Up Workload Trust

To generate operational credentials within an organization, the octo-sts app must first be installed there. It should have access to any repositories that the workload might need to engage with. Due to inherent GitHub App restrictions, octo-sts must request a broad range of permissions for this integration, although it primarily generates tokens with permissions defined by "trust policies."

Understanding the Trust Policy

Trust policies are stored in a file named .github/chainguard/{name}.sts.yaml and contain three main components:

Claim Matching Criteria for Federation: Specifications for associating tokens from different workloads.
Identity Permissions: Determines what actions a federated identity can perform.
Repository Access at Organization Level: Lists the repositories to which federated identities are granted access.

Example Policy:

issuer: https://token.actions.githubusercontent.com
subject: repo:chainguard-dev/foo:ref:refs/heads/main

permissions:
  contents: read
  issues: write

This sample policy provides GitHub Actions workflows running in the chainguard-dev/foo repository on the main branch with permissions to read repository contents and interact with issues.

Complex matching using regular expressions is possible too, allowing flexibility with issuer, subject, or custom claims.

Example with Regex:

issuer: https://accounts.google.com
subject_pattern: '[0-9]+'
claim_pattern:
  email: '.*@chainguard.dev'

permissions:
  contents: read

In this scenario, OIDC tokens from Google accounts affiliated with Chainguard email addresses can read repository contents.

Token Federation

The octo-sts app supports Chainguard's SecurityTokenService GRPC service. Sending a suitable ${TOKEN} to the service enacts as follows:

curl -H "Authorization: Bearer ${TOKEN}" \
  "https://octo-sts.dev/sts/exchange?scope=${REPO}&identity=${NAME}"

The app retrieves the trust policy from .github/chainguard/${NAME}.sts.yaml in ${REPO}, and if ${TOKEN} adheres to the defined rules, it responds with a token embodying the outlined permissions.

Agile Release Cadence

octo-sts operates on an as-needed release schedule. New features or bug fixes could prompt immediate updates, ensuring the app evolves dynamically with its users' needs.

Permission Management

Occasionally, adjustments to GitHub permissions are necessary, whether adding or removing. Recognizing GitHub Apps' constraints, octo-sts initially requests all potential permissions. To minimize disruption, such permission updates occur quarterly. Feedback or concerns about these updates can be addressed in discussions on GitHub issues.