Configuration

Overview

Bitwarden Server services are configured through appsettings.json files and environment variables. Each service has its own configuration file with service-specific settings and shared global settings.

Configuration Files

Each service has multiple configuration files that are loaded in order:

appsettings.json - Base configuration
appsettings.{Environment}.json - Environment-specific settings
Environment variables - Override any setting

Settings are loaded in order with later sources overriding earlier ones. Environment variables have the highest precedence.

Global Settings

All services share a common globalSettings section:

appsettings.json

{
  "globalSettings": {
    "selfHosted": true,
    "siteName": "Bitwarden",
    "projectName": "Api",
    "sqlServer": {
      "connectionString": "Server=localhost;Database=vault;User Id=sa;Password=YourPassword;"
    },
    "identityServer": {
      "certificateThumbprint": "YOUR_CERTIFICATE_THUMBPRINT"
    },
    "dataProtection": {
      "certificateThumbprint": "YOUR_CERTIFICATE_THUMBPRINT"
    },
    "storage": {
      "connectionString": "DefaultEndpointsProtocol=https;AccountName=youraccountname;AccountKey=yourkey;"
    },
    "mail": {
      "replyToEmail": "[email protected]",
      "sendGridApiKey": "YOUR_SENDGRID_KEY",
      "smtp": {
        "host": "smtp.example.com",
        "port": 587,
        "ssl": true,
        "username": "smtp-user",
        "password": "smtp-password"
      }
    },
    "baseServiceUri": {
      "api": "https://api.example.com",
      "identity": "https://identity.example.com",
      "admin": "https://admin.example.com",
      "notifications": "https://notifications.example.com",
      "sso": "https://sso.example.com",
      "vault": "https://vault.example.com"
    },
    "serviceBus": {
      "connectionString": "Endpoint=sb://yournamespace.servicebus.windows.net/;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=yourkey",
      "applicationCacheTopicName": "application-cache"
    }
  }
}

Core Settings

selfHosted

boolean

default:"false"

Set to true for self-hosted deployments. Disables cloud-specific features and telemetry.

siteName

string

default:"Bitwarden"

Display name shown in emails and UI.

projectName

string

required

Service name (Api, Identity, Admin, etc.). Auto-set in Docker images.

Database Configuration

sqlServer.connectionString

string

required

SQL Server connection string. Supports SQL Server, PostgreSQL, and MySQL.Examples:

SQL Server: Server=localhost;Database=vault;User Id=sa;Password=pass;
PostgreSQL: Host=localhost;Database=vault;Username=postgres;Password=pass;
MySQL: Server=localhost;Database=vault;Uid=root;Pwd=pass;

sqlServer.readOnlyConnectionString

string

Optional read replica connection string for read-heavy operations.

Certificate Configuration

identityServer.certificateThumbprint

string

required

SHA-1 thumbprint of certificate used for signing tokens. The certificate must:

Be installed in the certificate store
Have a private key
Be valid (not expired)

Generate thumbprint:

openssl x509 -in certificate.crt -fingerprint -noout | tr -d ':'

dataProtection.certificateThumbprint

string

required

Certificate for ASP.NET Core Data Protection. Can be the same as Identity Server certificate.

Storage Configuration

storage.connectionString

string

required

Blob storage connection string for attachments and sends.Azure Blob Storage:

DefaultEndpointsProtocol=https;AccountName=account;AccountKey=key;

Local Filesystem (Development only):

UseDevelopmentStorage=true

AWS S3 (requires additional configuration):

https://s3.amazonaws.com;AccessKey=key;SecretKey=secret;

attachment.connectionString

string

Separate storage for file attachments. Falls back to storage.connectionString.

send.connectionString

string

Separate storage for Send files. Falls back to storage.connectionString.

Mail Configuration

SendGrid (Recommended)

"mail": {
  "replyToEmail": "[email protected]",
  "sendGridApiKey": "SG.xxxxxxxxxx"
}

SMTP

"mail": {
  "replyToEmail": "[email protected]",
  "smtp": {
    "host": "smtp.gmail.com",
    "port": 587,
    "ssl": true,
    "username": "[email protected]",
    "password": "your-password"
  }
}

