Fix remaining review comments

- Standardize terminology: use 'OIDC claims' consistently
- Clarify audience verification comment
- Improve error handling when no bearer method is configured
- Fix Authorization header case in documentation (Bearer not bearer)

Co-authored-by: rchincha <45800463+rchincha@users.noreply.github.com>

pkg/api/authn.go

@@ -624,7 +624,14 @@ func bearerAuthHandler(ctlr *Controller) mux.MiddlewareFunc {
 			}
 
 			// No authentication succeeded
-			ctlr.Log.Error().Msg("bearer authentication failed")
+			if isAuthorizationHeaderEmpty(request) {
+				// No bearer token provided and no authentication method configured
+				ctlr.Log.Debug().Msg("no bearer token provided")
+			} else {
+				// Bearer token provided but authentication failed
+				ctlr.Log.Error().Msg("bearer authentication failed")
+			}
+
 			response.Header().Set("Content-Type", "application/json")
 			zcommon.WriteJSON(response, http.StatusUnauthorized, apiErr.NewError(apiErr.UNAUTHORIZED))
 		})

pkg/api/bearer_oidc.go

@@ -89,7 +89,7 @@ func (a *OIDCBearerAuthorizer) Authenticate(ctx context.Context, header string)
 		return "", nil, fmt.Errorf("%w: %w", zerr.ErrInvalidBearerToken, err)
 	}
 
-	// Verify audience manually (the verifier checks against the first audience only, but we need to check all)
+	// Additional audience verification to support multiple audiences
 	if !a.verifyAudience(idToken) {
 		a.log.Debug().Str("token_aud", fmt.Sprintf("%v", idToken.Audience)).
 			Strs("accepted_aud", a.audiences).

pkg/api/config/config.go

@@ -248,12 +248,12 @@ type OpenIDProviderConfig struct {
 	ClaimMapping    *ClaimMapping `mapstructure:",omitempty"`
 }
 
-// ClaimMapping specifies how OpenID claims are mapped to application fields.
+// ClaimMapping specifies how OIDC claims are mapped to application fields.
 // It allows customization of which claim is used as the username when authenticating users.
 type ClaimMapping struct {
-	// Username specifies which OpenID claim to use as the username for the authenticated user.
+	// ClaimMapping specifies which OIDC claim to use as the username for the authenticated user.
 	// Acceptable values include "preferred_username", "email", "sub", "name", or any custom claim name.
-	// If not configured, the default is "email".
+	// If not configured, the default is "sub".
 	Username string `mapstructure:"username,omitempty"`
 }