fixup! fixup! Bugfix #51: Ensures that user provided scopes overrides work.

.traefik.yml

@@ -76,6 +76,99 @@ testData:
   oidcEndSessionURL: https://accounts.google.com/logout # Provider's end session endpoint
   enablePKCE: false # Enables PKCE (Proof Key for Code Exchange) for additional security
 
+# --- Provider Specific Configuration Examples ---
+#
+# Below are example configurations tailored for specific OIDC providers.
+# Uncomment and adapt the relevant section for your provider.
+# Remember to replace placeholder values (like client IDs, secrets, domains)
+# with your actual credentials and settings.
+#
+# For all providers, ensure claims like email, roles, and groups are
+# configured to be included in the ID TOKEN. This plugin validates ID tokens.
+
+# --- Keycloak Example ---
+# testDataKeycloak:
+#   providerURL: https://your-keycloak-domain/realms/your-realm # e.g., http://localhost:8080/realms/master
+#   clientID: your-keycloak-client-id
+#   clientSecret: your-keycloak-client-secret # Store securely, e.g., urn:k8s:secret:namespace:secret-name:key
+#   callbackURL: /oauth2/callback
+#   sessionEncryptionKey: "a-very-secure-key-at-least-32-bytes-long-for-keycloak"
+#   scopes: # Default ["openid", "profile", "email"] are usually sufficient. Add others if mappers depend on them.
+#     - roles # Example: if you mapped Keycloak roles to a 'roles' claim in the ID token
+#     - groups # Example: if you mapped Keycloak groups to a 'groups' claim in the ID token
+#   allowedRolesAndGroups: # Corresponds to 'Token Claim Name' in Keycloak mappers
+#     - admin
+#     - editor
+#   # Ensure Keycloak client mappers add 'email', 'roles', 'groups' etc. to the ID Token.
+#   # See README.md "Provider Configuration Recommendations" for Keycloak.
+
+# --- Azure AD (Microsoft Entra ID) Example ---
+# testDataAzureAD:
+#   providerURL: https://login.microsoftonline.com/your-tenant-id/v2.0 # Replace your-tenant-id
+#   clientID: your-azure-ad-client-id
+#   clientSecret: your-azure-ad-client-secret # Store securely
+#   callbackURL: /oauth2/callback
+#   sessionEncryptionKey: "a-very-secure-key-at-least-32-bytes-long-for-azure"
+#   scopes: # Defaults ["openid", "profile", "email"] are good.
+#     # Azure AD may require specific scopes for certain graph API permissions if you were to use the access token,
+#     # but for ID token claims, defaults are often enough.
+#     # Group claims need to be configured in Azure AD App Registration -> Token Configuration -> Add groups claim.
+#   allowedUserDomains:
+#     - yourcompany.com
+#   allowedRolesAndGroups: # If you configured group claims (typically 'groups') or app roles in Azure AD
+#     - "group-object-id-1" # Azure AD group claims can be Object IDs by default
+#     - "AppRoleName"
+#   # See README.md "Provider Configuration Recommendations" for Azure AD.
+
+# --- Google Workspace / Google Cloud Identity Example ---
+# testDataGoogle:
+#   providerURL: https://accounts.google.com # This is standard for Google
+#   clientID: your-google-client-id.apps.googleusercontent.com
+#   clientSecret: your-google-client-secret # Store securely
+#   callbackURL: /oauth2/callback
+#   sessionEncryptionKey: "a-very-secure-key-at-least-32-bytes-long-for-google"
+#   scopes: # Defaults ["openid", "profile", "email"] are handled. Plugin manages Google-specifics.
+#     # Do NOT add 'offline_access' - plugin handles this.
+#   allowedUserDomains: # Useful for Google Workspace users
+#     - your-gsuite-domain.com
+#   # Google includes 'hd' (hosted domain) claim which can be used with allowedUserDomains.
+#   # Other claims like 'email', 'sub', 'name' are standard.
+#   # See README.md "Provider Configuration Recommendations" for Google.
+
+# --- Auth0 Example ---
+# testDataAuth0:
+#   providerURL: https://your-auth0-domain.auth0.com # Replace with your Auth0 domain
+#   clientID: your-auth0-client-id
+#   clientSecret: your-auth0-client-secret # Store securely
+#   callbackURL: /oauth2/callback
+#   sessionEncryptionKey: "a-very-secure-key-at-least-32-bytes-long-for-auth0"
+#   scopes: # Defaults ["openid", "profile", "email"]. Add custom scopes if your Auth0 Rules/Actions require them.
+#     - read:custom_data # Example custom scope
+#   allowedRolesAndGroups: # Based on claims added via Auth0 Rules or Actions (e.g. namespaced claims)
+#     - "https://your-app.com/roles:admin"
+#     - editor
+#   # Use Auth0 Rules or Actions to add custom claims (roles, permissions) to the ID Token.
+#   # Ensure postLogoutRedirectURI is in Auth0 app's "Allowed Logout URLs".
+#   # See README.md "Provider Configuration Recommendations" for Auth0.
+
+# --- Generic OIDC Provider Example ---
+# testDataGenericOIDC:
+#   providerURL: https://your-generic-oidc-provider.com/oidc # Issuer URL for your provider
+#   clientID: your-generic-client-id
+#   clientSecret: your-generic-client-secret # Store securely
+#   callbackURL: /oauth2/callback
+#   sessionEncryptionKey: "a-very-secure-key-at-least-32-bytes-long-for-generic"
+#   scopes: # Must include "openid". "profile" and "email" are common.
+#     - openid
+#     - profile
+#     - email
+#     - custom_scope_for_claims # If your provider needs specific scopes for ID token claims
+#   allowedRolesAndGroups:
+#     - user_role_from_id_token
+#   # Consult your provider's documentation on how to map attributes/roles/groups to ID Token claims.
+#   # Verify ID Token contents (e.g. jwt.io) to see available claims.
+#   # See README.md "Provider Configuration Recommendations" for Generic OIDC.
+
 # Configuration documentation
 configuration:
   providerURL:

