Skip to content

CONFIG.md

Latest commit

 

History

History
1194 lines (850 loc) · 30.5 KB

CONFIG.md

File metadata and controls

1194 lines (850 loc) · 30.5 KB
Raw

Configuration Reference

This document details all configuration options for Stargate.

Table of Contents

Configuration Methods

Stargate is configured via environment variables. All configuration items are set through environment variables, no configuration file is needed.

Setting Environment Variables

Linux/macOS:

export AUTH_HOST=auth.example.com
export PASSWORDS=plaintext:yourpassword

Docker:

docker run -e AUTH_HOST=auth.example.com -e PASSWORDS=plaintext:yourpassword stargate:latest

Docker Compose:

services:
  stargate:
    environment:
      - AUTH_HOST=auth.example.com
      - PASSWORDS=plaintext:yourpassword

Configuration Quick Reference

Below are all environment variables used in code. "Required" means the service will not start without it when applicable.

Variable Type/Values Default Required
AUTH_HOST String — Yes
PASSWORDS See password config — Yes when Warden disabled
DEBUG true/false false No
LOGIN_PAGE_TITLE String Stargate - Login No
LOGIN_PAGE_FOOTER_TEXT String Copyright © 2024 - Stargate No
USER_HEADER_NAME String X-Forwarded-User No
COOKIE_DOMAIN String empty No
LANGUAGE en, zh, fr, it, ja, de, ko en No
PORT String empty (:80) No
WARDEN_ENABLED true/false false No
WARDEN_URL String empty No
WARDEN_API_KEY String empty No
WARDEN_CACHE_TTL String 300 No
WARDEN_OTP_ENABLED true/false false No
WARDEN_OTP_SECRET_KEY String empty No
HERALD_ENABLED true/false false No
HERALD_URL String empty No
HERALD_API_KEY String empty No
HERALD_HMAC_SECRET String empty No
HERALD_TLS_CA_CERT_FILE path empty No
HERALD_TLS_CLIENT_CERT_FILE path empty No
HERALD_TLS_CLIENT_KEY_FILE path empty No
HERALD_TLS_SERVER_NAME String empty No
HERALD_TOTP_ENABLED true/false false No
LOGIN_SMS_ENABLED true/false true No
LOGIN_EMAIL_ENABLED true/false true No
SESSION_STORAGE_ENABLED true/false false No
SESSION_STORAGE_REDIS_ADDR String localhost:6379 No
SESSION_STORAGE_REDIS_PASSWORD String empty No
SESSION_STORAGE_REDIS_DB String 0 No
SESSION_STORAGE_REDIS_KEY_PREFIX String stargate:session: No
AUDIT_LOG_ENABLED true/false true No
AUDIT_LOG_FORMAT json/text json No
STEP_UP_ENABLED true/false false No
STEP_UP_PATHS comma-separated paths empty No
OTLP_ENABLED true/false false No
OTLP_ENDPOINT String empty No
AUTH_REFRESH_ENABLED true/false false No
AUTH_REFRESH_INTERVAL duration 5m No

Required Configuration

The following configuration items are required. Failure to set them will cause the service to fail to start.

AUTH_HOST

Hostname of the authentication service.

Attribute Value
Type String
Required Yes
Default None
Example auth.example.com

Description:

  • Used to build login callback URLs
  • Usually set to the hostname of the Stargate service
  • Supports wildcard * (not recommended for production use)

Example:

AUTH_HOST=auth.example.com

PASSWORDS

Password configuration, specifying the password encryption algorithm and password list.

