Authentication System
Relevant source files
The following files were used as context for generating this wiki page:
The Authentication System in DXKB is a multi-layered architecture designed to manage user identities, sessions, and secure access to protected resources. It integrates a React-based frontend context with a Next.js backend API that proxies requests to upstream authentication services. The system supports email/password authentication, account creation, and session persistence through secure cookies.
A key feature of the system is its shared infrastructure with the BV-BRC (Bacterial and Viral Bioinformatics Resource Center) platform, allowing users to utilize existing credentials across both resources.
Sources: src/contexts/auth-context.tsx:37-184, src/app/(auth)/sign-in/page.tsx:135-141, src/app/(footer)/privacy-policy/data/privacy-policy-sections.ts:58-65
Architecture Overview
The authentication architecture consists of three primary layers: the UI Layer (Forms and Context), the Client Logic Layer (API abstractions), and the Server Layer (API routes and Cookie management).
Authentication Layers and Flow
The following diagram illustrates the interaction between the frontend components and the backend services.
Explanation: The diagram shows how user interactions flow from the UI through a central context and client library before reaching backend API routes that interact with the cookie store and external services.
Sources: src/contexts/auth-context.tsx, src/lib/auth-client.ts, src/app/api/auth/sign-in/email/tests/route.test.ts
Client-Side Implementation
AuthContext
The AuthProvider serves as the central state management for authentication. It provides user profile data, authentication status, and methods for signing in, signing up, and signing out. It also implements automatic redirection for protected routes.
- Protected Routes: The system automatically identifies paths starting with
/services/,/workspace, or/jobsas protected. - Session Initialization: On mount, the provider attempts to fetch an existing session via
bvbrcAuth.getSession(). - Visibility Refresh: The system revalidates the session whenever the browser tab becomes visible.
Sources: src/contexts/auth-context.tsx:15-30, src/contexts/auth-context.tsx:55-68, src/contexts/auth-context.tsx:96-104
Authentication Client (bvbrcAuth)
The client library provides a clean interface for making HTTP requests to the authentication API endpoints.
| Method | Endpoint | Description |
|---|---|---|
signIn.email | /api/auth/sign-in/email | Authenticates using username/email and password. |
signUp.email | /api/auth/sign-up/email | Registers a new user account. |
signOut | /api/auth/sign-out | Ends the current session. |
getSession | /api/auth/get-session | Retrieves the current user profile and session status. |
Sources: src/lib/tests/auth-client.test.ts:15-165
Server-Side implementation
Session and Cookie Management
Authentication is maintained using specific cookies that store the session token and user metadata.
| Cookie Name | Description |
|---|---|
bvbrc_token | The primary authentication token used for API requests. |
user_id | The username of the currently logged-in user. |
user_profile | JSON-encoded user metadata (first name, last name, email). |
realm | The authentication realm (e.g., patricbrc.org). |
Sources: src/lib/tests/auth.test.ts:46-52, src/app/layout.tsx:64-70
Token Retrieval and Authorization
The backend utilizes getBvbrcAuthToken to retrieve and decode the session token from cookies. This token is then injected into the Authorization header for upstream service calls via serverAuthenticatedFetch.
Explanation: This sequence demonstrates how the system retrieves a token from the cookie store, decodes it, and applies it to authenticated requests.
Sources: src/lib/auth.ts:43-62, src/lib/auth.ts:68-90
Data Models
The system uses specific structures for user and credential data.
AuthUser Object
The AuthUser object represents the authenticated user state.
| Field | Type | Description |
|---|---|---|
id | string | Unique identifier for the user. |
username | string | User's login handle. |
email | string | User's contact email. |
first_name | string | User's given name. |
last_name | string | User's family name. |
realm | string | The authentication domain. |
email_verified | boolean | Flag indicating if the email has been validated. |
Sources: src/app/api/auth/sign-in/email/tests/route.test.ts:182-192, src/app/layout.tsx:84-93
Summary
The DXKB Authentication System provides a robust mechanism for managing user access by combining local session handling with BV-BRC integration. By utilizing a central context on the frontend and secure cookie-based token management on the backend, it ensures that sensitive user data and protected services remain accessible only to authorized researchers.
Sources: src/contexts/auth-context.tsx:162-182, src/app/layout.tsx:100-108