Authentication System: Deep Dive

The authentication system in sfp server supports both interactive user sessions and non-interactive application access. These flows are intentionally handled differently so that CI/CD systems and integrations use explicit, auditable credentials with predictable lifecycles.

Authentication Flows

The system implements two distinct authentication paths. Interactive users authenticate through OAuth flows that result in JWT tokens with standard expiration and refresh semantics. Non-interactive clients (CI/CD pipelines, automated integrations) use application tokens that are explicitly provisioned and have strict validation rules.

Interactive User Authentication

When a user authenticates through the UI or CLI, the system performs a chain of validations before granting access. The JWT signature is verified using the configured secret, and the token expiration is checked with a buffer to prevent edge-case failures near the expiration boundary. The issuer and audience claims are validated to ensure the token was issued for this specific instance.

After token validation succeeds, the system retrieves the user's account record and associated memberships. The role assignments are fetched and compared against the requirements of the requested operation. The role hierarchy (member, owner) determines which operations are permitted, with owner-level access required for administrative functions and production environment operations.

Application Token Handling

The system takes a deliberately strict approach to application tokens. Unlike interactive user tokens, application tokens do not support automatic renewal. When an application token expires, subsequent requests are rejected with a clear error indicating the token status. This design requires explicit token rotation, which creates a clear audit trail and prevents long-lived credentials from accumulating in CI/CD configurations.

Application tokens are bound to a specific instance and tenant at creation time. Each token has defined permission boundaries that cannot exceed those of the creating user. The token can be revoked at any time through the management API, immediately invalidating all subsequent requests that present that token.

FLXBL-Managed vs Self-Hosted Authentication

The platform supports two authentication deployment modes that share a common authorization model but differ in how identity is established.

In FLXBL-managed deployments, a global OAuth callback service handles authentication with social providers (GitHub, GitLab, and others). Users authenticate through FLXBL's registered OAuth applications, and the resulting identity is passed to their dedicated instance. This simplifies setup since organizations do not need to register their own OAuth applications with each provider.

In self-hosted deployments, organizations configure their own OAuth applications and handle callbacks directly within their instance. This provides complete control over the authentication process and eliminates dependencies on FLXBL's global services, but requires additional setup and maintenance of OAuth application registrations.

Once a request reaches the instance boundary, both modes converge on the same validation path. The auth guard verifies the token, retrieves membership information, and enforces role-based access control using identical logic regardless of how the identity was originally established.

Implementation Patterns

The authentication system follows several patterns that inform its behavior and error handling.

Token validation occurs before any request processing begins. The AuthGuard intercepts requests at the earliest possible point, ensuring that invalid requests are rejected immediately without consuming resources on downstream processing.

Database operations for membership lookups implement retry logic with exponential backoff. Transient failures (network issues, database connection resets) are automatically retried with randomized delays to prevent thundering herd problems. Non-retryable errors (invalid tokens, missing users) fail immediately with appropriate error responses.

Error responses are designed to avoid information leakage. Unauthenticated requests receive generic error messages that do not reveal whether a user exists or why authentication failed. Authenticated users receive more specific error messages that aid debugging while still protecting sensitive system information.