Documentation
¶
Overview ¶
Package oauth2 provides provider-neutral OAuth2 bearer-token helpers.
It models validated token claims, scope checks, bearer-token extraction, OpenAPI security-scheme registration, and mapping into authorization.Actor and authorization.Scope. It deliberately does not fetch JWKS documents, cache provider keys, implement issuer-specific validation, or adapt to any single identity provider.
Application code supplies a Validator or ValidatorFunc that verifies a bearer token and returns TokenClaims. Use RequireScopes for route-level scope checks, ScopeSet for normalized scope lookup, SecurityScheme for OpenAPI metadata, and RegisterSecurityScheme to attach that metadata to a specs.Registry.
Treat JWKSConfig as configuration data for app-owned validators. Validate issuers, audiences, expiry, not-before, clock skew, and tenant mapping in the validator before constructing authorization context. For examples, see docs/cookbook.md.
Purpose: See the package summary above. Import: `github.com/aatuh/api-toolkit/contrib/v4/oauth2`. Example: See docs/api-reference.md for package example links and docs/cookbook.md for task recipes. Errors: Constructors, parsers, and handlers return or write documented errors according to their signatures; packages with plain data types do not add hidden error channels. Concurrency: Treat configured middleware and helpers as immutable after construction; request and response values remain request-scoped unless a type documents stronger guarantees. Stability: Contrib API; it is not part of the stable root API promise. When not to use: Prefer net/http, application-owned types, or narrower helpers when this package contract is not needed.
Index ¶
- func BearerToken(r *http.Request) (string, bool)
- func RegisterSecurityScheme(registry *specs.Registry, name string, scheme specs.SecurityScheme)
- func RequireScopes(claims TokenClaims, required ...string) error
- func SecurityScheme(scopes ...string) specs.SecurityScheme
- type JWKSConfig
- type ScopeSet
- type TokenClaims
- type Validator
- type ValidatorFunc
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func BearerToken ¶
BearerToken extracts a bearer token from Authorization.
func RegisterSecurityScheme ¶
func RegisterSecurityScheme(registry *specs.Registry, name string, scheme specs.SecurityScheme)
RegisterSecurityScheme registers an OAuth2-compatible bearer security scheme.
func RequireScopes ¶
func RequireScopes(claims TokenClaims, required ...string) error
RequireScopes verifies that claims include all required scopes.
Example ¶
package main
import (
"fmt"
"github.com/aatuh/api-toolkit/contrib/v4/oauth2"
)
func main() {
claims := oauth2.TokenClaims{Scopes: []string{"widgets:read widgets:write"}}
err := oauth2.RequireScopes(claims, "widgets:read")
fmt.Println(err == nil)
}
Output: true
func SecurityScheme ¶
func SecurityScheme(scopes ...string) specs.SecurityScheme
SecurityScheme returns a bearer OAuth2 security scheme for OpenAPI.
Types ¶
type JWKSConfig ¶
JWKSConfig describes provider-neutral JWKS validation configuration.
type ScopeSet ¶
type ScopeSet map[string]struct{}
ScopeSet is a normalized set of OAuth2 scopes.
func NewScopeSet ¶
NewScopeSet constructs a normalized scope set from values.
type TokenClaims ¶
type TokenClaims struct {
Subject string
Issuer string
Audience []string
Scopes []string
TenantID string
ExpiresAt time.Time
IssuedAt time.Time
NotBefore time.Time
Raw map[string]any
}
TokenClaims captures validated OAuth2 token claims.
func (TokenClaims) Actor ¶
func (claims TokenClaims) Actor() authorization.Actor
Actor maps claims to the toolkit authorization actor.
func (TokenClaims) AuthorizationScope ¶
func (claims TokenClaims) AuthorizationScope() authorization.Scope
AuthorizationScope maps claims to the toolkit authorization scope.
type Validator ¶
type Validator interface {
ValidateToken(ctx context.Context, token string) (TokenClaims, error)
}
Validator validates a bearer token and returns provider-neutral claims.
type ValidatorFunc ¶
type ValidatorFunc func(context.Context, string) (TokenClaims, error)
ValidatorFunc adapts a function to Validator.
func (ValidatorFunc) ValidateToken ¶
func (f ValidatorFunc) ValidateToken(ctx context.Context, token string) (TokenClaims, error)
ValidateToken validates a bearer token.
Source Files