oauth2server

type AccessToken ¶

type AccessToken struct {
	IssuedAt  time.Time
	ExpiresAt time.Time

	// RevokedAt is when the token was revoked, or the zero time. Revocation is
	// recorded rather than deleting the row so that a sweep and a revocation
	// are different events, and so that the row survives long enough for a
	// resource server's next request to be answered "no" rather than "never
	// heard of it".
	RevokedAt time.Time

	Hash     string
	ClientID string

	// FamilyID ties this token to the refresh-token family it was minted
	// under, so revoking the family revokes it.
	FamilyID string

	Subject Subject

	Scopes []string

	// Audience is the RFC 8707 resource this token is for. A resource server
	// that finds its own identifier absent must refuse the token: that check
	// is the reason resource indicators exist, and this package cannot make it
	// on the resource server's behalf.
	Audience []string
}

AccessToken is one issued access token.

Opaque and stored, not signed and self-describing — see the package doc for why that is a decision rather than an accident, and what it costs. As with AuthorizationCode, what is stored is the digest.

func TokenFromContext(ctx context.Context) (*AccessToken, bool)

func (t *AccessToken) Active(now time.Time) bool

func (t *AccessToken) Clone() *AccessToken

func (t *AccessToken) HasScopes(required ...string) bool

type AuthorizationCode ¶

type AuthorizationCode struct {
	IssuedAt  time.Time
	ExpiresAt time.Time

	// RedeemedAt is when the code was consumed, or the zero time. It is what
	// makes a second redemption detectable rather than merely unsuccessful.
	RedeemedAt time.Time

	// Hash is the hex-encoded SHA-256 digest of the code. It is the store's
	// primary key.
	Hash string

	ClientID string

	// FamilyID is the token family this code will mint, minted here at
	// /authorize rather than at the redemption that uses it.
	//
	// The timing is the whole point. RFC 6749 §4.1.2 says a code presented a
	// second time should revoke what the first presentation issued, and a
	// family decided at redemption is one a replay cannot name: the record
	// comes back with ErrAlreadyRedeemed carrying everything about the code
	// except the one field that says which tokens to revoke. Deciding it here
	// costs an identifier for a code that is never redeemed and makes the
	// replay actionable.
	FamilyID string

	// RedirectURI is the one the authorization request nominated, re-checked at
	// the token endpoint. A code issued for one URI cannot be redeemed by
	// naming another.
	RedirectURI string

	// CodeChallenge is the S256 challenge the code is bound to. Never empty —
	// PKCE is mandatory.
	CodeChallenge string

	// Nonce is echoed into the token record for an OpenID-shaped caller that
	// wants it. This package does not issue ID tokens and does not interpret
	// it.
	Nonce string

	Subject Subject

	Scopes []string

	// Resources are the RFC 8707 resource indicators the authorization request
	// asked for. They become the access token's audience, which is what stops
	// a token minted for one resource server being replayed at another.
	Resources []string
}

AuthorizationCode is one issued authorization code.

The code itself is not in here. What the store holds is Hash — the SHA-256 digest of the value the client received — so that a dump of this table contains nothing that can be redeemed. That is a property a map-backed store gets for free by dying with the process and a table does not get at all.

func (c *AuthorizationCode) Clone() *AuthorizationCode

type AuthorizationServerMetadata ¶

type AuthorizationServerMetadata struct {
	Issuer                            string   `json:"issuer"`
	AuthorizationEndpoint             string   `json:"authorization_endpoint"`
	TokenEndpoint                     string   `json:"token_endpoint"`
	RegistrationEndpoint              string   `json:"registration_endpoint,omitempty"`
	RevocationEndpoint                string   `json:"revocation_endpoint"`
	ServiceDocumentation              string   `json:"service_documentation,omitempty"`
	ScopesSupported                   []string `json:"scopes_supported,omitempty"`
	ResponseTypesSupported            []string `json:"response_types_supported"`
	GrantTypesSupported               []string `json:"grant_types_supported"`
	TokenEndpointAuthMethodsSupported []string `json:"token_endpoint_auth_methods_supported"`

	// CodeChallengeMethodsSupported lists S256 and nothing else, which is also
	// how a client discovers that PKCE is not optional here.
	CodeChallengeMethodsSupported []string `json:"code_challenge_methods_supported"`

	RevocationEndpointAuthMethodsSupported []string `json:"revocation_endpoint_auth_methods_supported"`

	// AuthorizationResponseIssParameterSupported reports that every
	// authorization response carries the "iss" parameter (RFC 9207), which is
	// what lets a client with more than one authorization server tell which one
	// answered. A client holding two servers and no iss cannot detect a mix-up
	// attack.
	AuthorizationResponseIssParameterSupported bool `json:"authorization_response_iss_parameter_supported"`
}

AuthorizationServerMetadata is the RFC 8414 discovery document.

The field set is what this server actually implements, not the whole registry. A document advertising something the endpoints do not do is worse than a shorter one: a client believes it, and the failure surfaces at the token endpoint as an error the client's author has no reason to expect. The map-backed examples advertise client_secret_post from an endpoint that reads no secret, which is exactly this failure with the sign flipped.

RegistrationEndpoint is the one field here that can be absent rather than merely empty, and it is spelled omitempty for a reason an empty string cannot carry: a server built with WithDynamicRegistration(false) does not serve /register, and a client that resolved "" against the issuer would get this server's root rather than learning the endpoint is not there.

type Client ¶

