Authentication & Session Management
Relevant source files
The following files were used as context for generating this wiki page:
Authentication and Session Management in the DXKB platform is a client-side heavy system integrated with a Node.js Express backend. It leverages token-based authentication (Bearer tokens) stored in the browser's local storage to maintain user state across sessions. The system supports standard user login, administrative "Switch User" (SU) capabilities, and token refresh logic to ensure continuous access during active use.
The architecture ensures that sensitive operations, such as job submissions or accessing private workspaces, require a valid authorizationToken. The frontend components monitor token expiration and user activity to trigger automatic logouts or refreshes, maintaining a balance between security and user experience.
System Architecture & Token Storage
The system relies on localStorage to persist authentication data. Key data points include the raw token string, user profile information, and the authentication object containing expiration details.
Key Authentication Keys in LocalStorage
| Key | Description |
|---|---|
tokenstring | The active Bearer token used for API headers. |
auth | JSON object containing token metadata, including expiry (Unix timestamp) and roles. |
userProfile | JSON object containing user details (ID, email verification status). |
userid | The unique identifier for the logged-in user. |
realm | The authentication realm (e.g., 'patricbrc.org'). |
Sources: public/js/p3/app/p3app.js:435-450, public/js/p3/app/p3app.js:520-530
Authentication Flow
The following diagram illustrates the token validation and application initialization flow during startup:
Token Lifecycle Management
Token Validation and Refresh
The p3app.js module implements a timeout function that executes at intervals defined by localStorageCheckInterval. This function verifies if a token exists and if it has expired. If the token is near expiration but the user is active (indicated by activeMouse) or an upload is in progress (uploadInProgress), the system performs a silent refresh against the User Service.
- Refresh Endpoint:
${userServiceURL}/authenticate/refresh/ - Method: GET
- Header:
Authorization: window.App.authorizationToken
Sources: public/js/p3/app/p3app.js:421-432, public/js/p3/app/p3app.js:490-510
User Profile Synchronization
Active sessions periodically refresh user data via refreshUser(). This ensures that changes to user metadata, such as email_verified status, are reflected in the UI. If a user's email is unverified, the unverified_email class is added to the document body to restrict or notify the user.
Sources: public/js/p3/app/p3app.js:644-675
Administrative "Switch User" (SU) Login
The platform provides a "Switch User" feature for administrators to impersonate other accounts for troubleshooting. This process involves backing up the administrator's current session and replacing it with the target user's session.
SU Login Mechanism
- Validation: The system checks if the current user has the
adminrole. - Backup: Current admin credentials (
auth,tokenstring,userProfile,userid,realm) are moved to "A"-prefixed keys inlocalStorage(e.g.,Aauth). - Authentication: A request is made to
/authenticate/suloginwith the target username and administrative password. - Switch Back: Administrators can restore their original session using
suSwitchBack(), which moves the "A" keys back to the primary authentication keys.
Application-Level Security Enforcement
Required Authentication in Apps
Service widgets extending AppBase can enforce authentication by setting requireAuth: true. If a user attempts to access these services without a token, the AppBase logic replaces the application interface with an AppLogin template, prompting the user to sign in.
Sources: public/js/p3/widget/app/AppBase.js:63-75
API Authentication Headers
All data and service API calls are initialized with the authorizationToken. The CopilotApi and DataAPI modules explicitly include this token in the Authorization header for every request.
| Component | Usage |
|---|---|
CopilotApi | Validates _checkLoggedIn() before submitting queries. |
ReportProblem | Includes token in multipart/form-data submissions. |
AppBase | Uses AppService.start_app2 which requires RPC authentication. |
Sources: public/js/p3/widget/copilot/CopilotApi.js:144-155, public/js/p3/widget/ReportProblem.js:93-96, public/js/p3/widget/app/AppBase.js:235-240
Conclusion
DXKB utilizes a robust client-side session management strategy that prioritizes persistence and administrative flexibility. By combining localStorage for state with periodic server-side validation and refresh cycles, the system maintains secure access to bioinformatics services and workspaces while enabling advanced administrative features like user impersonation.