Skip to main content

Authentication

Thermocline supports multiple authentication mechanisms at the wire protocol level via the Gateway.

SCRAM-SHA-256​

The default authentication mechanism, compatible with all MongoDB drivers:

mongosh "mongodb://admin:password@localhost:27017/admin?authMechanism=SCRAM-SHA-256"

Enable authentication:

export GATEWAY_AUTH_REQUIRED=true
export GATEWAY_BOOTSTRAP_ROOT_USER=admin
export GATEWAY_BOOTSTRAP_ROOT_PASSWORD=securepassword

JWT Authentication​

Validate external JWTs from your identity provider:

export THERMOCLINE_JWT_ISSUER=https://auth.example.com
export THERMOCLINE_JWT_AUDIENCE=thermocline
export THERMOCLINE_JWT_USERNAME_CLAIM=sub
export THERMOCLINE_JWT_ROLE_CLAIM=roles

JWT claims are extracted and mapped to the MongoDB role system, enabling document-level security with $auth.* variables.

OIDC Authentication​

Connect to any OpenID Connect provider:

export THERMOCLINE_OIDC_ISSUER=https://accounts.google.com
export THERMOCLINE_OIDC_AUDIENCE=your-client-id

Account Lockout​

Protect against brute-force attacks:

export THERMOCLINE_AUTH_LOCKOUT_ENABLED=true
export THERMOCLINE_AUTH_LOCKOUT_MAX_ATTEMPTS=5
export THERMOCLINE_AUTH_LOCKOUT_DURATION_SECS=60

Lockout uses exponential backoff up to a configurable maximum duration.

TLS / mTLS​

Enable TLS termination at the Gateway:

export GATEWAY_TLS_ENABLED=true
export GATEWAY_TLS_CERT_PATH=/certs/server.pem
export GATEWAY_TLS_KEY_PATH=/certs/server-key.pem

# For mTLS (mutual TLS)
export GATEWAY_TLS_CA_CERT_PATH=/certs/ca.pem
export GATEWAY_TLS_REQUIRE_CLIENT_CERT=true

Inter-Service Authentication​

Internal gRPC calls between services use HMAC-SHA256 signed AuthContext headers:

export THERMOCLINE_AUTH_SIGNING_KEY=<base64-encoded-32-byte-key>

Source of Truth​

  • Gateway auth: services/gateway/src/proxy/handler/auth.rs
  • JWT validation: services/gateway/src/auth/jwt.rs
  • OIDC: services/gateway/src/auth/oidc.rs
  • Account lockout: services/gateway/src/auth/lockout.rs