# Mongonaut: Self-Hosted MongoDB Web GUI ## Authentication > Category: Security --- ## Pages - [Overview](https://mongonaut.org/about-mongonaut) - [Installation](https://mongonaut.org/installation) - [Docker setup](https://mongonaut.org/mongodb-gui-docker) ### Compare - [Mongonaut vs mongo-express](https://mongonaut.org/compare/mongonaut-vs-mongo-express) - [Mongonaut vs MongoDB Compass](https://mongonaut.org/compare/mongonaut-vs-mongodb-compass) ### Guides - [Migrate from mongo-express](https://mongonaut.org/guides/migrate-from-mongo-express) - [Read-only configuration](https://mongonaut.org/guides/read-only-configuration) - [Troubleshooting](https://mongonaut.org/guides/troubleshooting) ### Security - [Authentication](https://mongonaut.org/security/authentication) - [Cloudflare Zero Trust Tunnel](https://mongonaut.org/security/zero-trust-tunnel) ### Community - [FAQ](https://mongonaut.org/community/faq) - [Contributing](https://mongonaut.org/community/contributing) --- # Authentication Mongonaut includes an application-level authentication layer for the web interface. Use it when Mongonaut is reachable by anyone other than a single trusted local user. Access is enforced on the server before database operations are executed. MongoDB permissions still matter: the MongoDB user in `MONGO_CONNECTION_URL` defines what the application can ultimately do against the database. ## Prerequisites - A running Mongonaut container. - A strong random `MONGONAUT_AUTH_SECRET` for every mode except `NONE`. - A plan for who should access the MongoDB web GUI. - HTTPS at the proxy, tunnel or load balancer layer when accessed over a network. Generate a signing secret: ```bash openssl rand -base64 32 ``` Use it in your environment: ```env name=".env" MONGONAUT_AUTH_SECRET= MONGONAUT_SESSION_TTL=86400 ``` ## Authentication modes Choose one mode with `MONGONAUT_AUTH_MODE`. | Mode | Description | Typical use | | --- | --- | --- | | `ACCOUNT` | Individual Mongonaut accounts with per database and per collection permissions. This is the default. | Internal teams and shared instances. | | `STATIC_PASSWORD` | One shared password unlocks the interface. | Personal setups or small trusted groups. | | `OIDC` | Login through an external OpenID Connect provider. | Organizations with an existing identity provider. | | `NONE` | No Mongonaut login. Anyone who can reach the port can use it. | Only behind another trust boundary such as Cloudflare Access, VPN or an authenticated reverse proxy. | ## Mode 1: Account login Account mode is the default. On first start, Mongonaut redirects to `/setup` so you can create the first administrator account. ```env name=".env" MONGONAUT_AUTH_MODE=ACCOUNT MONGONAUT_AUTH_SECRET= MONGONAUT_SYSTEM_DB=__mongonaut ``` Start the container and open: ```text http://localhost:8081/setup ``` Administrators can manage accounts from the gear icon in the sidebar. They can: - Create accounts with email, password and optional display name. - Grant access to one database, one collection, or all collections in a database. - Choose read-only or read/write grants. - Mark accounts as administrators. - Disable or delete accounts. - Reset passwords. Mongonaut prevents removing the last active administrator to avoid lockout. ## Recover an administrator account If an administrator is locked out, generate a temporary one-time password from the server console. From a source checkout: ```bash pnpm recovery pnpm recovery admin@example.com ``` From a running Docker container: ```bash docker exec node scripts/recovery.mjs admin@example.com ``` The temporary password expires after `MONGONAUT_RECOVERY_TTL_MINUTES` minutes. The default is `30`. ## Mode 2: Static password Static password mode uses one shared password for the whole interface. ```env name=".env" MONGONAUT_AUTH_MODE=STATIC_PASSWORD MONGONAUT_AUTH_SECRET= MONGONAUT_AUTH_PASSWORD= ``` Docker Compose example: ```yaml name="docker-compose.yml" services: mongonaut: image: ghcr.io/withzu/mongonaut ports: - 8081:8081 environment: MONGO_CONNECTION_URL: mongodb://mongo:27017/ MONGONAUT_AUTH_MODE: STATIC_PASSWORD MONGONAUT_AUTH_SECRET: ${MONGONAUT_AUTH_SECRET} MONGONAUT_AUTH_PASSWORD: ${MONGONAUT_AUTH_PASSWORD} ``` Use static password mode only when every authorized user should have the same application-level access. ## Mode 3: OIDC OIDC mode lets users sign in with an external identity provider. ```env name=".env" MONGONAUT_AUTH_MODE=OIDC MONGONAUT_AUTH_SECRET= MONGONAUT_OIDC_ISSUER=https://id.example.com MONGONAUT_OIDC_CLIENT_ID= MONGONAUT_OIDC_CLIENT_SECRET= ``` Optional OIDC configuration: ```env name=".env" MONGONAUT_OIDC_SCOPES=openid profile email MONGONAUT_OIDC_ALLOWED_EMAILS=alice@example.com,bob@example.com MONGONAUT_OIDC_REDIRECT_URL=https://mongonaut.example.com/api/auth/oidc/callback ``` Register this callback URL in your identity provider: ```text https:///api/auth/oidc/callback ``` Use `MONGONAUT_OIDC_ALLOWED_EMAILS` if the identity provider authenticates more users than should access Mongonaut. ## Mode 4: No authentication Disable Mongonaut authentication only when another layer already controls access. ```env name=".env" MONGONAUT_AUTH_MODE=NONE ``` With `NONE`, anyone who can reach the HTTP port can use Mongonaut with the MongoDB permissions from `MONGO_CONNECTION_URL`. Do not publish this mode directly to the internet. ## Session behavior - Sessions are stored in a signed HTTP-only cookie named `mongonaut_session`. - The cookie uses `SameSite=Lax`. - The cookie is marked `Secure` when Mongonaut is reached over HTTPS. - Session lifetime is controlled by `MONGONAUT_SESSION_TTL` in seconds. - In account mode, the cookie stores an account id and token version. Permissions are read on every request. ## Login rate limiting `ACCOUNT` and `STATIC_PASSWORD` logins use rate limiting. Tune these values only when you have a reason: ```env MONGONAUT_LOGIN_MAX_ATTEMPTS=5 MONGONAUT_LOGIN_WINDOW_SECONDS=900 MONGONAUT_LOGIN_LOCKOUT_SECONDS=900 MONGONAUT_LOGIN_GLOBAL_MAX_ATTEMPTS=50 MONGONAUT_LOGIN_GLOBAL_WINDOW_SECONDS=300 ``` ## Common errors ### Missing `MONGONAUT_AUTH_SECRET` Every mode except `NONE` needs a signing secret. Generate one with `openssl rand -base64 32`. ### Cannot open `/setup` `/setup` only works before the first account exists. After that, sign in through `/login`. ### OIDC redirects to the wrong host Set `MONGONAUT_OIDC_REDIRECT_URL` to the public callback URL and make sure the same value is registered in the identity provider. ### Users authenticate but should not have access For OIDC, configure `MONGONAUT_OIDC_ALLOWED_EMAILS`. For account mode, adjust database and collection grants from account management. ## Related links - [Install Mongonaut](/installation) - [Cloudflare Zero Trust Tunnel](/security/zero-trust-tunnel) - [Read-only configuration](/guides/read-only-configuration) - [Troubleshooting](/guides/troubleshooting)