type Client struct {
	// CreatedAt is when the registration was accepted.
	CreatedAt time.Time

	// ExpiresAt is when the registration lapses, or the zero time for a
	// registration that does not.
	//
	// Dynamic registration is open by construction — RFC 7591 requires it for
	// the discovery flow to work at all — so the table it writes to has an
	// anonymous writer. An expiry is what keeps that table bounded without
	// requiring anybody to decide which rows are garbage: a client that is
	// still in use re-registers, and one that is not ages out.
	ExpiresAt time.Time

	// ID is the client_id. Minted by the server from crypto/rand.
	ID string

	// SecretHash is the SHA-256 digest of the client secret, hex-encoded, or
	// empty for a public client.
	//
	// SHA-256 rather than argon2, and that is not a shortcut. A client secret
	// is 256 bits minted by this server, so there is no dictionary to attack
	// and nothing a work factor would buy; what it would cost is an argon2
	// verification on every single token request. Passwords are the opposite
	// case and go through authentication/argon2.
	SecretHash string

	// Name is the client_name from the registration request, shown on the
	// consent form. Cosmetic, and attacker-supplied — render it, never trust
	// it.
	Name string

	// TokenEndpointAuthMethod is how this client authenticates at /token: one
	// of AuthMethodNone, AuthMethodClientSecret, AuthMethodClientBasic.
	TokenEndpointAuthMethod string

	// RedirectURIs are the exact URIs this client may receive an authorization
	// code at. Matched exactly, byte for byte, as OAuth 2.1 requires: no
	// prefix matching, no wildcard, no ignored query string.
	RedirectURIs []string

	// GrantTypes and ResponseTypes are what the registration asked for,
	// narrowed to what this server implements.
	GrantTypes    []string
	ResponseTypes []string

	// Scopes are the scopes this client may request. An authorization request
	// for anything outside it is rejected rather than silently narrowed —
	// silently narrowing hands back a token that looks like the one that was
	// asked for and is not.
	Scopes []string
}

Client is a registered OAuth client.

Every field except Name and SecretHash is load-bearing at request time. RedirectURIs in particular: it is the field the map-backed examples store and never read again, and reading it is the check that decides whether an authorization code may be sent somewhere the client did not nominate.

func (c *Client) Clone() *Client

func (c *Client) Public() bool

type LoginError ¶

type LoginError struct {

	// Message is shown to the human. Write it for them.
	Message string
	// contains filtered or unexported fields
}

LoginError is how a SubjectAuthenticator names the message the login form shows.

It exists because the alternative — rendering the error's own text — makes every authenticator's internal error message a string in a browser, and the author of that message had no reason to think it would be. A *LoginError's Message is the only string from an authenticator that reaches a page.

It wraps ErrLoginFailed, so an authenticator returning one gets the re-render behavior without also having to say so:

return nil, oauth2server.NewLoginError("That code has expired.", err)

func NewLoginError(message string, cause error) *LoginError

func (e *LoginError) Error() string

func (e *LoginError) Unwrap() []error

type LoginRenderer ¶

type LoginRenderer interface {
	RenderLogin(ctx context.Context, res http.ResponseWriter, view LoginView)
}

LoginRenderer draws the form the resource owner authenticates at.

A default is shipped — DefaultLoginRenderer — because a package that made every consumer write one would be shipping seven-eighths of an authorization server. It is deliberately plain: an application that cares how its login page looks replaces this, and one that does not gets a page that works without a stylesheet.

A renderer owns the whole response, status included, which is the one place this package hands that over. It has to: a renderer that wanted to answer 429 on a rate-limited login could not say so otherwise.

var DefaultLoginRenderer LoginRenderer = LoginRendererFunc(renderDefaultLogin)

type LoginRendererFunc ¶

type LoginRendererFunc func(ctx context.Context, res http.ResponseWriter, view LoginView)

LoginRendererFunc adapts a function to LoginRenderer.

func (f LoginRendererFunc) RenderLogin(ctx context.Context, res http.ResponseWriter, view LoginView)

type LoginView ¶

type LoginView struct {
	// Action is where the form posts: the /authorize URL with the original
	// query string intact. The authorization parameters travel in the query
	// rather than in hidden form fields so that the POST is validated against
	// exactly the same request the GET was.
	Action string

	// Error is the message to show, or empty on the first render.
	Error string

	// ClientName is the registered client_name, or the client_id if the
	// registration named none.
	ClientName string

	// Scopes are what the client asked for, so the human can see what they are
	// approving.
	Scopes []string
}

LoginView is what the login form is rendered from.

ClientName is attacker-supplied — it is whatever the registration request said, and registration is open — so a renderer must escape it. The shipped renderer uses html/template, which does that by construction; a renderer that builds HTML by concatenation is choosing to be an XSS.

type Option ¶

type Option func(*serverOptions)

Option configures a Server at construction.

func WithAccessTokenTTL(ttl time.Duration) Option

func WithAuthorizationCodeTTL(ttl time.Duration) Option

func WithClientRegistrationTTL(ttl time.Duration) Option

func WithClock(c clock.Clock) Option

func WithDynamicRegistration(serve bool) Option

func WithLogger(logger logging.Logger) Option

func WithLoginRenderer(renderer LoginRenderer) Option

func WithMetricsProvider(metricsProvider metrics.Provider) Option

func WithRefreshReuseDetection(detect bool) Option

func WithRefreshTokenTTL(ttl time.Duration) Option

func WithRegistrationLimiter(gate routing.Middleware) Option

