# Security

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

URL: https://docs.serverbee.app/en/docs/security

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

## Two-Factor Authentication (2FA) [#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 [#enabling-2fa]

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

<Callout type="info">
  Once enabled, a 6-digit TOTP code is required for every login. Codes refresh every 30 seconds.
</Callout>

### Disabling 2FA [#disabling-2fa]

1. Go to Settings → Security
2. Click **Disable 2FA**
3. Enter your current password to confirm
4. 2FA is disabled

### API Endpoints [#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         |

## OAuth Social Login [#oauth-social-login]

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 [#configuring-oauth]

Add OAuth configuration to `server.toml` (see [Server Setup](/en/docs/server)):

```toml
[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 [#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

<Callout type="warn">
  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.
</Callout>

### Login Flow [#login-flow]

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

## Password Management [#password-management]

### Changing Password [#changing-password]

1. Go to Settings → Security
2. Enter your current password and new password in "Change Password"
3. Click **Change Password**

Passwords are hashed with argon2, following OWASP recommendations.

### First-Run Admin Credentials [#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.

## Login Security [#login-security]

### Login Rate Limiting [#login-rate-limiting]

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-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-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`

<Cards>
  <Card title="Server Setup" href="/en/docs/server" />

  <Card title="Admin Guide" href="/en/docs/admin" />

  <Card title="Configuration" href="/en/docs/configuration" />
</Cards>