oidc

package
v0.8.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 19, 2026 License: Apache-2.0 Imports: 27 Imported by: 0

Documentation

Overview

Package oidc holds the OpenID Connect settings and discovery for secure-mode sign-in.

Index

Constants

View Source
const (
	ReasonUnauthenticated = "unauthenticated"
	ReasonInvalid         = "invalid"
)

Sign-in failure reasons, the only detail that reaches the browser.

Variables

View Source
var (
	// ErrNoRefreshToken means the sign-in returned no refresh token, so the identity cannot be renewed.
	ErrNoRefreshToken     = errors.New("no-refresh-token")
	ErrRefreshUnavailable = errors.New("refresh-unavailable")
	ErrTokenRefresh       = errors.New("token-refresh-failed")
	ErrIDTokenInvalid     = errors.New("id-token-invalid")
	ErrTokenReviewRefused = errors.New("token-review-refused")
	ErrTokenReviewFailed  = errors.New("token-review-failed")
)

Refresh failure categories. Refresh returns only these, so no issuer or cluster error text, which could quote a token, reaches a caller or a log.

View Source
var DefaultScopes = []string{"openid", "profile", "email", "groups", "offline_access"}

DefaultScopes are requested when Config.Scopes is empty.

View Source
var ErrUnauthenticated = errors.New("token review: not authenticated")

ErrUnauthenticated is the TokenReview refusal; any other Review error is a failure to ask.

Functions

This section is empty.

Types

type Auditor

type Auditor interface {
	Emit(ctx context.Context, rec audit.Record)
}

Auditor receives audit records; *audit.Logger is one.

type Completer

type Completer interface {
	Complete(w http.ResponseWriter, r *http.Request, res Result)
}

Completer finishes a sign-in that passed every check, usually by starting a session.

type Config

type Config struct {
	// IssuerURL is the issuer identifier; discovery reads it plus /.well-known/openid-configuration.
	IssuerURL string
	// ClientID identifies Snellius at the issuer.
	ClientID string
	// ClientSecretFile holds the client secret; empty means a public client.
	ClientSecretFile string
	// RedirectURL is the registered callback, normally https://<host>/auth/callback.
	RedirectURL string
	// Scopes are the requested scopes; empty means DefaultScopes.
	Scopes []string
	// CAFile is a PEM bundle added to the system roots for issuers behind a private CA.
	CAFile string
}

Config is the OpenID Connect client configuration.

func (Config) Set

func (c Config) Set() bool

Set reports whether any OIDC setting differs from its default.

func (Config) Validate

func (c Config) Validate() error

Validate checks that the issuer and redirect URLs are absolute https and the client ID is set. The redirect may be http on a loopback host, for testing. The error names every problem and holds no secret.

type Endpoints

type Endpoints struct {
	AuthorizationEndpoint string
	TokenEndpoint         string
	// EndSessionEndpoint is empty when the provider has none.
	EndSessionEndpoint string
}

Endpoints are the discovered provider endpoints.

type Flow

type Flow struct {
	// contains filtered or unexported fields
}

Flow serves /auth/login and /auth/callback: the authorization code flow with PKCE, checked in the order of design §4.1.

func NewFlow

func NewFlow(o FlowOptions) (*Flow, error)

NewFlow builds a Flow. A client secret file, when configured, must be readable and not empty.

func (*Flow) Callback

func (f *Flow) Callback(w http.ResponseWriter, r *http.Request)

Callback serves GET /auth/callback. It checks the transaction, state, code exchange, ID-token claims and TokenReview in that order, then hands the result to the Completer. Any failure redirects to /signin-failed with a reason.

func (*Flow) Login

func (f *Flow) Login(w http.ResponseWriter, r *http.Request)

Login serves GET /auth/login?return=<path>: it opens a transaction and redirects to the authorization endpoint.

func (*Flow) Refresh

