ravendb/sso repository overview

⁠RavenDB SSO

A reverse-proxy SSO gateway for RavenDB⁠ clusters. It sits in front of one or more RavenDB clusters, authenticates users via Windows/Kerberos SSO or OAuth2 (GitHub, Google, Microsoft/Entra ID), and forwards requests to the correct cluster node over mTLS using a short-lived, per-user client certificate — so end users never need to manage RavenDB client certificates themselves.

Browser → nginx (443) → auth (Kerberos / OAuth2) → RavenDB cluster (mTLS, per-user cert)

Each configured cluster is reachable at <node-tag>-<cluster-alias>.<sso-domain>, e.g. a-prod.sso.example.com.

Built from the main branch. Looking for bleeding-edge builds instead? See ravendb/sso-nightly⁠, built from dev.

⁠Tags

Multi-arch manifests (latest, X.Y.Z) cover linux/amd64, linux/arm64, and linux/arm/v7; Docker pulls the right one automatically. Single-arch tags (X.Y.Z-amd64, X.Y.Z-arm64, X.Y.Z-armv7) also exist on the registry but are build artifacts, not meant to be pulled directly.

⁠Quick start

The image bundles nginx, oauth2-proxy, and the .NET auth service in a single container. The minimum you need is a public HTTPS URL, a TLS certificate, and at least one auth provider configured.

docker run -d --name ravendb-sso \
  -p 443:443 -p 80:80 \
  -e RAVENDBSSO_Url=https://sso.example.com \
  -e RAVENDBSSO_CertificatePath=/app/certs/fullchain.pem \
  -e RAVENDBSSO_CertificateKeyPath=/app/certs/privkey.pem \
  -e RAVENDBSSO_Clusters='[{"ClusterUrls":["https://a.my-cluster.example.com"],"ClusterAlias":"my-cluster"}]' \
  -e OAUTH2_PROXY_COOKIE_SECRET=$(openssl rand -hex 16) \
  -e GITHUB_CLIENT_ID=... \
  -e GITHUB_CLIENT_SECRET=... \
  -v $(pwd)/certs:/app/certs \
  -v $(pwd)/users-certs:/app/users-certs \
  -v $(pwd)/logs:/app/logs \
  ravendb/sso:latest

For a production-ready setup with automated Let's Encrypt certificate issuance/renewal via Route53, see the example/⁠ directory in the source repo — it ships a complete docker-compose.yml pairing this image with a certbot sidecar.

services:
  sso:
    image: ravendb/sso:latest
    container_name: ravendb-sso
    restart: always
    user: "10000:10000"
    cap_add: [ NET_BIND_SERVICE ]
    env_file: [ sso.env ]
    ports: [ "80:80", "443:443" ]
    volumes:
      - ./config:/app/config
      - ./certs:/app/certs
      - ./logs:/app/logs

⁠Configuration

Settings are read from environment variables (prefix RAVENDBSSO_) or from a mounted /app/config/settings.json. Env vars take precedence, and the two sources can be mixed.

* Required unless clusters are supplied via settings.json instead. ** Only required once an OAuth provider is configured; Kerberos-only deployments don't need it.

At least one auth provider (Windows/Kerberos or one of the OAuth providers) must be configured for the gateway to be usable.

⁠Volumes

⁠Ports

• 443 — HTTPS (SSO login/UI/API and per-cluster reverse proxy)
• 80 — HTTP, redirects to 443

⁠User & capabilities

The container runs as a non-root user (10000:10000) and needs CAP_NET_BIND_SERVICE to bind ports 80/443 as that user — pass --cap-add NET_BIND_SERVICE (or the Compose equivalent) when running it.

⁠Source & docs

Full documentation, the security-hardened docker-compose.yml example (with Let's Encrypt automation), and issue tracking live at github.com/ravendb/sso⁠.