Documentation
¶
Overview ¶
Package oauthserver assembles the OAuth 2.1 authorization server and its storage behind one Handle: storage selection (Postgres when a database is present, else in-memory), bcrypt-hashed pre-registration of configured clients, the server itself, its authorization-state cleanup, and metrics wiring.
New takes an explicit Config so the server can be built and tested on its own; the package imports pkg/oauth (+ pkg/oauth/postgres) and pkg/observability, never pkg/platform. Callers translate their own config into Config at the boundary.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Client ¶
Client is a pre-registered OAuth client. Its Secret is the plaintext secret; New bcrypt-hashes it before persisting.
type Config ¶
type Config struct {
Issuer string
AccessTokenTTL time.Duration
SigningKey []byte
Clients []Client
DCR DCR
RateLimit RateLimit
Upstream *Upstream
// DCRUnusedTTL is the age after which an unused dynamically-registered
// client is reaped by the store's cleanup routine (database path only).
// Defaults to defaultDCRUnusedTTL when zero.
DCRUnusedTTL time.Duration
// DB selects Postgres-backed storage when non-nil; otherwise in-memory
// storage is used. Ignored when Storage is set. Only the DB path yields a
// shared (multi-replica) authorization-state store; see New.
DB *sql.DB
// Storage overrides storage selection with a pre-chosen backend. When set,
// DB is ignored and no store-closer is owned by the Handle. An injected
// Storage backs client/code/token persistence only: the server still uses
// the in-memory authorization-state store (multi-replica state sharing
// requires DB). Primarily a test seam.
Storage oauth.Storage
// Metrics records token issuance/refresh outcomes; may be nil.
Metrics *observability.Metrics
}
Config carries the values New needs to assemble the OAuth server. Callers build it from their own config so this package stays free of platform config types.
type Handle ¶
type Handle struct {
// contains filtered or unexported fields
}
Handle owns the assembled OAuth server together with the resources that must be torn down at shutdown: the Postgres store's closer (database path) and the in-memory state-store cleanup routine's cancellation (single-replica path).
The two torn-down resources belong to different shutdown phases, mirroring the original platform wiring: the store-closer is released by Close (the resource teardown phase), while the in-memory cleanup cancel is returned by StateStoreCleanup for the caller to wire into its lifecycle stop phase.
func New ¶
New assembles the OAuth server from cfg: it selects storage, pre-registers configured clients with bcrypt-hashed secrets, builds the server, wires the authorization-state store (shared Postgres store, or an in-memory cleanup routine whose cancel is returned by StateStoreCleanup), and attaches metrics.
The Postgres store's cleanup ticker starts before the failure-prone assembly steps, so the returned Handle owns its closer immediately: on any error after that point, New closes the Handle before returning so the store and its goroutine never outlive a failed construction.
func (*Handle) Close ¶
Close releases the Handle's resources: it stops the server's rate-limiter cleanup goroutines (both storage paths) and closes the Postgres store (database path only). It is nil-safe; the in-memory state-store cleanup routine is canceled separately via StateStoreCleanup.
func (*Handle) Server ¶
Server returns the assembled OAuth server, or nil when the Handle is nil (OAuth disabled).
func (*Handle) StateStoreCleanup ¶
func (h *Handle) StateStoreCleanup() context.CancelFunc
StateStoreCleanup returns the cancel for the in-memory authorization-state cleanup routine (single-replica path), or nil on the database path or a nil Handle. The caller wires it into its lifecycle stop so the ticker goroutine is canceled when the platform stops, without this package importing the caller's lifecycle.
type RateLimit ¶
type RateLimit struct {
Enabled *bool
TrustedProxies []string
TokenRPM int
TokenBurst int
RegisterRPM int
RegisterBurst int
}
RateLimit carries the OAuth HTTP rate-limiting policy for the /token and /register endpoints. It mirrors oauth.RateLimitConfig at the package boundary so callers do not import pkg/oauth directly.
type Upstream ¶
type Upstream struct {
Issuer string
ClientID string
ClientSecret string
RedirectURI string
// AuthorizationEndpoint and TokenEndpoint optionally override OIDC discovery
// for IdPs with broken discovery documents. Empty means discover.
AuthorizationEndpoint string
TokenEndpoint string
}
Upstream identifies the upstream identity provider used for the authorization-code flow, when one is configured.