December 2025 Improvements - Azure AD, Internal Networks, Startup Race Condition (#100)

* Allow internal IPs for OIDC configuration via extra flag.

Addresses issue #97

* Allow for internal IPs in OIDC configuration.

Addresses issue #97.

* feat: Add allowPrivateIPAddresses config option for internal networks

Adds a new configuration option `allowPrivateIPAddresses` that allows
OIDC provider URLs to use private IP addresses (10.x.x.x, 172.16-31.x.x,
192.168.x.x). This is useful for internal deployments where Keycloak or
other OIDC providers run on private networks without DNS resolution.

Security considerations:
- Loopback addresses (127.0.0.1, localhost, ::1) remain blocked
- Link-local addresses (169.254.x.x) remain blocked
- Default is false (secure by default)

Fixes #97

* feat: Support non-email user identifiers for Azure AD

Add userIdentifierClaim configuration option to support Azure AD users
without email addresses. This allows using alternative JWT claims like
"sub", "oid", "upn", or "preferred_username" for user identification.

- Default behavior uses "email" claim (backward compatible)
- Falls back to "sub" claim if configured claim is missing
- allowedUsers matches against the configured claim value
- allowedUserDomains only applies when using email-based identification

Fixes #95

* Race condition on traefik pod startup

When the plugin initializes and calls GetMetadataWithRecovery():

1. Checks cache first (if metadata is cached, returns immediately)
2. Creates a retry executor with startup-optimized settings (10 attempts, 1s delays)
3. Attempts to fetch metadata from the OIDC provider
4. If the fetch fails with a retryable error (connection refused, EOF, TLS/certificate errors, Traefik default cert), it waits and retries
5. After 10 attempts or on a non-retryable error, returns the error

This allows the plugin to handle the race condition where:
- Traefik initializes the plugin before routes are established
- Traefik serves its default certificate before loading real ones
- The OIDC provider pod isn't fully ready yet

Fixes issue #90

* Race condition on traefik pod startup

When the plugin initializes and calls GetMetadataWithRecovery():

1. Checks cache first (if metadata is cached, returns immediately)
2. Creates a retry executor with startup-optimized settings (10 attempts, 1s delays)
3. Attempts to fetch metadata from the OIDC provider
4. If the fetch fails with a retryable error (connection refused, EOF, TLS/certificate errors, Traefik default cert), it waits and retries
5. After 10 attempts or on a non-retryable error, returns the error

This allows the plugin to handle the race condition where:
- Traefik initializes the plugin before routes are established
- Traefik serves its default certificate before loading real ones
- The OIDC provider pod isn't fully ready yet

Fixes issue #90

* Headers too big and 431 responses

Added new option `minimalHeaders` to reduce the size of forwarded headers from the auth middleware to backend services.

  - When minimalHeaders: false (default): All headers are forwarded as before
    - X-Forwarded-User (always set)
    - X-Auth-Request-Redirect
    - X-Auth-Request-User
    - X-Auth-Request-Token (the large ID token)
    - X-User-Groups, X-User-Roles (if configured)
  - When minimalHeaders: true: Reduces header overhead
    - X-Forwarded-User (always set)
    - X-User-Groups, X-User-Roles (still forwarded if configured)
    - Custom templated headers (still processed)
    - Skipped: X-Auth-Request-Token, X-Auth-Request-User, X-Auth-Request-Redirect

Fixes issues #64 and #86

error_recovery.go

@@ -2,10 +2,14 @@ package traefikoidc
 
 import (
 	"context"
+	"crypto/x509"
+	"errors"
 	"fmt"
+	"io"
 	"math"
 	"math/rand/v2"
 	"net"
+	"strings"
 	"sync"
 	"sync/atomic"
 	"time"
@@ -411,6 +415,31 @@ func DefaultRetryConfig() RetryConfig {
 	}
 }
 
+// MetadataFetchRetryConfig returns retry configuration optimized for OIDC metadata
+// fetching during startup. Uses more aggressive retry settings to handle the race
+// condition where Traefik initializes the plugin before routes are fully established,
+// or before TLS certificates are properly loaded.
+// See: https://github.com/lukaszraczylo/traefikoidc/issues/90
+func MetadataFetchRetryConfig() RetryConfig {
+	return RetryConfig{
+		MaxAttempts:   10,               // More attempts for startup scenarios
+		InitialDelay:  1 * time.Second,  // 1 second between attempts as suggested
+		MaxDelay:      10 * time.Second, // Cap at 10 seconds
+		BackoffFactor: 1.5,              // Gentler backoff for startup
+		EnableJitter:  true,             // Prevent thundering herd
+		RetryableErrors: []string{
+			"connection refused",
+			"timeout",
+			"temporary failure",
+			"network unreachable",
+			"EOF",
+			"certificate",
+			"x509",
+			"tls",
+		},
+	}
+}
+
 // RetryExecutor implements retry logic with exponential backoff and jitter.
 // It automatically retries failed operations based on configurable error patterns
 // and uses exponential backoff to avoid overwhelming failing services.
@@ -487,11 +516,29 @@ func (re *RetryExecutor) Execute(ctx context.Context, fn func() error) error {
 // isRetryableError checks if an error should trigger a retry
 // isRetryableError determines if an error should trigger a retry attempt.
 // Checks error message against configured retryable error patterns.
+// Also handles startup-specific errors like Traefik default certificate errors
+// and EOF errors that occur during service initialization.
 func (re *RetryExecutor) isRetryableError(err error) bool {
 	if err == nil {
 		return false
 	}
 
+	// Check for Traefik default certificate error (startup race condition)
+	// See: https://github.com/lukaszraczylo/traefikoidc/issues/90
+	if isTraefikDefaultCertError(err) {
+		return true
+	}
+
+	// Check for EOF errors (common during startup when services aren't ready)
+	if isEOFError(err) {
+		return true
+	}
+
+	// Check for certificate errors (transient during startup)
+	if isCertificateError(err) {
+		return true
+	}
+
 	errStr := err.Error()
 
 	for _, retryableErr := range re.config.RetryableErrors {
@@ -1088,3 +1135,86 @@ func containsSubstring(s, substr string) bool {
 	}
 	return false
 }
+
+// isTraefikDefaultCertError detects when Traefik is serving its default self-signed
+// certificate during cold-start, before the real certificates are loaded.
+// This manifests as an x509.HostnameError where one of the certificate's DNS names
+// ends with "traefik.default" (the default Traefik certificate pattern).
+// See: https://github.com/lukaszraczylo/traefikoidc/issues/90
+func isTraefikDefaultCertError(err error) bool {
+	if err == nil {
+		return false
+	}
+
+	var hostnameErr x509.HostnameError
+	if errors.As(err, &hostnameErr) {
+		if hostnameErr.Certificate != nil {
+			for _, name := range hostnameErr.Certificate.DNSNames {
+				if strings.HasSuffix(name, "traefik.default") {
+					return true
+				}
+			}
+		}
+	}
+
+	return false
+}
+
+// isEOFError checks if an error is an EOF error, which can occur during
+// connection establishment when the remote end closes unexpectedly.
+// This is common during service startup when endpoints aren't fully ready.
+func isEOFError(err error) bool {
+	if err == nil {
+		return false
+	}
+
+	// Check for direct EOF
+	if errors.Is(err, io.EOF) {
+		return true
+	}
+
+	// Check for unexpected EOF
+	if errors.Is(err, io.ErrUnexpectedEOF) {
+		return true
+	}
+
+	// Check error message for EOF patterns (wrapped errors)
+	errStr := err.Error()
+	return strings.Contains(errStr, "EOF") || strings.Contains(errStr, "unexpected EOF")
+}
+
+// isCertificateError checks if an error is related to TLS certificate validation.
+// These errors are often transient during startup when services are still initializing.
+func isCertificateError(err error) bool {
+	if err == nil {
+		return false
+	}
+
+	// Check for x509 certificate errors
+	var certInvalidErr x509.CertificateInvalidError
+	var hostnameErr x509.HostnameError
+	var unknownAuthErr x509.UnknownAuthorityError
+
+	if errors.As(err, &certInvalidErr) ||
+		errors.As(err, &hostnameErr) ||
+		errors.As(err, &unknownAuthErr) {
+		return true
+	}
+
+	// Check error message for certificate patterns
+	errStr := strings.ToLower(err.Error())
+	certPatterns := []string{
+		"certificate",
+		"x509",
+		"tls",
+		"ssl",
+	}
+
+	for _, pattern := range certPatterns {
+		if strings.Contains(errStr, pattern) {
+			return true
+		}
+	}
+
+	return false
+}