Documentation
¶
Overview ¶
Package oauthprovider is test support: a dependency-free (standard-library only) fake upstream OAuth authorization server for exercising provider adapters against a real local HTTP server with a real RSA key.
The fake serves an RFC 8414 discovery document, a JWKS, and a token endpoint, and it can mint RS256-signed access tokens with the same key. Every configurable behavior a provider conformance table needs is reachable through Options and Claims:
- success: the default discovery/JWKS/token responses
- error classes: TokenStatus with a TokenBody carrying an OAuth error code
- slow/hung: TokenDelay (a delayed response the caller's fetch bound must cut)
- rotated refresh: a TokenBody whose refresh_token differs from the one presented (the presented form is recorded as LastTokenRequest)
- refresh: RefreshTokenStatus and RefreshTokenBody serve a grant_type=refresh_token response distinct from the code exchange — its own access token, its own upstream refresh token, and its own id_token — so a facade that hides upstream material is observable, while RefreshTokenStages stages the leading refresh responses in call order so a transient upstream failure that clears is observable too; RefreshCallCount and LastRefreshRequest report the refresh calls separately from the total TokenCallCount
- oversized body: TokenBodyBytes serves filler that is not JSON, while TokenBodyPaddingBytes serves a well-formed token document whose access_token is itself longer than the caller's cap, so a size bound is observable without the body also being unparseable
- missing iss: OmitDiscoveryIssuer on the document, or an empty Claims.Issuer, which omits the token's iss claim
- bad signature: Claims.TamperSignature, which corrupts the token signature
Nothing in production imports this package.
Index ¶
- type Claims
- type Options
- type RefreshStage
- type Server
- func (s *Server) BaseURL() string
- func (s *Server) Close()
- func (s *Server) DiscoveryURL() string
- func (s *Server) HTTPClient() *http.Client
- func (s *Server) Issuer() string
- func (s *Server) JWKSURL() string
- func (s *Server) LastRefreshRequest() url.Values
- func (s *Server) LastTokenRequest() url.Values
- func (s *Server) MintAccessToken(claims Claims) string
- func (s *Server) RefreshCallCount() int
- func (s *Server) TokenCallCount() int
- func (s *Server) TokenEndpoint() string
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Claims ¶
type Claims struct {
Issuer string `json:"iss"`
Audience string `json:"aud"`
AuthorizedParty string `json:"azp"`
Subject string `json:"sub"`
Scope string `json:"scope"`
ExpiresIn int `json:"expires_in"`
TamperSignature bool `json:"tamper_signature"`
}
Claims are the access-token claims MintAccessToken signs. The JSON tags match the shared provider conformance fixture's token object, so a fixture row can be decoded straight into Claims. An empty Issuer omits the iss claim.
type Options ¶
type Options struct {
// Issuer is the issuer URL the fake publishes and the origin every endpoint
// points at. The caller routes that origin to this server's listener with
// HTTPClient. It must be an absolute URL and is required.
Issuer string
// DiscoveryIssuer overrides the issuer the discovery document claims, for a
// document the adapter must reject. Zero value means Issuer.
DiscoveryIssuer string
// OmitDiscoveryIssuer serves a discovery document with no issuer claim.
OmitDiscoveryIssuer bool
// RedirectTo answers the discovery endpoint with a 302 to this location.
RedirectTo string
// TokenStatus is the token endpoint's status code. Zero means 200.
TokenStatus int
// TokenBody is the JSON body the token endpoint returns.
TokenBody map[string]any
// TokenBodyBytes serves that many bytes instead of TokenBody, for a body
// bound that must be enforced. The bytes are filler, so the body is not
// JSON and any bound it triggers is indistinguishable from a parse failure.
TokenBodyBytes int
// TokenBodyPaddingBytes serves a well-formed token document whose
// access_token value is this many bytes long. It differs from a body that
// is merely oversized by being valid JSON, so a case that expects an error
// only while the response cap holds fails once the cap is removed.
TokenBodyPaddingBytes int
// TokenDelay delays the token response, for a fetch timeout that must cut it.
TokenDelay time.Duration
// RefreshTokenStatus is the status of a grant_type=refresh_token response.
// Zero means TokenStatus.
RefreshTokenStatus int
// RefreshTokenBody is the JSON body of a grant_type=refresh_token response.
// Nil means TokenBody. It is how a test gives the refresh grant its own
// access token, its own upstream refresh token, and its own id_token, so a
// caller that must hide upstream material is observable.
RefreshTokenBody map[string]any
// RefreshTokenStages stages the leading grant_type=refresh_token responses in
// call order: the nth refresh call takes the nth stage, and every later call
// takes the steady-state response above. A stage whose Body is nil or whose
// Status is zero falls back to the steady-state value. It exists so a
// transient upstream failure that clears is observable.
RefreshTokenStages []RefreshStage
// Now is the mint clock for iat/exp. Nil means time.Now().UTC.
Now func() time.Time
}
Options configures NewServer.
type RefreshStage ¶
type RefreshStage struct {
// Status is the HTTP status. Zero means the steady-state refresh status.
Status int
// Body is the JSON body. Nil means the steady-state refresh body.
Body map[string]any
}
RefreshStage is one staged grant_type=refresh_token response.
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
Server is one running fake upstream.
func NewServer ¶
NewServer starts a real local HTTP server that impersonates the configured issuer. It registers Close with the test's cleanup, so a caller that does not call Close itself still releases the listener.
func (*Server) DiscoveryURL ¶
DiscoveryURL is the issuer-relative RFC 8414 discovery URL.
func (*Server) HTTPClient ¶
HTTPClient returns a client that rewrites the configured issuer origin onto this server's loopback listener, so an adapter built for the real issuer URL reaches the fake. It refuses any other origin, so a redirect to another host is never followed to something unintended.
func (*Server) Issuer ¶
Issuer is the configured issuer URL the fake publishes and every endpoint points at.
func (*Server) LastRefreshRequest ¶
LastRefreshRequest returns a copy of the form the last grant_type=refresh_token request presented, so a test can observe the material and client that refresh leg carried.
func (*Server) LastTokenRequest ¶
LastTokenRequest returns a copy of the form the token endpoint last received, which is how a test observes the material and client a caller presented.
func (*Server) MintAccessToken ¶
MintAccessToken returns a compact RS256 JWS over claims, signed with the fake's key and carrying the kid the fake publishes in its JWKS.
func (*Server) RefreshCallCount ¶
RefreshCallCount reports how many grant_type=refresh_token requests the fake served, counted separately from the total TokenCallCount, so a facade's single-flight rotation is observable.
func (*Server) TokenCallCount ¶
TokenCallCount reports how many token requests the fake served.
func (*Server) TokenEndpoint ¶
TokenEndpoint is the issuer-relative token endpoint URL.