GitHubTokenExchangeService#

class gafaelfawr.services.github_actions.GitHubTokenExchangeService(*, config, verifier, project_store, token_service, session, logger)#

Bases: object

Exchange GitHub Actions ID tokens for Gafaelfawr tokens.

The exchange is the one route of the GitHub Actions token exchange that a workflow calls. It verifies the ID token that GitHub issued to the workflow job, finds the enabled GitHub project whose constraints the token satisfies, and mints a token of type github for that project’s bot user with the scopes and lifetime the project allows.

Parameters:

Methods Summary

exchange_token(subject_token, *, scopes, ...)

Exchange a GitHub Actions ID token for a Gafaelfawr token.

Methods Documentation

async exchange_token(subject_token, *, scopes, ip_address)#

Exchange a GitHub Actions ID token for a Gafaelfawr token.

The errors raised for a rejected exchange are sent to the client. Their messages name the check that failed and values from the caller’s own ID token, which are already the caller’s to read, but never describe registry entries that did not match, so that the exchange cannot be used to probe what the registry trusts.

Parameters:
  • subject_token (str) – Encoded GitHub Actions ID token.

  • scopes (set[str] | None) – Scopes requested for the token, or None to receive every scope of the matching project. Requested scopes must be a subset of the project’s scopes; a request for a scope outside that set is rejected rather than silently narrowed, so that a misconfigured workflow fails visibly.

  • ip_address (str) – IP address from which the request came, which is that of the GitHub Actions runner.

Returns:

The minted token and the identity and claims it was minted from.

Return type:

GitHubTokenExchangeResult

Raises:
  • FetchKeysError – Raised if GitHub’s key data is syntactically invalid or contains no usable keys.

  • GitHubWebError – Raised if unable to retrieve signing keys from GitHub.

  • InvalidSubjectTokenError – Raised if the ID token fails verification or matches no enabled GitHub project.

  • InvalidTokenError – Raised if the minted token could not be stored, probably due to a desynchronization between Redis and the SQL database.

  • UnauthorizedScopeError – Raised if a requested scope is not allowed by the matching project.