limiter, err := ratelimiting.NewInMemoryRateLimiter(1, 5)
gate, err := ratelimitinghttp.NewMiddleware(limiter, ratelimitinghttp.KeyByRemoteAddr())
server, err := oauth2server.NewServer(issuer, store, authenticator,
	oauth2server.WithRegistrationLimiter(gate))

package main

import (
	"context"
	"fmt"
	"net/http"
	"net/http/httptest"
	"strings"

	"github.com/primandproper/platform-go/v13/authentication/oauth2server"
	"github.com/primandproper/platform-go/v13/authentication/oauth2server/memory"
	"github.com/primandproper/platform-go/v13/ratelimiting"

	ratelimitinghttp "github.com/primandproper/platform-go/v13/ratelimiting/http"
)

func main() {
	// One registration per second, and no burst beyond it. A real deployment
	// picks these from its own traffic; what it cannot delegate is the next
	// line.
	limiter, err := ratelimiting.NewInMemoryRateLimiter(1, 1)
	if err != nil {
		panic(err)
	}
	defer func() { _ = limiter.Close() }()

	// The address the connection came from, which is right for a server facing
	// clients directly and wrong behind a proxy — there, KeyByForwardedFor with
	// the number of proxies actually in front. That is the fact this package
	// cannot know and the deployment cannot avoid knowing.
	gate, err := ratelimitinghttp.NewMiddleware(limiter, ratelimitinghttp.KeyByRemoteAddr())
	if err != nil {
		panic(err)
	}

	authenticator := oauth2server.SubjectAuthenticatorFunc(
		func(_ context.Context, _ *http.Request) (*oauth2server.Subject, error) {
			return &oauth2server.Subject{ID: "user_1"}, nil
		})

	srv, err := oauth2server.NewServer("https://auth.example", memory.NewStore(), authenticator,
		oauth2server.WithRegistrationLimiter(gate))
	if err != nil {
		panic(err)
	}

	// The gate is inside RegisterHandler, so Handler, Mount, and a deployment
	// routing POST /register by hand are all behind it.
	front := httptest.NewServer(srv.Handler())
	defer front.Close()

	register := func() int {
		body := strings.NewReader(`{"redirect_uris":["https://client.example/callback"]}`)

		req, reqErr := http.NewRequestWithContext(context.Background(),
			http.MethodPost, front.URL+oauth2server.PathRegister, body)
		if reqErr != nil {
			panic(reqErr)
		}
		req.Header.Set("Content-Type", "application/json")

		res, doErr := front.Client().Do(req)
		if doErr != nil {
			panic(doErr)
		}
		defer func() { _ = res.Body.Close() }()

		return res.StatusCode
	}

	fmt.Println(register())
	fmt.Println(register())

}

Output:
201
429

func WithRegistrationPolicy(policy RegistrationPolicy) Option

func WithResources(resources ...string) Option

func WithRevocationObserver(observer RevocationObserver) Option

func WithScopes(scopes ...string) Option

func WithServiceDocumentation(url string) Option

func WithSubjectResolver(resolver SubjectResolver) Option

package main

import (
	"context"
	"fmt"
	"net/http"
	"net/http/httptest"
	"net/url"

	"github.com/primandproper/platform-go/v13/authentication/oauth2server"
	"github.com/primandproper/platform-go/v13/authentication/oauth2server/memory"
)

func main() {
	// The seam for clients that hold proof rather than a keyboard: a
	// first-party application with a session cookie, a CLI with a token, a
	// service exchanging one credential for another. Returning (nil, nil) means
	// "not one of mine", and the login form is rendered as usual.
	resolver := oauth2server.SubjectResolverFunc(
		func(_ context.Context, req *http.Request) (*oauth2server.Subject, error) {
			// A request with no session cookie is not this resolver's, which
			// is (nil, nil) rather than an error: the form is still the right
			// answer for whoever sent it.
			session, _ := req.Cookie("session")
			if session == nil {
				return nil, nil
			}

			return &oauth2server.Subject{ID: "user_" + session.Value}, nil
		})

	store := memory.NewStore()

	srv, err := oauth2server.NewServer("https://auth.example", store,
		oauth2server.SubjectAuthenticatorFunc(
			func(context.Context, *http.Request) (*oauth2server.Subject, error) {
				return nil, oauth2server.NewLoginError("Sign in to continue.", nil)
			}),
		oauth2server.WithSubjectResolver(resolver))
	if err != nil {
		panic(err)
	}

	ctx := context.Background()

	if err = store.CreateClient(ctx, &oauth2server.Client{
		ID:           "client_1",
		RedirectURIs: []string{"https://app.example/callback"},
	}); err != nil {
		panic(err)
	}

	query := url.Values{
		"response_type":         {oauth2server.ResponseTypeCode},
		"client_id":             {"client_1"},
		"redirect_uri":          {"https://app.example/callback"},
		"code_challenge":        {oauth2server.S256Challenge("0123456789012345678901234567890123456789abc")},
		"code_challenge_method": {oauth2server.CodeChallengeMethodS256},
	}

	// A GET, with no body to POST and nothing to type.
	req := httptest.NewRequestWithContext(context.Background(), http.MethodGet, oauth2server.PathAuthorize+"?"+query.Encode(), http.NoBody)
	req.AddCookie(&http.Cookie{Name: "session", Value: "1"})

	res := httptest.NewRecorder()
	srv.Handler().ServeHTTP(res, req)

	location, err := url.Parse(res.Header().Get("Location"))
	if err != nil {
		panic(err)
	}

	fmt.Println(res.Code)
	fmt.Println(location.Query().Has("code"))

}

Output:
302
true

