Principle:Treeverse LakeFS API Authentication Specification
| Knowledge Sources | |
|---|---|
| Domains | Authentication, API Specification, Security |
| Last Updated | 2026-02-08 00:00 GMT |
Overview
The API Authentication Specification principle defines the standards and patterns for authenticating users and services against the lakeFS platform through multiple pluggable authentication schemes.
Description
lakeFS follows a multi-scheme authentication design principle that enables flexible identity verification across diverse deployment environments. Rather than enforcing a single authentication mechanism, the authentication API specification supports five distinct security schemes that can be used interchangeably:
- HTTP Basic Authentication -- For simple username/password credential exchange, suitable for development and scripted environments
- JWT Bearer Tokens -- For stateless, token-based authentication with expiration support, used as the primary programmatic authentication method
- Cookie-based Session Authentication -- Three separate cookie mechanisms (internal_auth_session, oidc_auth_session, saml_auth_session) for browser-based web UI interactions
This multi-scheme approach enables lakeFS to integrate with enterprise identity providers (OIDC, SAML), directory services (LDAP), cloud-native security token services (STS), and external authentication systems while maintaining a unified API surface.
The specification adheres to the OpenAPI 3.0 standard, ensuring that the authentication contract is machine-readable, enabling automated client generation, validation, and documentation.
Usage
Apply this principle when designing or extending authentication flows in lakeFS. Any new authentication mechanism should be added as a new security scheme in the OpenAPI specification, maintaining backward compatibility with existing schemes. Client implementations should support scheme negotiation, allowing the server to accept any of the defined authentication methods on secured endpoints.
Theoretical Basis
The multi-scheme authentication principle is grounded in several security and API design concepts:
Defense in Depth: By supporting multiple authentication mechanisms, lakeFS does not create a single point of failure in its security architecture. If one scheme is compromised or unavailable, alternative authentication paths remain operational.
Protocol Diversity: Enterprise environments typically employ heterogeneous identity systems. LDAP is common in on-premises deployments, OIDC/SAML in cloud-native SSO configurations, and STS in AWS-integrated environments. Supporting all these protocols as first-class citizens enables lakeFS to fit naturally into existing security infrastructure.
Separation of Authentication and Authorization: The authentication specification is deliberately separated from the authorization specification. Authentication verifies who a user is, while authorization (defined in the companion authorization.yml) determines what they can do. This separation follows the principle of single responsibility and allows each concern to evolve independently.
Stateless vs. Stateful Authentication: The specification supports both stateless (JWT) and stateful (cookie-based) authentication patterns, recognizing that different client types (API clients vs. browser-based UIs) have different session management requirements.
OpenAPI Contract-First Design: Defining the authentication API as an OpenAPI 3.0 specification before implementation ensures that the API contract is explicit, testable, and can be used to generate both client libraries and server stubs, reducing integration errors.