Attribute Value
Type String
Required Yes
Default None
Format `algorithm:password1

Description:

  • Format: algorithm:password1|password2|password3
  • Supports multiple passwords, separated by |
  • Any password that passes verification allows login
  • Supported algorithms see Password Configuration section

Examples:

# Single plain text password
PASSWORDS=plaintext:test123

# Multiple plain text passwords
PASSWORDS=plaintext:test123|admin456|user789

# BCrypt hash
PASSWORDS=bcrypt:$2a$10$N9qo8uLOickgx2ZMRZoMyeIjZAgcfl7p92ldGxad68LJZdL17lhWy

# SHA512 hash
PASSWORDS=sha512:5e884898da28047151d0e56f8dc6292773603d0d6aabbdd62a11ef721d1542d8

Optional Configuration

The following configuration items are optional. Default values are used if not set.

DEBUG

Enable debug mode.

Attribute Value
Type Boolean
Required No
Default false
Possible Values true, false

Description:

  • When enabled, log level is set to DEBUG
  • Outputs more detailed debug information
  • Recommended to set to false in production

Example:

DEBUG=true

LANGUAGE

Interface language.

Attribute Value
Type String
Required No
Default en
Possible Values en (English), zh (Chinese), fr (French), it (Italian), ja (Japanese), de (German), ko (Korean)

Description:

  • Affects the language of error messages and interface text
  • Case-insensitive (EN, en, En all work)

Example:

LANGUAGE=zh

LOGIN_PAGE_TITLE

Login page title.

Attribute Value
Type String
Required No
Default Stargate - Login

Description:

  • Displayed at the title position of the login page
  • Supports HTML tags (not recommended)

Example:

LOGIN_PAGE_TITLE=My Auth Service

LOGIN_PAGE_FOOTER_TEXT

Login page footer text.

Attribute Value
Type String
Required No
Default Copyright © 2024 - Stargate

Description:

  • Displayed at the footer position of the login page
  • Supports HTML tags (not recommended)

Example:

LOGIN_PAGE_FOOTER_TEXT=© 2024 My Company

USER_HEADER_NAME

User header name set after successful authentication.

Attribute Value
Type String
Required No
Default X-Forwarded-User

Description:

  • After successful authentication, Stargate sets this header in the response
  • Header value is authenticated
  • Backend services can determine if a user is authenticated via this header
  • Must be a non-empty string

Example:

USER_HEADER_NAME=X-Authenticated-User

COOKIE_DOMAIN

Cookie domain, used for cross-domain session sharing.

Attribute Value
Type String
Required No
Default Empty (not set)

Description:

  • If set, session cookies will be set to the specified domain
  • Supports cross-subdomain session sharing
  • Format: .example.com (note the leading dot)
  • When set to empty, cookies are only valid for the current domain

Example:

# Allow session sharing across all *.example.com subdomains
COOKIE_DOMAIN=.example.com

Cross-Domain Session Sharing Scenario:

Assume the following domains:

  • auth.example.com - Authentication service
  • app1.example.com - Application 1
  • app2.example.com - Application 2

After setting COOKIE_DOMAIN=.example.com:

  1. User logs in at auth.example.com
  2. Session cookie is set to the .example.com domain
  3. User can use the same session on app1.example.com and app2.example.com

Cookie and session behavior (current implementation):

  • Session expiration: Fixed to 24 hours in code; there is no SESSION_TTL (or similar) env variable.
  • Cookie Secure: Set from request protocol (e.g. X-Forwarded-Proto: https); there is no COOKIE_SECURE env variable.
  • Cookie SameSite: Fixed to Lax; there is no COOKIE_SAME_SITE env variable.

PORT

Service listening port (local development only). Managed by the config package along with other env-based options.

Attribute Value
Type String
Required No
Default Empty (when empty, server uses default port :80)

Description:

  • Only for local development environment
  • Usually not needed in Docker containers (uses default port 80)
  • Format: port number (e.g., 8080) or :port (e.g., :8080)

Example:

PORT=8080

Warden Integration (Optional)

Warden is the user whitelist/authorized user information service. This is optional - if you don't need user whitelist functionality, you don't need to enable it. The following configuration options are available for integrating with Warden.

WARDEN_ENABLED

Enable Warden integration for user whitelist authentication functionality.

Attribute Value
Type Boolean
Required No
Default false
Possible Values true, false

Description:

  • When enabled, Stargate will use Warden service for user whitelist verification
  • Requires WARDEN_URL to be set
  • This is an optional feature, Stargate can be used independently with password authentication

Example:

WARDEN_ENABLED=true

WARDEN_URL

Base URL of the Warden service.

Attribute Value
Type String
Required No (required if WARDEN_ENABLED=true)
Default Empty
Example http://warden:8080 or https://warden.example.com

Description:

  • Full base URL of the Warden service (without trailing slash)
  • Must be set if WARDEN_ENABLED=true
  • Used for querying user information and whitelist verification

Example:

WARDEN_URL=http://warden:8080

WARDEN_API_KEY

API key for authenticating with Warden service.

Attribute Value
Type String
Required No
Default Empty

Description:

  • Simple authentication method using API key
  • Suitable for development and production environments
  • If not set, Warden client may not authenticate properly

Example:

WARDEN_API_KEY=your-warden-api-key-here

WARDEN_CACHE_TTL

TTL (Time To Live) for Warden user information cache.

Attribute Value
Type Integer
Required No
Default 300 (5 minutes)
Unit Seconds

Description:

  • Time to cache user information locally
  • Reduces request frequency to Warden service
  • Improves authentication performance

Example:

WARDEN_CACHE_TTL=300

WARDEN_OTP_ENABLED

Enable Warden-built-in OTP verification (distinct from Herald OTP; legacy/built-in capability).

Attribute Value
Type Boolean
Required No
Default false
Possible Values true, false

Description:

  • When true, uses Warden-side OTP verification (requires WARDEN_OTP_SECRET_KEY)
  • Independent from Herald verification code service (HERALD_ENABLED); use one or both as needed

Example:

WARDEN_OTP_ENABLED=true

WARDEN_OTP_SECRET_KEY

Secret key for Warden OTP verification (only when WARDEN_OTP_ENABLED=true).

Attribute Value
Type String
Required No
Default Empty

Example:

WARDEN_OTP_SECRET_KEY=your-warden-otp-secret

Herald Integration (Optional)

Herald is the OTP/verification code service. This is optional - if you don't need verification code functionality, you don't need to enable it. The following configuration options are available for integrating with Herald.

HERALD_ENABLED

Enable Herald integration for OTP/verification code functionality.

Attribute Value
Type Boolean
Required No
Default false
Possible Values true, false

Description:

  • When enabled, Stargate will use Herald service for sending and verifying OTP codes
  • Requires HERALD_URL to be set
  • This is an optional feature, Stargate can be used independently with password authentication

Example:

HERALD_ENABLED=true

LOGIN_SMS_ENABLED

Allow verification code login via SMS when Herald is enabled.

Attribute Value
Type Boolean
Required No
Default true
Possible Values true, false

Description:

  • When false, SMS is not offered as a deliver option and requests for SMS codes are rejected (or fall back to email if enabled)
  • Only applies when HERALD_ENABLED=true and Warden login is used

Example:

LOGIN_SMS_ENABLED=false

LOGIN_EMAIL_ENABLED

Allow verification code login via email when Herald is enabled.

Attribute Value
Type Boolean
Required No
Default true
Possible Values true, false

Description:

  • When false, email is not offered as a deliver option and requests for email codes are rejected (or fall back to SMS if enabled)
  • Only applies when HERALD_ENABLED=true and Warden login is used

Example:

LOGIN_EMAIL_ENABLED=false

HERALD_URL

Base URL of the Herald service.

Attribute Value
Type String
Required No (required if HERALD_ENABLED=true)
Default Empty
Example http://herald:8080 or https://herald.example.com

Description:

  • Full base URL of the Herald service (without trailing slash)
  • Must be set if HERALD_ENABLED=true
  • Used for creating challenges and verifying codes

Example:

HERALD_URL=http://herald:8080

HERALD_API_KEY

API key for authenticating with Herald service (simple authentication method).

Attribute Value
Type String
Required No
Default Empty

Description:

  • Simple authentication method using API key
  • Suitable for development environments
  • If both HERALD_API_KEY and HERALD_HMAC_SECRET are set, HMAC takes precedence
  • Must be set if HERALD_HMAC_SECRET is not set

Example:

HERALD_API_KEY=your-api-key-here

HERALD_HMAC_SECRET

HMAC secret for service-to-service authentication with Herald (recommended for production).

Attribute Value
Type String
Required No
Default Empty

Description:

  • HMAC-SHA256 signature-based authentication (more secure than API key)
  • Recommended for production environments
  • If both HERALD_API_KEY and HERALD_HMAC_SECRET are set, HMAC takes precedence
  • Provides better security for service-to-service communication
  • Must match the HMAC secret configured in Herald service

Authentication Methods:

Stargate supports two authentication methods for Herald:

  1. API Key (Simple, for development):

    • Set HERALD_API_KEY only
    • Less secure but easier to configure
    • Suitable for development and testing

  2. HMAC Signature (Secure, for production):

    • Set HERALD_HMAC_SECRET
    • More secure, uses HMAC-SHA256 signatures
    • Recommended for production environments
    • Provides timestamp-based request signing

Example:

# Production: Use HMAC
HERALD_HMAC_SECRET=your-hmac-secret-key-here

# Development: Use API Key
HERALD_API_KEY=your-api-key-here

Note: If neither HERALD_API_KEY nor HERALD_HMAC_SECRET is set, Herald client may not authenticate properly and requests may fail.

Herald mTLS (Optional)

When using TLS client certificate authentication to Herald, the following options apply. Can be used alongside API Key / HMAC; client implementation decides precedence.

HERALD_TLS_CA_CERT_FILE

Path to CA certificate file for Herald server verification.

Attribute Value
Type String (file path)
Required No
Default Empty

HERALD_TLS_CLIENT_CERT_FILE

Path to client certificate file (mTLS).

Attribute Value
Type String (file path)
Required No
Default Empty

HERALD_TLS_CLIENT_KEY_FILE

Path to client private key file (mTLS).

Attribute Value
Type String (file path)
Required No
Default Empty

HERALD_TLS_SERVER_NAME

Server Name Indication (SNI) for TLS handshake and certificate validation.

Attribute Value
Type String
Required No
Default Empty

Herald TOTP (Optional, per-user 2FA)

TOTP binding and verification are performed via Herald (Herald proxies to herald-totp internally). Separate from Herald OTP (SMS/email verification codes). Stargate only needs Herald URL/auth and this flag; herald-totp URL and auth are configured on the Herald service.

HERALD_TOTP_ENABLED

Enable TOTP (bind/verify TOTP codes). When true, Stargate calls Herald's /v1/totp/* API using the Herald client.

Attribute Value
Type Boolean
Required No
Default false
Possible Values true, false

Note: Herald must be enabled (HERALD_ENABLED, HERALD_URL) and Herald must be configured to proxy herald-totp (e.g. Herald's HERALD_TOTP_ENABLED, HERALD_TOTP_BASE_URL).

Session Storage (Redis, Optional)

When enabled, sessions are stored in Redis for multi-instance sharing and persistence; otherwise in-memory or cookie.

SESSION_STORAGE_ENABLED

Enable Redis session storage.

Attribute Value
Type Boolean
Required No
Default false
Possible Values true, false

SESSION_STORAGE_REDIS_ADDR

Redis address.

Attribute Value
Type String
Required No
Default localhost:6379

SESSION_STORAGE_REDIS_PASSWORD

Redis password (empty if none).

Attribute Value
Type String
Required No
Default Empty

SESSION_STORAGE_REDIS_DB

Redis database index.

Attribute Value
Type Integer (e.g. 0–15)
Required No
Default 0

SESSION_STORAGE_REDIS_KEY_PREFIX

Key prefix for session keys (to separate multiple Stargate deployments or other apps).

Attribute Value
Type String
Required No
Default stargate:session:

Audit Log (Optional)

AUDIT_LOG_ENABLED

Enable audit logging.

Attribute Value
Type Boolean
Required No
Default true
Possible Values true, false

AUDIT_LOG_FORMAT

Audit log output format.

Attribute Value
Type String
Required No
Default json
Possible Values json, text

Step-up Authentication (Optional)

Require a second factor (e.g. password or OTP) for selected paths.

STEP_UP_ENABLED

Enable step-up authentication.

Attribute Value
Type Boolean
Required No
Default false
Possible Values true, false

STEP_UP_PATHS

Paths that require step-up; comma-separated; prefix matching supported.

Attribute Value
Type String
Required No
Default Empty

Example: /admin,/api/sensitive

OpenTelemetry (Optional)

OTLP_ENABLED

Enable OTLP telemetry export.

Attribute Value
Type Boolean
Required No
Default false
Possible Values true, false

OTLP_ENDPOINT

OTLP collector endpoint (e.g. Jaeger/OTLP Collector).

Attribute Value
Type String
Required No
Default Empty

Example: http://jaeger:4318/v1/traces

Auth Refresh (Optional)

AUTH_REFRESH_ENABLED

Periodically refresh user/authorization info from Warden and update session during its lifetime.

Attribute Value
Type Boolean
Required No
Default false
Possible Values true, false

AUTH_REFRESH_INTERVAL

Refresh interval (Go duration, e.g. 5m, 1h).

Attribute Value
Type String (duration)
Required No
Default 5m

Example: AUTH_REFRESH_INTERVAL=10m

Password Configuration

Stargate supports multiple password encryption algorithms. Password configuration format: algorithm:password1|password2|password3

Supported Algorithms

plaintext - Plain Text Password

Description:

  • Stored in plain text, no encryption
  • Testing environment only
  • Strongly not recommended for production use

Example:

PASSWORDS=plaintext:test123|admin456

bcrypt - BCrypt Hash

Description:

  • Uses BCrypt algorithm for hashing
  • High security, recommended for production
  • Password must use BCrypt hash value

Generate BCrypt Hash:

# Using Go
go run -c 'golang.org/x/crypto/bcrypt' <<< 'password'

# Using online tools or other tools

Example:

PASSWORDS=bcrypt:$2a$10$N9qo8uLOickgx2ZMRZoMyeIjZAgcfl7p92ldGxad68LJZdL17lhWy

md5 - MD5 Hash

Description:

  • Uses MD5 algorithm for hashing
  • Lower security, not recommended for production
  • Password must use MD5 hash value (32-character hexadecimal string)

Generate MD5 Hash:

# Linux/macOS
echo -n "password" | md5sum

# Or use online tools

Example:

PASSWORDS=md5:5e884898da28047151d0e56f8dc6292773603d0d6aabbdd62a11ef721d1542d8

sha512 - SHA512 Hash

Description:

  • Uses SHA512 algorithm for hashing
  • High security, recommended for production
  • Password must use SHA512 hash value (128-character hexadecimal string)

Generate SHA512 Hash:

# Linux/macOS
echo -n "password" | shasum -a 512

# Or use online tools

Example:

PASSWORDS=sha512:5e884898da28047151d0e56f8dc6292773603d0d6aabbdd62a11ef721d1542d8

Password Verification Rules

  1. Password Normalization: Spaces are removed and converted to uppercase before verification
  2. Multiple Password Support: Multiple passwords can be configured, any password that passes verification is acceptable
  3. Algorithm Consistency: All passwords must use the same algorithm

Configuration Examples

Stargate + Redis Only (Password Auth, Sessions in Redis)

# Required
AUTH_HOST=auth.example.com
PASSWORDS=plaintext:test123

# Session storage in Redis (multi-instance or persistent sessions)
SESSION_STORAGE_ENABLED=true
SESSION_STORAGE_REDIS_ADDR=redis:6379
SESSION_STORAGE_REDIS_PASSWORD=
SESSION_STORAGE_REDIS_DB=0
SESSION_STORAGE_REDIS_KEY_PREFIX=stargate:session:

# Optional
DEBUG=false
LANGUAGE=zh

Use when you want password-only login but need sessions in Redis for multiple instances or to survive restarts.

Basic Configuration (Password Authentication)

# Required configuration
AUTH_HOST=auth.example.com
PASSWORDS=plaintext:test123

# Optional configuration
DEBUG=false
LANGUAGE=en

Production Configuration (Password Authentication)

# Required configuration
AUTH_HOST=auth.example.com
PASSWORDS=bcrypt:$2a$10$N9qo8uLOickgx2ZMRZoMyeIjZAgcfl7p92ldGxad68LJZdL17lhWy

# Optional configuration
DEBUG=false
LANGUAGE=zh
LOGIN_PAGE_TITLE=My Auth Service
LOGIN_PAGE_FOOTER_TEXT=© 2024 My Company
USER_HEADER_NAME=X-Forwarded-User
COOKIE_DOMAIN=.example.com

Warden + Herald OTP Authentication Configuration (Recommended for Production)

# Required configuration
AUTH_HOST=auth.example.com

# Warden configuration
WARDEN_ENABLED=true
WARDEN_URL=http://warden:8080
WARDEN_API_KEY=your-warden-api-key
WARDEN_CACHE_TTL=300

# Herald configuration
HERALD_ENABLED=true
HERALD_URL=http://herald:8080
HERALD_HMAC_SECRET=your-herald-hmac-secret

# Optional configuration
DEBUG=false
LANGUAGE=zh
LOGIN_PAGE_TITLE=My Auth Service
LOGIN_PAGE_FOOTER_TEXT=© 2024 My Company
USER_HEADER_NAME=X-Forwarded-User
COOKIE_DOMAIN=.example.com

Description:

  • This configuration demonstrates how to use both Warden and Herald integrations together
  • Warden provides user whitelist verification
  • Herald provides OTP/verification code sending and verification
  • Production environment recommends using HMAC signature (HERALD_HMAC_SECRET) instead of API Key
  • Note: This is an optional configuration, Stargate can be used independently with password authentication without these services

Docker Compose Configuration

Password Authentication Mode:

services:
  stargate:
    image: stargate:latest
    environment:
      # Required configuration
      - AUTH_HOST=auth.example.com
      - PASSWORDS=bcrypt:$2a$10$N9qo8uLOickgx2ZMRZoMyeIjZAgcfl7p92ldGxad68LJZdL17lhWy
      
      # Optional configuration
      - DEBUG=false
      - LANGUAGE=zh
      - LOGIN_PAGE_TITLE=My Auth Service
      - LOGIN_PAGE_FOOTER_TEXT=© 2024 My Company
      - COOKIE_DOMAIN=.example.com

Warden + Herald OTP Authentication Mode:

services:
  stargate:
    image: stargate:latest
    environment:
      # Required configuration
      - AUTH_HOST=auth.example.com
      
      # Warden configuration
      - WARDEN_ENABLED=true
      - WARDEN_URL=http://warden:8080
      - WARDEN_API_KEY=your-warden-api-key
      - WARDEN_CACHE_TTL=300
      
      # Herald configuration
      - HERALD_ENABLED=true
      - HERALD_URL=http://herald:8080
      - HERALD_HMAC_SECRET=your-herald-hmac-secret
      
      # Optional configuration
      - DEBUG=false
      - LANGUAGE=zh
      - LOGIN_PAGE_TITLE=My Auth Service
      - LOGIN_PAGE_FOOTER_TEXT=© 2024 My Company
      - COOKIE_DOMAIN=.example.com
    depends_on:
      - warden
      - herald

  warden:
    image: warden:latest
    environment:
      - WARDEN_DB_URL=postgres://user:pass@db:5432/warden
    # ... other configuration

  herald:
    image: herald:latest
    environment:
      - HERALD_REDIS_URL=redis://redis:6379/0
    # ... other configuration

Local Development Configuration

# Required configuration
AUTH_HOST=localhost
PASSWORDS=plaintext:test123|admin456

# Optional configuration
DEBUG=true
LANGUAGE=zh
PORT=8080

Configuration Validation

Stargate validates all configuration items at startup:

  1. Required Configuration Check: If required configuration is not set, the service will fail to start and display an error message
  2. Format Validation: Incorrect password configuration format will cause startup failure
  3. Algorithm Validation: Unsupported password algorithms will cause startup failure
  4. Value Validation: Some configuration items have value restrictions (e.g., LANGUAGE, DEBUG)

Error Examples:

# Missing required configuration
Error: Configuration error: environment variable 'AUTH_HOST' is required but not set.

# Incorrect password format
Error: Configuration error: invalid value for environment variable 'PASSWORDS': 'invalid_format'

# Unsupported algorithm
Error: Configuration error: invalid value for environment variable 'PASSWORDS': 'unknown:password'

Configuration Dependencies

Configuration Item Dependencies

  • Warden Integration:

    • When WARDEN_ENABLED=true, must set WARDEN_URL
    • WARDEN_API_KEY is recommended (for service authentication)
    • If WARDEN_OTP_ENABLED=true, set WARDEN_OTP_SECRET_KEY

  • Herald Integration (OTP SMS/email):

    • When HERALD_ENABLED=true, must set HERALD_URL
    • Must set either HERALD_API_KEY or HERALD_HMAC_SECRET (recommend HMAC for production)
    • Optional: mTLS via HERALD_TLS_*; can be used alongside API Key/HMAC

  • Herald TOTP Integration (per-user 2FA):

    • Stargate: set HERALD_TOTP_ENABLED=true only (TOTP is via Herald proxy)
    • Herald service must be configured with HERALD_TOTP_ENABLED, HERALD_TOTP_BASE_URL, and HERALD_TOTP_API_KEY or HERALD_TOTP_HMAC_SECRET

  • Session Storage:

    • When SESSION_STORAGE_ENABLED=true, Redis must be reachable (default SESSION_STORAGE_REDIS_ADDR=localhost:6379)

  • Step-up Authentication:

    • When STEP_UP_ENABLED=true, use STEP_UP_PATHS to define paths that require a second factor

  • Auth Refresh:

    • When AUTH_REFRESH_ENABLED=true, Warden must be enabled (WARDEN_ENABLED=true); use AUTH_REFRESH_INTERVAL to tune refresh interval

  • Warden + Herald Combined Usage (Optional):

    • When OTP authentication is needed, can optionally enable both Warden and Herald
    • Warden provides user whitelist verification and user information
    • Herald provides verification code sending and verification
    • Note: These integrations are optional, Stargate can be used independently

Authentication Mode Selection

  1. Password Authentication Mode (Simple, suitable for development/testing):

    • Only need to set PASSWORDS
    • Does not require Warden and Herald

  2. Warden + Herald OTP Authentication Mode (Optional, suitable for scenarios requiring advanced features):

    • Need to enable WARDEN_ENABLED=true and HERALD_ENABLED=true
    • Provides user whitelist management and OTP verification code functionality
    • More secure, supports rate limiting and auditing
    • Note: This is an optional feature, Stargate can be used independently with password authentication

Configuration Best Practices

  1. Production Security:

    • Use bcrypt or sha512 algorithms, avoid plaintext
    • Set DEBUG=false
    • Use strong passwords (password authentication mode)
    • Or use Warden + Herald OTP authentication (recommended)

  2. Inter-Service Security (if optional service integrations are enabled):

    • Production environment use HERALD_HMAC_SECRET instead of HERALD_API_KEY
    • Ensure Warden and Herald services are accessible
    • Configure appropriate network policies and firewall rules

  3. Cross-Domain Sessions:

    • If you need to share sessions across subdomains, set COOKIE_DOMAIN
    • Format: .example.com (note the leading dot)

  4. Multi-Language Support:

    • Set LANGUAGE according to user base
    • Supports en, zh, fr, it, ja, de, ko

  5. Custom Interface:

    • Use LOGIN_PAGE_TITLE and LOGIN_PAGE_FOOTER_TEXT to customize the login page

  6. Monitoring and Debugging:

    • Set DEBUG=true in development environment for detailed logs
    • Set DEBUG=false in production environment to reduce log output

  7. Performance Optimization:

    • Set WARDEN_CACHE_TTL to reduce requests to Warden
    • Adjust cache time according to actual needs