A "Security Token Service" for GitHub

tl;dr Octo STS is a GitHub App that acts as a "Security Token Service" (aka
STS) for the GitHub API.

Octo STS enables workloads running anywhere to exchange short-lived OIDC tokens
for short-lived GitHub credentials thereby eliminating the need for those
workloads to manage long-lived GitHub credentials.

Leveraging Octo STS,Chainguard has been able to eliminate a small horde of
assorted long-lived GitHub credentials including:

• Dozens of Classic and Fine-grained "Personal Access Tokens" (aka PATs),
• A handful of dedicated GitHub App private keys,
• A handful of"deploy keys".

Chainguard does not currently offer any level of support for Octo STS, but if you are interested thenplease reach out to us.

Setting up workload trust

For the App to produce credentials that work with resources inyour-org
it must be installed intoyour-org and have access to any repositories (e.g.your-repo)
that you will want workloads to be able to interact with.

Due to the way Github Apps work, the App must ask for a superset of the
permissions that any user might ask for in a token, so the full set of
permissions the App requests is large, but the only permissions the
App itself uses iscontents: read for reading trust policies, andchecks: write for validating trust policies.
All of the remaining permissions are requested exclusively for producing
tokens as specified in trust policies.

The Trust Policy

Trust policies are checked into.github/chainguard/{name}.sts.yaml, and
consist of a few key parts:

1. The claim matching criteria for federation,
2. The permissions to grant the identity, and
3. (for Org-level policies) The list of repositories to grant access.

Here is a simple example that allows the Github actions workflows in
chainguard-dev/foo running on themain branch to read the repo contents and
interact with issues:

issuer:https://token.actions.githubusercontent.comsubject:repo:chainguard-dev/foo:ref:refs/heads/mainpermissions:contents:readissues:write

The Trust Policy can also match the issuer, subject, and even custom claims with
regular expressions. For example:

issuer:https://accounts.google.comsubject_pattern:'[0-9]+'claim_pattern:email:'.*@chainguard\.dev'permissions:contents:read

This policy will allow OIDC tokens from Google accounts of folks with a
Chainguard email address to federate and read the repo contents.

Federating a token (GitHub Actions)

To support federation from GitHub Actions, we provide
octo-sts/actionhere, which can be used like so:

permissions:id-token:write# Needed to federate tokens.steps:-uses:octo-sts/action@6177b4481c00308b3839969c3eca88c96a91775f# v1.0.0id:octo-stswith:scope:your-org/your-repoidentity:foo-env:GITHUB_TOKEN:${{ steps.octo-sts.outputs.token }}run:|    gh repo list

The App will attempt to load the trust policy from
.github/chainguard/foo.sts.yaml fromyour-org/your-repo and if the
workflow's identity token satisfies the trust policy, it will return a token
with the enclosed permissions.

Federating a token (Go)

The Github App implements a subset of the ChainguardSecurityTokenService GRPC
service definitionhere, and we have some higher-level libraries
around this.

Here is an example program that takes in an input token via-token, performs
the federation, and prints the resulting token toSTDOUT:

package mainimport ("context""flag""log""os""chainguard.dev/sdk/sts")vartoken=flag.String("token","","Bot token")funcmain() {flag.Parse()xchg:=sts.New("https://octo-sts.dev","does-not-matter",sts.WithScope("your-org/your-repo"),sts.WithIdentity("foo"),)res,err:=xchg.Exchange(context.Background(),*token)iferr!=nil {log.Fatalf("exchange failed: %v",err)}os.Stdout.WriteString(res)}

The App will attempt to load the trust policy from
.github/chainguard/foo.sts.yaml fromyour-org/your-repo and if the
workflow's identity token satisfies the trust policy, it will return a token
with the enclosed permissions.

Federating a token (low-level)

If you would like to try this out on the command-line withcurl, here is how.

If a${TOKEN} suitable for federation is sent like so:

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

The App will attempt to load the trust policy from
.github/chainguard/foo.sts.yaml fromyour-org/your-repo and if the
workflow's identity token satisfies the trust policy, it will return a token
with the enclosed permissions.