Run it in
production.

Deploy

Production checklist

Check every configuration change before deploying it with oauth2relay --check-config --config config.json. It exits with status 1 and names the problem if the file is invalid, and prints warnings for discouraged settings. It contacts nothing, so it is safe in CI.

The relay needs its configuration file, outbound HTTPS to the identity provider, the API and any secrets managers, and nothing else: no database, and no disk apart from an optional logfile.

systemd

Each Linux archive includes deploy/systemd/oauth2relay.service, which runs the relay as an unprivileged oauth2relay user with a restrictive sandbox (systemd-analyze security rates it 1.2, "OK"). To install it:

sudo install -m 0755 oauth2relay /usr/local/bin/oauth2relay
sudo useradd --system --no-create-home --shell /usr/sbin/nologin oauth2relay
sudo install -d -m 0750 -g oauth2relay /etc/oauth2relay
sudo install -m 0640 -g oauth2relay config.json /etc/oauth2relay/config.json
sudo install -m 0600 /dev/null /etc/oauth2relay/oauth2relay.env   # then add VAR=value lines
sudo install -m 0644 deploy/systemd/oauth2relay.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now oauth2relay
journalctl -u oauth2relay -f

• Environment variables go in /etc/oauth2relay/oauth2relay.env, mode 0600, owned by root: credentials referenced as ${env:NAME}, and secrets manager settings such as AWS_REGION, VAULT_ADDR or VAULT_SECRET_ID. The configuration file then holds no secrets.
• The configuration is checked before each start, so a restart with an invalid configuration fails at once with the reason in the journal.
• Logs go to the journal. If you set logfile, use /var/log/oauth2relay/, the only directory the service can write to.
• The relay port must be 1024 or higher unless you uncomment the CAP_NET_BIND_SERVICE lines in the unit.
• Keep the unit's TimeoutStopSec (45 seconds) above shutdown_delay + shutdown_timeout.

To apply a configuration change, check it, then systemctl restart oauth2relay. In-flight requests are drained, but new connections are refused until the relay is ready again, so restart one instance at a time behind a load balancer.

Containers

Build an image from the Linux binary with the Dockerfile in the installation guide. It is distroless, has no shell, and runs as UID 65532.

docker build -t oauth2relay:2.1.0 .
docker run -d --name oauth2relay -p 8080:8080 -p 9090:9090 \
  -v /etc/oauth2relay:/etc/oauth2relay:ro \
  --env-file /etc/oauth2relay/oauth2relay.env \
  --read-only --cap-drop ALL --security-opt no-new-privileges \
  oauth2relay:2.1.0

• Set "host": "0.0.0.0", otherwise the relay only listens inside the container.
• The configuration file must be readable by UID 65532.
• The image has no HEALTHCHECK, because it has no shell or HTTP client; use the orchestrator's HTTP checks on /healthz and /readyz.

Kubernetes

The essential parts of a Deployment, with "host": "0.0.0.0", "admin_port": 9090 and "server": {"shutdown_delay": 5} in the configuration:

spec:
  template:
    spec:
      terminationGracePeriodSeconds: 30
      securityContext:
        runAsNonRoot: true
        seccompProfile: {type: RuntimeDefault}
      containers:
        - name: oauth2relay
          image: registry.example.com/oauth2relay:2.1.0
          ports:
            - {name: relay, containerPort: 8080}
            - {name: admin, containerPort: 9090}
          envFrom:
            - secretRef: {name: oauth2relay-env}     # API_CLIENT_SECRET=...
          livenessProbe:
            httpGet: {path: /healthz, port: admin}
          readinessProbe:
            httpGet: {path: /readyz, port: admin}
            periodSeconds: 5
          startupProbe:
            httpGet: {path: /healthz, port: admin}
            failureThreshold: 30
            periodSeconds: 2
          securityContext:
            readOnlyRootFilesystem: true
            allowPrivilegeEscalation: false
            capabilities: {drop: [ALL]}
          volumeMounts:
            - {name: config, mountPath: /etc/oauth2relay, readOnly: true}
      volumes:
        - name: config
          configMap:
            name: oauth2relay-config

