litellm-rs: Skill for Claude Code

Authentication Architecture Guide

Overview

AuthSystem (src/auth/system.rs) composes three subsystems behind one authenticate() entry point:

pub struct AuthSystem {
    config: Arc<AuthConfig>,
    storage: Arc<StorageLayer>,
    jwt: Arc<JwtHandler>,        // src/auth/jwt/types.rs
    api_key: Arc<ApiKeyHandler>, // src/auth/api_key/creation.rs
    rbac: Arc<RbacSystem>,       // src/auth/rbac/system.rs
}

AuthSystem::authenticate(auth_method, context) -> Result<AuthResult> dispatches on AuthMethod::{Jwt, ApiKey, Session, None} (src/auth/types.rs). Session auth is a stub that always rejects ("Session authentication is not yet implemented"). Semantic rejections return AuthResult { success: false, error: Some(..) }; infrastructure failures return Err(GatewayError).

Middleware pipeline

Wired in src/server/http.rs (actix runs wraps in reverse registration order, so the request path is outermost-first):

RequestIdMiddleware -> AuditMiddleware -> IpAccessMiddleware -> CORS/Metrics
  -> AuthMiddleware            (src/server/middleware/auth.rs)
  -> RateLimitMiddleware       (src/server/middleware/rate_limit.rs)
  -> SecurityHeadersMiddleware -> handler

AuthMiddleware per request: public-route bypass → fail-closed check when both auth methods are disabled (allow_anonymous gate) → brute-force lockout via AuthRateLimiter → credential extraction → authentication → endpoint/operation authorization → insert User / ApiKey into request extensions.

Credential Extraction

extract_auth_method_with_api_key_header (src/server/middleware/helpers.rs) resolves credentials in this priority order:

1. Authorization: Bearer <jwt> → AuthMethod::Jwt
2. Authorization: ApiKey <key> → AuthMethod::ApiKey
3. Authorization: gw-... (raw key, no scheme) → AuthMethod::ApiKey
4. Configured API key header (auth.api_key_header, default Authorization)
5. X-API-Key fallback (when the configured header differs)
6. session=<id> cookie → AuthMethod::Session