func WithTracerProvider(tracerProvider tracing.Provider) Option

type ProtectedResourceMetadata ¶

type ProtectedResourceMetadata struct {
	Resource               string   `json:"resource"`
	ResourceName           string   `json:"resource_name,omitempty"`
	ResourceDocumentation  string   `json:"resource_documentation,omitempty"`
	AuthorizationServers   []string `json:"authorization_servers"`
	ScopesSupported        []string `json:"scopes_supported,omitempty"`
	BearerMethodsSupported []string `json:"bearer_methods_supported"`
}

ProtectedResourceMetadata is the RFC 9728 document a resource server publishes so that a client which discovered the resource at runtime can find the authorization server behind it.

It is emitted by the resource server rather than by this one, and the two are not necessarily the same process — which is why it is a separate mountable thing rather than a sixth route on the Server.

type RefreshToken ¶

type RefreshToken struct {
	IssuedAt  time.Time
	ExpiresAt time.Time

	// RedeemedAt is when this token was exchanged, or the zero time. One-time
	// use: a second exchange is a replay.
	RedeemedAt time.Time

	// RevokedAt is when this token was revoked, whether individually through
	// /revoke or as part of its family.
	RevokedAt time.Time

	Hash     string
	ClientID string
	FamilyID string

	Subject Subject

	Scopes    []string
	Audience  []string
	Resources []string
}

RefreshToken is one issued refresh token.

FamilyID is what makes rotation worth doing. Every refresh minted from a given authorization code carries the same family identifier, so when a redeemed token is presented a second time the server knows exactly which tokens to revoke: all of them. Rotation without that detects nothing — the replay is refused and the copy the attacker is actually using keeps working.

func (t *RefreshToken) Clone() *RefreshToken

type RegistrationPolicy ¶

type RegistrationPolicy interface {
	// AllowRegistration vets a request. An error wrapping
	// ErrRegistrationRejected renders as a 400 with invalid_client_metadata
	// and the error's message; anything else is a 500.
	AllowRegistration(ctx context.Context, req *RegistrationRequest) error
}

RegistrationPolicy decides whether a registration is accepted.

The default — DefaultRegistrationPolicy — enforces what the protocol cannot be safe without: at least one redirect URI, every one of them absolute, https or loopback, and free of a fragment. Replace it to add whatever else a deployment needs: an allowlist of hosts, a cap tied to a tenant, a check against an out-of-band approval.

What it is not is a rate limiter. A policy is handed the parsed metadata and not the request, so it cannot see a caller at all — and identifying one depends on how a deployment is fronted anyway: source address, a proxy header, an API gateway's own token. WithRegistrationLimiter is where that answer goes, and ratelimiting/http builds the gate it takes.

var DefaultRegistrationPolicy RegistrationPolicy = RegistrationPolicyFunc(defaultRegistrationPolicy)

type RegistrationPolicyFunc ¶

type RegistrationPolicyFunc func(ctx context.Context, req *RegistrationRequest) error

RegistrationPolicyFunc adapts a function to RegistrationPolicy.

func (f RegistrationPolicyFunc) AllowRegistration(ctx context.Context, req *RegistrationRequest) error

type RegistrationRequest ¶

type RegistrationRequest struct {
	ClientName              string   `json:"client_name,omitempty"`
	TokenEndpointAuthMethod string   `json:"token_endpoint_auth_method,omitempty"`
	Scope                   string   `json:"scope,omitempty"`
	RedirectURIs            []string `json:"redirect_uris"`
	GrantTypes              []string `json:"grant_types,omitempty"`
	ResponseTypes           []string `json:"response_types,omitempty"`
}

RegistrationRequest is an RFC 7591 dynamic client registration request, as received.

Every field is attacker-supplied. /register is unauthenticated because RFC 7591 requires it to be for the discovery flow to work at all, which makes vetting this the authorization server's problem rather than an optional extra.

type RegistrationResponse ¶

type RegistrationResponse struct {
	ClientID     string `json:"client_id"`
	ClientSecret string `json:"client_secret,omitempty"`
	ClientName   string `json:"client_name,omitempty"`

	Scope                   string `json:"scope,omitempty"`
	TokenEndpointAuthMethod string `json:"token_endpoint_auth_method"`

	RedirectURIs  []string `json:"redirect_uris"`
	GrantTypes    []string `json:"grant_types"`
	ResponseTypes []string `json:"response_types"`

	// ClientIDIssuedAt and ClientSecretExpiresAt are seconds since the epoch,
	// as RFC 7591 specifies. Zero for ClientSecretExpiresAt means the secret
	// does not expire.
	ClientIDIssuedAt      int64 `json:"client_id_issued_at"`
	ClientSecretExpiresAt int64 `json:"client_secret_expires_at"`
}

RegistrationResponse is the RFC 7591 §3.2.1 client information response.

ClientSecret appears exactly once in the lifetime of a registration: here. The store holds a digest, so this response is the only time the value exists outside the client — which is why the endpoint answers 201 with it rather than answering 201 and offering a way to read it back.

type ResourceMetadata ¶

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

ResourceMetadata publishes the RFC 9728 protected resource metadata document.

It is a separate type from Server, and separately mountable, because the resource server and the authorization server are not necessarily the same process — usually they are not. A resource server publishes this to say "the tokens I accept come from over there"; the authorization server publishes its own document at PathAuthorizationServerMetadata to say what it can do.

A client that discovered the resource at runtime reads this first, follows authorization_servers to the other document, registers, and only then has a client_id. That chain is the reason any of this exists.

