High Availability

Balance load across several Gate One replicas with shared session and revocation state.

This example runs several Gate One replicas behind a load balancer and uses Redis as the shared OIDC session/revocation store. It is the multi-instance variant of the multi-app SSO example.

File

examples/high-availability/routes.json

{
  "authProvider": {
    "type": "oidc",
    "issuer": "https://auth.example.com/realms/company",
    "clientId": "gate-one",
    "clientSecretEnv": "OIDC_CLIENT_SECRET",
    "loginBaseUrl": "https://login.example.com",
    "cookieDomain": "example.com",
    "sessionKeyEnv": "OIDC_SESSION_KEY",
    "sessionStore": {
      "type": "redis",
      "url": "redis://redis:6379/0",
      "passwordEnv": "REDIS_PASSWORD",
      "prefix": "cladone:auth:v1:"
    }
  },
  "routes": [{
    "host": "app.example.com", "path": "/*", "frontend": true,
    "backend": "http://app:8080", "auth": {}
  }]
}

Run it

The packaged demo runs two Gate One instances, two tenants, two IAMs and Redis (Docker Compose):

cd gate-one-src/deploy/local/redis
BIN_DIR=~/gate-one-bin ./run.sh

The script prints the URLs and stops with ./run.sh down. See [deploy/local/redis](https://github.com/clad-one/gate-one/tree/main/deploy/local/redis) for the stack and its README.

To run it by hand instead:

export OIDC_CLIENT_SECRET=...
export OIDC_SESSION_KEY="$(openssl rand -base64 32)"
export REDIS_PASSWORD=...
gate-one -check -config routes.json
gate-one -config routes.json

OIDC_SESSION_KEY must be identical on every Gate One replica: it signs the shared session cookie. The Redis URL and password are also shared.

When to use it

When you need horizontal scaling using several Gate One replicas behind a load balancer.

Single-instance alternative

A single Gate One instance keeps the default bbolt store. See multi-app SSO for that simpler setup.

Failure mode

When sessionStore is Redis and Redis is unavailable, authenticated routes fail with 502 authentication_unavailable. Public routes keep working.

Sentinel, TLS and ACL authentication are configured in authProvider.sessionStore.