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

ServiceDefault PortProtocolPublic
API4000HTTPSYes
Identity33656HTTPSYes
Admin5000HTTPSNo
Notifications5002WSSYes
Events5003HTTPSNo
SSO51822HTTPSYes
SCIM44559HTTPSYes
Billing5004HTTPSNo
Icons5005HTTPSYes
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

Build docs developers (and LLMs) love

Get started for freeTalk to us