Proposal: authentication and authorization #870

Zaba505 · 2026-10-18T15:16:07Z

Zaba505
Oct 18, 2026
Maintainer

Note

Part of the humus re-evaluation; see Proposal: humus on the bedrock process model, wave 5, which revision 7 planned. It replaces REST security, which #485 deleted. It builds on wave 1 (the lifecycle, configuration, OpenTelemetry without globals and humustest), on HTTP server foundation and gRPC services, and on two wave-4 proposals: OpenAPI endpoint DSL, whose openapi.Security it adds, and outbound HTTP clients, with which auth/jwt fetches keys. It depends on no other wave-5 proposal: neither Proposal: failure injection nor Proposal: humus's own metrics.

Summary

A new package, auth, authenticates and authorizes the requests a humus service serves, over HTTP and gRPC alike:

A scheme is a typed value. auth.Bearer("bearer", verify) declares a way to authenticate a request, and verify turns the credential into the end user's own principal type, such as their User. A handler reads it back with bearer.From(ctx), typed, with no context key of the end user's. There is one constructor for each of OpenAPI's security scheme types: bearer, Basic, an API key in a header, query parameter or cookie, mutual TLS, OAuth2 and OpenID Connect. Every scheme verifies: there is no scheme that only documents.
A requirement is what a request must have. auth.Require(bearer), auth.RequireScopes(bearer, "carts:write") for a principal that has scopes, auth.All(a, b) for both, and auth.Anonymous() for optional authentication. A list of requirements is met by any one of them, as OpenAPI's security is.
Three places enforce them, one per way humus serves requests:
- openapi.Security(reqs...), an APIOption, for an OpenAPI API: given to NewAPI it is every operation's, given to an operation it replaces the API's, and the document lists the schemes and requirements;
- auth.NewHandler(s, h, answers, reqs...) for a plain http.Handler served by httpserver;
- grpcauth.Interceptors(s, rules...) for a grpcserver Service, per method.
401, 403 and the server's. A request no requirement authenticates is a 401, or Unauthenticated, with RFC 9110's WWW-Authenticate challenges. One authenticated without a scope it needs is a 403, or PermissionDenied. A verifier's error that doesn't wrap auth.ErrUnauthenticated, such as a directory outage, is the server's: never a 401. Every answer's body is the end user's.
An opt-in auth/jwt verifies JWT bearer tokens against an identity provider's JSON Web Key Set, which it fetches with the end user's httpclient. It is on go-jose v4, which grpc-go already brings into every humus module graph.

func Init(ctx context.Context, s *humus.Setup) ([]humus.Service, error) {
	idp, err := httpclient.NewClient(s, idpSettings) // for https://idp.example.com
	if err != nil {
		return nil, err
	}
	tokens, err := jwt.NewVerifier[Claims](s, jwtSettings, idp) // jwt.Settings, sourced with config.Struct
	if err != nil {
		return nil, err
	}
	bearer := auth.Bearer("bearer", tokens.Verify).Format("JWT")
	c := carts{store: store, bearer: bearer} // the handlers read bearer.From(ctx)

	api, err := openapi.NewAPI(s, info, unmatched,
		openapi.RequestErrors(problem.FromRequestError, jsoncodec.Problem), // answers 401 and 403 too
		openapi.CatchAll(http.StatusInternalServerError, internalError, jsoncodec.Problem),
		[]openapi.Operation{
			openapi.Get(cart, c.getCart, jsoncodec.Encoder),
			openapi.Delete(cart, c.deleteCart, openapi.EmptyEncoder,
				openapi.Security(auth.RequireScopes(bearer, "carts:write")),
			),
			openapi.Document(openapi.Root().Lit("openapi.json"), openapi.Security()), // public
		},
		openapi.Security(auth.RequireScopes(bearer, "carts:read")),
	)
	if err != nil {
		return nil, err
	}
	svc, err := httpserver.NewService(s, serverSettings, api)
	if err != nil {
		return nil, err
	}
	return []humus.Service{svc}, nil
}

// Claims are the end user's: whatever their identity provider puts in a token.
type Claims struct {
	Subject string `json:"sub"`
	Scope   string `json:"scope"` // space-separated, as RFC 9068 has it
}

func (c Claims) HasScope(s string) bool { return slices.Contains(strings.Fields(c.Scope), s) }

Background

