oidc

func GenerateCacheKey ¶ added in v0.2.45

func GenerateCacheKey(tokenEndpoint, connectorID, userID string) string

GenerateCacheKey creates a cache key from the token endpoint, connector ID, and user ID. This creates a key that uniquely identifies the exchange target without including the subject token itself (for security).

The key is a SHA-256 hash of the input parameters, which:

• Prevents collision attacks (e.g., if parameters contain delimiter characters)
• Creates fixed-length keys for consistent memory usage
• Does not expose sensitive information if the cache is inspected

Security Requirements ¶

IMPORTANT: The userID parameter MUST be extracted from trusted, validated claims in the subject token (e.g., the "sub" claim after JWT signature verification), NOT from user input or unvalidated sources. Using untrusted userID values could lead to cache poisoning attacks where an attacker retrieves tokens cached for other users.

Example:

// Extract userID from validated JWT claims (after signature verification)
userID := validatedClaims.Subject
key := GenerateCacheKey("https://dex.cluster-b.example.com/token", "cluster-a", userID)
cachedToken := cache.Get(key)

func GetAudienceFromClaims ¶ added in v0.2.39

func GetAudienceFromClaims(claims jwt.MapClaims) []string

GetAudienceFromClaims extracts the audience claim from JWT claims. The audience can be a single string or an array of strings. Returns nil if no audience is present.

func IsJWT ¶ added in v0.2.39

func IsJWT(token string) bool

IsJWT checks if a token string looks like a JWT (has 3 parts separated by dots). This is a quick syntactic check, not cryptographic validation.

func NewPrivateIPAllowedHTTPClient ¶ added in v0.2.40

func NewPrivateIPAllowedHTTPClient(timeout time.Duration) *http.Client

NewPrivateIPAllowedHTTPClient creates an HTTP client without SSRF protection. This client allows connections to private IP addresses, which is necessary for private IdP deployments (e.g., internal Dex).

WARNING: This reduces SSRF protection. Only use when connecting to trusted internal services where the IdP legitimately runs on private networks.

Parameters:

• timeout: HTTP client timeout (0 uses default 10 seconds)

Security Features:

• TLS Verification: Uses default TLS settings (no InsecureSkipVerify)
• No SSRF Protection: Private, loopback, and link-local addresses are ALLOWED

Use Cases:

• Home lab deployments with internal Dex
• Air-gapped environments
• Enterprise deployments with private IdPs

Example:

client := NewPrivateIPAllowedHTTPClient(30 * time.Second)
resp, err := client.Get("https://dex.internal/keys")

func NewSSRFSafeHTTPClient ¶ added in v0.2.39

func NewSSRFSafeHTTPClient(timeout time.Duration) *http.Client

NewSSRFSafeHTTPClient creates an HTTP client with DNS rebinding protection. This client validates that resolved IP addresses are not private/restricted at connection time, preventing DNS rebinding attacks.

Parameters:

• timeout: HTTP client timeout (0 uses default 10 seconds)

Security Features:

• DNS Rebinding Protection: Validates resolved IPs at connection time
• SSRF Protection: Blocks private, loopback, and link-local addresses
• TLS Verification: Uses default TLS settings (no InsecureSkipVerify)

Example:

client := NewSSRFSafeHTTPClient(30 * time.Second)
resp, err := client.Get("https://example.com/jwks")

func ParseUnverifiedClaims ¶ added in v0.2.39

func ParseUnverifiedClaims(tokenString string) (jwt.MapClaims, error)

ParseUnverifiedClaims extracts claims from a JWT without verifying the signature. This is useful for routing decisions (e.g., checking audience) before full validation. SECURITY: Never trust the claims returned from this function for authorization decisions.

func SSRFSafeDialContext ¶ added in v0.2.39

func SSRFSafeDialContext(dialer *net.Dialer) func(ctx context.Context, network, addr string) (net.Conn, error)

SSRFSafeDialContext creates a DialContext function that validates resolved IPs to prevent DNS rebinding attacks. DNS rebinding occurs when an attacker controls a DNS server that initially returns a public IP (passing URL validation) but later returns a private IP (when the actual connection is made).

Security Features:

