# Mongonaut

## Authentication

> Category: Security

---

## Pages

- [About Mongonaut](https://mongonaut.org/about-mongonaut)
- [Installation](https://mongonaut.org/installation)

### Security

- [Authentication](https://mongonaut.org/security/authentication)
- [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 ships with a small built in authentication layer. It is optional and disabled by default, so existing deployments keep working unchanged. When enabled, every request is gated behind a signed, HTTP only session cookie.

There are three modes, selected through `MONGONAUT_AUTH_MODE`:

| Mode              | When to use                                                                                          |
| ----------------- | ---------------------------------------------------------------------------------------------------- |
| `NONE`            | No authentication. Anyone who can reach the port can use Mongonaut. The default.                     |
| `STATIC_PASSWORD` | A single shared password gates the UI. Good for personal use or small trusted teams.                 |
| `OIDC`            | Sign in through an external identity provider (Authentik, Keycloak, Auth0, Google, ...).             |

<Alert type="warning">

`NONE` is only safe behind another trust boundary, for example a [Zero Trust Tunnel](/security/zero-trust-tunnel), a VPN or a reverse proxy that enforces authentication itself.

</Alert>

---

## Shared Setup

For any mode other than `NONE`, set a strong random `MONGONAUT_AUTH_SECRET`. It is used to sign session cookies, so leaking it lets anyone forge a valid session.

```bash
# 32 random bytes, base64 encoded
openssl rand -base64 32
```

```env name=".env"
MONGONAUT_AUTH_SECRET=<paste the generated value>
# Optional: session lifetime in seconds (default 86400 = 24h)
MONGONAUT_SESSION_TTL=86400
```

If `MONGONAUT_AUTH_SECRET` is missing while `MONGONAUT_AUTH_MODE` is not `NONE`, Mongonaut logs an error and treats auth as disabled until it is configured.

---

## Mode 1: Static Password

The simplest setup. One shared password unlocks the UI for every visitor.

```env name=".env"
MONGONAUT_AUTH_MODE=STATIC_PASSWORD
MONGONAUT_AUTH_SECRET=<your signing secret>
MONGONAUT_AUTH_PASSWORD=<the shared password>
```

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

Visiting Mongonaut now redirects to `/login`, where the password is entered once and stored as a session cookie until `MONGONAUT_SESSION_TTL` expires.

---

## Mode 2: OIDC

Use an external identity provider through OpenID Connect. Mongonaut performs a standard authorization code flow with PKCE and verifies the returned `id_token` against the issuer's JWKS.

### Required variables

```env name=".env"
MONGONAUT_AUTH_MODE=OIDC
MONGONAUT_AUTH_SECRET=<your signing secret>

MONGONAUT_OIDC_ISSUER=https://id.example.com
MONGONAUT_OIDC_CLIENT_ID=<your client id>
MONGONAUT_OIDC_CLIENT_SECRET=<your client secret>
```

### Optional variables

```env name=".env"
# Defaults to "openid profile email" if unset
MONGONAUT_OIDC_SCOPES=openid profile email

# Restrict access to specific email addresses. Empty means everyone the IdP authenticates.
MONGONAUT_OIDC_ALLOWED_EMAILS=alice@example.com,bob@example.com

# Override the redirect URL if the request URL Mongonaut sees does not match your public URL
# (for example, behind a reverse proxy that does not forward the original host).
MONGONAUT_OIDC_REDIRECT_URL=https://mongonaut.example.com/api/auth/oidc/callback
```

### Provider configuration

When registering Mongonaut as a client in your identity provider, use these values:

- **Redirect URI**: `https://<your-mongonaut-host>/api/auth/oidc/callback`
- **Grant type**: Authorization Code
- **Response type**: `code`
- **PKCE**: enabled (method `S256`)
- **Scopes**: `openid`, `profile`, `email`

The login button on `/login` starts the flow at `/api/auth/oidc/start` and the provider redirects back to `/api/auth/oidc/callback` after authentication.

### Restricting access by email

If you want only specific people to be able to sign in, set `MONGONAUT_OIDC_ALLOWED_EMAILS` to a comma separated list. The comparison is case insensitive. If the variable is empty or unset, every user the OIDC provider authenticates can log in.

---

## How sessions work

- Sessions are stored in a signed, HTTP only cookie named `mongonaut_session`.
- The cookie uses `SameSite=Lax` and is marked `Secure` when Mongonaut is reached over HTTPS.
- Lifetime is controlled by `MONGONAUT_SESSION_TTL` (seconds, default 24 hours).
- Sign out via `POST /api/auth/logout`. The current session info is available at `GET /api/auth/me`.

No session data is stored server side, the cookie itself carries the signed payload.

---

## Combining with Zero Trust

The built in authentication and [Zero Trust Tunnel](/security/zero-trust-tunnel) are not mutually exclusive. A common pattern is to:

1. Expose Mongonaut only through a Cloudflare Tunnel.
2. Use Cloudflare Access policies as the first authentication layer.
3. Use `MONGONAUT_AUTH_MODE=STATIC_PASSWORD` or `OIDC` as a second factor inside Mongonaut itself.

This way the application is never reachable from the public internet, and a session cookie alone is not enough to access it.