gRPC Authentication Middleware#

Flipt's gRPC authentication middleware lives in internal/server/authn/middleware/grpc/middleware.go and enforces identity checks on all incoming gRPC unary calls. It is composed of several interceptors that run in sequence, each responsible for a different authentication mechanism or enforcement check.

Interceptor Chain#

The interceptors are assembled in internal/cmd/grpc.go and appended to the base interceptor list. The core auth interceptors are constructed by authenticationGRPC() and then followed by FliptAcceptServerVersionUnaryInterceptor and EvaluationUnaryInterceptor.

The four primary authentication interceptors are:

A fifth interceptor, NamespaceMatchingInterceptor, enforces namespace scoping for static token authentications.

Token extraction reads from the gRPC metadata authorization key (expecting Bearer <token> or JWT <token>) or falls back to the grpcgateway-cookie header 1.

Skipping Authentication#

Servers can opt out of authentication in two ways:

1. Interface-based skip: implement SkipsAuthenticationServer (SkipsAuthentication(ctx) bool) 2.
2. Instance-based skip: pass WithServerSkipsAuthentication(server) when wiring up interceptors 3.

In practice, the health server always skips authentication 4, and the management, evaluation, OFREP servers can be selectively excluded via config flags authentication.exclude.* 5.

Log Levels for Unauthenticated Requests#

All auth failures emit logs at ERROR level. This is consistent across all interceptors:

• AuthenticationRequiredInterceptor: logs "unauthenticated" with reason "authentication required" 6.
• ClientTokenAuthenticationInterceptor: logs "unauthenticated" for missing metadata, missing token, token lookup failure, and expired tokens .
• JWTAuthenticationInterceptor: logs "unauthenticated" for missing metadata, missing token, and validation errors .
• EmailMatchingInterceptor: logs "unauthenticated" with reason "email is not allowed" at ERROR 14.
• Skipped servers log "skipping authentication for server" at DEBUG level 15.

Log Level Configuration#

Flipt exposes two separate log level knobs 16:

The grpc_level is applied to the underlying gRPC framework logger (not to Flipt's own auth middleware) via grpc_zap.ReplaceGrpcLoggerV2 17. This means:

• Auth middleware failures are controlled by the global log.level. They are always emitted at ERROR, so they appear at any level setting of ERROR or below (i.e., DEBUG, INFO, WARN, ERROR).
• Internal gRPC library noise (e.g., transport-layer events) is controlled by log.grpc_level, which defaults to ERROR to suppress verbose gRPC framework messages.

Environment variable overrides follow the pattern FLIPT_LOG_LEVEL and FLIPT_LOG_GRPC_LEVEL 18.

The LogConfig struct defaults are set in 19:

log:
  level: INFO
  grpc_level: ERROR
  encoding: console

Key Source Files#