• Validates each resolved IP before allowing connection
• Blocks loopback, private, and link-local addresses
• Prevents access to cloud metadata services (169.254.169.254)

Example:

transport := &http.Transport{
    DialContext: SSRFSafeDialContext(&net.Dialer{Timeout: 10 * time.Second}),
}
client := &http.Client{Transport: transport}

func ValidateConnectorID ¶

func ValidateConnectorID(connectorID string) error

ValidateConnectorID validates a Dex connector_id parameter. Connector IDs should be alphanumeric with hyphens/underscores only.

Security Considerations:

• Character Whitelist: Prevents injection attacks
• Length Limit: Prevents DoS via extremely long values

Example:

if err := ValidateConnectorID("github"); err != nil {
    return fmt.Errorf("invalid connector: %w", err)
}

func ValidateExternalURL ¶ added in v0.2.39

func ValidateExternalURL(rawURL, context string) error

ValidateExternalURL validates an external URL with SSRF protection. It enforces HTTPS and blocks private IP ranges to prevent Server-Side Request Forgery attacks. This is a generic version of ValidateIssuerURL that accepts a context parameter for error messages.

Security Considerations:

• HTTPS Enforcement: Prevents credential interception
• Private IP Blocking: Prevents SSRF against internal services (Kubernetes API, metadata services, etc.)
• Loopback Blocking: Prevents attacks against localhost services
• Link-local Blocking: Prevents metadata service attacks (169.254.169.254)

Example:

if err := ValidateExternalURL("https://provider.example.com/.well-known/jwks", "JWKS URI"); err != nil {
    return fmt.Errorf("invalid JWKS URI: %w", err)
}

func ValidateGroups ¶

func ValidateGroups(groups []string, maxGroups int) ([]string, bool, error)

ValidateGroups validates and truncates an OIDC groups claim. If maxGroups is <= 0, DefaultMaxGroups (600) is used.

Groups exceeding maxGroups are truncated (not rejected) so authentication can proceed. The second return value indicates whether truncation occurred. Individual group names exceeding DefaultMaxGroupNameLength are rejected with an error, as oversized names may indicate an injection attempt.

Returns a defensive copy of the groups slice.

Security Considerations:

• Array Size Limit: Prevents memory exhaustion from excessive groups
• String Length Limit: Prevents memory exhaustion from long group names

Example:

validated, truncated, err := ValidateGroups(groups, 0)
if err != nil {
    return fmt.Errorf("invalid groups: %w", err)
}
if truncated {
    slog.Warn("groups truncated", "original", len(groups))
}

func ValidateHTTPSURL ¶

func ValidateHTTPSURL(rawURL, context string) error

ValidateHTTPSURL validates that a URL uses HTTPS scheme. This is a reusable helper to enforce HTTPS across all endpoints.

Example:

if err := ValidateHTTPSURL("https://example.com", "issuer"); err != nil {
    return err
}

func ValidateIssuerURL ¶

func ValidateIssuerURL(issuerURL string) error

ValidateIssuerURL validates an OIDC issuer URL with SSRF protection. It enforces HTTPS and blocks private IP ranges to prevent Server-Side Request Forgery attacks.

This is a convenience wrapper around ValidateExternalURL with "issuer URL" as the context.

Security Considerations:

• HTTPS Enforcement: Prevents credential interception
• Private IP Blocking: Prevents SSRF against internal services (Kubernetes API, metadata services, etc.)
• Loopback Blocking: Prevents attacks against localhost services
• Link-local Blocking: Prevents metadata service attacks (169.254.169.254)

Example:

if err := ValidateIssuerURL("https://dex.example.com"); err != nil {
    return fmt.Errorf("invalid issuer: %w", err)
}

func ValidateScopes ¶

func ValidateScopes(scopes []string) error

ValidateScopes validates OAuth scopes.

Security Considerations:

• Array Size Limit: Prevents DoS from excessive scopes
• String Length Limit: Prevents memory exhaustion
• Empty Scope Detection: Prevents malformed requests

Example:

scopes := []string{"openid", "profile", "email"}
if err := ValidateScopes(scopes); err != nil {
    return fmt.Errorf("invalid scopes: %w", err)
}