Skip to main content
The Admin service provides a web-based administrative portal for Bitwarden cloud operations, offering tools for user management, organization administration, billing operations, and system utilities.

Overview

The Admin service is primarily for Bitwarden cloud infrastructure. Self-hosted instances have limited admin functionality.
The Admin service provides:
  • User Management: View, edit, and delete user accounts
  • Organization Management: Organization configuration and licensing
  • Billing Operations: Manual billing adjustments and Stripe operations
  • System Tools: Database migrations, cache management, utilities
  • Provider Administration: MSP provider management
  • Reporting: System statistics and usage reports

Architecture

Configuration

Application Settings

From src/Admin/Startup.cs:33:
Service Configuration
public void ConfigureServices(IServiceCollection services)
{
    // Settings
    var globalSettings = services.AddGlobalSettingsServices(Configuration, Environment);
    services.Configure<AdminSettings>(Configuration.GetSection("AdminSettings"));
    
    // Data Protection
    services.AddCustomDataProtectionServices(Environment, globalSettings);
    
    // Stripe Billing
    StripeConfiguration.ApiKey = globalSettings.Stripe.ApiKey;
    StripeConfiguration.MaxNetworkRetries = globalSettings.Stripe.MaxNetworkRetries;
    
    // Repositories with database provider selection
    var databaseProvider = services.AddDatabaseRepositories(globalSettings);
    switch (databaseProvider)
    {
        case Core.Enums.SupportedDatabaseProviders.SqlServer:
            services.AddSingleton<IDbMigrator, Migrator.SqlServerDbMigrator>();
            break;
        case Core.Enums.SupportedDatabaseProviders.MySql:
            services.AddSingleton<IDbMigrator, MySqlMigrations.MySqlDbMigrator>();
            break;
        case Core.Enums.SupportedDatabaseProviders.Postgres:
            services.AddSingleton<IDbMigrator, PostgresDbMigrator>();
            break;
        case Core.Enums.SupportedDatabaseProviders.Sqlite:
            services.AddSingleton<IDbMigrator, SqliteDbMigrator>();
            break;
    }
    
    // Identity with read-only user store
    services.AddPasswordlessIdentityServices<ReadOnlyEnvIdentityUserStore>(globalSettings);
    
    // Access control
    services.AddScoped<IAccessControlService, AccessControlService>();
}

Admin Settings

AdminSettings Configuration
{
  "AdminSettings": {
    "Admins": "[email protected],[email protected]",
    "ReadOnlyAdmins": "[email protected]"
  }
}

Authentication

Read-Only Identity Store

The Admin service uses a read-only environment-based identity store:
Admin users are configured via environment variables, not stored in the database.
Read-Only User Store
services.AddPasswordlessIdentityServices<ReadOnlyEnvIdentityUserStore>(globalSettings);

services.Configure<SecurityStampValidatorOptions>(options =>
{
    options.ValidationInterval = TimeSpan.FromMinutes(5);
});
For self-hosted deployments:
Cookie Path
if (globalSettings.SelfHosted)
{
    services.ConfigureApplicationCookie(options =>
    {
        options.Cookie.Path = "/admin";
    });
}

Controllers

The Admin service includes several controller areas:

Core Controllers

HomeController.cs - Dashboard and navigation
UsersController.cs - User account management
ToolsController.cs - Administrative utilities
InfoController.cs - System information
ErrorController.cs - Error handling

Tools Controller

From src/Admin/Controllers/ToolsController.cs:25: Provides administrative utilities:

Braintree Charging

Manual payment processing for Braintree customers

Stripe Operations

Direct Stripe API operations and adjustments

License Generation

Generate organization licenses

User Promotion

Promote users to premium

Organization Management

Administrative organization operations:
Organization Tools
// License generation
GET /Tools/GenerateOrganizationLicense?organizationId={guid}

// Manual billing adjustments
POST /Tools/ChargeBraintree
POST /Tools/AdjustStorage

// Organization upgrades
POST /Organizations/{id}/Upgrade

Database Migrations

Database migrations run automatically on startup for self-hosted instances.
From src/Admin/Startup.cs:120:
Migration Service
if (globalSettings.SelfHosted)
{
    services.AddHostedService<HostedServices.DatabaseMigrationHostedService>();
}
Supported database providers:
  • SQL Server
  • MySQL
  • PostgreSQL
  • SQLite

