Documentation
¶
Overview ¶
Package validator provides shared token validation logic for both gRPC and HTTP servers.
Index ¶
Constants ¶
const ( // IntrospectionPrivateKeyJWTAlgorithmRS256 signs private_key_jwt assertions using RSASSA-PKCS1-v1_5 + SHA-256. IntrospectionPrivateKeyJWTAlgorithmRS256 = "RS256" // IntrospectionPrivateKeyJWTAlgorithmES256 signs private_key_jwt assertions using ECDSA P-256 + SHA-256. IntrospectionPrivateKeyJWTAlgorithmES256 = "ES256" )
Variables ¶
This section is empty.
Functions ¶
func ExtractScopes ¶
ExtractScopes extracts scopes from JWT claims. Supports both "scope" and "scp" claims, and handles both string and array formats.
Types ¶
type IntrospectionClientAuthConfig ¶ added in v1.1.0
type IntrospectionClientAuthConfig struct {
Method IntrospectionClientAuthMethod
ClientID string
// #nosec G117 -- Public API field name is intentional for OAuth client_secret config.
ClientSecret string
// #nosec G117 -- Public API field name is intentional for private_key_jwt config.
PrivateKey string
PrivateKeyJWTKeyID string
PrivateKeyJWTAlgorithm string
}
IntrospectionClientAuthConfig configures client authentication for the introspection request.
type IntrospectionClientAuthMethod ¶ added in v1.1.0
type IntrospectionClientAuthMethod string
IntrospectionClientAuthMethod defines the OAuth2 client authentication method used when calling the introspection endpoint.
const ( // IntrospectionClientAuthMethodClientSecretBasic uses RFC 6749 client_secret_basic authentication. IntrospectionClientAuthMethodClientSecretBasic IntrospectionClientAuthMethod = "client_secret_basic" // IntrospectionClientAuthMethodPrivateKeyJWT uses RFC 7523 private_key_jwt authentication. IntrospectionClientAuthMethodPrivateKeyJWT IntrospectionClientAuthMethod = "private_key_jwt" )
type JWTTokenValidator ¶
type JWTTokenValidator struct {
// contains filtered or unexported fields
}
JWTTokenValidator validates JWT tokens against JWKS from an OAuth2/OIDC provider. It caches public keys and automatically refreshes them when needed.
func NewJWTTokenValidator ¶
func NewJWTTokenValidator(jwksURL, issuer, audience string, httpClient *http.Client, cacheTTL time.Duration, logger Logger, logPrefix string) (*JWTTokenValidator, error)
NewJWTTokenValidator creates a new JWT token validator.
Parameters:
- jwksURL: URL to the JWKS endpoint (e.g., "https://auth.example.com/.well-known/jwks.json")
- issuer: Expected token issuer (iss claim)
- audience: Expected token audience (aud claim)
- httpClient: HTTP client for fetching JWKS (optional, uses http.DefaultClient if nil)
- cacheTTL: Duration to cache JWKS before refreshing (0 uses default of 1 hour)
- logger: Optional logger for debugging (can be nil)
- logPrefix: Prefix for log messages (e.g., "grpcserver", "httpserver")
Returns:
- *JWTTokenValidator: Configured validator instance
- error: Error if JWKS initialization fails
func (*JWTTokenValidator) Close ¶
func (v *JWTTokenValidator) Close()
Close releases resources used by the validator. Should be called when the validator is no longer needed.
func (*JWTTokenValidator) ValidateToken ¶
func (v *JWTTokenValidator) ValidateToken(ctx context.Context, tokenString string) (*TokenClaims, error)
ValidateToken validates a JWT token and extracts its claims.
This method: - Parses and validates the JWT signature using JWKS - Verifies the token expiry, issuer, and audience - Extracts standard and custom claims
Parameters:
- ctx: Context for the validation (currently unused but available for future use)
- tokenString: JWT token string to validate
Returns:
- *TokenClaims: Extracted token claims if validation succeeds
- error: Error if validation fails
type OpaqueTokenValidator ¶ added in v1.0.0
type OpaqueTokenValidator struct {
// contains filtered or unexported fields
}
OpaqueTokenValidator validates OAuth2 opaque tokens via RFC 7662 token introspection.
func NewOpaqueTokenValidator ¶ added in v1.0.0
func NewOpaqueTokenValidator( introspectionURL, issuer, audience, clientID, clientSecret string, httpClient *http.Client, logger Logger, ) (*OpaqueTokenValidator, error)
NewOpaqueTokenValidator creates a validator that uses token introspection for opaque tokens.
Parameters:
- introspectionURL: OAuth2 introspection endpoint URL
- issuer: Expected token issuer (iss claim when provided by introspection)
- audience: Expected token audience (aud claim when provided by introspection)
- clientID: OAuth2 client ID for introspection endpoint authentication
- clientSecret: OAuth2 client secret for introspection endpoint authentication
- httpClient: HTTP client for introspection requests (optional, uses http.DefaultClient if nil)
- logger: Optional logger for debugging (can be nil)
func NewOpaqueTokenValidatorWithAuth ¶ added in v1.1.0
func NewOpaqueTokenValidatorWithAuth( introspectionURL, issuer, audience string, authConfig IntrospectionClientAuthConfig, httpClient *http.Client, logger Logger, ) (*OpaqueTokenValidator, error)
NewOpaqueTokenValidatorWithAuth creates a validator that uses token introspection for opaque tokens and supports multiple OAuth2 client authentication methods for the introspection call.
func (*OpaqueTokenValidator) ValidateToken ¶ added in v1.0.0
func (v *OpaqueTokenValidator) ValidateToken(ctx context.Context, tokenString string) (*TokenClaims, error)
ValidateToken validates an opaque token via introspection and extracts claims.
type TokenClaims ¶
type TokenClaims struct {
Subject string // Subject (sub) - user identifier
Issuer string // Issuer (iss) - token issuer
Audience []string // Audience (aud) - intended recipients
Expiry time.Time // Expiry time (exp)
IssuedAt time.Time // Issued at (iat)
Scopes []string // Scopes - extracted from "scope" or "scp" claim
Email string // Email - optional user email
RawClaims map[string]any // Raw token claims for provider-agnostic authorization checks
}
TokenClaims represents the claims extracted from a validated JWT token.
type TokenValidator ¶
type TokenValidator interface {
ValidateToken(ctx context.Context, token string) (*TokenClaims, error)
}
TokenValidator validates OAuth2/OIDC access tokens.
Source Files