lukaszraczylo/traefikoidc
1
0
Fork 0
mirror of https://github.com/lukaszraczylo/traefikoidc.git synced 2026-10-16 04:29:15 +00:00
Code Issues Packages Projects Releases Wiki Activity

fixup! Further pursue of perfection.

Browse Source
This commit is contained in:
lukaszraczylo
2025-09-04 22:43:39 +01:00
parent 29ec26cbaa
commit f291dcca26
43 changed files with 3995 additions and 2916 deletions
Download Patch File Download Diff File Expand all files Collapse all files
helpers.go
+93 -122
View File
@@ -15,14 +15,11 @@ import (
"time"
)
// generateNonce creates a cryptographically secure random string suitable for use as an OIDC nonce.
// The nonce is used during the authentication flow to mitigate replay attacks by associating
// the ID token with the specific authentication request.
// It generates 32 random bytes and encodes them using base64 URL encoding.
//
// generateNonce creates a cryptographically secure random nonce for OIDC flows.
// The nonce is used to prevent replay attacks and associate client sessions with ID tokens.
// Returns:
// - A base64 URL encoded random string (nonce).
// - An error if the random byte generation fails.
// - A base64 URL-encoded nonce string (43 characters)
// - An error if the random byte generation fails
func generateNonce() (string, error) {
nonceBytes := make([]byte, 32)
_, err := rand.Read(nonceBytes)
@@ -32,15 +29,13 @@ func generateNonce() (string, error) {
return base64.URLEncoding.EncodeToString(nonceBytes), nil
}
// generateCodeVerifier creates a cryptographically secure random string suitable for use as a PKCE code verifier.
// According to RFC 7636, the verifier should be a high-entropy string between 43 and 128 characters long.
// This function generates 32 random bytes, resulting in a 43-character base64 URL encoded string.
//
// generateCodeVerifier creates a PKCE code verifier according to RFC 7636.
// The code verifier is a cryptographically random string used for the PKCE flow
// to prevent authorization code interception attacks.
// Returns:
// - A base64 URL encoded random string (code verifier).
// - An error if the random byte generation fails.
// - A base64 raw URL-encoded code verifier string (43 characters)
// - An error if the random byte generation fails
func generateCodeVerifier() (string, error) {
// Using 32 bytes (256 bits) will produce a 43 character base64url string
verifierBytes := make([]byte, 32)
_, err := rand.Read(verifierBytes)
if err != nil {
@@ -49,52 +44,50 @@ func generateCodeVerifier() (string, error) {
return base64.RawURLEncoding.EncodeToString(verifierBytes), nil
}
// deriveCodeChallenge computes the PKCE code challenge from a given code verifier.
// It uses the S256 challenge method (SHA-256 hash followed by base64 URL encoding)
// as defined in RFC 7636.
//
// deriveCodeChallenge creates a PKCE code challenge from the code verifier.
// It computes the SHA-256 hash of the code verifier and base64 URL-encodes it
// according to RFC 7636 specification.
// Parameters:
// - codeVerifier: The high-entropy string generated by generateCodeVerifier.
// - codeVerifier: The code verifier string
//
// Returns:
// - The base64 URL encoded SHA-256 hash of the code verifier (code challenge).
// - The base64 URL encoded SHA-256 hash of the code verifier (code challenge)
func deriveCodeChallenge(codeVerifier string) string {
// Calculate SHA-256 hash of the code verifier
hasher := sha256.New()
hasher.Write([]byte(codeVerifier))
hash := hasher.Sum(nil)
// Base64url encode the hash to get the code challenge
return base64.RawURLEncoding.EncodeToString(hash)
}
// TokenResponse represents the response from the OIDC token endpoint.
// It contains the various tokens and metadata returned after successful
// TokenResponse represents the standard OAuth 2.0/OIDC token response.
// It contains the tokens and metadata returned by the authorization server during
// code exchange or token refresh operations.
type TokenResponse struct {
IDToken string `json:"id_token"`
AccessToken string `json:"access_token"`
// IDToken contains the OpenID Connect identity token (JWT)
IDToken string `json:"id_token"`
// AccessToken is the OAuth 2.0 access token for API access
AccessToken string `json:"access_token"`
// RefreshToken allows obtaining new tokens when the access token expires
RefreshToken string `json:"refresh_token"`
TokenType string `json:"token_type"`
ExpiresIn int `json:"expires_in"`
// TokenType specifies the token type (typically "Bearer")
TokenType string `json:"token_type"`
// ExpiresIn indicates token lifetime in seconds
ExpiresIn int `json:"expires_in"`
}
// exchangeTokens performs the OAuth 2.0 token exchange with the OIDC provider's token endpoint.
// It handles both the "authorization_code" grant type (exchanging an authorization code for tokens)
// and the "refresh_token" grant type (using a refresh token to obtain new tokens).
// It includes necessary parameters like client credentials and handles PKCE verification if applicable.
// The function follows redirects and handles potential errors during the exchange.
//
// exchangeTokens performs OAuth 2.0 token exchange with the authorization server.
// It supports both authorization code and refresh token grant types with PKCE support.
// Parameters:
// - ctx: The context for the outgoing HTTP request.
// - grantType: The OAuth 2.0 grant type ("authorization_code" or "refresh_token").
// - codeOrToken: The authorization code (for "authorization_code" grant) or the refresh token (for "refresh_token" grant).
// - redirectURL: The redirect URI that was used in the initial authorization request (required for "authorization_code" grant).
// - codeVerifier: The PKCE code verifier (required for "authorization_code" grant if PKCE was used).
// - ctx: Context for request timeout and cancellation
// - grantType: OAuth grant type ("authorization_code" or "refresh_token")
// - codeOrToken: Authorization code or refresh token depending on grant type
// - redirectURL: Redirect URI used in authorization (required for code exchange)
// - codeVerifier: PKCE code verifier (optional, used with PKCE flow)
//
// Returns:
// - A TokenResponse containing the obtained tokens (ID, access, refresh).
// - An error if the token exchange fails (e.g., network error, provider error, invalid grant).
// - *TokenResponse: Parsed token response from the authorization server
// - An error if the token exchange fails (e.g., network error, provider error, invalid grant)
func (t *TraefikOidc) exchangeTokens(ctx context.Context, grantType string, codeOrToken string, redirectURL string, codeVerifier string) (*TokenResponse, error) {
data := url.Values{
"grant_type": {grantType},
@@ -106,7 +99,6 @@ func (t *TraefikOidc) exchangeTokens(ctx context.Context, grantType string, code
data.Set("code", codeOrToken)
data.Set("redirect_uri", redirectURL)
// Add code_verifier if PKCE is being used
if codeVerifier != "" {
data.Set("code_verifier", codeVerifier)
}
@@ -141,14 +133,12 @@ func (t *TraefikOidc) exchangeTokens(ctx context.Context, grantType string, code
return nil, fmt.Errorf("failed to exchange tokens: %w", err)
}
defer func() {
// Always drain the body before closing to ensure connection can be reused
io.Copy(io.Discard, resp.Body)
resp.Body.Close()
}()
if resp.StatusCode != http.StatusOK {
// Limit body read to prevent memory issues
limitReader := io.LimitReader(resp.Body, 1024*10) // 10KB limit
limitReader := io.LimitReader(resp.Body, 1024*10)
bodyBytes, _ := io.ReadAll(limitReader)
return nil, fmt.Errorf("token endpoint returned status %d: %s", resp.StatusCode, string(bodyBytes))
}
@@ -161,16 +151,14 @@ func (t *TraefikOidc) exchangeTokens(ctx context.Context, grantType string, code
return &tokenResponse, nil
}
// getNewTokenWithRefreshToken uses a refresh token to obtain a new set of tokens (ID, access, refresh)
// from the OIDC provider's token endpoint. It wraps the exchangeTokens function with the
// "refresh_token" grant type.
//
// getNewTokenWithRefreshToken refreshes access and ID tokens using a refresh token.
// This is used when the current tokens are expired but the refresh token is still valid.
// Parameters:
// - refreshToken: The refresh token previously obtained during authentication or a prior refresh.
// - refreshToken: The refresh token to exchange for new tokens
//
// Returns:
// - A TokenResponse containing the newly obtained tokens.
// - An error if the refresh operation fails.
// - *TokenResponse: New token set from the authorization server
// - An error if the refresh operation fails
func (t *TraefikOidc) getNewTokenWithRefreshToken(refreshToken string) (*TokenResponse, error) {
ctx := context.Background()
tokenResponse, err := t.exchangeTokens(ctx, "refresh_token", refreshToken, "", "")
@@ -182,17 +170,15 @@ func (t *TraefikOidc) getNewTokenWithRefreshToken(refreshToken string) (*TokenRe
return tokenResponse, nil
}
// extractClaims decodes the payload (claims set) part of a JWT string.
// It splits the JWT into its three parts, base64 URL decodes the second part (payload),
// and unmarshals the resulting JSON into a map.
// Note: This function does *not* validate the token's signature or claims.
//
// extractClaims extracts and parses claims from a JWT token without signature verification.
// This is a utility function for quickly accessing token payload data when signature
// verification is not required or has already been performed.
// Parameters:
// - tokenString: The raw JWT string.
// - tokenString: The JWT token string to parse
//
// Returns:
// - A map representing the JSON claims extracted from the token payload.
// - An error if the token format is invalid, decoding fails, or JSON unmarshaling fails.
// - map[string]interface{}: Parsed claims from the token payload
// - An error if the token format is invalid, decoding fails, or JSON unmarshaling fails
func extractClaims(tokenString string) (map[string]interface{}, error) {
parts := strings.Split(tokenString, ".")
if len(parts) != 3 {
@@ -212,22 +198,22 @@ func extractClaims(tokenString string) (map[string]interface{}, error) {
return claims, nil
}
// TokenCache provides a caching mechanism for validated tokens.
// It stores token claims to avoid repeated validation of the
// same token, improving performance for frequently used tokens.
// TokenCache provides a specialized cache for validated JWT tokens.
// It wraps the generic Cache with token-specific prefixing to avoid
// TokenCache provides a specialized cache for JWT tokens and their parsed claims.
// It wraps the base Cache with token-specific prefixing to prevent
// key collisions and provides a clean interface for token caching operations.
type TokenCache struct {
// cache is the underlying generic cache implementation
cache *Cache
}
// Default configuration constants for the token cache.
const (
defaultTokenCacheMaxSize = 1000
defaultTokenCacheCleanupInterval = 2 * time.Minute
// defaultTokenCacheMaxSize limits the number of cached tokens
defaultTokenCacheMaxSize = 1000
)
// NewTokenCache creates and initializes a new TokenCache.
// NewTokenCache creates and initializes a new TokenCache with default settings.
// The cache is configured with a maximum size and automatic cleanup of expired entries.
func NewTokenCache() *TokenCache {
cache := NewCache()
cache.SetMaxSize(defaultTokenCacheMaxSize)
@@ -237,28 +223,24 @@ func NewTokenCache() *TokenCache {
}
}
// Set stores the claims associated with a specific token string in the cache.
// It prefixes the token string to avoid potential collisions with other cache types
// and sets the provided expiration duration.
//
// Set stores parsed token claims in the cache with expiration.
// The token is prefixed to prevent collisions with other cache entries.
// Parameters:
// - token: The raw token string (used as the key).
// - claims: The map of claims associated with the token.
// - expiration: The duration for which the cache entry should be valid.
// - token: The JWT token string (used as cache key)
// - claims: Parsed claims from the token
// - expiration: The duration for which the cache entry should be valid
func (tc *TokenCache) Set(token string, claims map[string]interface{}, expiration time.Duration) {
token = "t-" + token
tc.cache.Set(token, claims, expiration)
}
// Get retrieves the cached claims for a given token string.
// It prefixes the token string before querying the underlying cache.
//
// Get retrieves cached claims for a token.
// Parameters:
// - token: The raw token string to look up.
// - token: The JWT token string to look up
//
// Returns:
// - The cached claims map if found and valid.
// - A boolean indicating whether the token was found in the cache (true if found, false otherwise).
// - map[string]interface{}: The cached claims if found
// - A boolean indicating whether the token was found in the cache (true if found, false otherwise)
func (tc *TokenCache) Get(token string) (map[string]interface{}, bool) {
token = "t-" + token
value, found := tc.cache.Get(token)
@@ -269,39 +251,37 @@ func (tc *TokenCache) Get(token string) (map[string]interface{}, bool) {
return claims, ok
}
// Delete removes the cached entry for a specific token string.
// It prefixes the token string before calling the underlying cache's Delete method.
//
// Delete removes a token from the cache.
// Parameters:
// - token: The raw token string to remove from the cache.
// - token: The raw token string to remove from the cache
func (tc *TokenCache) Delete(token string) {
token = "t-" + token
tc.cache.Delete(token)
}
// Cleanup triggers the cleanup process for the underlying generic cache,
// Cleanup removes expired entries from the token cache.
// This is typically called automatically but can be invoked manually for
// removing expired token entries.
func (tc *TokenCache) Cleanup() {
tc.cache.Cleanup()
}
// Close stops the cleanup goroutine in the underlying cache.
// Close stops the cleanup goroutine and releases resources.
// Should be called when the token cache is no longer needed.
func (tc *TokenCache) Close() {
tc.cache.Close()
}
// exchangeCodeForToken is a convenience function that wraps exchangeTokens specifically
// for the "authorization_code" grant type. It handles the conditional inclusion of the
// PKCE code verifier based on the middleware's configuration (t.enablePKCE).
//
// exchangeCodeForToken exchanges an authorization code for tokens.
// This implements the OAuth 2.0 authorization code flow with optional PKCE support.
// Parameters:
// - code: The authorization code received from the OIDC provider.
// - redirectURL: The redirect URI used in the initial authorization request.
// - codeVerifier: The PKCE code verifier stored in the session (if PKCE is enabled).
// - code: The authorization code received from the authorization server
// - redirectURL: The redirect URI used in the authorization request
// - codeVerifier: PKCE code verifier (used if PKCE is enabled)
//
// Returns:
// - A TokenResponse containing the obtained tokens.
// - An error if the code exchange fails.
// - *TokenResponse: The token response containing access, refresh, and ID tokens
// - An error if the code exchange fails
func (t *TraefikOidc) exchangeCodeForToken(code string, redirectURL string, codeVerifier string) (*TokenResponse, error) {
ctx := context.Background()
@@ -317,15 +297,13 @@ func (t *TraefikOidc) exchangeCodeForToken(code string, redirectURL string, code
return tokenResponse, nil
}
// createStringMap converts a slice of strings into a map[string]struct{} (a set).
// This is useful for creating efficient lookups (O(1) average time complexity)
// for checking the presence of items like allowed domains, roles, or groups.
//
// createStringMap converts a slice of strings to a set-like map for fast lookups.
// This is a utility function for creating efficient membership tests.
// Parameters:
// - keys: A slice of strings to be added to the set.
// - keys: Slice of strings to convert to a map
//
// Returns:
// - A map where the keys are the strings from the input slice and the values are empty structs.
// - A map where the keys are the strings from the input slice and the values are empty structs
func createStringMap(keys []string) map[string]struct{} {
result := make(map[string]struct{})
for _, key := range keys {
@@ -334,16 +312,9 @@ func createStringMap(keys []string) map[string]struct{} {
return result
}
// handleLogout processes requests to the configured logout path.
// It performs the following steps:
// 1. Retrieves the current user session.
// 2. Gets the access token (ID token hint) from the session.
// 3. Clears all authentication-related data from the session cookies.
// 4. Determines the final post-logout redirect URI.
// 5. If an OIDC end_session_endpoint is configured and an ID token hint is available,
// it builds the OIDC logout URL and redirects the user agent to the provider for logout.
// 6. Otherwise, it redirects the user agent directly to the post-logout redirect URI.
//
// handleLogout processes user logout requests and performs proper session cleanup.
// It retrieves the ID token for logout URL construction, clears the session,
// and redirects to the provider's logout endpoint or configured post-logout URI.
// It handles potential errors during session retrieval or clearing.
func (t *TraefikOidc) handleLogout(rw http.ResponseWriter, req *http.Request) {
session, err := t.sessionManager.GetSession(req)
@@ -386,18 +357,16 @@ func (t *TraefikOidc) handleLogout(rw http.ResponseWriter, req *http.Request) {
http.Redirect(rw, req, postLogoutRedirectURI, http.StatusFound)
}
// BuildLogoutURL constructs the URL for redirecting the user agent to the OIDC provider's
// end_session_endpoint, including the required id_token_hint and optional
// post_logout_redirect_uri parameters as query arguments.
//
// BuildLogoutURL constructs a logout URL for the OIDC provider's end session endpoint.
// It includes the ID token hint and post-logout redirect URI according to OIDC specifications.
// Parameters:
// - endSessionURL: The URL of the OIDC provider's end session endpoint.
// - idToken: The ID token previously issued to the user (used as id_token_hint).
// - postLogoutRedirectURI: The optional URI where the provider should redirect the user agent after logout.
// - endSessionURL: The provider's logout/end session endpoint
// - idToken: The ID token to include as a hint
// - postLogoutRedirectURI: Where to redirect after logout
//
// Returns:
// - The fully constructed logout URL string.
// - An error if the provided endSessionURL is invalid.
// - The complete logout URL with query parameters
// - An error if the provided endSessionURL is invalid
func BuildLogoutURL(endSessionURL, idToken, postLogoutRedirectURI string) (string, error) {
u, err := url.Parse(endSessionURL)
if err != nil {
@@ -414,7 +383,9 @@ func BuildLogoutURL(endSessionURL, idToken, postLogoutRedirectURI string) (strin
return u.String(), nil
}
// deduplicateScopes removes duplicate strings from a slice while preserving order.
// deduplicateScopes removes duplicate scopes from a slice while preserving order.
// This ensures that OAuth scope parameters don't contain duplicates which could
// cause issues with some authorization servers.
// The first occurrence of each scope is kept.
func deduplicateScopes(scopes []string) []string {
if len(scopes) == 0 {