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
2026-10-18 04:47:28 +00:00 · 2025-12-08 14:21:17 +00:00
parent a750c4f5b9
commit 9126c74723
25 changed files with 1642 additions and 212 deletions
@@ -77,6 +77,7 @@ testData:
  # Custom claim names for Auth0 and other providers with namespaced claims
  roleClaimName: roles # JWT claim name for extracting user roles (default: "roles")
  groupClaimName: groups # JWT claim name for extracting user groups (default: "groups")
+  userIdentifierClaim: email # JWT claim for user identification (default: "email", alternatives: "sub", "oid", "upn", "preferred_username")

  # ⚠️ CRITICAL for TLS termination scenarios (AWS ALB, Cloud Load Balancers, etc.)
  # When NOT specified in config: defaults to FALSE (Go zero value)
@@ -120,6 +121,8 @@ testData:
  allowOpaqueTokens: false # Enable opaque (non-JWT) access token support via RFC 7662 introspection
  requireTokenIntrospection: false # Force introspection for opaque tokens (requires introspection endpoint)
  disableReplayDetection: false # Disable JTI replay detection for multi-replica deployments (default: false)
+  allowPrivateIPAddresses: false # Allow private IP addresses in provider URLs for internal networks (default: false)
+  minimalHeaders: false # Reduce forwarded headers to prevent 431 errors (default: false)

  # Security Headers Configuration (enabled by default with 'default' profile)
  securityHeaders:
@@ -266,6 +269,8 @@ testDataWithRedis:
 #   allowedRolesAndGroups: # Corresponds to 'Token Claim Name' in Keycloak mappers
 #     - admin
 #     - editor
+#   # For internal Keycloak deployments with private IPs (Docker/Kubernetes internal):
+#   # allowPrivateIPAddresses: true  # Enable for private IP addresses like 192.168.x.x, 10.x.x.x
 #   # Ensure Keycloak client mappers add 'email', 'roles', 'groups' etc. to the ID Token.
 #   # See README.md "Provider Configuration Recommendations" for Keycloak.

@@ -287,6 +292,26 @@ testDataWithRedis:
 #     - "AppRoleName"
 #   # See README.md "Provider Configuration Recommendations" for Azure AD.

+# --- Azure AD Users Without Email Example (Issue #95) ---
+# testDataAzureADNoEmail:
+#   providerURL: https://login.microsoftonline.com/your-tenant-id/v2.0
+#   clientID: your-azure-ad-client-id
+#   clientSecret: your-azure-ad-client-secret
+#   callbackURL: /oauth2/callback
+#   sessionEncryptionKey: "a-very-secure-key-at-least-32-bytes-long-for-azure"
+#   # Use 'sub' claim instead of 'email' for user identification
+#   userIdentifierClaim: sub  # or "oid", "upn", "preferred_username"
+#   overrideScopes: true  # Remove email scope if not needed
+#   scopes:
+#     - openid
+#     - profile
+#     - groups  # For group-based access control
+#   # When using non-email identifiers, allowedUsers matches against the claim value
+#   allowedUsers:
+#     - "abc12345-6789-0abc-def0-123456789abc"  # Azure AD user object ID (sub or oid claim)
+#   # NOTE: allowedUserDomains is ignored when userIdentifierClaim is not "email"
+#   # See: https://github.com/lukaszraczylo/traefikoidc/issues/95
+
 # --- Google Workspace / Google Cloud Identity Example ---
 # testDataGoogle:
 #   providerURL: https://accounts.google.com # Standard Google OIDC endpoint
@@ -605,6 +630,38 @@ configuration:
    items:
      type: string

+  userIdentifierClaim:
+    type: string
+    description: |
+      Specifies the JWT claim to use as the user identifier for authentication and authorization.
+
+      This allows authentication for users without email addresses, such as Azure AD service
+      accounts or organizational accounts that don't have email attributes configured.
+
+      When set to a non-email claim (e.g., "sub", "oid", "upn"):
+      - AllowedUsers will match against this claim value instead of email
+      - AllowedUserDomains validation is skipped (domains only apply to email addresses)
+      - The session stores this identifier as the user's identity
+      - If the configured claim is missing, falls back to "sub" (required by OIDC spec)
+
+      Common values by provider:
+      - Default: "email" (standard email-based identification)
+      - Azure AD: "sub", "oid" (object ID), "upn" (User Principal Name), "preferred_username"
+      - Generic OIDC: "sub" (always present per OIDC specification)
+      - Keycloak: "sub", "preferred_username"
+
+      Example for Azure AD users without email:
+      ```yaml
+      userIdentifierClaim: sub
+      allowedUsers:
+        - "abc123-user-object-id"
+        - "xyz789-another-user-id"
+      ```
+
+      Default: "email"
+      See: https://github.com/lukaszraczylo/traefikoidc/issues/95
+    required: false
+
  revocationURL:
    type: string
    description: |
@@ -903,6 +960,67 @@ configuration:
      Default: false (replay detection enabled)
    required: false

+  allowPrivateIPAddresses:
+    type: boolean
+    description: |
+      Allow private IP addresses in OIDC provider URLs for internal network deployments.
+
+      By default, the plugin blocks URLs containing private IP address ranges
+      (10.x.x.x, 172.16-31.x.x, 192.168.x.x) to prevent SSRF attacks and ensure
+      OIDC providers are publicly accessible.
+
+      Enable this option when:
+      - Your OIDC provider (e.g., Keycloak) runs on an internal network with private IPs
+      - You don't have DNS resolution available for internal services
+      - Your entire stack runs in a Docker network or Kubernetes cluster with private addressing
+
+      When enabled, the plugin will accept provider URLs like:
+      - https://192.168.1.100:8443/auth/realms/your-realm
+      - https://10.0.0.50:8080/realms/master
+      - https://172.16.0.10/auth
+
+      Security Warning:
+      Enabling this option reduces SSRF protection. Only use in trusted network
+      environments where the OIDC provider is known and controlled. Loopback
+      addresses (127.0.0.1, localhost, ::1) remain blocked even with this option enabled.
+
+      Default: false (private IPs are blocked for security)
+      See: https://github.com/lukaszraczylo/traefikoidc/issues/97
+    required: false
+
+  minimalHeaders:
+    type: boolean
+    description: |
+      Reduce forwarded headers to prevent "431 Request Header Fields Too Large" errors.
+
+      When enabled, the middleware only forwards the X-Forwarded-User header and skips
+      the larger authentication headers that can cause downstream services to reject
+      requests due to header size limits (typically 8KB).
+
+      Headers when disabled (default):
+      - X-Forwarded-User: User's email address (always set)
+      - X-Auth-Request-Redirect: Original request URI
+      - X-Auth-Request-User: User's email address
+      - X-Auth-Request-Token: Full ID token (can be very large with many claims)
+      - X-User-Groups: Comma-separated user groups (if configured)
+      - X-User-Roles: Comma-separated user roles (if configured)
+
+      Headers when enabled:
+      - X-Forwarded-User: User's email address (always set)
+      - X-User-Groups: Comma-separated user groups (if configured, still forwarded)
+      - X-User-Roles: Comma-separated user roles (if configured, still forwarded)
+      - Custom templated headers (still processed)
+
+      Use this option when:
+      - Downstream services return "431 Request Header Fields Too Large" errors
+      - Your ID tokens are large (many claims, long group lists)
+      - You don't need the full ID token forwarded to backend services
+      - You want to reduce request overhead
+
+      Default: false (all headers forwarded for backward compatibility)
+      See: https://github.com/lukaszraczylo/traefikoidc/issues/64
+    required: false
+
  headers:
    type: array
    description: |