REST security before the reset was mostly documentation. v0.15.0's rest attached a scheme to a parameter: rest.Header("Authorization", rest.Required(), rest.JWTAuth("jwt", verifier)) (rest/parameter.go), and the authentication page described five schemes. Only JWTAuth verified anything: it called a JWTVerifier, Verify(ctx, token) (context.Context, error), and answered a missing or malformed header with a 400 and the verifier's error with a 401. The rest added a security scheme to the document and left verification to each handler:
- APIKey documented the key, and the handler looked it up (L423);
- BasicAuth documented Basic as an apiKey scheme, and the handler decoded the header itself (L443);
- OAuth2 documented no flows (L569);
- OpenIDConnect ignored its name and always wrote openid-connect (L592);
- MutualTLS panicked: "swaggest/openapi3 does not support this" (L555).
A verifier put claims in the context with context.WithValue, under string keys in the docs' examples, and a role check was a hand-written transform.
The open issues asked for verification. story(rest): provide jwt validation out of the box #257 asked for JWT validation out of the box, with JWKS fetching behind an interface; story(rest): provide oidc validation out of the box #262 for OIDC validation; story(rest): add argument for api key transformer #277, story(rest): add required argument for basic auth transformer #278, story(rest): allow users to register specific oauth2 flows and transformers #280 and story(rest): implement openid transformer #281 for a verifying "transformer" on the API key, Basic, OAuth2 and OpenID Connect schemes. story(rest): add options for setting additional openapi values #283 asked for OpenAPI's optional fields, which openapi/v3 now has. The reset closed all of them, and the charter made them this proposal's background.
gRPC had no authentication. grpcserver's doc shows the end user's own interceptor, grpc.ChainUnaryInterceptor(authenticate) (grpc/grpcserver/doc.go#L20). Outbound gRPC clients left per-RPC credentials to the end user's opts, and outbound HTTP clients left credentials to service code.
What waves 3 and 4 hand on.
- httpserver and grpcserver serve TLS from Settings.TLS, so a client certificate is the end user's ClientAuth to ask for, and the verified chains reach every request.
- grpcserver chains the end user's interceptors inside its own: after otelgrpc has started the span, and inside panic recovery and the stream cancellation of shutdown.
- openapi/v3 makes every answer the end user's: RequestErrors for what it rejects, Error and a catch-all for the handler's errors. Its revision 1 named this proposal's part: "openapi.Security(…), an APIOption. Given to NewAPI, it is every operation's requirement. Given to an operation, it replaces the API's."
- Exposing health probes left this proposal to say "how a probe path is left open".
- httpclient dials through the Host, with retries and a breaker, and is what fetches an identity provider's keys.
go-jose is already in the module graph. grpc-go v1.84.0, which the core module requires for the OTLP exporters, requires github.com/go-jose/go-jose/v4 v4.1.4. go-jose has no dependencies of its own.

Proposed API

package auth // github.com/z5labs/humus/auth

// ErrUnauthenticated is what a verifier's error wraps when the credential
// it was given authenticates no one: a token that is expired, forged or
// for another audience, an API key that doesn't exist, a wrong password.
// Any other error from a verifier is the server's, and is never answered
// with a 401.
var ErrUnauthenticated = errors.New("unauthenticated")

// ErrForbidden is the error of a request that a scheme authenticated, but
// whose principal lacks a scope its requirement needs.
var ErrForbidden = errors.New("forbidden")

// Scheme is a way to authenticate a request, whose principal is a P: the
// value the scheme's verify function returns, such as the end user's User
// or Claims. Each method returns a copy, so a declaration can be shared.
// The zero Scheme is a mistake that NewAPI, NewHandler and Interceptors
// report.
type Scheme[P any] struct{ /* unexported */ }

// Bearer reads a token from the Authorization header's Bearer scheme,
// whatever its case, and from the authorization metadata of an RPC.
func Bearer[P any](name string, verify func(ctx context.Context, token string) (P, error)) Scheme[P]

// Basic reads a username and password from the Authorization header's
// Basic scheme. realm is the realm of its challenge, which RFC 7617
// requires.
func Basic[P any](name, realm string, verify func(ctx context.Context, username, password string) (P, error)) Scheme[P]

// APIKeyHeader, APIKeyQuery and APIKeyCookie read an API key from a
// header, a query parameter or a cookie. Only a header can be read from
// an RPC, as its metadata.
func APIKeyHeader[P any](name, header string, verify func(ctx context.Context, key string) (P, error)) Scheme[P]
func APIKeyQuery[P any](name, param string, verify func(ctx context.Context, key string) (P, error)) Scheme[P]
func APIKeyCookie[P any](name, cookie string, verify func(ctx context.Context, key string) (P, error)) Scheme[P]

// MutualTLS reads the client certificate chains the TLS handshake verified,
// against Settings.TLS's ClientCAs. A certificate the handshake didn't
// verify is no credential.
func MutualTLS[P any](name string, verify func(ctx context.Context, chains [][]*x509.Certificate) (P, error)) Scheme[P]

// OAuth2 and OpenIDConnect read a bearer token, as Bearer does. They
// differ from it in the document: flows lists how a client gets a token,
// and discovery is the provider's OpenID Connect discovery document.
func OAuth2[P any](name string, flows Flows, verify func(ctx context.Context, token string) (P, error)) Scheme[P]
func OpenIDConnect[P any](name string, discovery *url.URL, verify func(ctx context.Context, token string) (P, error)) Scheme[P]

// Description returns s, described by d in a document, in CommonMark.
func (s Scheme[P]) Description(d string) Scheme[P]

// Format returns s, whose tokens are in format f, such as JWT: the
// document's bearerFormat. It is for Bearer alone; on another scheme it is
// a mistake.
func (s Scheme[P]) Format(f string) Scheme[P]

// From returns the principal s authenticated ctx's request with, and false
// when the request wasn't authenticated with s: it met a requirement
// without s, or Anonymous.
func (s Scheme[P]) From(ctx context.Context) (P, bool)

// Flows are an OAuth2 scheme's flows, as a document lists them. Scopes map
// each scope to its description, and a scope a requirement names must be
// in one of them.
type Flows struct {
	AuthorizationCode   *AuthorizationCodeFlow
	ClientCredentials   *ClientCredentialsFlow
	DeviceAuthorization *DeviceAuthorizationFlow
}

type AuthorizationCodeFlow struct {
	AuthorizationURL, TokenURL, RefreshURL *url.URL // RefreshURL is optional
	Scopes                                 map[string]string
}

type ClientCredentialsFlow struct {
	TokenURL, RefreshURL *url.URL
	Scopes               map[string]string
}

type DeviceAuthorizationFlow struct {
	DeviceAuthorizationURL, TokenURL, RefreshURL *url.URL
	Scopes                                       map[string]string
}

// Requirement is what a request must have to be served: every scheme of
// it, each with its scopes. Given a list of requirements, a request must
// meet one.
type Requirement struct{ /* unexported */ }

// Scoped is a principal that has scopes. A role is a scope: OpenAPI 3.1
// and later let a requirement of any scheme list roles.
type Scoped interface {
	HasScope(scope string) bool
}

// Require is the requirement that s authenticates the request.
func Require[P any](s Scheme[P]) Requirement

// RequireScopes is the requirement that s authenticates the request with
// a principal that has every one of scopes. P must be Scoped, so a scope
// on a principal that has none doesn't compile.
func RequireScopes[P Scoped](s Scheme[P], scopes ...string) Requirement

// All is the requirement that every one of reqs is met: OpenAPI's
// requirement object with more than one scheme.
func All(reqs ...Requirement) Requirement

// Anonymous is the requirement a request meets without credentials, for
// an operation whose authentication is optional: OpenAPI's empty
// requirement object. Credentials that a scheme of the other requirements
// rejects are still refused, never served anonymously.
func Anonymous() Requirement

// Answers answers the requests NewHandler's handler refuses. Each one is
// the end user's: auth writes no body of its own.
type Answers struct {
	// Unauthenticated answers a request no requirement authenticated, with
	// WWW-Authenticate already set.
	Unauthenticated http.Handler

	// Forbidden answers a request authenticated without a scope it needs,
	// with WWW-Authenticate already set for a bearer scheme.
	Forbidden http.Handler

	// Failed answers a request a verifier failed on with an error of the
	// server's, after it is recorded.
	Failed http.Handler
}

// NewHandler returns a handler that serves h only to a request that meets
// one of reqs, with its principals in the request's context, and answers
// any other with answers.
//
// It returns one error that names every mistake: a nil h or answer, no
// requirement, and every mistake in reqs that NewAPI reports.
//
// It logs through s.Telemetry's LoggerProvider, with the logger name
// "github.com/z5labs/humus/auth".
func NewHandler(s *humus.Setup, h http.Handler, answers Answers, reqs ...Requirement) (http.Handler, error)

The package is in the core module, and uses only the standard library and OpenTelemetry's API. openapi/v3 and grpcauth read a Requirement through internal/authn, the engine the three share. auth exports nothing for them, only what the end user writes.

`openapi/v3`

// Security is what a request must have: one of reqs. Given to NewAPI, it
// is every operation's, and the document's. Given to an operation or to
// Document, it replaces the API's. Security() with no requirement makes
// what it is given to public.
func Security(reqs ...auth.Requirement) APIOption

// Document gains opts, of which it takes Security alone: the document
// doesn't describe itself, so any other Option is a NewAPI error.
func Document(p Path, opts ...Option) Operation

type RequestError struct {
	// Status gains two values:
	//   - 401 for a request no Security requirement authenticated;
	//   - 403 for one authenticated without a scope its requirement needs.
	// Err is then auth.ErrUnauthenticated or auth.ErrForbidden.
	Status int
	// ... Param and Err as today
}

`grpc/grpcauth`

package grpcauth // github.com/z5labs/humus/grpc/grpcauth

// Rule is the requirement of the methods Default or Method names.
type Rule struct{ /* unexported */ }

// Default is the requirement of every method no Method names: one of
// reqs. Default() with no requirement makes those methods public.
func Default(reqs ...auth.Requirement) Rule

// Method is the requirement of the method fullMethod, such as a generated
// Service_Method_FullMethodName constant: one of reqs. Method(m) with no
// requirement makes m public.
func Method(fullMethod string, reqs ...auth.Requirement) Rule

// Interceptors returns a unary and a stream interceptor, as server options
// for grpcserver.NewService, which serve an RPC only when it meets its
// method's requirement, with its principals in the handler's context.
//
// It returns one error that names every mistake: no Default, or two; a
// method given twice, or that isn't /package.Service/Method; an API key in
// a query parameter or a cookie, which an RPC doesn't have; and every
// mistake in the requirements that NewAPI reports.
//
// It logs through s.Telemetry's LoggerProvider, with the logger name
// "github.com/z5labs/humus/grpc/grpcauth".
func Interceptors(s *humus.Setup, rules ...Rule) (unary, stream grpc.ServerOption, err error)

unary, stream, err := grpcauth.Interceptors(s,
	grpcauth.Default(auth.Require(bearer)),
	grpcauth.Method(cartpb.CartService_DeleteCart_FullMethodName, auth.RequireScopes(bearer, "carts:write")),
	grpcauth.Method(healthpb.Health_Check_FullMethodName), // the kubelet presents no credentials
	grpcauth.Method(healthpb.Health_Watch_FullMethodName),
	grpcauth.Method(healthpb.Health_List_FullMethodName),
)
if err != nil {
	return nil, err
}
svc, err := grpcserver.NewService(s, settings, unary, stream)

`auth/jwt`

package jwt // github.com/z5labs/humus/auth/jwt

// Algorithm is a JWS signature algorithm that a token may be signed with.
// There is no none, and no HMAC: a key set publishes public keys.
type Algorithm string

const (
	RS256, RS384, RS512 Algorithm = "RS256", "RS384", "RS512"
	PS256, PS384, PS512 Algorithm = "PS256", "PS384", "PS512"
	ES256, ES384, ES512 Algorithm = "ES256", "ES384", "ES512"
	EdDSA               Algorithm = "EdDSA"
)

// Settings configures a Verifier. Start from DefaultSettings: JWKSURL,
// Issuer and Audience have no default.
type Settings struct {
	// JWKSURL is the identity provider's JSON Web Key Set. Valid: an
	// absolute https URL. Check: CheckJWKSURL.
	JWKSURL *url.URL

	// Issuer is the iss every token must have. Check: CheckIssuer.
	Issuer string

	// Audience is what every token's aud must hold: the service. Check:
	// CheckAudience.
	Audience string

	// Algorithms are the algorithms a token may be signed with. Default:
	// RS256, PS256, ES256 and EdDSA. Check: CheckAlgorithms.
	Algorithms []Algorithm

	// Leeway is the clock skew allowed on exp, nbf and iat. Default: 1m.
	// Valid: 0 to 5m. Check: CheckLeeway.
	Leeway time.Duration

	// MinRefreshInterval is the least time between two fetches of the key
	// set. Default: 1m. Valid: positive. Check: CheckMinRefreshInterval.
	MinRefreshInterval time.Duration

	// MaxKeyAge is how long fetched keys are used before the key set is
	// fetched again. Default: 1h. Valid: at least MinRefreshInterval.
	// Check: CheckMaxKeyAge, and the order in NewVerifier.
	MaxKeyAge time.Duration
}

func DefaultSettings() Settings

func CheckJWKSURL(u *url.URL) error
func CheckIssuer(iss string) error
func CheckAudience(aud string) error
func CheckAlgorithms(algs []Algorithm) error
func CheckLeeway(d time.Duration) error
func CheckMinRefreshInterval(d time.Duration) error
func CheckMaxKeyAge(d time.Duration) error

// Verifier verifies JWTs, and decodes each one's claims into a C.
type Verifier[C any] struct{ /* unexported */ }

// NewVerifier runs every check on settings, rejects a nil client, and
// returns a Verifier that fetches the key set with client: the end user's
// httpclient client for JWKSURL's origin. It fetches nothing until the
// first token. It logs through s.Telemetry's LoggerProvider, with the
// logger name "github.com/z5labs/humus/auth/jwt".
func NewVerifier[C any](s *humus.Setup, settings Settings, client *http.Client) (*Verifier[C], error)

// Verify is a verify function for Bearer, OAuth2 and OpenIDConnect. It
// verifies token's signature with the key its kid names, and its iss, aud,
// exp, nbf and iat, and returns its claims. A token that fails is an error
// that wraps auth.ErrUnauthenticated. A key set it can't fetch is the
// server's error.
func (v *Verifier[C]) Verify(ctx context.Context, token string) (C, error)

auth/jwt is in the core module. It adds github.com/go-jose/go-jose/v4 to the core module's go.mod as a direct requirement, at v4.1.6. Its jwt package parses a compact JWS against an algorithm allowlist, and validates the registered claims.

How a request is authenticated

The engine is the same for the three. Given a list of requirements:

The requirements are tried in order, and the first one met wins. A requirement is met when every scheme of it authenticates the request, and its principal has every scope the requirement names.
A scheme is verified only when the request carries its credential, and at most once per request, however many requirements name it. A request with only an API key never reaches the bearer scheme's verifier.
A malformed credential is a rejected one, as a verifier's ErrUnauthenticated is. Examples: Authorization: Bearer with no token, two Authorization headers, Basic credentials that aren't base64 or have no colon, an API key given twice or empty.
A verifier's other error ends the request at once, as the server's, whatever the requirements after it. The outcome never depends on which alternative happened to fail.
Anonymous is met when no scheme in the list rejects the request's credentials. To know that, it verifies every credential the request carries.
When none is met, the request is forbidden if some requirement had every scheme authenticated and only lacked scopes, and unauthenticated otherwise.

The context of a request that is served carries the principals of the requirement it met, and only those: From of any other scheme returns false.

Answers

Outcome	`openapi.Security`	`auth.NewHandler`	`grpcauth`
unauthenticated	`RequestErrors`, status 401, `Err` `auth.ErrUnauthenticated`	`Answers.Unauthenticated`	`codes.Unauthenticated`, "unauthenticated"
forbidden	`RequestErrors`, status 403, `Err` `auth.ErrForbidden`	`Answers.Forbidden`	`codes.PermissionDenied`, "forbidden"
a verifier's other error	answered as the handler's error is: the first `Error` that matches, else the catch-all, which records it	recorded, then `Answers.Failed`	recorded; the error's own gRPC status if it has one, else `codes.Internal`, "authentication failed"
a verifier's panic	the catch-all, recorded as `operation panicked`	passes to `httpserver`, which records it and aborts	`grpcserver`'s recovery: `codes.Internal`

No verifier's text reaches the client. A 401's Err is the sentinel, so problem.FromRequestError's detail is "unauthenticated", not "token expired at 10:04" or "no user alice@example.com". gRPC's messages are fixed. A verifier's reason is the end user's to log or put on the span, in verify.
openapi answers a verifier's error as the handler's. So an end user whose verifier returns a DirectoryUnavailable gives openapi.Error[DirectoryUnavailable](http.StatusServiceUnavailable, enc), and clients retry a 503 rather than drop their token.
gRPC passes a status through. A verifier that returns status.Error(codes.Unavailable, …) for a directory outage gets Unavailable, which grpcclient's default classification retries. Its message is the verifier's, which is the end user's to choose.

`WWW-Authenticate`

A 401 sets one challenge for each scheme of the list that HTTP authentication defines, in order, without repeats:

Bearer for Bearer, OAuth2 and OpenID Connect together, or Bearer error="invalid_token" when one of them rejected the request's token, as RFC 6750 §3 has it. There is no realm.
Basic realm="<realm>", charset="UTF-8", as RFC 7617 has it.

A 403 sets Bearer error="insufficient_scope", scope="<the scopes>" when a bearer scheme lacked them, and nothing otherwise. An API key and mutual TLS have no HTTP challenge, so a 401 for a list of only those carries none: RFC 9110 asks for at least one, and no standard challenge exists for them. openapi sets the header before it calls RequestErrors' encoder, as it sets Allow before MethodNotAllowed.

Where each credential is read

Scheme	HTTP	gRPC
`Bearer`, `OAuth2`, `OpenIDConnect`	`Authorization: Bearer <token>`	`authorization` metadata, the same value
`Basic`	`Authorization: Basic <base64>`	`authorization` metadata, the same value
`APIKeyHeader`	the header	the metadata key, lowercased
`APIKeyQuery`, `APIKeyCookie`	the query parameter, the cookie	an `Interceptors` error
`MutualTLS`	`r.TLS.VerifiedChains`	the peer's `credentials.TLSInfo`

Mutual TLS needs the server's Settings.TLS to verify client certificates: ClientAuth set to VerifyClientCertIfGiven, so the same server also serves requests that authenticate otherwise, or RequireAndVerifyClientCert. A certificate that is only requested, not verified, is no credential.

`openapi`'s requests and document

Authentication comes first. An operation with requirements authenticates the request before anything else. Only then does it decode its parameters, check the Content-Type and read the body. So an unauthenticated client gets a 401, not a 400 that says which parameter it got wrong, and its body is never read. A request Unmatched answers isn't authenticated: it matched no operation.

The document lists the schemes. NewAPI collects every scheme of every requirement into components.securitySchemes, keyed by its name, so a requirement can't name a scheme the document lacks:

Scheme	Security scheme object
`Bearer`	`{"type": "http", "scheme": "bearer", "bearerFormat": <Format>}`
`Basic`	`{"type": "http", "scheme": "basic"}`
`APIKey…`	`{"type": "apiKey", "name": <param>, "in": "header" \| "query" \| "cookie"}`
`MutualTLS`	`{"type": "mutualTLS"}`
`OAuth2`	`{"type": "oauth2", "flows": {…}}`, with each flow's URLs and scopes
`OpenIDConnect`	`{"type": "openIdConnect", "openIdConnectUrl": <discovery>}`

The Security given to NewAPI is the document's top-level security.
An operation with its own Security lists it under its security, [] for Security().
Each requirement is an object from each of its schemes' names to its scopes, and Anonymous is {}.
Every operation with requirements lists RequestErrors' E at 401, and at 403 when one of its requirements names a scope.

The document is secured like the API. It lists every operation, which is what grpcserver keeps from anyone who can reach its port by registering no reflection. So Document takes the API's Security, and Document(path, openapi.Security()) serves it to anyone. Open question 2.

NewAPI reports the mistakes, in the one error it returns, never as a panic:

the zero Scheme or Requirement, and a nil verify function;
two different schemes with one name, and a name that isn't made of letters, digits, ., - and _, which OpenAPI requires of a components key;
one scheme twice in one All;
Format on a scheme that isn't Bearer;
a Basic realm that is empty or holds a quote;
an OAuth2 with no flow, a flow without the URLs it needs, and a scope that no flow declares;
an OpenIDConnect whose discovery URL isn't absolute;
an Error at 401 on an operation that can answer 401, and at 403 on one that can answer 403, as for 400;
an option given to Document that isn't Security.

Probes and other open paths

A probes server (httphealth.NewService, grpchealth.NewService) has no authentication, as exposing health probes decided.
HTTP probes attached to the end user's mux are open, because nothing wraps them. openapi.Security covers the API's operations, and auth.NewHandler covers only the handler it is given. The mux next to them, with the probes, is the end user's.
gRPC health attached to the end user's Service passes through grpcauth, like every RPC. The end user names Health's Check, Watch and List with grpcauth.Method and no requirement. The docs show it. If they don't, the kubelet's probes get Unauthenticated, and the pod never turns ready. That fails at the first deploy, never silently.
Server reflection, if the end user registers it, is covered by Default. So the schema is served only to authenticated clients.

Verifying JWTs

(*jwt.Verifier[C]).Verify is a verify function for any bearer scheme. For each token:

go-jose parses it as a compact JWS signed with one of Algorithms. Anything else is rejected, none and HS256 among them.
Its header must have a kid, and the key set must have that key. A token without kid is rejected.
The signature is verified, and the payload is decoded twice: into the registered claims, and into a C. C is the end user's, and auth/jwt reads nothing from it.
iss must be Issuer, aud must hold Audience, exp must be present and later than now minus Leeway, and nbf and iat must not be later than now plus Leeway. Now is time.Now(), so a test moves it with synctest.

Every rejection wraps auth.ErrUnauthenticated.

Keys are fetched when they are needed, never at startup. An identity provider that is down when the pod starts doesn't fail Init. A failed Init would put the pod in a crash loop, and an API whose tokens can't be verified still serves its public operations. The key set is fetched:

with the first token;
when a token names a kid the set doesn't have, which is how an identity provider's key rotation reaches the service;
when the keys are older than MaxKeyAge, so a key the provider withdrew stops verifying.

The fetches are at most one per MinRefreshInterval, whatever the tokens. So a client that sends tokens with made-up kids can't make the service fetch on every request: within the interval, an unknown kid is rejected. Concurrent requests share one fetch. The fetch uses context.WithoutCancel of the request's context, so it is in the request's trace, and a client that goes away doesn't fail it for the requests waiting on it. httpclient's Timeout bounds it.

Failures. The body is read up to 1 MiB, as a JSON Web Key Set. A key without kid, with use other than sig, with private parts, or of a type go-jose doesn't read is skipped, rather than failing the set.

When a refresh fails and keys are already held, the service keeps verifying with them, and logs one WARN record. A short identity-provider outage doesn't log every user out.
When no keys have ever been fetched, the request fails as the server's. Within MinRefreshInterval of the failed fetch, it fails at once, without fetching again.

JWKSURL must be https. A key set fetched in plain text would let anyone on the path add a key and sign their own tokens. The client must trust the provider through its TLS.RootCAs: httpclient refuses InsecureSkipVerify, and httpclient refuses a request to another origin, so the client is built for JWKSURL's.

Field	Default	Valid	Check
`JWKSURL`	none	absolute `https` URL with a host	`CheckJWKSURL`
`Issuer`	none	not empty	`CheckIssuer`
`Audience`	none	not empty	`CheckAudience`
`Algorithms`	`RS256`, `PS256`, `ES256`, `EdDSA`	not empty, each one of the constants, none twice	`CheckAlgorithms`
`Leeway`	`1m`	0 to 5m	`CheckLeeway`
`MinRefreshInterval`	`1m`	positive	`CheckMinRefreshInterval`
`MaxKeyAge`	`1h`	positive, and at least `MinRefreshInterval`	`CheckMaxKeyAge`; the order in `NewVerifier`

Telemetry

Nothing reads or sets OpenTelemetry's globals.

A refusal isn't recorded. A 401 or 403, Unauthenticated or PermissionDenied, is the client's mistake, as a RequestError is. otelhttp and otelgrpc already record its status on the request's span and in the duration metric. So a credential-stuffing attempt shows as a rise in 401s, with no log line per attempt.
A verifier's failure is recorded once. In openapi, it is the catch-all's request failed, or an Error's answer, which isn't logged, as for any handler's error. auth.NewHandler and grpcauth record:
- an exception event on the request's span;
- one ERROR record, authentication failed, in the request's context, with auth.scheme, error.type and exception.message, plus http.request.method or rpc.method.
When the client has gone away, the error goes on the span alone, as openapi's records do.
auth/jwt logs one WARN record, keys refresh failed, for a refresh that failed while keys were held, with url.full, error.type and exception.message. Its fetches are spans and metrics of the end user's httpclient.
No principal is recorded. humus puts no user.id, subject or key on a span or a record, since that is personal data in most services. A verify function that wants it on the span adds it, from trace.SpanFromContext(ctx).
No instruments of its own. The refusals are in http.server.request.duration and rpc.server.call.duration, by status.

Panics

auth recovers nothing itself. A verifier runs on the request's goroutine, before the handler, so a panic in it is recovered where a handler's would be. openapi answers it with the catch-all and records operation panicked, as it does for a decoder's. httpserver records handler panicked and aborts the response for auth.NewHandler. grpcserver's recovery answers codes.Internal.

Design decisions

One package for every protocol, with the bindings beside the protocols. auth declares schemes and requirements once. An end user with an OpenAPI API and a gRPC Service on one pod uses one bearer value for both. openapi/v3 holds Security, because its options' interfaces have unexported methods. auth holds NewHandler, because net/http is the standard library and openapi reads credentials the same way. grpcauth is in the grpc module, so a pod without gRPC doesn't link grpc-go's server.
The schemes are OpenAPI's security scheme types. They are the standard list of how an HTTP API authenticates. So one declaration both verifies and documents, and nothing can be documented without being verified. Old humus's five schemes come back, every one of them verifying, and MutualTLS works. Other HTTP schemes, such as Digest, HOBA or HTTP message signatures, are out of scope.
Typed principals. Scheme[P] carries the end user's type from verify to From. There is no claims map, no context.WithValue with a key of the end user's, and no type assertion in a handler. From is the scheme's own method, so the same call works in an openapi handler, an http.Handler and a gRPC method.
Scopes are checked at compile time against the principal. RequireScopes is constrained to a Scoped P. So a scope on a principal that can't have one doesn't compile, and auth never guesses where scopes live in a token: scope, scp, roles and groups are all common. The end user's HasScope decides, including hierarchies.
ErrUnauthenticated marks a rejection, and any other error is the server's. A directory or identity-provider outage answered with a 401 tells clients to drop a valid token and log the user out, and shows on no 5xx alert. A sloppy verifier that returns a plain error for a bad token gets a 500 in its first test, with the error in the record, rather than shipping. Open question 3.
401 for a missing or malformed credential, never 400. Old humus answered those with a 400. RFC 6750 allows a 400 for a malformed request, but a client that sends Authorization: Basic … to a bearer API needs the challenge, which only a 401 carries.
The refusal answers are the end user's. No format is imposed: openapi uses RequestErrors, which already answers every request the API rejects, and NewHandler takes http.Handlers, as openapi.Unmatched does. Err is a sentinel, so the verifier's reason never reaches the client through a wrap that prints it.
Authentication before everything else in openapi. Parameters, Content-Type and body are only looked at for a client that may see their errors.
grpcauth.Interceptors returns both interceptors, and requires Default. gRPC has no way to make one ServerOption of a unary and a stream interceptor. A function returning one of them invites an end user to install it and leave every streaming method open. Two return values make dropping one a visible _. Default is required because there is no document to show which methods are open: a method added later is covered by it, and Default() makes "public unless listed" an explicit choice.
Health is opened by name, not by humus. grpcauth doesn't exempt grpc.health.v1.Health on its own. An exemption that the end user can't see is a hole, and the failure of forgetting it is loud.
auth/jwt is opt-in, like jsoncodec and problem. auth names no token format, as openapi names no body format. JWT bearer tokens from an identity provider are what most APIs verify, and story(rest): provide jwt validation out of the box #257 asked for them out of the box. Open question 1.
go-jose, rather than writing JOSE or another library. It has no dependencies, is already in every humus module graph through grpc-go, and is what Kubernetes and go-oidc verify tokens with. golang-jwt/jwt reads no JSON Web Keys, so it would need a second library or a hand-written JWK parser. lestrrat-go/jwx brings a dozen modules. Signature verification is not code humus should write itself.
No OpenID Connect discovery fetch. jwt.Settings takes JWKSURL and Issuer as they are: two settings an operator reads once from the discovery document. OpenIDConnect's discovery URL is for the document, where clients use it. Fetching discovery would be a second fetch to fail and refresh, for values that never change.
Keys at first use, stale keys over no keys. See Verifying JWTs. Fetching at startup turns an identity-provider outage into a crash loop for every pod. Failing every request once MaxKeyAge passes turns a short outage into logging out every user.
No principal in telemetry, and no audit log. Who did what is the end user's to record, with their own retention rules.
Credentials on outbound calls stay out of scope, as outbound HTTP clients and outbound gRPC clients left them. Getting and refreshing a token for a client is a separate domain from verifying one: grant types, caching and refresh windows. x/oauth2's TokenSource with the end user's httpclient covers it today.

Testing

A prototype of auth, the shared engine, openapi/v3's Security, grpcauth and auth/jwt passed the tests below, under go test -race -count=3, on Go 1.27, with go-jose v4.1.6 and grpc-go v1.84.0. Each test runs the end user's whole App inside a testing/synctest bubble, on a humustest Host, served by httpserver or grpcserver over TLS with certificates from humustest.NewCA. The auth/jwt tests serve a JSON Web Key Set from the end user's own handler, on httpserver, at idp:8443 on the same Host, and fetch it with httpclient. That is the end user's test of their own verifier, not a fake identity provider. Keys come from ecdsa.GenerateKey with crypto/rand, passwords from rand.Text, and client certificates from the test's CA, so no key, token or password is fixed. Token expiry, MinRefreshInterval and MaxKeyAge take no real time. The prototype was in a scratchpad and is not kept, and the sketches below are trimmed from it.

An API whose operations answer by the request's credentials:

var (
	bearer = auth.Bearer("bearer", verifyToken).Format("JWT") // "alice" has carts:read, "admin" carts:write too
	apiKey = auth.APIKeyHeader("apiKey", "X-API-Key", verifyKey)
)

func TestSecurity_answers_each_request_by_its_credentials(t *testing.T) {
	synctest.Test(t, func(t *testing.T) {
		s := serveAPI(t, []openapi.Operation{
			openapi.Get(cart, getCart, jsonEncoder),
			openapi.Delete(cart, deleteCart, openapi.EmptyEncoder, openapi.Security(auth.RequireScopes(bearer, "carts:write"))),
			openapi.Get(me, getMe, jsonEncoder, openapi.Security(auth.Require(bearer), auth.Anonymous())),
			openapi.Document(docPath),
		}, openapi.Security(auth.RequireScopes(bearer, "carts:read"), auth.Require(apiKey)))

		r := s.as(http.MethodGet, "/carts/7", "", "")
		require.Equal(t, http.StatusUnauthorized, r.status)
		require.Equal(t, []string{"Bearer"}, r.header.Values("WWW-Authenticate"))
		require.Equal(t, http.StatusUnauthorized, s.as(http.MethodGet, "/carts/abc", "", "").status) // before the parameters

		r = s.as(http.MethodGet, "/carts/7", "Authorization", "Bearer nope")
		require.Equal(t, []string{`Bearer error="invalid_token"`}, r.header.Values("WWW-Authenticate"))
		require.JSONEq(t, `{"id":7,"user":"alice"}`, s.as(http.MethodGet, "/carts/7", "Authorization", "bearer alice").body)
		require.JSONEq(t, `{"id":7,"by":"batch"}`, s.as(http.MethodGet, "/carts/7", "X-API-Key", "k-1").body)

		r = s.as(http.MethodDelete, "/carts/7", "Authorization", "Bearer alice")
		require.Equal(t, http.StatusForbidden, r.status)
		require.Equal(t, []string{`Bearer error="insufficient_scope", scope="carts:write"`}, r.header.Values("WWW-Authenticate"))
		require.Equal(t, http.StatusUnauthorized, s.as(http.MethodDelete, "/carts/7", "X-API-Key", "k-1").status) // replaced

		require.Equal(t, http.StatusOK, s.as(http.MethodGet, "/me", "", "").status)                                     // anonymous
		require.Equal(t, http.StatusUnauthorized, s.as(http.MethodGet, "/me", "Authorization", "Bearer nope").status) // never anonymous
		require.Equal(t, http.StatusUnauthorized, s.as(http.MethodGet, docPath.String(), "", "").status)               // the API's Security

		require.Empty(t, records(s.tel)) // a refusal isn't logged
		s.stop()
	})
}

The identity provider rotates its keys, and a refresh fails:

func TestVerifier_fetches_rotates_and_rate_limits(t *testing.T) {
	synctest.Test(t, func(t *testing.T) {
		p := &idp{} // the test's JWKS handler, which counts its fetches
		p.add(t, "k1")
		hs := start(t, p) // the IdP at idp:8443, and an API at carts:9443 behind auth.NewHandler with jwt

		t1 := p.sign(t, "k1", "carts", 10*time.Minute)
		require.Equal(t, 200, hs.get(t1))
		require.Equal(t, 200, hs.get(t1))
		require.Equal(t, 1, p.count()) // fetched once, on the first token
		require.Equal(t, 401, hs.get(p.sign(t, "k1", "orders", time.Hour)))

		time.Sleep(12 * time.Minute) // past exp and the 1m leeway
		require.Equal(t, 401, hs.get(t1))

		p.add(t, "k2") // rotated in
		require.Equal(t, 200, hs.get(p.sign(t, "k2", "carts", time.Hour)))
		require.Equal(t, 2, p.count())

		p.add(t, "k3")
		require.Equal(t, 401, hs.get(p.sign(t, "k3", "carts", time.Hour)))
		require.Equal(t, 2, p.count()) // at most one fetch a minute
		time.Sleep(time.Minute)
		require.Equal(t, 200, hs.get(p.sign(t, "k3", "carts", time.Hour)))

		p.setDown(true)
		time.Sleep(time.Hour) // past MaxKeyAge
		require.Equal(t, 200, hs.get(p.sign(t, "k3", "carts", time.Hour))) // stale keys outlive a failed refresh
		require.Equal(t, []string{"WARN keys refresh failed"}, hs.logs())
	})
}

The prototype's tests also showed the following:

A verifier's error is the server's. A directory outage is a 500 from the catch-all, with no WWW-Authenticate, and one request failed record whose message holds the verifier's error. A verifier's error that matches an openapi.Error gets that answer, such as a 503. A verifier's panic is the catch-all's 500 and operation panicked.
The document. components.securitySchemes holds each scheme as the table above lists it. The top-level security is [{"bearer":["carts:read"]},{"apiKey":[]}]. An operation's own is listed, [] for Security(), [{"bearer":[]},{}] with Anonymous, and [{"oauth":["carts:admin"],"apiKey":[]}] for an All. A secured operation's responses gain 401, and 403 when it is scoped. A document with every scheme type validates against OpenAPI 3.2's schema-base: Basic, a cookie API key, mutual TLS, OpenID Connect, and OAuth2 with device authorization, authorization code and client credentials flows among them. Document(path, openapi.Security()) is served without credentials.
NewAPI's errors. Two schemes named bearer, an OAuth2 scope no flow declares, a nil verify function, and an Error at 401 on a secured operation are each reported, in one error.
auth.NewHandler on a mux. With ClientAuth: tls.VerifyClientCertIfGiven, a client certificate from the test's CA authenticates by MutualTLS, and its common name reaches the handler. Without one, a request is a 401 with Basic realm="admin", charset="UTF-8", and the right password authenticates. /healthz, beside it on the mux, answers without credentials.
grpcauth. A unary call without metadata is Unauthenticated, and with authorization: Bearer alice is served with alice in the handler's context. A server-streaming call that needs a scope is PermissionDenied for alice, and served for a principal with it, the principal in the stream's context. A verifier's plain error is Internal "authentication failed", and its status.Error(codes.Unavailable, …) is Unavailable. grpchealth's Check, on the same Service, answers SERVING without credentials. Interceptors reports a missing Default, a method given twice, a malformed method name and a query API key.
An unreachable identity provider. With no keys held, a token is a 500 and an authentication failed record. Within a minute, the next token fails too. Once the provider is back and the minute has passed, it is served, after one more fetch.

The stories add the tests the prototype didn't have:

The checks. Each of auth/jwt's accepts an in-range value with nil and rejects an out-of-range one without naming the field. NewVerifier names each bad field, reports two together, and rejects a MaxKeyAge below MinRefreshInterval and a nil client. DefaultSettings() with the three required fields set passes. The package never reads a bedrock.Environment.
Malformed credentials. Two Authorization headers, Bearer with no token, Basic that isn't base64 or has no colon, an empty API key and one given twice, are 401s. The scheme name in Authorization matches whatever its case.
Names and flows. An empty scheme name, one with a character OpenAPI doesn't allow, and an OAuth2 flow without the URLs it needs are NewAPI errors.
Mutual TLS over gRPC, from the peer's verified chains, and a requested-but-unverified certificate being no credential.
The records. authentication failed carries auth.scheme, error.type, exception.message and the method, isn't emitted when the client went away, and carries no principal. Nothing is recorded for a 401 or 403.
From after All and after Anonymous, and a scheme verified once when two requirements name it.
A token's claims. A token without exp or kid, signed with an algorithm not in Algorithms, with alg: none, or with a future nbf is rejected. A key set with an encryption key, a private key or a key type go-jose doesn't read keeps its other keys.

Each package's example is an Example function or a package main with an app_test.go, as the charter requires, and auth, auth/jwt and grpcauth are held to the 80% coverage gate.

Changes to other files

This proposal's stories make these, as it owns authentication and authorization:

openapi/v3. Security, Document's options, RequestError's 401 and 403, authentication before parameters, the document's components.securitySchemes, security and 401 and 403 responses, the NewAPI checks, and a "Security" section in its package doc. Proposal: OpenAPI endpoint DSL #760 foresaw the option in its revision 1.
grpcserver's doc. Its example's own authenticate interceptor becomes grpcauth.Interceptors.
grpchealth's doc says to name Health's methods public under grpcauth.
The example module's shoppingcart, with auth/jwt (open question 1). It requires a bearer token on every operation, and carts:write to change a cart, and serves its document publicly. Its tests serve a key set from a handler of their own, on the humustest Host in its unit tests and on OSHost beside its Postgres container in its container tests.
A docs page, "Authentication and authorization," at docs/content/auth.md. It covers schemes and principals, requirements and scopes, the three places, the answers and challenges, leaving probes open, verifying JWTs with auth/jwt, and testing with a key set served on a humustest Host. The OpenAPI, gRPC and health pages link to it, and the gRPC page shows the health rules.
The root package's "Being rebuilt" paragraph, the README and the docs site's index name the packages.
The core module's go.mod requires github.com/go-jose/go-jose/v4 v4.1.6 directly.

httpserver, httphealth, grpcclient, httpclient, humustest and telemetry don't change. No lint rule changes.

Migration from today

Before the reset	With this proposal
`rest.Header("Authorization", rest.Required(), rest.JWTAuth("jwt", verifier))`	`bearer := auth.Bearer("jwt", verify).Format("JWT")`, and `openapi.Security(auth.Require(bearer))`
`JWTVerifier.Verify(ctx, token) (context.Context, error)`, claims put in the context	`verify(ctx, token) (P, error)`, read with `bearer.From(ctx)`
a JWT verifier written by hand, on golang-jwt and a hand-loaded public key	`jwt.NewVerifier[Claims](s, settings, idpClient)`, with keys fetched and rotated
`rest.APIKey("api-key")` on a header, query parameter or cookie, checked in the handler	`auth.APIKeyHeader`, `APIKeyQuery` or `APIKeyCookie`, verified before the handler
`rest.BasicAuth("basic")`, documented as an API key, decoded in the handler	`auth.Basic(name, realm, verify)`, documented as `http`/`basic`
`rest.OAuth2("oauth2")`, with no flows	`auth.OAuth2(name, auth.Flows{…}, verify)`
`rest.OpenIDConnect(name, url)`, always named `openid-connect`	`auth.OpenIDConnect(name, url, verify)`
`rest.MutualTLS`, which panicked	`auth.MutualTLS(name, verify)`
a `requireRole` transform	`auth.RequireScopes(bearer, "admin")`, with the principal's `HasScope`
`JWTAuth` without `Required()`, for optional authentication	`openapi.Security(auth.Require(bearer), auth.Anonymous())`
a missing or malformed header: 400	401, with a challenge
the verifier's error: 401	wrapping `auth.ErrUnauthenticated`: 401; any other: the server's
a gRPC interceptor of the end user's own	`grpcauth.Interceptors`

Open questions

Ship auth/jwt? As proposed, an opt-in package verifies JWT bearer tokens against a JSON Web Key Set fetched with the end user's httpclient, on go-jose v4. Without it, auth stays format-free, and every end user writes the verifier, with key fetching, rotation and the claims checks, which old humus left to them too. It is the one place this proposal adds a dependency, though go-jose is already in the module graph through grpc-go. Recommendation: ship it, opt-in, as jsoncodec and problem are.
Is the document secured like the API? As proposed, Document takes the API's Security, and Document(path, openapi.Security()) makes it public. The alternative is a document that is always public, which needs no option on Document, but serves the schema of an internal API to anyone who can reach it. Recommendation: secured like the API. That is the choice grpcserver made by registering no reflection.
A verifier's other errors: the server's, or a 401? As proposed, only an error wrapping auth.ErrUnauthenticated is a 401, and any other is the server's: openapi's catch-all or an Error, NewHandler's Failed, gRPC's Internal or the error's own status. The alternative answers every error with a 401, as old humus did. That is simpler to write a verifier for, but it turns a directory outage into a 401 that tells clients to drop valid tokens, and shows on no 5xx alert. Recommendation: the server's.

Out of scope

Getting tokens, that is, a login: OAuth2 and OpenID Connect relying-party flows (redirect, callback, state, sessions), session cookies, and CSRF. story(rest): provide oidc validation out of the box #262's "UI facing endpoints" asked for one. humus verifies the tokens a client brings.
Credentials on outbound calls, such as a token source for httpclient or per-RPC credentials for grpcclient. Outbound HTTP clients and outbound gRPC clients leave them to service code and opts.
OpenID Connect discovery fetching, token introspection (RFC 7662) and encrypted tokens (JWE). An end user with opaque tokens writes a verify function that calls their introspection endpoint.
A token's typ, and sender-constrained tokens: DPoP, and certificate-bound tokens (RFC 8705).
The implicit and password OAuth2 flows, which RFC 9700 says not to use.
HTTP authentication schemes outside OpenAPI's types: Digest, HOBA, HTTP message signatures, and webhook signatures computed over the body.
Authorization beyond scopes: checks that depend on the resource, such as whether this user owns this cart, and policy engines. A handler makes those, with its principal from From.
Rate limiting, lockout and other brute-force protection.
CORS.
Authenticating records consumed from Kafka or RabbitMQ. The brokers authenticate their clients, with SASL.
Showing authentication in production-ready services: Proposal: walkthroughs and a humus MIGRATING.md (wave 6). Generating it: Proposal: AI tooling (wave 6).

References

Proposal: humus on the bedrock process model, the charter, and its revision 7: this proposal, in wave 5, and its independence from failure injection
Proposal: OpenAPI endpoint DSL and its revision 1 (openapi.Security) and revision 5 (RequestErrors, problem)
Proposal: HTTP server foundation and Proposal: gRPC services: TLS, and the order of interceptors
Proposal: exposing health probes: probes servers without authentication, and attached probes
Proposal: outbound HTTP clients and Proposal: outbound gRPC clients: the client auth/jwt fetches with, and outbound credentials left out of scope
Telemetry's revision 2: no globals; the configuration revision: Settings, DefaultSettings and Check<Field>; humustest's revision 2: the in-memory network and NewCA
Before the reset: v0.15.0's rest/parameter.go and its authentication page; story(rest): provide jwt validation out of the box #257, story(rest): provide oidc validation out of the box #262, story(rest): add argument for api key transformer #277, story(rest): add required argument for basic auth transformer #278, story(rest): allow users to register specific oauth2 flows and transformers #280, story(rest): implement openid transformer #281 and story(rest): add options for setting additional openapi values #283
OpenAPI 3.2.0: the Security Scheme, OAuth Flows and Security Requirement objects
RFC 9110 §11: 401, 403 and WWW-Authenticate; RFC 6750: bearer challenges and their errors; RFC 7617: Basic; RFC 9068: JWT access tokens and scope; RFC 7517 and RFC 7519: JWK and JWT; RFC 9700: the OAuth 2.0 security best current practice
go-jose v4 and its jwt package
gRPC's authentication guide and status codes: Unauthenticated and PermissionDenied

Zaba505 · 2026-10-18T15:56:15Z

Zaba505
Oct 18, 2026
Maintainer Author

Revision 1: the open questions answered, a key set the end user plugs in, `auth.Disabled()`, and `humus.auth.scheme`

The open questions:

auth/jwt ships, opt-in, as recommended. Its keys now come from a KeySet that the end user passes to NewVerifier, in place of Settings.JWKSURL. jwt.RemoteKeySet is the KeySet of a standard JSON Web Key Set. An end user whose key infrastructure serves something else implements KeySet over it. A test of a verify function gives the Verifier keys from memory, with no identity provider to serve.
The document is secured like the API, as recommended, and opening it is spelled out: Document(path, openapi.Security(auth.Disabled())). Some teams require their document secured. Others keep an internal API's document open, so their tooling can read it. Either is one visible choice. Security() with no requirement no longer opens anything: it is a mistake that NewAPI reports. auth.Disabled() is how an operation, the document or a gRPC method is opened, as insecure.NewCredentials() is how grpc-go serves without TLS.
A verifier's other errors are the server's, as recommended. The answer a client gets is openapi's and the end user's: an Error, the catch-all, Answers.Failed, or a gRPC status from their verify function. So that they can tell an unreachable key set from a bad token, Verify returns a *jwt.KeySetError when it had no key to verify a token with because its KeySet failed. openapi.Error[*jwt.KeySetError](http.StatusServiceUnavailable, enc) answers it with a 503, and clients retry rather than drop their token.

grpcauth's rules keep naming methods. A full method name is the only thing an interceptor knows a call by, and gRPC's own authorization policies, Istio's and go-grpc-middleware key on it too. Design decisions records it.

The record attribute auth.scheme becomes humus.auth.scheme, as Telemetry below says.

These changes weren't prototyped. The stories' tests, listed in Testing below, cover them.

Each section below replaces or adds to the part of the same name in the post.

Summary

The second bullet becomes:

A requirement is what a request must have. auth.Require(bearer), auth.RequireScopes(bearer, "carts:write") for a principal that has scopes, auth.All(a, b) for both, auth.Anonymous() for optional authentication, and auth.Disabled() for none at all. A list of requirements is met by any one of them, as OpenAPI's security is.

The last bullet becomes:

An opt-in auth/jwt verifies JWT bearer tokens against keys from a KeySet. jwt.RemoteKeySet fetches an identity provider's JSON Web Key Set with the end user's httpclient, and any other source of keys is a KeySet of the end user's. When the KeySet fails, Verify's error is a *jwt.KeySetError, which the end user answers as their server's. It is on go-jose v4, which grpc-go already brings into every humus module graph.

In the example, the start of Init becomes:

	idp, err := httpclient.NewClient(s, idpSettings) // for https://idp.example.com
	if err != nil {
		return nil, err
	}
	keys, err := jwt.NewRemoteKeySet(jwksURL, idp) // the provider's jwks_uri
	if err != nil {
		return nil, err
	}
	tokens, err := jwt.NewVerifier[Claims](s, jwtSettings, keys) // jwt.Settings, sourced with config.Struct
	if err != nil {
		return nil, err
	}

and its document is opened with openapi.Document(openapi.Root().Lit("openapi.json"), openapi.Security(auth.Disabled())), // public.

Proposed API

auth gains Disabled, after Anonymous:

// Disabled is the requirement every request meets, with no credential
// read: it turns authentication off. It is how an operation, the document
// or a method is made public when the API or Service requires
// authentication. It stands alone: with another requirement in the list,
// or in All, it is a mistake. Unlike Anonymous, it verifies nothing, so
// From of every scheme returns false, even for a request that carries a
// credential.
func Disabled() Requirement

NewHandler's doc names one more mistake: Disabled, since a handler that authenticates no one is h itself.

// It returns one error that names every mistake: a nil h or answer, no
// requirement, Disabled, and every mistake in reqs that NewAPI reports.

`openapi/v3`

Security's doc becomes:

// Security is what a request must have: one of reqs. Given to NewAPI, it
// is every operation's, and the document's. Given to an operation or to
// Document, it replaces the API's. Security(auth.Disabled()) makes what it
// is given to public. Security() with no requirement is a mistake that
// NewAPI reports.
func Security(reqs ...auth.Requirement) APIOption

`grpc/grpcauth`

Default's and Method's docs become:

// Default is the requirement of every method no Method names: one of
// reqs. Default(auth.Disabled()) makes those methods public.
func Default(reqs ...auth.Requirement) Rule

// Method is the requirement of the method fullMethod, such as a generated
// Service_Method_FullMethodName constant: one of reqs.
// Method(m, auth.Disabled()) makes m public.
func Method(fullMethod string, reqs ...auth.Requirement) Rule

Interceptors' doc adds a Default or a Method with no requirement to the mistakes it reports. The sketch becomes:

unary, stream, err := grpcauth.Interceptors(s,
	grpcauth.Default(auth.Require(bearer)),
	grpcauth.Method(cartpb.CartService_DeleteCart_FullMethodName, auth.RequireScopes(bearer, "carts:write")),
	grpcauth.Method(healthpb.Health_Check_FullMethodName, auth.Disabled()), // the kubelet presents no credentials
	grpcauth.Method(healthpb.Health_Watch_FullMethodName, auth.Disabled()),
	grpcauth.Method(healthpb.Health_List_FullMethodName, auth.Disabled()),
)
if err != nil {
	return nil, err
}
svc, err := grpcserver.NewService(s, settings, unary, stream)

`auth/jwt`

The block becomes:

package jwt // github.com/z5labs/humus/auth/jwt

// Algorithm is a JWS signature algorithm that a token may be signed with.
// There is no none, and no HMAC: a key set holds public keys.
type Algorithm string

const (
	RS256, RS384, RS512 Algorithm = "RS256", "RS384", "RS512"
	PS256, PS384, PS512 Algorithm = "PS256", "PS384", "PS512"
	ES256, ES384, ES512 Algorithm = "ES256", "ES384", "ES512"
	EdDSA               Algorithm = "EdDSA"
)

// Settings configures a Verifier. Start from DefaultSettings: Issuer and
// Audience have no default.
type Settings struct {
	// Issuer is the iss every token must have. Check: CheckIssuer.
	Issuer string

	// Audience is what every token's aud must hold: the service. Check:
	// CheckAudience.
	Audience string

	// Algorithms are the algorithms a token may be signed with. Default:
	// RS256, PS256, ES256 and EdDSA. Check: CheckAlgorithms.
	Algorithms []Algorithm

	// Leeway is the clock skew allowed on exp, nbf and iat. Default: 1m.
	// Valid: 0 to 5m. Check: CheckLeeway.
	Leeway time.Duration

	// MinRefreshInterval is the least time between two calls of the
	// KeySet. Default: 1m. Valid: positive. Check: CheckMinRefreshInterval.
	MinRefreshInterval time.Duration

	// MaxKeyAge is how long the keys a call returned are used before the
	// KeySet is called again. Default: 1h. Valid: at least
	// MinRefreshInterval. Check: CheckMaxKeyAge, and the order in
	// NewVerifier.
	MaxKeyAge time.Duration
}

func DefaultSettings() Settings

func CheckIssuer(iss string) error
func CheckAudience(aud string) error
func CheckAlgorithms(algs []Algorithm) error
func CheckLeeway(d time.Duration) error
func CheckMinRefreshInterval(d time.Duration) error
func CheckMaxKeyAge(d time.Duration) error

// Key is a public key, which verifies the tokens whose header's kid is ID.
type Key struct {
	ID string

	// Public is an *rsa.PublicKey, an *ecdsa.PublicKey or an
	// ed25519.PublicKey.
	Public crypto.PublicKey
}

// KeySet gets the keys tokens are signed with, from wherever the end user
// keeps them. The Verifier holds the keys Keys returns, and calls it only
// when it needs keys: at most once per MinRefreshInterval, with concurrent
// requests sharing one call. So a KeySet needs no cache of its own.
type KeySet interface {
	Keys(ctx context.Context) ([]Key, error)
}

// RemoteKeySet is the KeySet of a JSON Web Key Set, as RFC 7517 has it,
// served at an https URL: an identity provider's jwks_uri.
type RemoteKeySet struct{ /* unexported */ }

// NewRemoteKeySet returns the RemoteKeySet of u, which it fetches with
// client: the end user's httpclient client for u's origin. It returns one
// error that names every mistake: a nil client, and a u that isn't an
// absolute https URL with a host.
func NewRemoteKeySet(u *url.URL, client *http.Client) (*RemoteKeySet, error)

// Keys fetches the set, and returns its keys. It reads up to 1 MiB. It
// skips a key without kid, with a use other than sig, with private parts,
// or of a type go-jose doesn't read, rather than failing the set.
func (k *RemoteKeySet) Keys(ctx context.Context) ([]Key, error)

// KeySetError is Verify's error when it had no key to verify a token with
// because its KeySet failed. Err is the KeySet's error. It doesn't wrap
// auth.ErrUnauthenticated, so it is the server's to answer, such as with
// openapi.Error[*jwt.KeySetError] at 503.
type KeySetError struct {
	Err error
}

func (e *KeySetError) Error() string
func (e *KeySetError) Unwrap() error

// Verifier verifies JWTs, and decodes each one's claims into a C.
type Verifier[C any] struct{ /* unexported */ }

// NewVerifier runs every check on settings, rejects a nil keys, and
// returns a Verifier that verifies tokens with the keys from keys. It
// calls keys for nothing until the first token. It logs through
// s.Telemetry's LoggerProvider, with the logger name
// "github.com/z5labs/humus/auth/jwt".
func NewVerifier[C any](s *humus.Setup, settings Settings, keys KeySet) (*Verifier[C], error)

// Verify is a verify function for Bearer, OAuth2 and OpenIDConnect. It
// verifies token's signature with the key its kid names, and its iss, aud,
// exp, nbf and iat, and returns its claims. A token that fails is an error
// that wraps auth.ErrUnauthenticated. A token it has no key for because
// the KeySet failed is a *KeySetError.
func (v *Verifier[C]) Verify(ctx context.Context, token string) (C, error)

The paragraph after the block doesn't change.

How a request is authenticated

This is added after the list:

A list that is auth.Disabled() skips all of this. The request is served, no credential is read, and no principal is in its context.

Answers

This bullet is added:

An unreachable key set is the end user's to answer. auth/jwt's *KeySetError is a verifier's other error. openapi.Error[*jwt.KeySetError](http.StatusServiceUnavailable, enc) answers it with a 503. Over gRPC, a verify function that turns it into status.Error(codes.Unavailable, …) gets Unavailable. Without either, it is the catch-all's 500, Answers.Failed or Internal, never a 401.

`openapi`'s requests and document

The second bullet under "The document lists the schemes" becomes:

An operation with its own Security lists it under its security, [] for Security(auth.Disabled()).

"The document is secured like the API" becomes:

The document is secured like the API. It lists every operation, which is what grpcserver keeps from anyone who can reach its port by registering no reflection. So Document takes the API's Security, and Document(path, openapi.Security(auth.Disabled())) serves it to anyone. A team that keeps an internal API's document open for its tooling says so in that one line, where a review sees it.

NewAPI's mistakes gain one bullet, and the last one becomes:

Security() with no requirement, and auth.Disabled() with another requirement in the list or in an All;
an option given to Document that isn't Security.

Probes and other open paths

The third bullet becomes:

gRPC health attached to the end user's Service passes through grpcauth, like every RPC. The end user names Health's Check, Watch and List with grpcauth.Method and auth.Disabled(). The docs show it. If they don't, the kubelet's probes get Unauthenticated, and the pod never turns ready. That fails at the first deploy, never silently.

Verifying JWTs

Step 2 becomes:

Its header must have a kid, and the keys held must have that key. A token without kid is rejected.

"Keys are fetched when they are needed" becomes:

Keys are got when they are needed, never at startup. An identity provider that is down when the pod starts doesn't fail Init. A failed Init would put the pod in a crash loop, and an API whose tokens can't be verified still serves its public operations. The Verifier calls its KeySet:

with the first token;
when a token names a kid the held keys lack, which is how an identity provider's key rotation reaches the service;
when the keys are older than MaxKeyAge, so a key the provider withdrew stops verifying.

The calls are at most one per MinRefreshInterval, whatever the tokens. So a client that sends tokens with made-up kids can't make the service fetch on every request: within the interval, an unknown kid is rejected. Concurrent requests share one call. It gets context.WithoutCancel of the request's context, so it is in the request's trace, and a client that goes away doesn't fail it for the requests waiting on it. A request stops waiting when its own context ends. httpclient's Timeout bounds a RemoteKeySet's fetch. A KeySet of the end user's bounds its own calls.

"Failures" becomes:

Failures. The Verifier skips a key whose ID is empty, or whose Public isn't one of the three public key types, a private key among them. It keeps the others, rather than failing the set.

When a call fails and keys are already held, the Verifier keeps verifying with them, and logs one WARN record. A short outage of the key set doesn't log every user out.
When no keys have ever been got, the token's error is a *KeySetError. Within MinRefreshInterval of the failed call, the next token fails at once with the same error, without calling again.
When a token names a kid the held keys lack, and the call for it fails, or the last call failed within MinRefreshInterval, the token's error is a *KeySetError too, not a 401. The kid may be a key the provider rotated in, which the service couldn't get. A kid that a successful call still lacks is a 401, so made-up kids stay rejected.

"JWKSURL must be https" becomes:

RemoteKeySet's URL must be https. A key set fetched in plain text would let anyone on the path add a key and sign their own tokens. The client must trust the provider through its TLS.RootCAs: httpclient refuses InsecureSkipVerify, and httpclient refuses a request to another origin, so the client is built for the URL's. A KeySet of the end user's is theirs to secure: whoever can add a key to it can sign tokens the service accepts.

The table loses its JWKSURL row.

Telemetry

The ERROR record's attribute auth.scheme becomes humus.auth.scheme, as every telemetry name humus defines of its own now starts with humus., after humus's own metrics' revision 1 and revision 2. The record's other attributes are OpenTelemetry's, error.type, exception.message, http.request.method and rpc.method, and keep their names. The second sub-bullet of "A verifier's failure is recorded once" becomes:

one ERROR record, authentication failed, in the request's context, with humus.auth.scheme, error.type and exception.message, plus http.request.method or rpc.method.

The auth/jwt bullet becomes:

auth/jwt logs one WARN record, keys refresh failed, for a call of its KeySet that failed while keys were held, with error.type and exception.message. It has no url.full, since a KeySet may have no URL; a RemoteKeySet's error names its URL instead. A RemoteKeySet's fetches are spans and metrics of the end user's httpclient.

Design decisions

These bullets change:

grpcauth.Interceptors returns both interceptors, and requires Default. gRPC has no way to make one ServerOption of a unary and a stream interceptor. A function returning one of them invites an end user to install it and leave every streaming method open. Two return values make dropping one a visible _. Default is required because there is no document to show which methods are open: a method added later is covered by it, and Default(auth.Disabled()) makes "public unless listed" an explicit choice.
No OpenID Connect discovery fetch. NewRemoteKeySet takes the key set's URL, and jwt.Settings takes Issuer, as they are: two values an operator reads once from the discovery document. OpenIDConnect's discovery URL is for the document, where clients use it. Fetching discovery would be a second fetch to fail and refresh, for values that never change.

These are added:

Rules name methods. A full method name is the only thing an interceptor knows a call by, and it is the usual key. grpc-go's own authorization policies match rules on paths that are full method names, and so do Istio's authorization policies. go-grpc-middleware gives a service's AuthFuncOverride the full method name, and its example skips health with a selector on the service's name. The generated _FullMethodName constants keep the names from being typed by hand.
Turning authentication off is spelled out. auth.Disabled() opens an operation, the document or a method, and an empty Security(), Default() or Method(m) is a mistake. An empty list reads as "public" only to someone who knows the rule. Disabled names itself in the code, so a review sees it and a search finds every open path, as insecure.NewCredentials() does in grpc-go. It differs from Anonymous, which still verifies a credential that a request carries.
The key set is the end user's to plug in. Not every key infrastructure serves RFC 7517's JSON Web Key Set: keys come from secret stores, files and providers' own APIs. KeySet is the one method such a source needs, and RemoteKeySet is the standard one. The Verifier, not the KeySet, holds the keys and decides when to get them. So the rate limit, the shared call, rotation, MaxKeyAge and stale keys over none hold for every source, and a KeySet is only a fetch. go-oidc's verifier takes a KeySet too, but its RemoteKeySet caches by itself, so a KeySet of the end user's would have to rebuild that. A test of a verify function gives the Verifier keys from memory, with no identity provider to serve.
Key is humus's, not go-jose's. go-jose stays a detail of auth/jwt, so its next major version doesn't change humus's API. A source that isn't a JSON Web Key Set usually holds PEM keys, which x509.ParsePKIXPublicKey turns into a crypto.PublicKey.
An unreachable key set is a type. *jwt.KeySetError is a type, not a sentinel, because openapi.Error matches with errors.As on a type. So openapi.Error[*jwt.KeySetError] answers it, with no wrapping in the end user's verify function. A token whose kid the service couldn't get is one too, not a 401: the provider may have rotated that key in during the outage, and a 401 would tell the client to drop a valid token.

Testing

The sketch of TestVerifier_fetches_rotates_and_rate_limits builds its Verifier on jwt.NewRemoteKeySet of the test's JWKS handler, and otherwise stands.

Under "The prototype's tests also showed", these change:

The document: an operation's own security is [] for Security(auth.Disabled()), and Document(path, openapi.Security(auth.Disabled())) is served without credentials.
grpcauth: Health's methods are opened with auth.Disabled().
An unreachable identity provider: with no keys held, a token's error is a *jwt.KeySetError, answered as the server's, with an authentication failed record.

Under "The stories add the tests the prototype didn't have", "The checks" becomes the first bullet below, "A token's claims" the second and "The records" the third, and the rest are added:

The checks. Each of auth/jwt's accepts an in-range value with nil and rejects an out-of-range one without naming the field. NewVerifier names each bad field, reports two together, and rejects a MaxKeyAge below MinRefreshInterval and a nil KeySet. DefaultSettings() with Issuer and Audience set passes. NewRemoteKeySet rejects a nil client, and a URL that is relative, http or has no host. The package never reads a bedrock.Environment.
A token's claims. A token without exp or kid, signed with an algorithm not in Algorithms, with alg: none, or with a future nbf is rejected.
The records. authentication failed carries humus.auth.scheme, error.type, exception.message and the method, and no attribute named auth.scheme. It isn't emitted when the client went away, and carries no principal. Nothing is recorded for a 401 or 403.
The Verifier on a KeySet in memory, the test's own, which counts its calls: the first token calls it, rotation and the rate limit, MaxKeyAge, concurrent tokens sharing one call, stale keys after a failed call, and a key with no ID or a private key skipped while the others are kept.
*jwt.KeySetError. With no keys held and a failing KeySet, Verify's error is a *KeySetError that wraps the KeySet's error and not auth.ErrUnauthenticated, and openapi.Error[*jwt.KeySetError] answers it with a 503. A kid the held keys lack while the KeySet fails is one too. The same kid after a successful call that lacks it is a 401.
RemoteKeySet, on a key set served by the test's handler: a body over 1 MiB fails, and an encryption key, a private key or a key type go-jose doesn't read is skipped while the others are kept.
auth.Disabled(). An operation with Security(auth.Disabled()) under a secured API is served without a credential and with a forged one, and From returns false. Security(), Disabled with another requirement and Disabled in an All are NewAPI errors. Default() and Method(m) with no requirement are Interceptors errors, and Disabled is a NewHandler error.

Changes to other files

These bullets become:

grpchealth's doc says to name Health's methods with auth.Disabled() under grpcauth.
The example module's shoppingcart, with auth/jwt on a RemoteKeySet. It requires a bearer token on every operation, and carts:write to change a cart. It serves its document publicly, with openapi.Security(auth.Disabled()), and answers a *jwt.KeySetError with a 503. Its tests serve a key set from a handler of their own, on the humustest Host in its unit tests and on OSHost beside its Postgres container in its container tests, so they reach the key set through its configuration.
A docs page, "Authentication and authorization," at docs/content/auth.md. It covers schemes and principals, requirements and scopes, opening a path with auth.Disabled(), the three places, the answers and challenges, leaving probes open, verifying JWTs with auth/jwt on a RemoteKeySet or a KeySet of the end user's, answering a *jwt.KeySetError, and testing: a verify function on a KeySet in memory, and an App on a key set served on a humustest Host. The OpenAPI, gRPC and health pages link to it, and the gRPC page shows the health rules.

Migration from today

The third row becomes:

Before the reset	With this proposal
a JWT verifier written by hand, on golang-jwt and a hand-loaded public key	`jwt.NewVerifier[Claims](s, settings, keys)`, with keys from a `jwt.RemoteKeySet` or a `KeySet` of the end user's, held and rotated

Open questions

All three are answered above.

References

These are added:

grpc-go's authz policies, whose rules match full method names; go-grpc-middleware's auth and selector interceptors, and its example server; Istio's authorization policy paths
grpc-go's insecure.NewCredentials
go-oidc's KeySet and RemoteKeySet

0 replies

Zaba505 · 2026-10-18T20:40:17Z

Zaba505
Oct 18, 2026
Maintainer Author

Closing: authentication and authorization have landed

The revision's stories are done:

story(auth): serve an http.Handler only to requests that meet a requirement, with auth.NewHandler #881 served an http.Handler only to requests that meet a requirement, with auth.NewHandler, on the shared engine in internal/authn (story(auth): serve an http.Handler only to requests that meet a requirement, with auth.NewHandler #889);
story(openapi): secure operations and the document with openapi.Security #882 secured operations and the document with openapi.Security, listing each scheme under components.securitySchemes (story(openapi): secure operations and the document with openapi.Security #899);
story(grpcauth): authenticate and authorize each RPC by its method with grpcauth.Interceptors #883 authenticated and authorized each RPC by its full method name with grpcauth.Interceptors (story(grpcauth): authenticate and authorize each RPC by its method with grpcauth.Interceptors #902);
story(jwt): verify JWT bearer tokens with auth/jwt, on keys from the end user's KeySet #884 verified JWT bearer tokens with auth/jwt on keys from the end user's KeySet, with *jwt.KeySetError when the key set fails (story(jwt): verify JWT bearer tokens with auth/jwt, on keys from the end user's KeySet #905);
story(jwt): fetch an identity provider's JSON Web Key Set with jwt.RemoteKeySet #885 fetched an identity provider's JSON Web Key Set with jwt.RemoteKeySet (story(jwt): fetch an identity provider's JSON Web Key Set with jwt.RemoteKeySet #919);
story(example): require bearer tokens in the shoppingcart with auth/jwt #886 required bearer tokens in the shoppingcart, with carts:write to change a cart, a public document and a 503 for an unreachable key set (story(example): require bearer tokens in the shoppingcart with auth/jwt #926);
story(docs): document authentication and authorization #887 documented authentication and authorization on a new page, with sections on the OpenAPI and gRPC pages (story(docs): document authentication and authorization #933).

Revision 1 left no open questions. auth/jwt ships opt-in, on a KeySet the end user plugs in; the document is secured like the API, and auth.Disabled() is how an operation, the document or a method is opened; a verifier's other errors are the server's to answer, with *jwt.KeySetError for an unreachable key set; and the record attribute is humus.auth.scheme.

The rest is out of scope or belongs to other proposals, as "Out of scope" lists:

Showing authentication in production-ready services is Proposal: walkthroughs and a humus MIGRATING.md (wave 6). Generating it is Proposal: AI tooling (wave 6).
Getting tokens (OAuth2 and OpenID Connect relying-party flows, sessions, CSRF), credentials on outbound calls, OpenID Connect discovery fetching, token introspection, JWE, a token's typ, sender-constrained tokens, the implicit and password flows, HTTP authentication schemes outside OpenAPI's types, authorization beyond scopes, brute-force protection, CORS, and authenticating records consumed from Kafka or RabbitMQ stay out of scope.

0 replies

Navigation Menu

Repository navigation

Proposal: authentication and authorization #870

Uh oh!

{{title}}

Uh oh!

Replies: 2 comments

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Select a reply

Uh oh!

Proposal: authentication and authorization #870

Uh oh!

Zaba505 Oct 18, 2026 Maintainer

Summary

Background

Proposed API

openapi/v3

grpc/grpcauth

auth/jwt

How a request is authenticated

Answers

WWW-Authenticate

Where each credential is read

openapi's requests and document

Probes and other open paths

Verifying JWTs

Telemetry

Panics

Design decisions

Testing

Changes to other files

Migration from today

Open questions

Out of scope

References

Replies: 2 comments

Uh oh!

Zaba505 Oct 18, 2026 Maintainer Author

Revision 1: the open questions answered, a key set the end user plugs in, auth.Disabled(), and humus.auth.scheme

Summary

Proposed API

openapi/v3

grpc/grpcauth

auth/jwt

How a request is authenticated

Answers

openapi's requests and document

Probes and other open paths

Verifying JWTs

Telemetry

Design decisions

Testing

Changes to other files

Migration from today

Open questions

References

Uh oh!

Zaba505 Oct 18, 2026 Maintainer Author

Closing: authentication and authorization have landed

Zaba505
Oct 18, 2026
Maintainer

`openapi/v3`

`grpc/grpcauth`

`auth/jwt`

`WWW-Authenticate`

`openapi`'s requests and document

Zaba505
Oct 18, 2026
Maintainer Author

Revision 1: the open questions answered, a key set the end user plugs in, `auth.Disabled()`, and `humus.auth.scheme`

`openapi/v3`

`grpc/grpcauth`

`auth/jwt`

`openapi`'s requests and document

Zaba505
Oct 18, 2026
Maintainer Author