Skip to main content

0017: Multiple Account Management Strategy

Date: 2025-08-11

Status: Accepted

Context​

Users may have multiple distinct accounts on the platform (e.g., a personal account and a work account, or accounts for different companies they manage). They need a convenient way to switch between these accounts without having to log out and log back in repeatedly.

This is distinct from "User Impersonation" (as described in the now-superseded ADR-0016), which is an administrative feature for support staff. This strategy is for end-users managing their own multiple, concurrent sessions.

Decision​

We will implement a Multiple Account Management feature that allows users to be signed into several accounts in the same browser session and switch between them.

  1. Opt-in Feature: This feature will be disabled by default. It can be enabled via a boolean flag in the runtime configuration file (/assets/config.json), for example: {"enableMultiAccount": true}. The AuthService and UserMenuComponent will check this flag to enable or disable the multi-account functionality.

  2. Multi-Session Token Storage: The shell-app's AuthService will be enhanced to manage tokens for multiple user sessions. The storage key for each user's data (in localStorage or sessionStorage) will be namespaced by a unique, stable user identifier, such as the sub (subject) claim from their JWT.

    • Example Key: citadel.user:{sub}

  3. Active User Concept: The AuthService will maintain the concept of a single "active" user. The tokens for the active user will be used for all API requests. The active user's sub will be stored under a well-known key (e.g., citadel.activeUserSub).

  4. Adding an Account: The UI (e.g., the UserMenuComponent) will provide an "Add another account" option. This will initiate a new OIDC authorization flow, potentially using the prompt=select_account parameter to encourage the IdP to allow logging in with a different account.

  5. Switching Accounts: The UserMenuComponent will display a list of all authenticated user sessions.

    • When a user selects a different account, the AuthService will update the citadel.activeUserSub key in storage.
    • To ensure a clean state transition and that all services and components are re-initialized with the new user's context, the application will perform a full page reload.

Consequences​

Positive​

  • Improved User Experience: Provides a highly convenient and expected feature for users who manage multiple accounts.
  • Secure: Each session is based on a full, independent authentication flow. There is no privilege escalation or impersonation.
  • Configurable: The feature can be disabled for deployments that do not require it, simplifying the user experience.
  • Clean State Management: The full page reload on switching is a simple and robust way to ensure the entire application state is reset correctly for the new user context.

Negative​

  • Increased Client-Side Complexity: The AuthService and any related token management logic become more complex as they must handle a collection of users instead of a single one.
  • UX Disruption on Switch: A full page reload is a noticeable disruption. A more seamless in-app state reset could be considered in the future but would add significant complexity.