oauthprovider

package
v7.4.0 Latest Latest
Warning

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

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

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

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

func NewServer(tb testing.TB, opts Options) *Server

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) BaseURL

func (s *Server) BaseURL() string

BaseURL is the loopback listener URL the transport rewrites onto.

func (*Server) Close

func (s *Server) Close()

Close stops the server. It is idempotent.

func (*Server) DiscoveryURL

func (s *Server) DiscoveryURL() string

DiscoveryURL is the issuer-relative RFC 8414 discovery URL.

func (*Server) HTTPClient

func (s *Server) HTTPClient() *http.Client

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

func (s *Server) Issuer() string

Issuer is the configured issuer URL the fake publishes and every endpoint points at.

func (*Server) JWKSURL

func (s *Server) JWKSURL() string

JWKSURL is the issuer-relative JWKS URL.

func (*Server) LastRefreshRequest

func (s *Server) LastRefreshRequest() url.Values

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

func (s *Server) LastTokenRequest() url.Values

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

func (s *Server) MintAccessToken(claims Claims) string

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

func (s *Server) RefreshCallCount() int

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

func (s *Server) TokenCallCount() int

TokenCallCount reports how many token requests the fake served.

func (*Server) TokenEndpoint

func (s *Server) TokenEndpoint() string

TokenEndpoint is the issuer-relative token endpoint URL.

Jump to

Keyboard shortcuts

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