func NewResourceMetadata(resource string, authorizationServers []string, opts ...ResourceOption) (*ResourceMetadata, error)

package main

import (
	"fmt"

	"github.com/primandproper/platform-go/v13/authentication/oauth2server"
)

func main() {
	meta, err := oauth2server.NewResourceMetadata(
		"https://api.example/",
		[]string{"https://auth.example"},
		oauth2server.WithResourceName("Recipes API"),
		oauth2server.WithResourceScopes("recipes:read"))
	if err != nil {
		panic(err)
	}

	// Sent with every 401, so a client that was never configured with this
	// server is told where to look rather than simply refused.
	fmt.Println(meta.Challenge("invalid_token", "the token expired"))

}

Output:
Bearer resource_metadata="https://api.example/.well-known/oauth-protected-resource", error="invalid_token", error_description="the token expired"

func (m *ResourceMetadata) Challenge(errorCode, description string) string

func (m *ResourceMetadata) Document() ProtectedResourceMetadata

func (m *ResourceMetadata) Handler() http.Handler

func (m *ResourceMetadata) Mount(r *routing.Router, middleware ...routing.Middleware)

func (m *ResourceMetadata) ScopeChallenge(description string, scopes []string) string

type ResourceOption ¶

type ResourceOption func(*ProtectedResourceMetadata)

ResourceOption configures a ResourceMetadata.

func WithResourceDocumentation(url string) ResourceOption

func WithResourceName(name string) ResourceOption

func WithResourceScopes(scopes ...string) ResourceOption

type RevocationObserver ¶

type RevocationObserver func(ctx context.Context, subject Subject, familyID string)

RevocationObserver is told what a /revoke request actually revoked.

It is a function rather than an interface because there is nothing for a deployment to implement here: this is a notification, and the only thing an interface would add is a type to declare somewhere.

When it is called ¶

After a revocation that removed something, with the subject the record belonged to and the family it was part of. Never for a token that was already gone, never for a token belonging to another client, and never when the store refused the write — RFC 7009 §2.2 requires the same empty 200 in all of those cases, and this is the difference the response cannot carry.

Revoking a refresh token takes its whole family, so this is called once for the family rather than once per record. Revoking an access token names the family it belonged to, which is still live: an access token revocation is not a sign-out, and a consumer that treats it as one will emit an event for a session that is still going.

What does not reach it is a revocation this server decided on: the family killed by refresh token reuse detection, or by a refresh token presented by the wrong client. Those are not sign-outs — reporting them through the same callback would have a deployment logging "user signed out" for a theft — and they are already visible as oauth2server_refresh_reuse_detected and a recorded operation.

What it must not do ¶

Block. It runs inline, on the request goroutine, before the 200 is written, so a slow observer is a slow sign-out; a deployment publishing a message should hand it to whatever it already has for that rather than waiting on a broker from in here. The context is the request's, so it is cancelled the moment the client hangs up.

A panic is recovered and recorded rather than allowed to take down the request: the records are already gone by the time this runs, and a failing analytics callback must not turn a sign-out that succeeded into a 500 the client retries.

type Server ¶

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

Server is an OAuth 2.1 authorization server: the five endpoints, the grant logic behind them, and nothing about who the resource owner is.

It is a concrete type rather than an interface because there is one implementation of the protocol and there is not going to be a second. What swaps is underneath it — the Store — and beside it, in the seams a deployment owns: SubjectAuthenticator, the optional SubjectResolver, and LoginRenderer.

func NewServer(issuer string, store Store, authenticator SubjectAuthenticator, opts ...Option) (*Server, error)

package main

import (
	"context"
	"fmt"
	"net/http"

	"github.com/primandproper/platform-go/v13/authentication/oauth2server"
	"github.com/primandproper/platform-go/v13/authentication/oauth2server/memory"
)

func main() {
	// Whatever this application actually does to identify a human — a password
	// and a TOTP code against its own identity repository, an existing session
	// cookie, a corporate identity provider. There is no default, because a
	// default would be a server that issues authorization codes to whoever
	// asks.
	authenticator := oauth2server.SubjectAuthenticatorFunc(
		func(_ context.Context, req *http.Request) (*oauth2server.Subject, error) {
			username := req.PostFormValue(oauth2server.FieldUsername)
			if username == "" {
				return nil, oauth2server.NewLoginError("Enter your username.", nil)
			}

			return &oauth2server.Subject{
				ID: "user_" + username,
				// The application-shaped half of the identity. This package
				// carries it into every token and never reads it.
				Claims: map[string]string{"account_id": "acct_9"},
			}, nil
		})

	// memory for this example; a deployment wants oauth2server/database, or two
	// replicas cannot complete each other's logins.
	srv, err := oauth2server.NewServer("https://auth.example", memory.NewStore(), authenticator,
		oauth2server.WithScopes("recipes:read", "recipes:write"),
		oauth2server.WithResources("https://api.example/"))
	if err != nil {
		panic(err)
	}

	// srv.Mount(router) registers all six endpoints; srv.Handler() is the same
	// set as one http.Handler.
	doc := srv.Metadata()

	fmt.Println(doc.TokenEndpoint)
	fmt.Println(doc.CodeChallengeMethodsSupported)
	fmt.Println(doc.GrantTypesSupported)

}

Output:
https://auth.example/token
[S256]
[authorization_code refresh_token]

func (s *Server) Authenticate(ctx context.Context, bearer string) (*AccessToken, error)

func (s *Server) AuthorizeHandler() http.Handler

func (s *Server) Handler() http.Handler

func (s *Server) Issuer() string

