gofr-dev/gofr · info

authorization error

Error message

authorization error

What it means

errAuthorizationError is a generic placeholder returned by sanitizeErrorForTrace for any authorization error that is not ErrRoleNotFound or ErrAccessDenied. The middleware records it on the OpenTelemetry span (instead of the real error) to prevent information leakage about internal claim structure into distributed traces. Developers see "authorization error" in trace backends while the detailed cause is only in the HTTP response/audit logs.

Source

Thrown at pkg/gofr/rbac/middleware.go:77

	errInvalidArrayNotation = errors.New("invalid array notation")

	// errInvalidArrayIndex is returned when array index is invalid.
	errInvalidArrayIndex = errors.New("invalid array index")

	// errClaimKeyNotFound is returned when a claim key is not found.
	errClaimKeyNotFound = errors.New("claim key not found")

	// errClaimValueNotArray is returned when a claim value is not an array.
	errClaimValueNotArray = errors.New("claim value is not an array")

	// errArrayIndexOutOfBounds is returned when array index is out of bounds.
	errArrayIndexOutOfBounds = errors.New("array index out of bounds")

	// errInvalidClaimStructure is returned when claim structure is invalid.
	errInvalidClaimStructure = errors.New("invalid claim structure")

	// errAuthorizationError is returned as a generic error message for unknown errors in traces.
	errAuthorizationError = errors.New("authorization error")
)

// Middleware creates an HTTP middleware function that enforces RBAC authorization.
// It extracts the user's role and checks if the role is allowed for the requested route.
//
//nolint:gocognit,gocyclo // Middleware complexity is acceptable due to multiple authorization paths
func Middleware(config *Config) func(handler http.Handler) http.Handler {
	return func(handler http.Handler) http.Handler {
		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
			// If config is nil, allow all requests (fail open)
			if config == nil {
				handler.ServeHTTP(w, r)

				return
			}

			// Check if endpoint is public using unified Endpoints config
			endpoint, isPublic := getEndpointForRequest(r, config)

View on GitHub (pinned to 187eb24962)

Solutions

1. Correlate using the trace ID and inspect the RBAC audit log (AuditLog entries via config.Logger) for the real rejection reason.
2. Check the HTTP response body — default handler returns distinct 401 vs 403 messages with full detail.
3. If you need richer traces, wrap the middleware with your own instrumentation or supply config.ErrorHandler to capture the real error.
4. Do not modify the library to leak internals into traces; keep sanitization and use logs for diagnosis.

Example fix

// before (debugging via traces only, sees "authorization error")
span := trace.SpanFromContext(ctx)
log.Printf("trace err: %v", span) // opaque
// after (capture real error via custom handler)
config.ErrorHandler = func(w http.ResponseWriter, r *http.Request, role, route string, err error) {
    logger.Error("rbac rejection", "route", route, "err", err)
    http.Error(w, "forbidden", http.StatusForbidden)
}

// Trace shows only "authorization error"; correlate via trace ID and fall back to logs:
tid := trace.SpanFromContext(r.Context()).SpanContext().TraceID().String()
logger.Error("rbac rejected request", "trace_id", tid, "route", route)
// then grep audit logs (AuditLog entries) for that correlation ID

When it happens

Trigger: Any auth failure in handleAuthError when tracing is enabled (config.Tracer != nil) and the underlying error is one of the internal sentinel errors (errJWTClaimsNotFound, errClaimPathNotFound, errInvalidArrayNotation, etc.) or any other non-whitelisted error; the span status/recorded error becomes errAuthorizationError.

Common situations: Debugging why requests are rejected via a tracing dashboard (Jaeger/Tempo) and seeing only the opaque "authorization error"; confusing the sanitized trace message with the actual HTTP response; assuming the trace lacks detail due to a bug when redaction is intentional.

Related errors

• failed to parse YAML config file %s: %w
• failed to parse JSON config file %s: %w
• unsupported config file format: %s (supported: .json, .yaml,
• invalid RBAC config: %w
• failed to process unified config: %w

AI-assisted analysis of gofr-dev/gofr@187eb24962 (2026-09-01). Data as JSON: /api/errors/7d111641556757fd. Report an issue: GitHub.