Background Jobs

From src/Admin/Startup.cs:118:
Job Services
Jobs.JobsHostedService.AddJobsServices(services, globalSettings.SelfHosted);
services.AddHostedService<Jobs.JobsHostedService>();

if (!globalSettings.SelfHosted)
{
    if (CoreHelpers.SettingHasValue(globalSettings.Mail.ConnectionString))
    {
        services.AddHostedService<HostedServices.AzureQueueMailHostedService>();
    }
}
Background jobs handle:
  • Email queue processing (cloud only)
  • Database migrations (self-hosted)
  • Scheduled maintenance tasks

View Structure

The Admin service uses Razor views organized by feature:
View Locations
services.Configure<RazorViewEngineOptions>(o =>
{
    o.ViewLocationFormats.Add("/Auth/Views/{1}/{0}.cshtml");
    o.ViewLocationFormats.Add("/AdminConsole/Views/{1}/{0}.cshtml");
    o.ViewLocationFormats.Add("/Billing/Views/{1}/{0}.cshtml");
});
View areas:
  • Auth: Login and authentication views
  • AdminConsole: Organization and user management
  • Billing: Billing operations and reports

Middleware Pipeline

From src/Admin/Startup.cs:133:
Request Pipeline
public void Configure(IApplicationBuilder app)
{
    // Security headers
    app.UseMiddleware<SecurityHeadersMiddleware>();
    
    // Self-hosted path base
    if (globalSettings.SelfHosted)
    {
        app.UsePathBase("/admin");
        app.UseForwardedHeaders(globalSettings);
    }
    
    // Error handling
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }
    else
    {
        app.UseExceptionHandler("/error");
    }
    
    // Static files
    app.UseStaticFiles();
    
    // Routing
    app.UseRouting();
    
    // Authentication & Authorization
    app.UseAuthentication();
    app.UseAuthorization();
    
    // Endpoints
    app.UseEndpoints(endpoints => endpoints.MapDefaultControllerRoute());
}

Access Control

The Admin service implements permission-based access control:
Permission System
public enum Permission
{
    Tools_ChargeBrainTreeCustomer,
    Tools_CreateEditTransaction,
    Tools_ManageStripeSubscription,
    Tools_GenerateLicenseFile,
    Tools_ManageOrganization,
    Tools_ViewUser,
    Tools_EditUser,
    Tools_DeleteUser
}
Permissions are enforced via attributes:
Permission Attribute
[RequirePermission(Permission.Tools_ChargeBrainTreeCustomer)]
public IActionResult ChargeBraintree()
{
    return View(new ChargeBraintreeModel());
}

Deployment

Environment Variables

GLOBALSETTINGS__SELFHOSTED=true
GLOBALSETTINGS__SQLSERVER__CONNECTIONSTRING=<connection>
GLOBALSETTINGS__STRIPE__APIKEY=<stripe_key>
ADMINSETTINGS__ADMINS=[email protected]

Docker

docker run -d \
  --name bitwarden-admin \
  -p 5004:5000 \
  -e GLOBALSETTINGS__SelfHosted=true \
  -e GLOBALSETTINGS__SqlServer__ConnectionString="<connection>" \
  bitwarden/admin:latest

Self-Hosted Access

In self-hosted deployments, admin functionality is limited. The portal runs at /admin path.
Nginx Configuration
location /admin {
    proxy_pass http://admin:5000/admin;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
}

Self-Hosted vs Cloud

FeatureSelf-HostedCloud
Database MigrationsAutomaticManual
User ManagementLimitedFull
Billing ToolsDisabledEnabled
Stripe IntegrationN/AEnabled
Email QueueN/AEnabled
Access ControlBasicPermission-based

Integration with Other Services

Stripe

Direct Stripe API integration for billing operations

Database

Direct database access for administrative queries

Email

Azure Queue integration for email processing (cloud)

Cache

Distributed cache for performance

Security Considerations

The Admin service should only be accessible to trusted administrators.
  • Environment-based user authentication
  • No user self-registration
  • Permission-based access control
  • Read-only operations preferred
  • Audit logging for sensitive operations

Build docs developers (and LLMs) love