Security

Configure two-factor authentication, OAuth login, password management, and login security policies.

ServerBee layers several security controls: two-factor authentication (2FA), OAuth social login, password policies, and login rate limiting.

Two-Factor Authentication (2FA)

ServerBee supports TOTP (Time-based One-Time Password) based two-factor authentication, compatible with all standard authenticator apps (Google Authenticator, Authy, 1Password, etc.).

Enabling 2FA

Log in and go to Settings → Security
In the Two-Factor Authentication section, click Setup
Scan the QR code (or enter the Base32 secret manually)
Enter the 6-digit code from your authenticator app
Click Enable to finish setup

Once enabled, a 6-digit TOTP code is required for every login. Codes refresh every 30 seconds.

Disabling 2FA

Go to Settings → Security
Click Disable 2FA
Enter your current password to confirm
2FA is disabled

API Endpoints

Endpoint	Method	Description
`/api/auth/2fa/setup`	POST	Generate TOTP secret and QR code
`/api/auth/2fa/enable`	POST	Verify code and enable 2FA
`/api/auth/2fa/disable`	POST	Verify password and disable 2FA
`/api/auth/2fa/status`	GET	Check current 2FA status

ServerBee supports three OAuth providers:

Provider	Config Section	Callback URL
GitHub	`[oauth.github]`	`{base_url}/api/auth/oauth/github/callback`
Google	`[oauth.google]`	`{base_url}/api/auth/oauth/google/callback`
OIDC	`[oauth.oidc]`	`{base_url}/api/auth/oauth/oidc/callback`

Configuring OAuth

Add OAuth configuration to server.toml (see Server Setup):

[oauth]
base_url = "https://monitor.example.com"
allow_registration = false

[oauth.github]
client_id = "your-github-client-id"
client_secret = "your-github-client-secret"

OAuth Account Management

View linked OAuth accounts in Settings → Security
Click Unlink to disconnect an OAuth account
If allow_registration = false (default), first-time OAuth logins do not create new users — an admin must create the user first

Enable allow_registration = true only when the OAuth provider itself is access-controlled (self-hosted OIDC or an org-internal IdP). Auto-created accounts get the Member role, which can read all monitoring data — including security events and public IPs. With a public provider such as GitHub, enabling it grants that access to every user of the provider.

Click an OAuth provider button on the login page (e.g., "Login with GitHub")
Redirect to the provider's authorization page
After authorization, redirect back to ServerBee
If the OAuth account is linked to an existing user, log in directly
If not linked and allow_registration = true, create a new Member user and log in
If not linked and allow_registration = false, return an error

Password Management

Changing Password

Go to Settings → Security
Enter your current password and new password in "Change Password"
Click Change Password

Passwords are hashed with argon2, following OWASP recommendations.

First-Run Admin Credentials

On first start (when no users exist), ServerBee auto-creates an admin account with a randomly generated password and prints it once to the server/container logs as a highlighted credentials banner. The username and password cannot be preset via environment variables. On first login you must change this password, and may optionally choose a different username.

ServerBee enforces IP-level rate limiting on the login endpoint:

Maximum 5 failed attempts per 15-minute window by default (configurable via rate_limit.login_max)
Returns 429 Too Many Requests when exceeded
Expired rate limit records are cleaned up by the background session_cleaner task

Agent Registration Rate Limiting

Agent registration endpoints are also rate limited:

Maximum 10 registration attempts per 15-minute window by default (configurable via rate_limit.register_max). The Railway template deliberately overrides this to 3 as a stricter hosted default

Session Security

Session cookies are set with HttpOnly + Secure flags by default
Session lifetime is 24 hours (configurable via auth.session_ttl)
For HTTP-only development, set auth.secure_cookie = false