func (s *Server) Metadata() AuthorizationServerMetadata

func (s *Server) MetadataHandler() http.Handler

func (s *Server) Mount(r *routing.Router, middleware ...routing.Middleware)

func (s *Server) RegisterHandler() http.Handler

func (s *Server) RevokeHandler() http.Handler

func (s *Server) TokenHandler() http.Handler

type Store ¶

type Store interface {
	// CreateClient records a registration. An identifier already in use is
	// ErrClientExists rather than an overwrite: registrations are created by
	// anonymous callers, and a silent overwrite would let one of them take over
	// another's client by guessing an identifier.
	CreateClient(ctx context.Context, client *Client) error

	// GetClient reads a registration. A registration past its ExpiresAt is
	// ErrExpired, not a value the caller has to check.
	GetClient(ctx context.Context, clientID string) (*Client, error)

	// DeleteClient removes a registration. A registration that was already
	// gone is not an error — the caller wanted it gone.
	DeleteClient(ctx context.Context, clientID string) error

	// CreateAuthorizationCode records an issued code.
	CreateAuthorizationCode(ctx context.Context, code *AuthorizationCode) error

	// ConsumeAuthorizationCode marks the code redeemed and returns it, in one
	// atomic operation.
	//
	// A code that was already redeemed returns the record *and*
	// ErrAlreadyRedeemed. The record is not a courtesy: RFC 6749 §4.1.2 says a
	// replayed code should revoke what it previously issued, and the caller
	// cannot find those tokens without knowing which family the code belongs
	// to. AuthorizationCode.FamilyID is that field, which is why it is on the
	// code rather than only on the tokens — an implementation that drops it
	// leaves the replay detectable and unanswerable.
	ConsumeAuthorizationCode(ctx context.Context, hash string) (*AuthorizationCode, error)

	// CreateAccessToken records an issued access token.
	CreateAccessToken(ctx context.Context, token *AccessToken) error

	// GetAccessToken reads an access token. Expired or revoked is ErrExpired —
	// a resource server asking about a token it holds wants a straight answer,
	// and "expired" and "revoked" are the same answer to it.
	GetAccessToken(ctx context.Context, hash string) (*AccessToken, error)

	// RevokeAccessToken marks one access token revoked. A token that is absent
	// or already revoked is not an error: RFC 7009 §2.2 requires the
	// revocation endpoint to answer 200 either way, and a store that
	// distinguished them would be inviting the endpoint to leak which tokens
	// exist.
	RevokeAccessToken(ctx context.Context, hash string) error

	// CreateRefreshToken records an issued refresh token.
	CreateRefreshToken(ctx context.Context, token *RefreshToken) error

	// ConsumeRefreshToken marks the token redeemed and returns it, in one
	// atomic operation. As with ConsumeAuthorizationCode, a replay returns the
	// record alongside ErrAlreadyRedeemed so that the family can be revoked.
	ConsumeRefreshToken(ctx context.Context, hash string) (*RefreshToken, error)

	// GetRefreshToken reads a refresh token without consuming it.
	//
	// It exists for /revoke, which needs the record to learn whose token this
	// is and which family to end — and must not spend the token to find out.
	// An already-redeemed token is still returned: a sign-out arriving after a
	// rotation is the ordinary case, and the family it names is exactly what
	// needs revoking. Expired or revoked is ErrExpired.
	GetRefreshToken(ctx context.Context, hash string) (*RefreshToken, error)

	// RevokeRefreshToken marks one refresh token revoked, without touching the
	// rest of its family. This is what /revoke does; RevokeFamily is what a
	// detected replay does.
	RevokeRefreshToken(ctx context.Context, hash string) error

	// RevokeFamily revokes every access and refresh token in a family and
	// reports how many records it touched.
	//
	// The count is for the caller's metric, not its control flow — a family
	// whose tokens have all expired legitimately revokes nothing.
	RevokeFamily(ctx context.Context, familyID string) (int64, error)

	// Sweep removes records whose deadlines have passed as of now, reporting
	// how many it removed.
	//
	// It is a garbage collector, not a security control: every read above
	// already refuses an expired record, so a row this has not reached yet is
	// unusable. What it stops is the table growing with every code ever
	// issued, which under dynamic registration is a table an anonymous caller
	// can add to.
	Sweep(ctx context.Context, now time.Time) (int64, error)

	// Close releases whatever the implementation holds.
	Close() error
}

Store is where an authorization server's four kinds of state live: registered clients, authorization codes, access tokens, and refresh tokens.

It is one interface rather than four because three of the four operations that matter span two of them. Redeeming a code mints a token pair; detecting a replayed refresh token revokes a family that includes access tokens; revoking a registration has to reach whatever it issued. Four interfaces would leave a caller holding four handles that have to be to the same database for any of that to be atomic, and nothing would say so.

Why the consuming methods are shaped the way they are ¶

ConsumeAuthorizationCode and ConsumeRefreshToken are not "read, then mark". A caller cannot write that pair correctly against a shared table: two requests carrying the same code both read it unredeemed, both mint a token pair, and the credential that was supposed to be single-use was used twice. The check and the mark are therefore one method, and an implementation owes its callers that they happen atomically — one statement, one transaction, one lock, whatever the backend makes available.

Expiry is inside the same operation for the same reason, and it is the case a map-backed store gets for free and a table does not. A store that checks `expires_at > now` in Go, between the read and the write, has a window in which a code expires and is redeemed anyway. The guard belongs in the predicate.

What is stored ¶

