# Security and Audit

This page summarizes how SelfDocHub protects access and data, and what it records in the audit log. Use it when you review a deployment.

## Authentication model

- Users sign in at `/login`. The server returns a signed bearer token that the browser stores and sends as `Authorization: Bearer <token>`. Because the token is attached explicitly instead of through a cookie, cross-site request forgery is not a risk for authenticated requests.
- There is no server-side session store. Signing out forgets the token on the client. Token lifetime is `session_timeout`, or `remember_me_timeout` with "Remember me".
- Passwords are stored as bcrypt hashes only. Failed logins return one generic error, and attempts are rate-limited per login and client IP.
- Two-factor authentication (TOTP) and OIDC single sign-on are available. See [Users and Two-Factor Auth](/documentation/users-and-two-factor) and [Single Sign-On (SSO)](/documentation/single-sign-on).
- Every `/api/v1/...` route needs a valid token and answers `401` without one. The page shell itself is served unconditionally, so access control happens at the API.
- Service upload tokens are a separate mechanism. Only salted hashes are stored, raw tokens are shown once and never logged.

## Secrets at rest

Two-factor secrets, SSO client secrets and notification secrets are stored encrypted (AES-GCM) with a key derived from `session_secret`. Secrets are write-only: no API returns them. Changing `session_secret` makes them unreadable. See [Configuration Reference](/documentation/configuration).

## HTTP hardening

- Responses carry `Content-Security-Policy`, `X-Content-Type-Options`, `X-Frame-Options` and `Referrer-Policy` headers.
- The web interface JavaScript is served from the application itself. No external CDN script is loaded by default.
- Read, write and idle timeouts are configurable.
- Uploaded pictures and export images are checked by content, SVG files are sanitized, and files are served with `nosniff` and a policy that forbids scripts.

## Try-It limits

The Try-It proxy limits the request body to 1 MiB and the response to `max_tryit_response_bytes`, applies per-request timeouts, validates the target URL, never forwards `Cookie` or `Authorization`, and returns only allow-listed response headers. The target is chosen by the client, so deploy SelfDocHub where reaching internal hosts from users' Try-It requests is acceptable. See [Try-It](/documentation/try-it).

## Notification targets

Notification channels cannot reach loopback, private or link-local addresses unless you turn on `notifications_allow_private_targets`. See [Notifications](/documentation/notifications).

## MCP

MCP tokens are individually scoped, can be limited by IP, and every rejection is logged. Try-It through MCP has additional controls. See [MCP Server](/documentation/mcp-server) and [Try-It Through MCP](/documentation/mcp-try-it).

## HTTPS

Serve SelfDocHub over HTTPS for anything beyond `localhost`. The copy buttons use the browser clipboard API, which exists only in a secure context. Over plain HTTP they fall back to a legacy method. See [Installation](/documentation/installation).

## Audit log

Audit events are emitted as structured JSON log lines (one object per line, on stderr) for:

- login outcomes;
- spec publishing;
- admin changes to users, services, groups and teams;
- overlay changes, rebuilds and snapshot promotes;
- SSO events such as `sso_login_success`, `sso_login_denied`, `sso_link`, `sso_unlink` and provider changes;
- label changes (`service_label_added`, `service_label_removed`);
- MCP events (`mcp_request_rejected`, `mcp_tryit_request`, `mcp_tryit_rejected`, `mcp_tryit_selection_saved`).

Audit events carry metadata only. Passwords, session tokens, service tokens, MCP secrets, raw request bodies and generated tokens are never logged.

View the log with `docker compose logs -f docs-hub`.

## Next steps

- [Roles and Permissions](/documentation/roles-and-permissions)
- [Upgrading and Backups](/documentation/upgrading-and-backups)

---
Source: https://selfdochub.com/documentation/audit-and-security
