Documentation
¶
Overview ¶
Package cijwt provides an http.RoundTripper that authenticates outbound requests on a per-host basis with a JWT, sourcing the token from a CI/CD platform's OIDC integration or signing it locally.
Each configured host gets its token one of four ways:
- WithHostTokenFunc invokes a caller-supplied function to obtain the JWT, then caches it for the first 50% of its 'exp' claim's remaining lifetime and re-invokes the function on demand. The caller decides where the token comes from (e.g. actionsoidc.FetchToken for the GitHub/Forgejo Actions endpoint, idtoken.NewTokenSource for GCP, etc.).
- WithHostToken sends a static JWT as-is, e.g. a GitLab CI id_token injected into the job environment.
- WithHostTokenFile reads the JWT from a file for every request, so a token rotated by an external process is picked up without restarting.
- WithHostJWK signs a fresh, short-lived JWT with a private key from a JWK, issuing a new token for every request rather than caching it.
Requests to hosts that were not configured are forwarded unchanged, so a request to a registry the JWT is not meant for keeps its existing authentication.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Option ¶
type Option func(*options)
Option configures a Transport.
func WithHostJWK ¶
WithHostJWK configures host to be authenticated with a JWT signed locally using a private key parsed from jwk (a single JSON Web Key holding an Ed25519 or ECDSA private key; the signing algorithm is derived from the key type, see the jwt package). Each request gets a freshly signed, 60-second-lived token carrying iss, aud, and sub as given and the signing key's id in the "kid" header. Unlike WithHostAudience, the token is never cached.
func WithHostToken ¶
WithHostToken configures host to be authenticated with the given static JWT, sent as-is (e.g. a GitLab CI id_token).
func WithHostTokenFile ¶ added in v0.49.0
WithHostTokenFile configures host to be authenticated with a static JWT read from path. The file is read on every request, with leading and trailing whitespace trimmed, so a token rotated by an external process (e.g. a projected service account token) is picked up without restarting. An unreadable or empty file errors the request.
func WithHostTokenFunc ¶ added in v0.49.0
WithHostTokenFunc configures host to be authenticated with a JWT obtained by calling fn. The Transport caches the returned token for the first 50% of its 'exp' claim's remaining lifetime and re-invokes fn on demand. fn errors and tokens missing an 'exp' claim are returned wrapped to the RoundTrip caller.
func WithInner ¶
func WithInner(rt http.RoundTripper) Option
WithInner sets the underlying RoundTripper that requests are forwarded to. Defaults to http.DefaultTransport.
type TokenFunc ¶ added in v0.49.0
TokenFunc returns a fresh JWT. The Transport parses the returned token's 'exp' claim without verifying the signature and caches it for the first 50% of its remaining lifetime, re-invoking fn on demand.
type Transport ¶
type Transport struct {
// contains filtered or unexported fields
}
Transport is an http.RoundTripper that stamps Authorization: Bearer <jwt> on requests whose URL host was configured with WithHostToken, WithHostTokenFile, WithHostTokenFunc, or WithHostJWK. Any existing Authorization header on a configured host is overwritten; requests to other hosts pass through untouched.
func NewTransport ¶
NewTransport returns a Transport configured by opts. At least one host must be configured. It returns an error if the same host is configured more than once, whether via WithHostToken, WithHostTokenFile, WithHostTokenFunc, WithHostJWK, or a mix of them, or if a WithHostJWK key fails to parse.
Source Files