OAuth2 Proxy Configuration

Erato uses OAuth2 Proxy  to handle authentication. It sits in front of the application and handles OIDC authentication flows with your identity provider.

Configuration

The configuration for OAuth2 Proxy is provided via the oauth2Proxy.config value in the Helm chart. This value corresponds to the content of the oauth2-proxy.cfg file.

When backend.loadBalancer.enabled is true, the chart injects path-aware upstreams and reverse-proxy settings through environment variables. The load balancer uses the original X-Forwarded-For client address for consistent routing.

An admin-panel service can be routed before the intermediate load balancer:

oauth2Proxy:
  upstreams:
    adminPanelUrl: http://erato-admin-panel:3131

This generates routes for both /admin and /admin/ (including nested static assets and API paths), followed by the backend load balancer as the catch-all fallback. oauth2Proxy.upstreams.backendUrl overrides that fallback; when it is empty, the chart selects the load balancer if enabled or the direct Erato backend Service otherwise. Authentication and configured group restrictions are evaluated by OAuth2 Proxy before either upstream is selected.

Set oauth2Proxy.upstreams.enabled to false to stop automatic OAUTH2_PROXY_UPSTREAMS injection and manage the upstream list through oauth2Proxy.config or externally supplied environment variables.

Recommended Configuration

Below is a commented version of a recommended configuration file.

# Listening address
http_address = "0.0.0.0:4180"
 
# Upstreams are injected by the Helm chart through OAUTH2_PROXY_UPSTREAMS.
# Set oauth2Proxy.upstreams.enabled=false before defining them in this file.
# upstreams = ["http://erato-backend:3130"]
 
# Email domains to allow authentication for
# Use "*" to allow any email domain (access control is handled by the application)
email_domains = ["*"]
 
# The provider type (e.g., oidc, google, github, etc.)
provider = "oidc"
 
# Client ID and Secret from your OIDC provider
client_id = "your-client-id"
client_secret = "your-client-secret"
 
# OIDC Provider URLs
# These depend on your provider (e.g., Keycloak, Dex, Auth0)
oidc_issuer_url = "https://your-idp.example.com"
# Optional if discovery is working
# login_url = "https://your-idp.example.com/auth"
# redeem_url = "https://your-idp.example.com/token"
# oidc_jwks_url = "https://your-idp.example.com/keys"
 
# Redirect URL (callback URL)
# Must match what is configured in your OIDC provider
redirect_url = "https://erato.example.com/oauth2/callback"
 
# Cookie configuration
# Generate a strong random secret for cookie_secret:
# python -c 'import os,base64; print(base64.urlsafe_b64encode(os.urandom(32)).decode())'
cookie_secret = "your-cookie-secret"
cookie_secure = true
# Required for the Office add-in in Outlook and Word on the web, which load Erato
# in a cross-site frame. Needs cookie_secure = true. Has no effect where the
# browser blocks third-party cookies (Safari, Firefox's default protection).
cookie_samesite = "none"
cookie_expire = "168h" # 7 days
cookie_refresh = "30m" # Refresh the cookie every 30 minutes (recommended)
 
# Session Storage
# By default, the Helm chart configures Redis for session storage if enabled.
# You can override this if needed, but Redis is recommended for production.
#
# session_store_type = "redis"
# redis_connection_url = "redis://erato-oauth2-proxy-redis:6379"
 
# Pass tokens to the backend
pass_authorization_header = true
pass_access_token = true
pass_user_headers = true
 
# Skip authentication for health checks and metrics
skip_auth_regex = ["^/health", "^/metrics"]

Entra ID group overage

Erato resolves group overage in the backend by default. Configure your Entra application to grant delegated Microsoft Graph User.Read, request that scope, and forward the access token:

provider = "entra-id"
scope = "openid profile email offline_access https://graph.microsoft.com/User.Read"
pass_authorization_header = true
pass_access_token = true

oauth2-proxy can resolve overage for its own group checks and forward the result in X-Forwarded-Groups, but it does not add resolved memberships to the ID or access token. Erato uses the original ID token’s overage signal and the forwarded Graph access token to fetch the same transitive membership set. The backend lookup is independent of integrations.entra_id.enabled; see group-overage configuration for disabling it, cache lifetimes and failure behavior.

Backend resolution cannot recover a request rejected by the proxy’s group checks, and does not remove large membership headers emitted by the proxy. For a token accepted through skip_jwt_bearer_tokens, make sure the proxy forwards a usable delegated Graph access token; an ID token used as an access token cannot call Graph.

Redis Session Storage

The Erato Helm chart includes an optional Redis deployment for OAuth2 Proxy session storage. This is enabled by default and recommended for production deployments to ensure sessions persist across pod restarts and to allow for scaling the proxy.

You can configure the Redis settings in the values.yaml file under oauth2Proxy.redis:

oauth2Proxy:
  redis:
    enabled: true
    persistence:
      enabled: true
      size: 1Gi