Skip to main content

Authentication Configuration

Authentication Cookies​

GeoPulse uses HTTP-only cookies for secure authentication. Understanding how cookie domains work with GeoPulse's architecture is important for proper deployment.

GeoPulse Architecture Overview:

  • nginx serves the frontend and proxies /api/* requests to the backend
  • Browser sees all requests as same-origin (e.g., https://geopulse.yourdomain.com)
  • Frontend assets: https://geopulse.yourdomain.com/
  • API requests: https://geopulse.yourdomain.com/api/*
  • nginx internally forwards API requests to http://geopulse-backend:8080

Cookie Domain Configuration:

Environment VariableDefaultDescription
GEOPULSE_COOKIE_DOMAIN(empty)Cookie domain for authentication. Keep empty for nginx
GEOPULSE_AUTH_SECURE_COOKIESfalseEnable secure cookies (requires HTTPS)

When to use GEOPULSE_COOKIE_DOMAIN:

Standard Deployments (99% of cases) - Keep Empty:

# ✅ Recommended for all standard deployments
GEOPULSE_COOKIE_DOMAIN=

This works for:

  • Localhost: http://localhost:5555
  • Homelab: http://192.168.1.100:5555
  • Production: https://geopulse.yourdomain.com
  • Any deployment using nginx proxy (standard GeoPulse setup)

Why keep it empty?

  • Nginx creates same-origin context - browser automatically handles cookies
  • More secure - cookies won't leak to other subdomains
  • Simpler configuration with fewer issues

Alternative Deployments (rare) - Set Cookie Domain:

# ❌ Only for non-standard deployments WITHOUT nginx proxy
# Example: Frontend at app.yourdomain.com, Backend at api.yourdomain.com
GEOPULSE_COOKIE_DOMAIN=.yourdomain.com

⚠️ Warning: This is NOT a standard GeoPulse deployment. Requires:

  • Removing nginx proxy
  • Updating CORS configuration
  • Modifying frontend to call backend directly
  • Security implications (cookies shared across all subdomains)

Cookie Security:

For production deployments with HTTPS:

GEOPULSE_AUTH_SECURE_COOKIES=true

This ensures authentication cookies are only transmitted over secure HTTPS connections.

For local/development deployments with HTTP:

GEOPULSE_AUTH_SECURE_COOKIES=false

Kubernetes / Helm Configuration​

Configure in values.yaml:

config:
  cookieDomain: ""  # Keep empty for standard nginx deployments
  authSecureCookies: true  # Set to true for HTTPS/production

Apply with: helm upgrade geopulse ./helm/geopulse -f custom-values.yaml

For more details, see the Helm Configuration Guide.

Login Controls​

GeoPulse provides granular control over login methods to restrict access during maintenance or enforce specific authentication patterns.

Environment Variables​

Global Login Control​

  • Variable: GEOPULSE_AUTH_LOGIN_ENABLED
  • Default: true
  • Description: Master switch for all login methods

Password Login Control​

  • Variable: GEOPULSE_AUTH_PASSWORD_LOGIN_ENABLED
  • Default: true
  • Description: Controls email/password login

OIDC Login Control​

  • Variable: GEOPULSE_AUTH_OIDC_LOGIN_ENABLED
  • Default: true
  • Description: Controls OIDC provider login

Admin Login Bypass Control​

  • Variable: GEOPULSE_AUTH_ADMIN_LOGIN_BYPASS_ENABLED
  • Default: true
  • Description: Controls whether admins can bypass login restrictions

Hierarchical Structure​

Login controls use a hierarchical pattern:

  • Password login requires: GEOPULSE_AUTH_LOGIN_ENABLED=true AND GEOPULSE_AUTH_PASSWORD_LOGIN_ENABLED=true
  • OIDC login requires: GEOPULSE_AUTH_LOGIN_ENABLED=true AND GEOPULSE_AUTH_OIDC_LOGIN_ENABLED=true

Admin Bypass​

Configurable: Admin bypass behavior is controlled by GEOPULSE_AUTH_ADMIN_LOGIN_BYPASS_ENABLED.

By default (true), admin users bypass login restrictions to prevent system lockout. When set to false, admins are subject to the same restrictions as regular users.

WARNING: Disabling admin bypass can result in complete system lockout if login is disabled globally. Only use this setting in high-security environments where you have alternative access methods.

Admin Panel Configuration​

Login settings can also be configured via the Admin Panel:

  1. Navigate to Settings → Authentication
  2. Toggle the login controls as needed
  3. Changes take effect immediately

Behavior​

  • Existing sessions: Remain valid when login is disabled. Only NEW logins are blocked.
  • Token refresh: Continues to work. Users with valid refresh tokens can extend their sessions.
  • Frontend: Shows informative messages explaining why login is disabled.

Use Cases​

Maintenance Mode:

GEOPULSE_AUTH_LOGIN_ENABLED=false

Blocks all new logins while allowing existing users to continue working. Admins can still log in.

Force OIDC Authentication:

GEOPULSE_AUTH_PASSWORD_LOGIN_ENABLED=false
GEOPULSE_AUTH_OIDC_LOGIN_ENABLED=true

Requires all users to authenticate via OIDC providers.

Disable External Authentication:

GEOPULSE_AUTH_OIDC_LOGIN_ENABLED=false

Only allows password-based login for internal users.