With the credentials in a Secret exposed as environment variables, the configuration has no secrets and can live in a ConfigMap. For Vault, use the kubernetes auth method with a dedicated service account; for AWS and Azure, use workload identity (IRSA, EKS Pod Identity or Azure Workload Identity) rather than static keys.

Liveness passes as soon as the admin port is listening, so a slow first login does not get the pod restarted; readiness passes once the first token is obtained. TLS certificates mounted from a Secret, e.g. by cert-manager, are reloaded without a restart.

Shutdown

On SIGTERM or SIGINT the relay:

1. reports draining on /readyz and keeps serving for server.shutdown_delay seconds (default 0), so load balancers stop sending traffic;
2. stops accepting connections and waits up to server.shutdown_timeout seconds (default 15) for in-flight requests;
3. exits with status 0.

Run

Scaling

The relay is stateless apart from its current token, so it scales horizontally behind any load balancer without session affinity.

Each replica obtains and renews its own token: with background refresh, N replicas make about N token requests per token lifetime, whether or not they serve traffic. Check that this stays within the identity provider's rate limits and any limit on active tokens per client. Login retries are jittered so replicas do not retry in step after an outage.

Form and JSON bodies are read into memory to merge parameters, up to max_request_body_bytes (10 MiB) each; other bodies are streamed. There are no published benchmarks yet: size replicas by load testing with your own traffic, watching process_resident_memory_bytes and oauth2relay_request_duration_seconds.

Monitoring

Scrape /metrics with Prometheus (all metrics are in the documentation). Suggested alerts:

Readiness does not fail when token renewal fails, so these alerts, not the load balancer, are how an identity provider problem is noticed. Every response carries an X-Request-ID header that matches the relay's log line and is sent to the API; ask callers for it when they report a failed request.

Startup failures

Startup failures are logged at ERROR with the cause in error, and the process exits with status 1.

Request failures

The relay's own errors are JSON with an error code, and the request log line with the same request_id has the cause in detail. Responses without that body come from the API.

To investigate, restart one instance with --log-level debug. Debug logs include token and relayed requests and responses with secrets masked, but may contain personal data from request bodies; switch back to info afterwards. If a renewed certificate is not picked up, look for Could not reload the TLS certificate, usually a key that does not match.

Rotating credentials

Client secret or private key

With the credential in a secrets manager and secrets_refresh_interval set, no restart is needed:

1. Create the new secret, or register the new public key, at the identity provider, keeping the old one valid.
2. Store the new value in the secrets manager under the same name (and update jwt_key_id if the provider selects keys by kid).
3. Wait one interval (check oauth2relay_secrets_last_refresh_timestamp_seconds on every replica) plus one token lifetime, so the next login uses the new credential.
4. Revoke the old credential.

With ${env:NAME} or a value in the file, update it and restart the replicas one at a time, then revoke the old credential.

Relay API key

The relay accepts one apiKey, so callers and relay switch together: make the new key available to callers, change it on the relay (at the next re-fetch if it comes from a secrets manager, otherwise by restarting), then switch the callers. Requests with the old key fail with 401 in between, so keep the window short.

Secrets manager credentials

• AWS: use an IAM role (instance profile, IRSA or EKS Pod Identity); the SDK renews it itself.
• Vault AppRole: update the SecretID variable and restart. With kubernetes auth there is nothing to rotate.
• Azure: use a managed or workload identity; with a service principal, update the secret's variable and restart.

TLS certificate

Replace the files at tls.cert_file and tls.key_file; the relay picks them up within 10 seconds of the next connection. Write the key first or rename both into place atomically, since the old certificate stays in use while the pair does not match.

Upgrading

Read the upgrade notes for the versions you are crossing, run --check-config with the new binary, then upgrade one replica at a time and check readiness and oauth2relay_token_renewals_total before continuing. The relay keeps no state apart from its token, so rolling back means starting the old binary, as long as the configuration uses no setting the older version lacks, such as ${env:...} before 2.1.