README.md

@@ -13,6 +13,8 @@ The Traefik OIDC middleware provides a complete OIDC authentication solution wit
 - Rate limiting
 - Excluded paths (public URLs)
 
+**Important Note on Token Validation:** This middleware performs authentication and claim extraction based on the **ID Token** provided by the OIDC provider. It does not primarily use the Access Token for these purposes (though the Access Token is available for templated headers if needed). Therefore, ensure that all necessary claims (e.g., email, roles, custom attributes) are included in the ID Token by your OIDC provider's configuration.
+
 The middleware has been tested with Auth0, Logto, Google and other standard OIDC providers. It includes special handling for Google's OAuth implementation.
 
 ## Traefik Version Compatibility
@@ -702,6 +704,89 @@ The middleware also sets the following security headers:
 - `X-XSS-Protection: 1; mode=block`
 - `Referrer-Policy: strict-origin-when-cross-origin`
 
+## Provider Configuration Recommendations
+
+**Important: ID Token Validation**
+
+This Traefik OIDC plugin performs authentication and extracts user claims (like email, roles, groups) exclusively from the **ID Token** provided by your OIDC provider. It does not primarily use the Access Token for these critical functions. Therefore, it is crucial to ensure that all necessary claims are included in the ID Token itself. A common issue is that some OIDC providers might, by default, place certain claims only in the Access Token or UserInfo endpoint.
+
+This section provides guidance on configuring popular OIDC providers to work optimally with this plugin.
+
+### Keycloak
+
+Keycloak is highly configurable, which means you need to ensure your client mappers are set up correctly to include necessary claims in the ID Token.
+
+*   **Ensure Claims in ID Token**:
+    *   **Email**: Navigate to your Keycloak realm -> Clients -> Your Client ID -> Mappers. Ensure there's a mapper for 'email' (e.g., a "User Property" mapper for the `email` property) and that "Add to ID token" is **ON**.
+    *   **Roles**: For client roles or realm roles, create or edit mappers (e.g., "User Client Role" or "User Realm Role"). Ensure "Add to ID token" is **ON**. You might want to customize the "Token Claim Name" (e.g., to `roles` or `groups`).
+    *   **Groups**: Similarly, for group membership, use a "Group Membership" mapper and ensure "Add to ID token" is **ON**. Customize the "Token Claim Name" as needed (e.g., `groups`).
+*   **Scopes**: Ensure your client requests appropriate scopes that trigger the inclusion of these claims if your mappers are scope-dependent. The default `openid`, `profile`, `email` scopes are a good starting point.
+*   **Troubleshooting**: If claims are missing, double-check the "Mappers" tab for your client in Keycloak. The "Token Claim Name" you define here is what you'll use in the `allowedRolesAndGroups` or `headers` configuration in this plugin. (See also the [Troubleshooting](#troubleshooting) section for Keycloak).
+
+### Azure AD (Microsoft Entra ID)
+
+Azure AD generally works well with standard OIDC configurations.
+
+*   **ID Token Claims**: Azure AD typically includes standard claims like `email`, `name`, `preferred_username`, and `oid` (Object ID) in the ID Token by default when `openid profile email` scopes are requested.
+*   **Group Claims**: To include group claims in the ID Token, you need to configure this in the Azure AD application registration:
+    *   Go to your App Registration -> Token configuration -> Add groups claim.
+    *   You can choose which types of groups (Security groups, Directory roles, All groups) to include.
+    *   Be aware of the "overage" issue: If a user is a member of too many groups, Azure AD will send a link to fetch groups instead of embedding them. This plugin currently expects group claims to be directly in the ID token. For users with many groups, consider alternative role/permission management strategies.
+    *   The claim name for groups is typically `groups`.
+*   **Optional Claims**: You can add other optional claims via the "Token configuration" section of your App Registration. Ensure these are configured for the ID token.
+*   **Endpoints**: The `providerURL` should be `https://login.microsoftonline.com/{your-tenant-id}/v2.0`. The plugin will auto-discover the necessary endpoints.
+*   **Optimization**: Ensure your application manifest in Azure AD is configured for the desired token version (v1.0 or v2.0). This plugin works with v2.0 endpoints.
+
+### Google Workspace / Google Cloud Identity
+
+Google's OIDC implementation is well-supported.
+
+*   **Optimal Configuration**: The plugin automatically handles Google-specific requirements, such as using `access_type=offline` and `prompt=consent` to ensure refresh tokens are issued for long-lived sessions. You do not need to add `offline_access` to scopes.
+*   **ID Token Claims**: Google includes standard claims like `email`, `sub`, `name`, `given_name`, `family_name`, `picture` in the ID Token by default with `openid profile email` scopes.
+*   **Hosted Domain (hd claim)**: If you are using Google Workspace and want to restrict access to users within your organization's domain, Google includes an `hd` (hosted domain) claim in the ID Token. You can use this with the `allowedUserDomains` setting or for custom header logic.
+*   **Best Practices**:
+    *   Use the `providerURL`: `https://accounts.google.com`.
+    *   Ensure your OAuth consent screen in Google Cloud Console is configured correctly and published. For production, it should be "External" and in "Production" status. "Testing" status limits refresh token lifetime.
+    *   Refer to the [Google OAuth Compatibility Fix](#google-oauth-compatibility-fix) section for more details on how the plugin handles Google's specifics.
+
+### Auth0
+
+Auth0 is generally OIDC compliant and works well.
+
+*   **ID Token Claims**:
+    *   To add custom claims or standard claims not included by default (like roles or permissions) to the ID Token, you'll need to use Auth0 Rules or Actions.
+    *   **Using Actions (Recommended)**: Create a custom Action that runs after login to add claims to the ID Token. Example:
+        ```javascript
+        // Auth0 Action to add email and roles to ID Token
+        exports.onExecutePostLogin = async (event, api) => {
+          const namespace = 'https://your-app.com/'; // Or your custom namespace
+          if (event.authorization) {
+            api.idToken.setCustomClaim(namespace + 'roles', event.authorization.roles);
+            api.idToken.setCustomClaim('email', event.user.email); // Standard claim, ensure it's there
+            // Add other claims as needed
+          }
+        };
+        ```
+    *   Ensure the claims you add (e.g., `https://your-app.com/roles`) are then used in the plugin's `allowedRolesAndGroups` or `headers` configuration.
+*   **Scopes**: Request appropriate scopes. You might need custom scopes if your Actions/Rules depend on them to add specific claims.
+*   **Endpoints**: Your `providerURL` will be `https://your-auth0-domain.auth0.com`.
+*   **Logout**: Ensure `postLogoutRedirectURI` is registered in your Auth0 application settings under "Allowed Logout URLs".
+
+### Generic OIDC Providers
+
+For other OIDC providers (e.g., Okta, Zitadel, self-hosted solutions):
+
+*   **ID Token is Key**: The primary requirement is that all claims needed for authentication decisions (email, roles, groups, custom attributes for headers) **must** be included in the ID Token.
+*   **Check Provider Documentation**: Consult your OIDC provider's documentation on how to:
+    *   Configure client applications.
+    *   Map user attributes, roles, or group memberships to claims in the ID Token.
+    *   Define custom scopes if they are necessary to include certain claims.
+*   **Standard Endpoints**: Ensure your provider exposes a standard OIDC discovery document (`.well-known/openid-configuration`) at the `providerURL`. The plugin uses this to find authorization, token, JWKS, and end_session endpoints.
+*   **Scopes**: Always include `openid` in your scopes. `profile` and `email` are generally recommended. Add other scopes as required by your provider to release specific claims to the ID Token.
+*   **Troubleshooting**: If the plugin isn't working as expected (e.g., access denied, claims missing), the first step is to decode the ID Token received from your provider (e.g., using jwt.io) to verify its contents. This will show you exactly what claims the plugin is seeing.
+
+For common issues and general troubleshooting, please refer to the [Troubleshooting](#troubleshooting) section.
+
 ## Troubleshooting
 
 ### Logging
@@ -726,6 +811,12 @@ logLevel: debug
    - Verify you're using a version of the middleware that includes the Google OAuth compatibility fix.
    - For more details, see the [Google OAuth Compatibility Fix](#google-oauth-compatibility-fix) section or the [detailed documentation](docs/google-oauth-fix.md).
 
+7.  **Keycloak: Claims Missing from ID Token (e.g., email, roles)**
+
+    If you are using Keycloak and claims like `email`, `roles`, or `groups` are missing from the ID Token, this plugin may not function as expected (e.g., for domain restrictions or RBAC).
+    *   **Solution**: This plugin validates the **ID Token**. You **must** configure Keycloak client mappers to add all necessary claims (email, roles, groups, etc.) to the ID Token.
+    *   For detailed instructions, please see the [Keycloak](#keycloak) section under [Provider Configuration Recommendations](#provider-configuration-recommendations).
+
 ## Contributing
 
 Contributions are welcome! Please feel free to submit a Pull Request.

helpers.go

@@ -404,3 +404,20 @@ func BuildLogoutURL(endSessionURL, idToken, postLogoutRedirectURI string) (strin
 
 	return u.String(), nil
 }
+
+// deduplicateScopes removes duplicate strings from a slice while preserving order.
+// The first occurrence of each scope is kept.
+func deduplicateScopes(scopes []string) []string {
+	if len(scopes) == 0 {
+		return []string{}
+	}
+	seen := make(map[string]struct{})
+	result := []string{}
+	for _, scope := range scopes {
+		if _, ok := seen[scope]; !ok {
+			seen[scope] = struct{}{}
+			result = append(result, scope)
+		}
+	}
+	return result
+}

main.go

@@ -614,6 +614,7 @@ func New(ctx context.Context, next http.Handler, config *Config, name string) (h
 
 	// Initialize logger
 	logger := NewLogger(config.LogLevel)
+	// Log the scopes received from Traefik to help diagnose duplication issues
 	// Ensure key meets minimum length requirement
 	if len(config.SessionEncryptionKey) < minEncryptionKeyLength {
 		if runtime.Compiler == "yaegi" {
@@ -660,10 +661,19 @@ func New(ctx context.Context, next http.Handler, config *Config, name string) (h
 		enablePKCE:     config.EnablePKCE,
 		overrideScopes: config.OverrideScopes,
 		scopes: func() []string {
+			// Deduplicate user-provided scopes from the configuration.
+			userProvidedScopes := deduplicateScopes(config.Scopes)
+
 			if config.OverrideScopes {
-				return append([]string(nil), config.Scopes...)
+				// When overriding, only the explicitly user-provided scopes are used.
+				// Default scopes like "openid", "profile", "email" are NOT added.
+				return userProvidedScopes
 			}
-			return mergeScopes([]string{"openid", "profile", "email"}, config.Scopes)
+
+			// When not overriding (overrideScopes is false), merge user-provided scopes
+			// with the system's default scopes.
+			defaultSystemScopes := []string{"openid", "profile", "email"}
+			return deduplicateScopes(mergeScopes(defaultSystemScopes, userProvidedScopes))
 		}(),
 		limiter:               rate.NewLimiter(rate.Every(time.Second), config.RateLimit),
 		tokenCache:            cacheManager.GetSharedTokenCache(),
@@ -723,7 +733,7 @@ func New(ctx context.Context, next http.Handler, config *Config, name string) (h
 	}
 
 	startReplayCacheCleanup(pluginCtx, logger)
-
+	logger.Debugf("TraefikOidc.New: Final t.scopes initialized to: %v", t.scopes)
 	go t.initializeMetadata(config.ProviderURL)
 
 	return t, nil
@@ -1687,27 +1697,40 @@ func (t *TraefikOidc) buildAuthURL(redirectURL, state, nonce, codeChallenge stri
 			}
 		}
 
-		if !hasOfflineAccess {
-			scopes = append(scopes, "offline_access")
-			t.logger.Debug("Azure AD provider detected, added offline_access scope for refresh tokens")
+		// For Azure AD, add offline_access scope if not overriding or if overriding with no user scopes
+		if !t.overrideScopes || (t.overrideScopes && len(t.scopes) == 0) {
+			if !hasOfflineAccess {
+				scopes = append(scopes, "offline_access")
+				t.logger.Debugf("Azure AD provider: Added offline_access scope (overrideScopes: %t, user scopes count: %d)", t.overrideScopes, len(t.scopes))
+			}
+		} else {
+			t.logger.Debugf("Azure AD provider: User is overriding scopes (count: %d), offline_access not automatically added.", len(t.scopes))
 		}
 	} else {
 		// For other providers, use the standard offline_access scope
-		hasOfflineAccess := false
-		for _, scope := range scopes {
-			if scope == "offline_access" {
-				hasOfflineAccess = true
-				break
+		// Only add offline_access if overrideScopes is false,
+		// or if overrideScopes is true AND no scopes were provided by the user (edge case, effectively defaults)
+		if !t.overrideScopes || (t.overrideScopes && len(t.scopes) == 0) {
+			hasOfflineAccess := false
+			for _, scope := range scopes {
+				if scope == "offline_access" {
+					hasOfflineAccess = true
+					break
+				}
 			}
-		}
-
-		if !hasOfflineAccess {
-			scopes = append(scopes, "offline_access")
+			if !hasOfflineAccess {
+				scopes = append(scopes, "offline_access")
+				t.logger.Debugf("Standard provider: Added offline_access scope (overrideScopes: %t, user scopes count: %d)", t.overrideScopes, len(t.scopes))
+			}
+		} else {
+			t.logger.Debugf("Standard provider: User is overriding scopes (count: %d), offline_access not automatically added.", len(t.scopes))
 		}
 	}
 
 	if len(scopes) > 0 {
-		params.Set("scope", strings.Join(scopes, " "))
+		finalScopeString := strings.Join(scopes, " ")
+		params.Set("scope", finalScopeString)
+		t.logger.Debugf("TraefikOidc.buildAuthURL: Final scope string being sent to OIDC provider: %s", finalScopeString)
 	}
 
 	// Use buildURLWithParams which handles potential relative authURL from metadata

main_test.go

@@ -3998,9 +3998,12 @@ func TestBuildAuthURLWithMergedScopes(t *testing.T) {
 		t.Run(tc.name, func(t *testing.T) {
 			// Configure the test instance with specific scopes
 			tOidc := ts.tOidc
-			tOidc.scopes = tc.scopes
+			tOidc.scopes = tc.scopes // These scopes are already deduplicated by New()
 			tOidc.authURL = "https://auth.example.com/oauth/authorize"
 			tOidc.issuerURL = "https://auth.example.com"
+			// Reset overrideScopes for each test case, as it's part of tOidc state
+			// Default to false, specific tests will set it.
+			tOidc.overrideScopes = false
 
 			// Build auth URL
 			result := tOidc.buildAuthURL("https://app.example.com/callback", "test-state", "test-nonce", "")
@@ -4019,3 +4022,182 @@ func TestBuildAuthURLWithMergedScopes(t *testing.T) {
 		})
 	}
 }
+
+// TestBuildAuthURL_OverrideScopes_And_OfflineAccess tests the offline_access logic in buildAuthURL
+// considering the overrideScopes flag.
+func TestBuildAuthURL_OverrideScopes_And_OfflineAccess(t *testing.T) {
+	ts := &TestSuite{t: t}
+	ts.Setup() // Sets up ts.tOidc
+
+	tests := []struct {
+		name           string
+		initialScopes  []string // Scopes as they would be in tOidc.scopes (after New processing)
+		overrideScopes bool
+		isGoogle       bool // To test Google-specific handling
+		isAzure        bool // To test Azure-specific handling
+		expectedParams map[string]string
+		expectedScope  string // The final scope string expected in the URL
+	}{
+		{
+			name:           "Override false, no user scopes, non-Google/Azure",
+			initialScopes:  []string{"openid", "profile", "email"}, // Defaults from New() when config.Scopes is empty
+			overrideScopes: false,
+			expectedScope:  "openid profile email offline_access",
+		},
+		{
+			name:           "Override false, user scopes without offline_access, non-Google/Azure",
+			initialScopes:  []string{"openid", "profile", "email", "custom1"}, // Merged and deduplicated by New()
+			overrideScopes: false,
+			expectedScope:  "openid profile email custom1 offline_access",
+		},
+		{
+			name:           "Override false, user scopes with offline_access, non-Google/Azure",
+			initialScopes:  []string{"openid", "profile", "email", "offline_access", "custom1"},
+			overrideScopes: false,
+			expectedScope:  "openid profile email offline_access custom1", // Order might vary based on merge, but offline_access present
+		},
+		{
+			name:           "Override true, user scopes without offline_access, non-Google/Azure",
+			initialScopes:  []string{"custom1", "custom2"}, // Directly from config.Scopes, deduplicated
+			overrideScopes: true,
+			expectedScope:  "custom1 custom2", // offline_access NOT added
+		},
+		{
+			name:           "Override true, user scopes with offline_access, non-Google/Azure",
+			initialScopes:  []string{"custom1", "offline_access", "custom2"},
+			overrideScopes: true,
+			expectedScope:  "custom1 offline_access custom2", // User explicitly included it
+		},
+		{
+			name:           "Override true, no user scopes (edge case), non-Google/Azure",
+			initialScopes:  []string{}, // config.Scopes was empty
+			overrideScopes: true,
+			// In this edge case, buildAuthURL's logic `(t.overrideScopes && len(t.scopes) == 0)`
+			// will lead to offline_access being added, as it behaves like defaults.
+			expectedScope: "offline_access",
+		},
+		// Google Provider Tests (access_type=offline, prompt=consent)
+		{
+			name:           "Google, Override false, no user scopes",
+			initialScopes:  []string{"openid", "profile", "email"},
+			overrideScopes: false,
+			isGoogle:       true,
+			expectedParams: map[string]string{"access_type": "offline", "prompt": "consent"},
+			expectedScope:  "openid profile email", // No offline_access scope for Google
+		},
+		{
+			name:           "Google, Override true, user scopes",
+			initialScopes:  []string{"custom1", "custom2"},
+			overrideScopes: true,
+			isGoogle:       true,
+			expectedParams: map[string]string{"access_type": "offline", "prompt": "consent"},
+			expectedScope:  "custom1 custom2", // No offline_access scope for Google
+		},
+		// Azure Provider Tests (response_mode=query, offline_access scope added if not present by user)
+		{
+			name:           "Azure, Override false, no user scopes",
+			initialScopes:  []string{"openid", "profile", "email"},
+			overrideScopes: false,
+			isAzure:        true,
+			expectedParams: map[string]string{"response_mode": "query"},
+			expectedScope:  "openid profile email offline_access",
+		},
+		{
+			name:           "Azure, Override true, user scopes without offline_access",
+			initialScopes:  []string{"custom1", "custom2"},
+			overrideScopes: true,
+			isAzure:        true,
+			expectedParams: map[string]string{"response_mode": "query"},
+			expectedScope:  "custom1 custom2", // offline_access NOT added by default when override is true
+		},
+		{
+			name:           "Azure, Override true, user scopes with offline_access",
+			initialScopes:  []string{"custom1", "offline_access"},
+			overrideScopes: true,
+			isAzure:        true,
+			expectedParams: map[string]string{"response_mode": "query"},
+			expectedScope:  "custom1 offline_access",
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			tOidc := ts.tOidc
+			tOidc.scopes = tc.initialScopes // Set the scopes as if they came from New()
+			tOidc.overrideScopes = tc.overrideScopes
+
+			// Adjust issuerURL for provider-specific tests
+			originalIssuerURL := tOidc.issuerURL
+			if tc.isGoogle {
+				tOidc.issuerURL = "https://accounts.google.com"
+			} else if tc.isAzure {
+				tOidc.issuerURL = "https://login.microsoftonline.com/common"
+			} else {
+				tOidc.issuerURL = "https://generic-provider.com" // Non-Google/Azure
+			}
+
+			authURLString := tOidc.buildAuthURL("http://localhost/callback", "state123", "nonce123", "challenge123")
+			parsedAuthURL, err := url.Parse(authURLString)
+			if err != nil {
+				t.Fatalf("Failed to parse auth URL: %v", err)
+			}
+			query := parsedAuthURL.Query()
+
+			actualScope := query.Get("scope")
+			if actualScope != tc.expectedScope {
+				t.Errorf("Expected scope string %q, got %q", tc.expectedScope, actualScope)
+			}
+
+			if tc.expectedParams != nil {
+				for k, v := range tc.expectedParams {
+					if query.Get(k) != v {
+						t.Errorf("Expected param %s=%s, got %s", k, v, query.Get(k))
+					}
+				}
+			}
+
+			// Restore original issuerURL for next test
+			tOidc.issuerURL = originalIssuerURL
+		})
+	}
+}
+
+// TestBuildAuthURL_SpecificUserCase tests the buildAuthURL function with the specific user-reported scenario.
+func TestBuildAuthURL_SpecificUserCase(t *testing.T) {
+	ts := &TestSuite{t: t}
+	ts.Setup() // Basic setup for tOidc
+
+	// Configure the TraefikOidc instance for the specific scenario
+	tOidc := ts.tOidc
+	tOidc.scopes = []string{"email", "test3"} // This is what t.scopes should be after New()
+	tOidc.overrideScopes = true
+	tOidc.issuerURL = "https://generic-provider.com"    // Non-Google/Azure
+	tOidc.authURL = "https://generic-provider.com/auth" // Dummy auth URL
+	tOidc.clientID = "test-client-id"
+
+	// Expected scope string in the URL
+	expectedScopeString := "email test3"
+
+	// Call buildAuthURL
+	authURLString := tOidc.buildAuthURL("http://localhost/callback", "test-state", "test-nonce", "")
+
+	// Parse the resulting URL
+	parsedAuthURL, err := url.Parse(authURLString)
+	if err != nil {
+		t.Fatalf("Failed to parse generated auth URL %q: %v", authURLString, err)
+	}
+
+	// Get the 'scope' query parameter
+	actualScopeString := parsedAuthURL.Query().Get("scope")
+
+	// Assert that the scope string is as expected
+	if actualScopeString != expectedScopeString {
+		t.Errorf("Expected scope parameter to be %q, but got %q. Full URL: %s",
+			expectedScopeString, actualScopeString, authURLString)
+	}
+
+	// Additionally, ensure 'offline_access' was not added
+	if strings.Contains(actualScopeString, "offline_access") {
+		t.Errorf("Scope parameter %q should not contain 'offline_access' when overrideScopes is true and it's not in tOidc.scopes", actualScopeString)
+	}
+}

scopes_test.go

@@ -1,6 +1,7 @@
 package traefikoidc
 
 import (
+	"net/url"
 	"reflect"
 	"testing"
 )
@@ -54,71 +55,308 @@ func TestMergeScopes(t *testing.T) {
 	}
 }
 
+func TestDeduplicateScopes(t *testing.T) {
+	testCases := []struct {
+		name           string
+		inputScopes    []string
+		expectedScopes []string
+	}{
+		{
+			name:           "No duplicates",
+			inputScopes:    []string{"openid", "profile", "email"},
+			expectedScopes: []string{"openid", "profile", "email"},
+		},
+		{
+			name:           "Simple duplicates",
+			inputScopes:    []string{"openid", "profile", "openid", "email"},
+			expectedScopes: []string{"openid", "profile", "email"},
+		},
+		{
+			name:           "Multiple duplicates",
+			inputScopes:    []string{"scope1", "scope2", "scope1", "scope2", "scope1"},
+			expectedScopes: []string{"scope1", "scope2"},
+		},
+		{
+			name:           "Empty input",
+			inputScopes:    []string{},
+			expectedScopes: []string{},
+		},
+		{
+			name:           "Nil input",
+			inputScopes:    nil,
+			expectedScopes: []string{},
+		},
+		{
+			name:           "Single element",
+			inputScopes:    []string{"openid"},
+			expectedScopes: []string{"openid"},
+		},
+		{
+			name:           "All duplicates",
+			inputScopes:    []string{"test", "test", "test"},
+			expectedScopes: []string{"test"},
+		},
+	}
+
+	for _, tc := range testCases {
+		t.Run(tc.name, func(t *testing.T) {
+			result := deduplicateScopes(tc.inputScopes)
+			if !reflect.DeepEqual(result, tc.expectedScopes) {
+				t.Errorf("Expected %v, got %v", tc.expectedScopes, result)
+			}
+		})
+	}
+}
+
 func TestScopesConfiguration(t *testing.T) {
 	defaultScopes := []string{"openid", "profile", "email"}
-	userScopes := []string{"roles", "custom_scope"}
 
-	t.Run("Default Append Behavior", func(t *testing.T) {
-		// Create config with user scopes but overrideScopes=false
-		config := &Config{
-			Scopes:         userScopes,
-			OverrideScopes: false,
-		}
+	testCases := []struct {
+		name           string
+		configScopes   []string // Scopes from Traefik config
+		overrideScopes bool
+		expectedResult []string
+	}{
+		{
+			name:           "Default Append Behavior - No user scopes",
+			configScopes:   []string{},
+			overrideScopes: false,
+			expectedResult: []string{"openid", "profile", "email"},
+		},
+		{
+			name:           "Default Append Behavior - With user scopes",
+			configScopes:   []string{"roles", "custom_scope"},
+			overrideScopes: false,
+			expectedResult: []string{"openid", "profile", "email", "roles", "custom_scope"},
+		},
+		{
+			name:           "Default Append Behavior - With duplicate user scopes",
+			configScopes:   []string{"roles", "custom_scope", "roles"},
+			overrideScopes: false,
+			expectedResult: []string{"openid", "profile", "email", "roles", "custom_scope"},
+		},
+		{
+			name:           "Default Append Behavior - User scopes overlap with defaults",
+			configScopes:   []string{"openid", "roles", "profile"},
+			overrideScopes: false,
+			expectedResult: []string{"openid", "profile", "email", "roles"},
+		},
+		{
+			name:           "Override Behavior - With user scopes",
+			configScopes:   []string{"roles", "custom_scope"},
+			overrideScopes: true,
+			expectedResult: []string{"roles", "custom_scope"},
+		},
+		{
+			name:           "Override Behavior - With duplicate user scopes",
+			configScopes:   []string{"roles", "custom_scope", "roles"},
+			overrideScopes: true,
+			expectedResult: []string{"roles", "custom_scope"},
+		},
+		{
+			name:           "Override Behavior - Empty user scopes",
+			configScopes:   []string{},
+			overrideScopes: true,
+			expectedResult: []string{},
+		},
+		{
+			name:           "Override Behavior - Nil user scopes",
+			configScopes:   nil,
+			overrideScopes: true,
+			expectedResult: []string{}, // Deduplicate will handle nil as empty
+		},
+		{
+			name:           "Override Behavior - Single user scope",
+			configScopes:   []string{"email"},
+			overrideScopes: true,
+			expectedResult: []string{"email"},
+		},
+	}
 
-		// Simulate middleware initialization
-		var result []string
-		if config.OverrideScopes {
-			result = append([]string(nil), config.Scopes...)
-		} else {
-			result = mergeScopes(defaultScopes, config.Scopes)
-		}
+	for _, tc := range testCases {
+		t.Run(tc.name, func(t *testing.T) {
+			// Simulate the logic within TraefikOidc.New for setting t.scopes
+			var result []string
+			uniqueConfigScopes := deduplicateScopes(tc.configScopes)
+			if tc.overrideScopes {
+				result = uniqueConfigScopes
+			} else {
+				result = mergeScopes(defaultScopes, uniqueConfigScopes)
+			}
 
-		// Expect defaultScopes + userScopes with deduplication
-		expectedScopes := []string{"openid", "profile", "email", "roles", "custom_scope"}
-		if !reflect.DeepEqual(result, expectedScopes) {
-			t.Errorf("Expected %v, got %v", expectedScopes, result)
-		}
-	})
-
-	t.Run("Override Behavior", func(t *testing.T) {
-		// Create config with user scopes and overrideScopes=true
-		config := &Config{
-			Scopes:         userScopes,
-			OverrideScopes: true,
-		}
-
-		// Simulate middleware initialization
-		var result []string
-		if config.OverrideScopes {
-			result = append([]string(nil), config.Scopes...)
-		} else {
-			result = mergeScopes(defaultScopes, config.Scopes)
-		}
-
-		// Expect only userScopes
-		if !reflect.DeepEqual(result, userScopes) {
-			t.Errorf("Expected %v, got %v", userScopes, result)
-		}
-	})
-
-	t.Run("Empty Scopes with Override", func(t *testing.T) {
-		// Create config with empty scopes and overrideScopes=true
-		config := &Config{
-			Scopes:         []string{},
-			OverrideScopes: true,
-		}
-
-		// Simulate middleware initialization
-		var result []string
-		if config.OverrideScopes {
-			result = append([]string(nil), config.Scopes...)
-		} else {
-			result = mergeScopes(defaultScopes, config.Scopes)
-		}
-
-		// Expect empty scopes - check length instead of DeepEqual
-		if len(result) != 0 {
-			t.Errorf("Expected empty slice, got %v with length %d", result, len(result))
-		}
-	})
+			if !reflect.DeepEqual(result, tc.expectedResult) {
+				t.Errorf("Expected scopes %v, got %v", tc.expectedResult, result)
+			}
+		})
+	}
+}
+
+func TestBuildAuthURLScopeHandling(t *testing.T) {
+	ts := &TestSuite{t: t}
+	ts.Setup() // Basic setup for TraefikOidc instance
+
+	// Default scopes expected if not overridden and no user scopes provided
+	defaultInitialScopes := []string{"openid", "profile", "email"}
+
+	testCases := []struct {
+		name                string
+		configScopes        []string // Scopes from Traefik config
+		overrideScopes      bool
+		isGoogle            bool
+		isAzure             bool
+		expectedScopeString string // Expected final scope string in the auth URL
+		expectedParams      map[string]string
+	}{
+		{
+			name:                "Deduplication: Default append, duplicate in user scopes",
+			configScopes:        []string{"openid", "custom", "profile", "custom"},
+			overrideScopes:      false,
+			expectedScopeString: "openid profile email custom offline_access",
+		},
+		{
+			name:                "Deduplication: Override, duplicate in user scopes",
+			configScopes:        []string{"openid", "custom", "profile", "custom"},
+			overrideScopes:      true,
+			expectedScopeString: "openid custom profile", // offline_access not added
+		},
+		{
+			name:                "Override True: No automatic offline_access",
+			configScopes:        []string{"scope1", "scope2"},
+			overrideScopes:      true,
+			expectedScopeString: "scope1 scope2",
+		},
+		{
+			name:                "Override True: User includes offline_access",
+			configScopes:        []string{"scope1", "offline_access", "scope2"},
+			overrideScopes:      true,
+			expectedScopeString: "scope1 offline_access scope2",
+		},
+		{
+			name:                "Override False: Automatic offline_access added",
+			configScopes:        []string{"scope1", "scope2"},
+			overrideScopes:      false,
+			expectedScopeString: "openid profile email scope1 scope2 offline_access",
+		},
+		{
+			name:                "Override False: User includes offline_access (deduplicated)",
+			configScopes:        []string{"scope1", "offline_access", "scope2"},
+			overrideScopes:      false,
+			expectedScopeString: "openid profile email scope1 offline_access scope2",
+		},
+		{
+			name:                "Integration: Duplicate scopes in config, override true",
+			configScopes:        []string{"scope1", "scope1", "scope2"},
+			overrideScopes:      true,
+			expectedScopeString: "scope1 scope2",
+		},
+		{
+			name:                "Integration: No auto offline_access with override true",
+			configScopes:        []string{"scope1", "scope2"},
+			overrideScopes:      true,
+			expectedScopeString: "scope1 scope2",
+		},
+		{
+			name:                "Integration: Duplicates and no auto offline_access with override true",
+			configScopes:        []string{"scope1", "scope1", "scope2"},
+			overrideScopes:      true,
+			expectedScopeString: "scope1 scope2",
+		},
+		{
+			name:                "Integration: Google provider, override false, no user scopes",
+			configScopes:        []string{},
+			overrideScopes:      false,
+			isGoogle:            true,
+			expectedScopeString: "openid profile email", // Google uses access_type=offline param
+			expectedParams:      map[string]string{"access_type": "offline", "prompt": "consent"},
+		},
+		{
+			name:                "Integration: Google provider, override true, user scopes",
+			configScopes:        []string{"custom1", "custom2"},
+			overrideScopes:      true,
+			isGoogle:            true,
+			expectedScopeString: "custom1 custom2", // Google uses access_type=offline param
+			expectedParams:      map[string]string{"access_type": "offline", "prompt": "consent"},
+		},
+		{
+			name:                "Integration: Azure provider, override false, no user scopes",
+			configScopes:        []string{},
+			overrideScopes:      false,
+			isAzure:             true,
+			expectedScopeString: "openid profile email offline_access", // Azure adds offline_access scope
+			expectedParams:      map[string]string{"response_mode": "query"},
+		},
+		{
+			name:                "Integration: Azure provider, override true, user scopes without offline_access",
+			configScopes:        []string{"custom1", "custom2"},
+			overrideScopes:      true,
+			isAzure:             true,
+			expectedScopeString: "custom1 custom2", // Azure respects override
+			expectedParams:      map[string]string{"response_mode": "query"},
+		},
+		{
+			name:                "Integration: Azure provider, override true, user scopes with offline_access",
+			configScopes:        []string{"custom1", "offline_access"},
+			overrideScopes:      true,
+			isAzure:             true,
+			expectedScopeString: "custom1 offline_access", // Azure respects override
+			expectedParams:      map[string]string{"response_mode": "query"},
+		},
+	}
+
+	for _, tc := range testCases {
+		t.Run(tc.name, func(t *testing.T) {
+			// Simulate the TraefikOidc instance's scope initialization
+			var initializedScopes []string
+			uniqueConfigScopes := deduplicateScopes(tc.configScopes)
+			if tc.overrideScopes {
+				initializedScopes = uniqueConfigScopes
+			} else {
+				initializedScopes = mergeScopes(defaultInitialScopes, uniqueConfigScopes)
+			}
+
+			// Create a new TraefikOidc instance for this test case
+			// to ensure proper isolation of 'scopes' and 'overrideScopes' fields.
+			// We use parts of the TestSuite's tOidc for common setup like logger, clientID etc.
+			// but override the scope-related fields.
+			testOidc := &TraefikOidc{
+				clientID:       ts.tOidc.clientID,
+				logger:         ts.tOidc.logger,
+				scopes:         initializedScopes, // Use scopes processed as New() would
+				overrideScopes: tc.overrideScopes,
+				// Set other necessary fields for buildAuthURL to function
+				authURL:    "https://provider.com/auth", // Dummy authURL
+				issuerURL:  "https://provider.com",      // Dummy issuerURL
+				httpClient: ts.tOidc.httpClient,         // Reuse from TestSuite
+			}
+
+			originalIssuerURL := testOidc.issuerURL
+			if tc.isGoogle {
+				testOidc.issuerURL = "https://accounts.google.com"
+			} else if tc.isAzure {
+				testOidc.issuerURL = "https://login.microsoftonline.com/common"
+			}
+
+			authURLString := testOidc.buildAuthURL("http://localhost/callback", "state", "nonce", "challenge")
+			parsedURL, err := url.Parse(authURLString)
+			if err != nil {
+				t.Fatalf("Failed to parse auth URL: %v", err)
+			}
+
+			query := parsedURL.Query()
+			actualScopeString := query.Get("scope")
+
+			if actualScopeString != tc.expectedScopeString {
+				t.Errorf("Expected scope string %q, got %q", tc.expectedScopeString, actualScopeString)
+			}
+
+			if tc.expectedParams != nil {
+				for k, v := range tc.expectedParams {
+					if query.Get(k) != v {
+						t.Errorf("Expected param %s=%s, got %s", k, v, query.Get(k))
+					}
+				}
+			}
+			testOidc.issuerURL = originalIssuerURL // Restore
+		})
+	}
 }