Amazon SES

"mail": {
  "replyToEmail": "[email protected]",
  "amazon": {
    "accessKeyId": "AKIAIOSFODNN7EXAMPLE",
    "accessKeySecret": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
    "region": "us-east-1"
  }
}

Service URLs

baseServiceUri

object

required

Public URLs for all services. Required for CORS, redirects, and inter-service communication.All URLs must:

Use HTTPS in production
Be publicly accessible
Match your reverse proxy configuration

Message Bus Configuration

Azure Service Bus
RabbitMQ

"serviceBus": {
  "connectionString": "Endpoint=sb://namespace.servicebus.windows.net/;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=key",
  "applicationCacheTopicName": "application-cache"
}

"serviceBus": {
  "connectionString": "amqp://username:password@localhost:5672",
  "useRabbitMq": true
}

Service-Specific Configuration

API Service

appsettings.json

{
  "globalSettings": { /* ... */ },
  "IpRateLimitOptions": {
    "EnableEndpointRateLimiting": true,
    "StackBlockedRequests": false,
    "RealIpHeader": "X-Forwarded-For",
    "ClientIdHeader": "X-ClientId",
    "HttpStatusCode": 429,
    "GeneralRules": [
      {
        "Endpoint": "post:*",
        "Period": "1m",
        "Limit": 60
      },
      {
        "Endpoint": "post:/connect/token",
        "Period": "1m",
        "Limit": 10
      }
    ]
  },
  "importCiphersLimitation": {
    "ciphersLimit": 40000,
    "collectionRelationshipsLimit": 80000,
    "collectionsLimit": 2000
  }
}

IpRateLimitOptions

object

Rate limiting configuration to prevent abuse:

EnableEndpointRateLimiting - Enable rate limiting
RealIpHeader - Header containing client IP (behind proxy)
GeneralRules - Array of rate limit rules by endpoint

importCiphersLimitation

object

Limits for bulk vault imports:

ciphersLimit - Max items per import (default: 40000)
collectionRelationshipsLimit - Max collection relationships (default: 80000)
collectionsLimit - Max collections per import (default: 2000)

Identity Service

appsettings.json

{
  "globalSettings": { /* ... */ },
  "IpRateLimitOptions": {
    "EnableEndpointRateLimiting": true,
    "GeneralRules": [
      {
        "Endpoint": "post:/connect/token",
        "Period": "1m",
        "Limit": 10
      },
      {
        "Endpoint": "post:/connect/token",
        "Period": "1h",
        "Limit": 100
      }
    ]
  },
  "IdentityServerOptions": {
    "IssuerUri": "https://identity.example.com"
  }
}

Strict rate limiting on /connect/token is critical for preventing brute force attacks.

Notifications Service

appsettings.json

{
  "globalSettings": { /* ... */ },
  "notificationHub": {
    "connectionString": "Endpoint=sb://namespace.servicebus.windows.net/;SharedAccessKeyName=DefaultFullSharedAccessSignature;SharedAccessKey=key",
    "hubName": "bitwarden-hub"
  }
}

SSO Service

appsettings.json

{
  "globalSettings": { /* ... */ },
  "SsoSettings": {
    "CacheLifetimeInMinutes": 5,
    "SamlCertificateLifetimeInYears": 10
  }
}

Environment-Specific Configurations

Development

appsettings.Development.json

{
  "globalSettings": {
    "selfHosted": true,
    "sqlServer": {
      "connectionString": "Server=localhost;Database=vault_dev;User Id=sa;Password=dev_password;TrustServerCertificate=True;"
    },
    "storage": {
      "connectionString": "UseDevelopmentStorage=true"
    },
    "mail": {
      "smtp": {
        "host": "localhost",
        "port": 1025,
        "ssl": false
      }
    },
    "baseServiceUri": {
      "api": "http://localhost:4000",
      "identity": "http://localhost:33656",
      "vault": "http://localhost:8080"
    }
  },
  "Logging": {
    "LogLevel": {
      "Default": "Debug",
      "Microsoft": "Information"
    }
  }
}

Production

