Skip to main content

​
Overview

Bitwarden Server follows a microservices architecture pattern, with each service responsible for specific functionality. Services communicate through HTTP APIs and message queues, with a shared database layer.

​
High-Level Architecture

​
Service Architecture

​
Core Services

Port: 4000 (default)The main REST API service that handles:
  • Vault operations (ciphers, folders, collections)
  • Organization management
  • User account operations
  • Attachment uploads/downloads
  • Sync endpoints
  • Two-factor authentication
Key Components:
  • Controllers/ - REST API endpoints
  • Validators/ - Request validation
  • Services/ - Business logic
  • Models/ - Request/response models
Dependencies:
  • SQL Database (primary data store)
  • Redis (caching and distributed locking)
  • Blob Storage (attachments)
  • Service Bus (event publishing)
Port: 33656 (default)OAuth 2.0 / OpenID Connect authentication server:
  • User login and registration
  • Token issuance and validation
  • OAuth 2.0 flows (authorization code, client credentials)
  • Two-factor authentication enforcement
  • Device authorization
Based on: IdentityServer4 frameworkKey Endpoints:
  • /connect/token - Token endpoint
  • /connect/authorize - Authorization endpoint
  • /.well-known/openid-configuration - Discovery
Dependencies:
  • SQL Database
  • Redis (rate limiting)
  • Certificate store (signing keys)
Port: 5000 (default)Administrative portal and API:
  • User management
  • Organization administration
  • System configuration
  • License management
  • Event log viewing
Authentication: Requires admin user credentialsDependencies:
  • SQL Database
  • Identity Service (authentication)
Port: 5002 (default)Real-time notification delivery:
  • WebSocket connections for live updates
  • Push notifications to connected clients
  • Vault sync notifications
  • Anonymous client connections
Protocol: SignalR over WebSocketsDependencies:
  • Service Bus (receives notifications)
  • Redis (connection management)
Port: 5003 (default)Event collection and audit logging:
  • Receives events from all services
  • Batches events for storage
  • Provides event query API
  • Audit trail compliance
Event Types:
  • User actions (login, cipher access)
  • Administrative changes
  • Policy violations
  • Security events
Dependencies:
  • SQL Database (event storage)
  • Service Bus (event ingestion)

​
Enterprise Services

Port: 51822 (default)Single Sign-On integration:
  • SAML 2.0 service provider
  • OpenID Connect integration
  • Just-in-time user provisioning
  • Multi-provider support per organization
Supported Protocols:
  • SAML 2.0
  • OpenID Connect (OIDC)
License: Requires commercial license
Port: 44559 (default)Automated user provisioning:
  • SCIM 2.0 protocol implementation
  • User lifecycle management
  • Group synchronization
  • Directory integration (Azure AD, Okta, etc.)
Operations:
  • User CRUD operations
  • Group management
  • Bulk operations
License: Requires commercial license
Port: 5004 (default)Payment and subscription management:
  • Stripe integration
  • Subscription lifecycle
  • Invoice generation
  • Payment method management
Payment Providers:
  • Stripe (credit cards)
  • PayPal
  • BitPay (cryptocurrency)

​
Background Services

Background worker service:
  • Processes events from Service Bus
  • Aggregates event data
  • Triggers notifications
  • Cleanup old events
Processing:
  • Asynchronous event handling
  • Batch processing
  • Retry logic
No HTTP Interface: Runs as background worker
Port: 5005 (default)Website icon fetching:
  • Downloads favicons for vault items
  • Caches icons in blob storage
  • Serves cached icons
  • Fallback to default icons
Caching Strategy:
  • Aggressive caching (30+ days)
  • CDN-friendly headers

​
Data Flow

​
Authentication Flow

​
Event Processing Flow

​
Technology Stack

Framework

  • .NET 8.0
  • ASP.NET Core
  • Entity Framework Core
  • Dapper (micro-ORM)

Authentication

  • IdentityServer4
  • OAuth 2.0 / OpenID Connect
  • JWT tokens
  • Certificate-based signing

Database

  • SQL Server 2022
  • PostgreSQL 14+
  • MySQL 8.0 / MariaDB 10+
  • Entity Framework migrations

Messaging

  • Azure Service Bus
  • RabbitMQ
  • SignalR (WebSockets)

Storage

  • Azure Blob Storage
  • Local filesystem
  • S3-compatible storage

Caching

  • Redis
  • In-memory caching
  • Distributed cache

​
Scalability Considerations

​
Horizontal Scaling

1

Stateless Services

All services are stateless and can be scaled horizontally behind a load balancer.
2

Shared State

Redis is used for distributed caching and session state across instances.
3

Database

Use read replicas for read-heavy operations. Consider database sharding for large deployments.
4

Message Bus

Service Bus handles async communication and decouples services for independent scaling.

​
High Availability

  • Deploy services across multiple availability zones
  • Use database clustering (SQL Server Always On, PostgreSQL replication)
  • Redis Sentinel or Redis Cluster for cache high availability
  • Load balancer health checks for automatic failover

​
Security Architecture

Transport Security

  • TLS 1.2+ required
  • Certificate pinning support
  • HSTS headers

Data Security

  • Client-side encryption
  • Database encryption at rest
  • Encrypted backups

Authentication

  • OAuth 2.0 / OpenID Connect
  • Two-factor authentication
  • Device authorization

Authorization

  • Role-based access control (RBAC)
  • Organization policies
  • Granular permissions

​
Network Ports

Only API, Identity, Notifications, SSO, SCIM, and Icons services should be exposed publicly. All others should be internal only.

​
Next Steps

Docker Deployment

Deploy the full stack using Docker Compose

Configuration

Configure services using appsettings.json

Database Setup

Set up and configure the database

Service Documentation

Learn about individual services