Digests, never credentials. Every method here takes and returns a hash — see Hash — and no implementation ever sees the value the client holds. That is invisible in a map that dies with the process and is the difference between a leaked database backup and a leaked database backup that authorizes people.

Conformance ¶

authentication/oauth2server/oauth2servertest holds the behavior every implementation owes, written once. Run it against any Store, including one a consumer writes.

type Subject ¶

type Subject struct {
	// Claims is the application-shaped part of a token's identity. Nil is
	// fine; an empty map and a nil map mean the same thing.
	Claims map[string]string

	// ID is the "sub" claim. Required — a token with no subject authorizes
	// nobody, and the store rejects it.
	ID string
}

Subject is who a token is for, and is the seam where this package stops deciding.

ID is the "sub": whatever the application calls a user, stable for as long as the tokens minted for it. Claims is everything else the resource server needs to act on the token — dinnerdonebetter's account identifier, a tenant, a role — and this package neither reads it nor constrains it beyond requiring it to be strings.

Strings rather than `any`, deliberately. What goes in here comes back out of a token introspection or a JWT claim set, both of which are string-keyed JSON, and a map[string]any would let an application store something that round-trips through the database store as a different Go type than it went in as. Anything richer belongs behind the identifier in ID.

func (s Subject) Clone() Subject

type SubjectAuthenticator ¶

type SubjectAuthenticator interface {
	AuthenticateSubject(ctx context.Context, req *http.Request) (*Subject, error)
}

SubjectAuthenticator identifies the human behind an authorization request.

This is one of the places this package deliberately stops. Everything else here is protocol — the same protocol for every deployment — and this is the application: dinnerdonebetter's is a username, an argon2 password, and a TOTP code checked against its own identity repository; another consumer's is a corporate identity provider.

It is asked only when nothing else has already answered: it means the human typed something. A resource owner who is already authenticated by other means — a session cookie, a token a first-party client holds — is SubjectResolver's, which is consulted first and needs no form at all.

What it is handed and what it owes back ¶

It receives the parsed /authorize request, form values included, so it can read whatever fields its own login form posts. It returns either the Subject the tokens will be minted for, or an error.

An error wrapping ErrLoginFailed re-renders the login form with a message, which is the answer to a wrong password: the human is still here and can try again. Any other error fails the request, which is the answer to a broken identity store — retrying a form against a database that is down produces a user who tries four times and then files a support ticket.

Returning (nil, nil) is treated as ErrLoginFailed. A Subject with an empty ID is rejected outright: a token whose subject is the empty string authorizes whoever the resource server decides the empty string is.

What it must not do ¶

Write to the ResponseWriter — it does not have one, deliberately. An authenticator that could render its own response could redirect somewhere this package never validated, which is the redirect it exists to prevent.

type SubjectAuthenticatorFunc ¶

type SubjectAuthenticatorFunc func(ctx context.Context, req *http.Request) (*Subject, error)

SubjectAuthenticatorFunc adapts a function to SubjectAuthenticator.

func (f SubjectAuthenticatorFunc) AuthenticateSubject(ctx context.Context, req *http.Request) (*Subject, error)

type SubjectResolver ¶

type SubjectResolver interface {
	ResolveSubject(ctx context.Context, req *http.Request) (*Subject, error)
}

SubjectResolver reports the resource owner when the request already carries proof of who they are.

It is the seam for the case a login form cannot serve: a first-party application holding a session cookie, a CLI holding a token, a service exchanging one credential for another. None of those has anything to type, and without this seam the only way to reach a subject is to POST a form — which is a strange thing to ask of a client whose parameters are all in the query string, and true only because that is where the seam used to be.

It is consulted on GET and on POST alike, before the login form is rendered and before SubjectAuthenticator is asked anything. A request carrying proof therefore never meets a form, and one carrying none behaves exactly as it did before — the seam is optional, and a Server built without one is unchanged.

What it owes back ¶

(nil, nil) means "not one of mine": no credential, an expired one, one this resolver does not recognize. The request carries on to the form, which is the honest answer to "I cannot say who this is" and the reason an expired session cookie still sends a browser to sign in again.

A Subject with a non-empty ID issues an authorization code and redirects, exactly as a successful form login would. An empty ID is refused: a token whose subject is the empty string authorizes whoever the resource server decides the empty string is.

An error ends the attempt at the client's registered redirect URI, with no form rendered. That is the difference between the two seams, and it is deliberate: a caller who presented a credential and had it rejected has nothing to type, so sending it a login page would be sending an answer it cannot use. Reserve the error for a resolver that is actually broken, or for a credential this deployment means to refuse outright — an absent or lapsed one is (nil, nil).

What it must not do ¶

Write to the ResponseWriter, for the same reason SubjectAuthenticator must not: it does not have one, and a seam that could render its own response could redirect somewhere this package never validated.

type SubjectResolverFunc ¶

type SubjectResolverFunc func(ctx context.Context, req *http.Request) (*Subject, error)

SubjectResolverFunc adapts a function to SubjectResolver.

func (f SubjectResolverFunc) ResolveSubject(ctx context.Context, req *http.Request) (*Subject, error)

type TokenAuthenticator ¶

type TokenAuthenticator interface {
	Authenticate(ctx context.Context, bearer string) (*AccessToken, error)
}

TokenAuthenticator resolves a bearer credential to the access token record behind it, and is the seam a Verifier stands on.

*Server implements it, and in the ordinary deployment — resource server and authorization server in one process, which is what opaque tokens require — that is what a Verifier is handed. It is an interface rather than a *Server so that a resource server holding only the Store, or a test wanting a controlled answer, has something to pass; it is deliberately the narrowest possible one, because a Verifier needs to look a token up and nothing else.

