Skip to main content
The Auth library (@bitwarden/auth) represents the public API of the Auth team at Bitwarden. It handles all authentication flows, login strategies, and token management.

​
Overview

The Auth library is responsible for managing user authentication across all Bitwarden client applications. It provides a comprehensive set of services and strategies for handling different authentication methods, from traditional master password login to modern WebAuthn and SSO.

​
Authentication Methods

Bitwarden supports five authentication methods, each implemented as a dedicated login strategy:

Master Password

Traditional login with master password and KDF validation

Auth Request

Login with Device - authenticate using a one-time access code

Single Sign-On

SSO login via SAML or OpenID Connect (OIDC)

Passkey (WebAuthn)

Passwordless authentication using WebAuthn credentials

User API Key

API key-based authentication for programmatic access

​
Core Architecture

​
Login Strategy Pattern

The library uses the Strategy Design Pattern to handle different authentication methods. Each authentication method has its own login strategy: 
// Base login strategy
LoginStrategy
├── PasswordLoginStrategy
├── AuthRequestLoginStrategy
├── SsoLoginStrategy
├── WebAuthnLoginStrategy
└── UserApiLoginStrategy

​
Login Flow

The authentication flow follows these steps:
1

Build Credentials Object

The initiating component creates a credentials object (e.g., PasswordLoginCredentials) containing the necessary authentication data.
2

Call LoginStrategyService

The credentials are passed to LoginStrategyService.logIn(credentials), which determines the appropriate strategy based on the AuthenticationType.
3

Execute Strategy

The selected strategy builds a LoginStrategyData object with a TokenRequest and caches it for potential 2FA or device verification.
4

Token Request

The strategy sends a POST request to /connect/token on the Identity Server with the appropriate credentials.
5

Process Response

The server responds with one of three types:
  • IdentityTokenResponse - Authentication successful
  • IdentityTwoFactorResponse - 2FA required
  • IdentityDeviceVerificationResponse - Device verification required
6

Return AuthResult

An AuthResult object is returned to the initiating component, which directs the user based on the authentication state.

​
Key Services

​
LoginStrategyService

The orchestrator service that manages login strategy initialization and execution.
libs/auth/src/common/services/login-strategies/login-strategy.service.ts
abstract class LoginStrategyServiceAbstraction {
  currentAuthType$: Observable<AuthenticationType | null>;
  
  abstract logIn(
    credentials: PasswordLoginCredentials | SsoLoginCredentials | ...
  ): Promise<AuthResult>;
  
  abstract logInTwoFactor(
    twoFactor: TokenTwoFactorRequest
  ): Promise<AuthResult>;
  
  abstract logInNewDeviceVerification(
    deviceVerificationOtp: string
  ): Promise<AuthResult>;
}

​
Auth Request Service

Manages authentication request flows for login-with-device scenarios.
libs/auth/src/common/abstractions/auth-request.service.abstraction.ts
abstract class AuthRequestServiceAbstraction {
  abstract approveOrDenyAuthRequest(
    approve: boolean,
    authRequest: AuthRequestResponse
  ): Promise<AuthRequestResponse>;
}

​
Logout Service

Handles cleanup and state management during user logout.
libs/auth/src/common/abstractions/logout.service.ts
abstract class LogoutService {
  abstract logout(): Promise<void>;
}

​
Directory Structure

libs/auth/
├── src/
│   ├── angular/              # Angular-specific components
│   │   ├── login/           # Login components
│   │   ├── registration/    # Registration flow
│   │   ├── two-factor-auth/ # 2FA components
│   │   └── sso/             # SSO components
│   └── common/              # Platform-agnostic code
│       ├── abstractions/    # Service interfaces
│       ├── login-strategies/# Strategy implementations
│       ├── models/          # Data models
│       └── services/        # Service implementations
│           ├── accounts/
│           ├── auth-request/
│           ├── login-strategies/
│           └── logout/

​
Domain Boundaries

Authentication vs. Authorization: The Auth library focuses on authentication (verifying user identity) and initial session establishment. Authorization and access control for specific resources are handled by other domain libraries like @bitwarden/admin-console for organization policies.
Token Management: While the Auth library handles token acquisition during login, long-term token storage and refresh logic may be coordinated with platform-level services in @bitwarden/platform.

​
Login Credentials

Each authentication method uses a specific credentials object:
Credentials TypeAuthentication MethodRequired Fields
PasswordLoginCredentialsMaster Passwordemail, masterPassword
AuthRequestLoginCredentialsLogin with Deviceemail, accessCode, authRequestId
SsoLoginCredentialsSingle Sign-Oncode, codeVerifier, redirectUrl
WebAuthnLoginCredentialsPasskey (WebAuthn)token, deviceResponse
UserApiLoginCredentialsAPI KeyclientId, clientSecret

​
Two-Factor Authentication

When 2FA is required, the authentication flow is modified:
  1. Initial login attempt returns IdentityTwoFactorResponse
  2. LoginStrategyData is cached in the LoginStrategyService
  3. User is routed to /2fa to enter their 2FA token
  4. logInTwoFactor() appends the 2FA token to the cached request
  5. Re-submit to /connect/token with 2FA token included

​
New Device Verification

For users without 2FA on a new device:
  1. Initial login returns IdentityDeviceVerificationResponse
  2. User receives verification code via email
  3. User is routed to /device-verification
  4. logInNewDeviceVerification() submits the OTP code
  5. Authentication completes upon successful verification

​
Usage Example

import { 
  LoginStrategyService,
  PasswordLoginCredentials,
  AuthenticationType 
} from '@bitwarden/auth';

// Build credentials
const credentials = new PasswordLoginCredentials(
  '[email protected]',
  'masterPassword123'
);

// Attempt login
const authResult = await loginStrategyService.logIn(credentials);

// Handle result
if (authResult.requiresTwoFactor) {
  // Route to 2FA page
  router.navigate(['/2fa']);
} else if (authResult.requiresDeviceVerification) {
  // Route to device verification
  router.navigate(['/device-verification']);
} else {
  // Login successful - route to vault
  router.navigate(['/vault']);
}

Build docs developers (and LLMs) love

Get started for freeTalk to us