Documentation
¶
Overview ¶
Package oidcauth implements a generic, provider-agnostic OpenID Connect machine-to-machine (client_credentials) auth exchange: it resolves the token endpoint (explicitly, via a discovery document, or via issuer discovery), requests a token, and returns the caller-selected token (access_token or id_token) for attachment to outbound requests.
Index ¶
- Constants
- func FetchToken(ctx context.Context, cfg Config, httpClient *http.Client) (string, error)
- func SubjectTokenRetriever(cfg SubjectTokenConfig) (func() (string, error), error)
- func TokenSource(ctx context.Context, cfg Config, httpClient *http.Client) (oauth2.TokenSource, error)
- type Config
- type ProviderMetadata
- type SubjectTokenConfig
- type Transport
Constants ¶
const ( // TokenTypeAccessToken selects the OAuth2 access_token as the credential. TokenTypeAccessToken string = "access_token" // TokenTypeIDToken selects the OIDC id_token as the credential. TokenTypeIDToken string = "id_token" // LocationHeader attaches the token to a request header (the default). LocationHeader string = "header" // LocationQuery attaches the token to a URL query parameter. LocationQuery string = "query" )
Variables ¶
This section is empty.
Functions ¶
func FetchToken ¶
FetchToken performs a one-shot client_credentials exchange and returns the selected token. Prefer TokenSource + Transport for long-lived clients, which refreshes automatically. httpClient may be nil.
func SubjectTokenRetriever ¶
func SubjectTokenRetriever(cfg SubjectTokenConfig) (func() (string, error), error)
SubjectTokenRetriever returns a closure that produces a current token on each call. File-backed retrievers re-read the file every invocation so that platform-rotated tokens (IRSA, GHA, k8s) are picked up transparently across downstream credential refreshes.
func TokenSource ¶
func TokenSource(ctx context.Context, cfg Config, httpClient *http.Client) (oauth2.TokenSource, error)
TokenSource builds an auto-refreshing OAuth2 token source for the OIDC client_credentials exchange. Endpoint discovery (when required) happens once, here; the returned source caches the token and transparently re-fetches it against the resolved endpoint whenever it expires. The supplied context governs the lifetime of those refreshes, so callers should pass a long-lived (e.g. background) context rather than a request-scoped one. httpClient (which may be nil) carries TLS/proxy configuration for discovery, the token request, and JWKS retrieval.
Types ¶
type Config ¶
type Config struct {
// Endpoint resolution. Precedence: TokenURL > DiscoveryURL > Issuer.
Issuer string
DiscoveryURL string
TokenURL string
// Client credentials and client-authentication style.
ClientID string
ClientSecret string
AuthStyle int
// Token request shaping.
Scopes []string
Audience string
EndpointParams url.Values
// TokenType selects which token is returned: access_token (default) or id_token.
TokenType string
// VerifyIssuer, when true, asserts that the issuer advertised in the
// discovery document matches the configured Issuer. Off by default.
VerifyIssuer bool
// VerifyIDToken, when true, cryptographically verifies the id_token in each
// (refreshed) token response against the provider's JWKS — checking
// signature, expiry, and issuer — before the token is used. Requires Issuer.
// Off by default.
VerifyIDToken bool
}
Config fully describes an OIDC token exchange. Every field is caller-supplied; FetchToken applies defaults only where a value is omitted.
type ProviderMetadata ¶
type ProviderMetadata struct {
Issuer string `json:"issuer"`
TokenEndpoint string `json:"token_endpoint"`
}
ProviderMetadata captures the subset of the OIDC discovery document that this package consumes. The full document carries far more, but only the token endpoint is required for the client_credentials grant.
type SubjectTokenConfig ¶
type SubjectTokenConfig struct {
// File is a literal filesystem path containing the token.
File string
// FileEnvVar is the name of an environment variable holding a filesystem
// path to the token. This is how IRSA (AWS_WEB_IDENTITY_TOKEN_FILE), GitHub
// Actions (ACTIONS_ID_TOKEN_REQUEST_TOKEN-style), and projected k8s
// service-account tokens are conventionally surfaced.
FileEnvVar string
// Inline is a literal token value. Primarily for tests; production tokens
// are short-lived and rotated by the platform via file.
Inline string
}
SubjectTokenConfig identifies where the foreign OIDC token used in cloud federation (AWS AssumeRoleWithWebIdentity, GCP Workload Identity Federation, Azure federated credentials) is read from. Resolution precedence on every retrieval: File > FileEnvVar > Inline.
type Transport ¶
type Transport struct {
Base http.RoundTripper
TokenSource oauth2.TokenSource
TokenType string
Location string
Name string
ValuePrefix string
}
Transport attaches an auto-refreshing OIDC token to every outbound request. By default it sets "Authorization: Bearer <token>"; the credential (access vs id token), the value prefix, the header/param name, and header-vs-query placement are all configurable.
Source Files