Authentication Providers
Relevant source files
The following files were used as context for generating this wiki page:
Authentication in the Care Ops Frontend is handled through a provider-based architecture that supports multiple Identity Providers (IdPs). The system is designed to decouple the application's authentication logic from the specific implementation details of external services like Auth0 or WorkOS. This is achieved via a dedicated @roundingwell/care-ops-auth package which provides a unified interface for authentication operations.
The choice of authentication provider is determined at deployment time based on organization-specific secrets. The configuration is injected into the application via the appconfig.json file, allowing the frontend to dynamically initialize the correct provider.
Architecture and Configuration
The authentication system relies on a central configuration builder that selects the provider based on the presence of specific credentials. WorkOS is treated as the priority provider; if WorkOsClientId is present in the organization secrets, the system defaults to WorkOS. Otherwise, it falls back to Auth0.
Provider Selection Logic
The following diagram illustrates how the build system determines which authentication provider to configure for a specific organization deployment.
Configuration Structure
The appconfig.json contains an auth block that defines the provider type and its specific configuration parameters.
| Field | Type | Description |
|---|---|---|
provider | String | The identifier for the provider (auth0 or workos). |
disableLoginPrompt | Boolean | Whether to bypass the initial login prompt. |
config | Object | Provider-specific settings (Client IDs, Domains, etc.). |
Sources: scripts/lib/appconfig.js:89-122, scripts/lib/appconfig.test.js:27-44
Authentication Provider Implementations
The project implements specific adapters for third-party authentication services within the packages/care-ops-auth/providers/ directory.
Auth0 Provider
The Auth0 implementation utilizes the @auth0/auth0-spa-js library. It is configured to use refresh tokens and local storage for caching to maintain session persistence.
Key configuration elements for Auth0 include:
- Domain: The Auth0 tenant domain.
- Client ID: The unique identifier for the application in Auth0.
- Authorization Params: Includes the specific
connection,organization(orAuth0OrgId), and a defaultaudienceset tocare-ops-backend.
Sources: packages/care-ops-auth/package.json:20, scripts/lib/appconfig.js:34-45, scripts/lib/appconfig.test.js:33-42
WorkOS Provider
The WorkOS implementation uses the @workos-inc/authkit-js library. It supports a "Dev Mode" that is automatically enabled when the deployment stage is dev or qa.
WorkOS Configuration features:
- API Hostname: Defaults to
login.roundingwell.comif not specified. - Dev Mode: Conditional based on the environment stage.
Sources: packages/care-ops-auth/package.json:21, scripts/lib/appconfig.js:14-25, scripts/lib/appconfig.test.js:77-85
Deployment and Secret Management
Authentication settings are derived from AWS Secrets Manager during the deployment process. The scripts/lib/appconfig.js module is responsible for mapping these raw secrets into the structured configuration required by the frontend AuthProvider.
Secret Mapping Reference
| Secret Key | Mapping | Provider |
|---|---|---|
WorkOsClientId | config.clientId | WorkOS |
WorkOsApiDomain | config.createClientOptions.apiHostname | WorkOS |
Auth0ClientDomain | config.domain | Auth0 |
Auth0ClientID | config.clientId | Auth0 |
Auth0Connection | config.authorizationParams.connection | Auth0 |
Auth0Organization | config.authorizationParams.organization | Auth0 |
Sources: scripts/lib/appconfig.js:16-43, scripts/lib/appconfig.test.js:58-67
Summary
The Authentication Provider system provides a flexible, environment-aware mechanism for securing the Care Ops Frontend. By abstracting Auth0 and WorkOS into a common package structure and using a build-time configuration generator, the application can support diverse organizational requirements without modifying core application logic.