Documentation
¶
Overview ¶
Package oauth provides RFC-defined types and constants for OAuth 2.0 and OpenID Connect. This package contains ONLY protocol-level definitions with no business logic. It serves as a shared foundation for both OAuth clients (consumers) and servers (producers).
Package oauth provides shared RFC-defined types, constants, and validation utilities for OAuth 2.0 and OpenID Connect. It serves as a shared foundation for both OAuth clients and servers, including redirect URI validation per RFC 6749 and RFC 8252.
Index ¶
Constants ¶
const ( // WellKnownOIDCPath is the standard OIDC discovery endpoint path // per OpenID Connect Discovery 1.0 specification. WellKnownOIDCPath = "/.well-known/openid-configuration" // WellKnownOAuthServerPath is the standard OAuth authorization server metadata endpoint path // per RFC 8414 (OAuth 2.0 Authorization Server Metadata). WellKnownOAuthServerPath = "/.well-known/oauth-authorization-server" // WellKnownOAuthResourcePath is the RFC 9728 standard path for OAuth Protected Resource metadata. // Per RFC 9728 Section 3, this endpoint and any subpaths under it should be accessible // without authentication to enable OIDC/OAuth discovery. WellKnownOAuthResourcePath = "/.well-known/oauth-protected-resource" )
Well-known endpoint paths as defined by RFC 8414, OpenID Connect Discovery 1.0, and RFC 9728.
const ( // GrantTypeAuthorizationCode is the authorization code grant type (RFC 6749 Section 4.1). GrantTypeAuthorizationCode = "authorization_code" // GrantTypeRefreshToken is the refresh token grant type (RFC 6749 Section 6). GrantTypeRefreshToken = "refresh_token" )
Grant types as defined by RFC 6749.
const MaxRedirectURILength = 2048
MaxRedirectURILength is the maximum allowed length for a single redirect URI. This limit provides DoS protection during URI parsing per RFC 3986 practical constraints.
const (
// PKCEMethodS256 uses SHA-256 hash of the code verifier (recommended).
PKCEMethodS256 = "S256"
)
PKCE (Proof Key for Code Exchange) methods as defined by RFC 7636.
const (
// ResponseTypeCode is the authorization code response type (RFC 6749 Section 4.1.1).
ResponseTypeCode = "code"
)
Response types as defined by RFC 6749.
const ( // TokenEndpointAuthMethodNone indicates no client authentication (public clients). // Typically used with PKCE for native/mobile applications. TokenEndpointAuthMethodNone = "none" )
Token endpoint authentication methods as defined by RFC 7591.
Variables ¶
var ( // ErrMissingIssuer indicates the issuer field is missing from the discovery document. ErrMissingIssuer = errors.New("missing issuer") // ErrMissingAuthorizationEndpoint indicates the authorization_endpoint field is missing. ErrMissingAuthorizationEndpoint = errors.New("missing authorization_endpoint") // ErrMissingTokenEndpoint indicates the token_endpoint field is missing. ErrMissingTokenEndpoint = errors.New("missing token_endpoint") // ErrMissingJWKSURI indicates the jwks_uri field is missing (required for OIDC). ErrMissingJWKSURI = errors.New("missing jwks_uri") // ErrMissingResponseTypesSupported indicates the response_types_supported field is missing (required for OIDC). ErrMissingResponseTypesSupported = errors.New("missing response_types_supported") )
Validation errors for discovery documents.
Functions ¶
func ValidateRedirectURI ¶ added in v0.8.1
func ValidateRedirectURI(uri string, policy RedirectURIPolicy) error
ValidateRedirectURI validates a redirect URI per RFC 6749 Section 3.1.2 and RFC 8252. The policy parameter controls whether private-use URI schemes are accepted.
Validation rules applied:
- URI must not exceed MaxRedirectURILength (DoS protection)
- URI must be an absolute URI with a scheme (RFC 6749 Section 3.1.2)
- URI must not contain a fragment component (RFC 6749 Section 3.1.2)
- Scheme security per policy:
- Strict: only https or http-loopback (RFC 8252 Section 8.4)
- AllowPrivateSchemes: also allows private-use schemes (RFC 8252 Section 7.1)
Types ¶
type AuthorizationServerMetadata ¶ added in v0.8.0
type AuthorizationServerMetadata struct {
// Issuer is the authorization server's issuer identifier (REQUIRED per RFC 8414).
Issuer string `json:"issuer"`
// AuthorizationEndpoint is the URL of the authorization endpoint (RECOMMENDED).
// Note: No omitempty to maintain backward compatibility with existing JSON serialization.
AuthorizationEndpoint string `json:"authorization_endpoint"`
// TokenEndpoint is the URL of the token endpoint (RECOMMENDED).
// Note: No omitempty to maintain backward compatibility with existing JSON serialization.
TokenEndpoint string `json:"token_endpoint"`
// JWKSURI is the URL of the JSON Web Key Set document (RECOMMENDED).
// Note: No omitempty to maintain backward compatibility with existing JSON serialization.
JWKSURI string `json:"jwks_uri"`
// RegistrationEndpoint is the URL of the Dynamic Client Registration endpoint (OPTIONAL).
RegistrationEndpoint string `json:"registration_endpoint,omitempty"`
// IntrospectionEndpoint is the URL of the token introspection endpoint (OPTIONAL, RFC 7662).
IntrospectionEndpoint string `json:"introspection_endpoint,omitempty"`
// UserinfoEndpoint is the URL of the UserInfo endpoint (OPTIONAL, OIDC specific).
// Note: No omitempty to maintain backward compatibility with existing JSON serialization.
UserinfoEndpoint string `json:"userinfo_endpoint"`
// ResponseTypesSupported lists the response types supported (RECOMMENDED).
ResponseTypesSupported []string `json:"response_types_supported,omitempty"`
// GrantTypesSupported lists the grant types supported (OPTIONAL).
GrantTypesSupported []string `json:"grant_types_supported,omitempty"`
// CodeChallengeMethodsSupported lists the PKCE code challenge methods supported (OPTIONAL).
CodeChallengeMethodsSupported []string `json:"code_challenge_methods_supported,omitempty"`
// TokenEndpointAuthMethodsSupported lists the authentication methods supported at the token endpoint (OPTIONAL).
TokenEndpointAuthMethodsSupported []string `json:"token_endpoint_auth_methods_supported,omitempty"`
}
AuthorizationServerMetadata represents the OAuth 2.0 Authorization Server Metadata per RFC 8414. This is the base structure that OIDC Discovery extends.
type OIDCDiscoveryDocument ¶ added in v0.8.0
type OIDCDiscoveryDocument struct {
// Embed OAuth 2.0 AS Metadata (RFC 8414) as the base
AuthorizationServerMetadata
// SubjectTypesSupported lists the subject identifier types supported (REQUIRED for OIDC).
SubjectTypesSupported []string `json:"subject_types_supported,omitempty"`
// IDTokenSigningAlgValuesSupported lists the JWS algorithms supported for ID tokens (REQUIRED for OIDC).
IDTokenSigningAlgValuesSupported []string `json:"id_token_signing_alg_values_supported,omitempty"`
// ScopesSupported lists the OAuth 2.0 scope values supported (RECOMMENDED for OIDC).
ScopesSupported []string `json:"scopes_supported,omitempty"`
// ClaimsSupported lists the claims that can be returned (RECOMMENDED for OIDC).
ClaimsSupported []string `json:"claims_supported,omitempty"`
}
OIDCDiscoveryDocument represents the OpenID Connect Discovery 1.0 document. It extends OAuth 2.0 Authorization Server Metadata (RFC 8414) with OIDC-specific fields. This unified type supports both producer (server) and consumer (client) use cases.
func (*OIDCDiscoveryDocument) SupportsGrantType ¶ added in v0.8.0
func (d *OIDCDiscoveryDocument) SupportsGrantType(grantType string) bool
SupportsGrantType returns true if the authorization server supports the given grant type.
func (*OIDCDiscoveryDocument) SupportsPKCE ¶ added in v0.8.0
func (d *OIDCDiscoveryDocument) SupportsPKCE() bool
SupportsPKCE returns true if the authorization server supports PKCE with S256.
func (*OIDCDiscoveryDocument) Validate ¶ added in v0.8.0
func (d *OIDCDiscoveryDocument) Validate(isOIDC bool) error
Validate performs basic validation on the discovery document. It checks for required fields based on whether this is an OIDC or pure OAuth document.
type RedirectURIPolicy ¶ added in v0.8.1
type RedirectURIPolicy int
RedirectURIPolicy controls which URI schemes are accepted during redirect URI validation.
const ( // RedirectURIPolicyStrict allows only https and http-loopback schemes. // This follows RFC 8252 Section 8.4 strict security recommendations and // is appropriate for dynamically registered clients where scheme hijacking // is a concern. RedirectURIPolicyStrict RedirectURIPolicy = iota // RedirectURIPolicyAllowPrivateSchemes also allows private-use URI schemes // (e.g., cursor://, vscode://) per RFC 8252 Section 7.1. // This is appropriate for pre-registered/static clients where the administrator // explicitly configures trusted redirect URIs for native applications. RedirectURIPolicyAllowPrivateSchemes )
Source Files