appsettings.Production.json

{
  "globalSettings": {
    "selfHosted": true,
    "baseServiceUri": {
      "api": "https://api.vault.example.com",
      "identity": "https://identity.vault.example.com",
      "vault": "https://vault.example.com"
    }
  },
  "Logging": {
    "LogLevel": {
      "Default": "Warning",
      "Microsoft": "Warning"
    }
  }
}

Environment Variables

Override any configuration using environment variables with double underscore notation:

# Format: Section__Property__SubProperty
globalSettings__selfHosted=true
globalSettings__sqlServer__connectionString="Server=db;Database=vault;"
globalSettings__identityServer__certificateThumbprint="ABC123"

In Docker Compose:

services:
  api:
    environment:
      globalSettings__selfHosted: "true"
      globalSettings__sqlServer__connectionString: "Server=mssql;Database=vault;User Id=sa;Password=${MSSQL_PASSWORD};"
      globalSettings__baseServiceUri__api: "https://${DOMAIN}/api"

See Environment Variables for complete reference.

Configuration Validation

Services validate configuration on startup. Common errors:

Certificate not found

System.InvalidOperationException: Certificate with thumbprint 'ABC123' not found

Solution: Ensure certificate is installed in correct store (My/Personal) and thumbprint is correct.

Database connection failed

Microsoft.Data.SqlClient.SqlException: Cannot open database "vault"

Solution:

Verify database exists
Check connection string credentials
Ensure SQL Server is accessible
Run database migrations

Invalid connection string

System.ArgumentException: Invalid connection string

Solution: Check connection string format and escape special characters in passwords.

Security Best Practices

Secrets Management

Never commit secrets to version control
Use environment variables for sensitive data
Consider using Azure Key Vault or HashiCorp Vault
Rotate credentials regularly

Certificate Security

Use certificates from trusted CAs
Store private keys securely
Set appropriate permissions on certificate stores
Monitor certificate expiration

Rate Limiting

Enable rate limiting on all public endpoints
Adjust limits based on usage patterns
Monitor for unusual traffic
Whitelist trusted IPs if needed

Logging

Set appropriate log levels
Never log sensitive data (passwords, tokens)
Configure log retention
Use structured logging

Configuration Templates

Official configuration templates are available in the source repository:

Next Steps

Environment Variables

Complete environment variable reference

Database Setup

Configure and initialize the database

SSL Certificates

Set up SSL/TLS certificates

Operations

Monitor and maintain your deployment

Getting Started

Deployment

Overview

Configuration Files

Global Settings

Core Settings

Database Configuration

Certificate Configuration

Storage Configuration

Mail Configuration

Service URLs

Message Bus Configuration

Service-Specific Configuration

API Service

Identity Service

Notifications Service

SSO Service

Environment-Specific Configurations

Development

Production

Environment Variables

Configuration Validation

Security Best Practices

Secrets Management

Certificate Security

Rate Limiting

Logging

Configuration Templates

Next Steps

Environment Variables

Database Setup

SSL Certificates

Operations

Build docs developers (and LLMs) love

Getting Started

Deployment

​Overview

​Configuration Files

​Global Settings

​Core Settings

​Database Configuration

​Certificate Configuration

​Storage Configuration

​Mail Configuration

​Service URLs

​Message Bus Configuration

​Service-Specific Configuration

​API Service

​Identity Service

​Notifications Service

​SSO Service

​Environment-Specific Configurations

​Development

​Production

​Environment Variables

​Configuration Validation

​Security Best Practices

Secrets Management

Certificate Security

Rate Limiting

Logging

​Configuration Templates

​Next Steps

Environment Variables

Database Setup

SSL Certificates

Operations

Build docs developers (and LLMs) love

Overview

Configuration Files

Global Settings

Core Settings

Database Configuration

Certificate Configuration

Storage Configuration

Mail Configuration

Service URLs

Message Bus Configuration

Service-Specific Configuration

API Service

Identity Service

Notifications Service

SSO Service

Environment-Specific Configurations

Development

Production

Environment Variables

Configuration Validation

Security Best Practices

Configuration Templates

Next Steps