type TokenResponse ¶

type TokenResponse struct {
	AccessToken  string `json:"access_token"`
	TokenType    string `json:"token_type"`
	RefreshToken string `json:"refresh_token,omitempty"`
	Scope        string `json:"scope,omitempty"`
	ExpiresIn    int64  `json:"expires_in"`
}

TokenResponse is the RFC 6749 §5.1 successful token response.

type Verifier ¶

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

Verifier is the resource server's half of this package: the checks a request carrying a bearer token has to survive before a handler sees it.

The authorization server mints tokens; a Verifier decides whether the one in front of it authorizes this request, at this resource. Three checks, and the package would be incomplete without all three:

• the token is live. Delegated to TokenAuthenticator, which reads it from the Store — the lookup that opaque tokens are for, and the reason a revoked session stops working now rather than in fifteen minutes.
• the token names this resource. RFC 8707 puts the resource identifier in the token's audience so a token minted for one resource server cannot be replayed at another; a resource server that does not compare it has the field and not the property.
• the token carries the scopes the route requires.

The second is the one that gets left out, and it is the one this type exists for. Server.Authenticate hands back a live token whoever it was minted for, because it is the authorization server's lookup and the authorization server serves every resource behind it. A deployment running two resource servers against one authorization server — an HTTP API and an MCP endpoint, which is the shape that keeps arriving — has a cross-resource replay the moment one of them treats "Authenticate returned a token" as "this request is authorized".

It is not specific to any protocol built on top of it. An MCP server is an http.Handler and mounts behind Middleware; so does a REST API, and a resource server with its own response envelope calls Verify and writes its own.

func NewVerifier(metadata *ResourceMetadata, tokens TokenAuthenticator, opts ...VerifierOption) (*Verifier, error)

package main

import (
	"context"
	"fmt"
	"net/http"
	"net/http/httptest"

	"github.com/primandproper/platform-go/v13/authentication/oauth2server"
	"github.com/primandproper/platform-go/v13/authentication/oauth2server/memory"
)

func main() {
	// The authorization server, in this process, so a revoked token stops
	// working now rather than in fifteen minutes.
	srv, err := oauth2server.NewServer("https://auth.example", memory.NewStore(),
		oauth2server.SubjectAuthenticatorFunc(
			func(context.Context, *http.Request) (*oauth2server.Subject, error) {
				return &oauth2server.Subject{ID: "user_1"}, nil
			}),
		oauth2server.WithScopes("recipes:read", "recipes:write"),
		// The same string the resource names itself by, below. Two spellings of
		// one identifier, and a token's audience is compared against it.
		oauth2server.WithResources("https://api.example/"))
	if err != nil {
		panic(err)
	}

	// What this resource server is, and where its tokens come from. A client
	// that has never heard of either reads this document and finds out.
	meta, err := oauth2server.NewResourceMetadata("https://api.example/",
		[]string{srv.Issuer()},
		oauth2server.WithResourceName("Recipes MCP"),
		oauth2server.WithResourceScopes("recipes:read", "recipes:write"))
	if err != nil {
		panic(err)
	}

	guard, err := oauth2server.NewVerifier(meta, srv)
	if err != nil {
		panic(err)
	}

	// Whatever the MCP SDK assembled from twenty-five tool registrations. It is
	// an http.Handler, so this is the whole of the mount.
	mcpHandler := http.HandlerFunc(func(res http.ResponseWriter, req *http.Request) {
		// A tool that writes where the others read asks for itself, against the
		// token the guard already looked up.
		token, _ := oauth2server.TokenFromContext(req.Context())
		if !token.HasScopes("recipes:write") {
			res.WriteHeader(http.StatusForbidden)

			return
		}

		res.WriteHeader(http.StatusOK)
	})

	// srv.Mount(router) puts the six OAuth endpoints on; meta.Mount(router)
	// publishes the document; this is the resource itself.
	protected := guard.Middleware("recipes:read")(mcpHandler)

	// A client that was never configured with this server gets told where to
	// look rather than simply refused.
	res := httptest.NewRecorder()
	req := httptest.NewRequestWithContext(context.Background(), http.MethodPost, "/mcp", http.NoBody)
	protected.ServeHTTP(res, req)

	fmt.Println(res.Code)
	fmt.Println(res.Header().Get("WWW-Authenticate"))

}

Output:
401
Bearer resource_metadata="https://api.example/.well-known/oauth-protected-resource"

func (v *Verifier) Metadata() *ResourceMetadata

func (v *Verifier) Middleware(requiredScopes ...string) routing.Middleware

func (v *Verifier) Verify(ctx context.Context, bearer string, requiredScopes ...string) (*AccessToken, error)

func (v *Verifier) WriteChallenge(res http.ResponseWriter, err error)

type VerifierOption ¶

type VerifierOption func(*verifierOptions)

VerifierOption configures a Verifier at construction.

A distinct type from Option, with distinct names, because this package already spends WithLogger and its siblings on Server. The alternative — one Option type covering both — would make NewVerifier accept WithLoginRenderer and silently do nothing with it. See ResourceOption, which is prefixed for the same reason.

func WithVerifierClock(c clock.Clock) VerifierOption

func WithVerifierLogger(logger logging.Logger) VerifierOption

func WithVerifierMetricsProvider(metricsProvider metrics.Provider) VerifierOption

func WithVerifierTracerProvider(tracerProvider tracing.Provider) VerifierOption