func (f *Flow) Refresh(ctx context.Context, refreshToken string) (Result, error)

Refresh redeems refreshToken at the token endpoint (OIDC Core §12), checks the new ID token's claims and reviews it. The caller compares iss and sub with the session's. Every error is one of the categories above.

type FlowOptions

type FlowOptions struct {
	Config Config
	// Provider supplies the discovered endpoints and the HTTP client for the code exchange.
	Provider  *Provider
	Reviewer  Reviewer
	Completer Completer
	Audit     Auditor
	// Clock checks ID-token times; nil means the real clock.
	Clock clock.PassiveClock
	// CookieSecure marks the login cookie Secure.
	CookieSecure bool
	// Logger receives failure steps, never a token; nil means slog.Default().
	Logger *slog.Logger
}

FlowOptions configure a Flow.

type Identity

type Identity struct {
	Username string
	UID      string
	Groups   []string
	Extra    map[string][]string
}

Identity is the Kubernetes identity the API server returns for a token.

type KubeReviewer

type KubeReviewer struct {
	// contains filtered or unexported fields
}

KubeReviewer reviews tokens through the authentication.k8s.io/v1 TokenReview API.

func NewKubeReviewer

func NewKubeReviewer(kube kubernetes.Interface) *KubeReviewer

NewKubeReviewer returns a Reviewer backed by the cluster's TokenReview API.

func (*KubeReviewer) Review

func (k *KubeReviewer) Review(ctx context.Context, idToken string) (Identity, error)

Review returns the identity the API server gives the token, if it authenticates it. It sets no spec.audiences: the API server checks a JWT against its own configured audiences, and matches spec.audiences only against its ServiceAccount audiences. The binding to Snellius's client is the aud check in checkClaims, trusted once this passes.

type Provider

type Provider struct {
	// contains filtered or unexported fields
}

Provider discovers the issuer's endpoints and holds the HTTP client for discovery and token calls.

func NewProvider

func NewProvider(cfg Config, clk clock.Clock) (*Provider, error)

NewProvider builds a Provider. With cfg.CAFile, its PEM certificates are added to a copy of the system roots; an unreadable or empty bundle is an error.

func (*Provider) Discover

func (p *Provider) Discover(ctx context.Context, client *http.Client) (*Endpoints, error)

Discover reads the issuer's discovery document with client. The document's issuer must equal the configured one, and the endpoints must always be https.

func (*Provider) Endpoints

func (p *Provider) Endpoints() *Endpoints

Endpoints returns the discovered endpoints, or nil before discovery succeeds.

func (*Provider) HTTPClient

func (p *Provider) HTTPClient() *http.Client

HTTPClient is the client for discovery and token calls; it trusts the configured CA.

func (*Provider) Ready

func (p *Provider) Ready() (ready bool, err error)

Ready reports whether discovery succeeded; when not, err is the last failure.

func (*Provider) Run

func (p *Provider) Run(ctx context.Context)

Run discovers until it succeeds, retrying with a doubling backoff from 1 s to 1 min, and returns on success or when ctx is done.

type RedirectCompleter

type RedirectCompleter struct{}

RedirectCompleter redirects to the return path and keeps nothing.

func (RedirectCompleter) Complete

func (RedirectCompleter) Complete(w http.ResponseWriter, r *http.Request, res Result)

Complete implements Completer.

type Result

type Result struct {
	// Identity is what TokenReview returned; Issuer and Subject come from the ID token.
	Identity        Identity
	Issuer, Subject string
	IDToken         string
	// Expiry is the ID token's exp.
	Expiry                    time.Time
	AccessToken, RefreshToken string
	// ReturnPath is a same-origin relative path.
	ReturnPath string
}

Result is a completed sign-in. Its tokens stay on the server.

type Reviewer

type Reviewer interface {
	Review(ctx context.Context, idToken string) (Identity, error)
}

Reviewer asks the cluster who an ID token belongs to (design §4.2).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL