Configuration Reference

Environment variables

Authgent is configured via environment variables. All variables use the AUTHGENT_ prefix.

Core settings

Variable	Required	Default	Description
AUTHGENT_ISSUER	Yes	—	Public URL of this Authgent instance. Must match the iss claim in issued tokens. Example: https://auth.yourcompany.com
AUTHGENT_SIGNING_KEY	Yes	—	Path to EC or RSA private key PEM file. Example: /keys/ec-private.pem
AUTHGENT_SIGNING_KEY_DATA	No	—	PEM-encoded private key as a string. Alternative to AUTHGENT_SIGNING_KEY for environments where file mounting is unavailable
AUTHGENT_SIGNING_ALG	No	ES256	JWT signing algorithm. Supported: ES256 (EC P-256), ES384 (EC P-384), RS256 (RSA 2048+)
AUTHGENT_DB_DSN	Yes	—	Database connection string. SQLite: sqlite:///path/to/db.sqlite. PostgreSQL: postgres://user:pass@host:5432/dbname?sslmode=require
AUTHGENT_PORT	No	8080	HTTP port to listen on
AUTHGENT_HOST	No	0.0.0.0	Address to bind to. Use 127.0.0.1 to restrict to localhost

Token settings

Variable	Required	Default	Description
AUTHGENT_TOKEN_TTL	No	300	Access token TTL in seconds (5 minutes default). Short-lived tokens reduce the blast radius of token theft
AUTHGENT_REFRESH_TTL	No	86400	Refresh token TTL in seconds (24 hours default). Set to 0 to disable refresh tokens
AUTHGENT_ID_TOKEN_TTL	No	3600	ID token TTL in seconds (1 hour default)
AUTHGENT_CODE_TTL	No	600	Authorization code TTL in seconds (10 minutes default)
AUTHGENT_KEY_ROTATION_DAYS	No	30	Days between automatic signing key rotation. Set to 0 to disable automatic rotation

Identity Provider (IdP) settings

Configure an upstream OIDC provider for user authentication. When set, Authgent delegates the login UI to your IdP (Okta, Entra ID, Google Workspace, etc.).

Variable	Required	Default	Description
AUTHGENT_IDP_ISSUER	No	—	Upstream OIDC IdP issuer URL. Example: https://yourcompany.okta.com
AUTHGENT_IDP_CLIENT_ID	No	—	OIDC client ID registered with the upstream IdP
AUTHGENT_IDP_CLIENT_SECRET	No	—	OIDC client secret
AUTHGENT_IDP_SCOPES	No	openid profile email	Space-separated OIDC scopes to request from the upstream IdP
AUTHGENT_IDP_CALLBACK_PATH	No	/oauth/callback	Path for the OIDC callback endpoint

When no IdP is configured, Authgent uses its built-in consent screen for development and testing.

Dynamic Client Registration (DCR)

Variable	Required	Default	Description
AUTHGENT_DCR_MODE	No	open	DCR mode. open: any client can register (dev). constrained: clients must provide a valid redirect URI pattern. disabled: no self-registration
AUTHGENT_DCR_ALLOWED_REDIRECTS	No	—	Comma-separated list of allowed redirect URI patterns when DCR_MODE=constrained. Supports glob: https://*.yourcompany.com/*
AUTHGENT_DCR_MAX_CLIENTS	No	1000	Maximum number of registered clients. Prevents abuse in open mode

Logging

Variable	Required	Default	Description
AUTHGENT_LOG_LEVEL	No	info	Log level. debug, info, warn, error
AUTHGENT_LOG_FORMAT	No	json	Log format. json for structured logging (production), text for human-readable (development)

Observability

Variable	Required	Default	Description
AUTHGENT_OTEL_ENDPOINT	No	—	OpenTelemetry collector endpoint for traces and metrics. Example: http://otel-collector:4317
AUTHGENT_OTEL_SERVICE_NAME	No	authgent	Service name reported to the OpenTelemetry collector
AUTHGENT_OTEL_INSECURE	No	false	Use insecure (non-TLS) connection to the OTel collector
AUTHGENT_METRICS_PORT	No	—	If set, expose Prometheus metrics on this port at /metrics

Security

Variable	Required	Default	Description
AUTHGENT_CORS_ORIGINS	No	—	Comma-separated list of allowed CORS origins. Example: https://app.yourcompany.com,https://admin.yourcompany.com
AUTHGENT_RATE_LIMIT	No	100	Maximum requests per second per IP address
AUTHGENT_RATE_LIMIT_BURST	No	20	Burst allowance above the rate limit
AUTHGENT_TRUSTED_PROXIES	No	—	Comma-separated list of trusted proxy CIDRs for X-Forwarded-For handling. Example: 10.0.0.0/8,172.16.0.0/12

YAML configuration file

As an alternative to environment variables, Authgent can read configuration from a YAML file:

authgent.yml

issuer: https://auth.yourcompany.com
port: 8080
host: 0.0.0.0

signing:
  key: /keys/ec-private.pem
  algorithm: ES256
  key_rotation_days: 30

database:
  dsn: postgres://authgent:password@postgres:5432/authgent?sslmode=require

tokens:
  access_ttl: 300
  refresh_ttl: 86400
  id_token_ttl: 3600
  code_ttl: 600

idp:
  issuer: https://yourcompany.okta.com
  client_id: 0oa1234567890
  client_secret: ${AUTHGENT_IDP_CLIENT_SECRET}  # Supports env var interpolation
  scopes: openid profile email
  callback_path: /oauth/callback

dcr:
  mode: constrained
  allowed_redirects:
    - "https://*.yourcompany.com/*"
    - "http://localhost:*/*"
  max_clients: 1000

logging:
  level: info
  format: json

observability:
  otel_endpoint: http://otel-collector:4317
  otel_service_name: authgent
  metrics_port: 9090

security:
  cors_origins:
    - https://app.yourcompany.com
    - https://admin.yourcompany.com
  rate_limit: 100
  rate_limit_burst: 20
  trusted_proxies:
    - 10.0.0.0/8
    - 172.16.0.0/12

Pass the config file path:

docker run -d \
  -v $(pwd)/authgent.yml:/etc/authgent/authgent.yml:ro \
  -v $(pwd)/keys/ec-private.pem:/keys/ec-private.pem:ro \
  -e AUTHGENT_CONFIG=/etc/authgent/authgent.yml \
  authgent/authgent:latest

Precedence

When both environment variables and a YAML config file are present, environment variables take precedence. This allows you to use a base YAML config and override specific values per environment:

# Base config from YAML, override issuer for staging
docker run -d \
  -v $(pwd)/authgent.yml:/etc/authgent/authgent.yml:ro \
  -e AUTHGENT_CONFIG=/etc/authgent/authgent.yml \
  -e AUTHGENT_ISSUER=https://auth-staging.yourcompany.com \
  authgent/authgent:latest

Secret interpolation

The YAML config supports environment variable interpolation with ${VAR_NAME} syntax. Use this for sensitive values that shouldn’t be in the config file:

database:
  dsn: postgres://authgent:${DB_PASSWORD}@postgres:5432/authgent

idp:
  client_secret: ${IDP_CLIENT_SECRET}

IdP configuration examples

Okta

idp:
  issuer: https://yourcompany.okta.com
  client_id: 0oa1234567890abcdef
  client_secret: ${OKTA_CLIENT_SECRET}
  scopes: openid profile email groups

In Okta:

1. Create a new Web Application
2. Set the redirect URI to https://auth.yourcompany.com/oauth/callback
3. Enable Authorization Code grant type
4. Copy the client ID and secret

Microsoft Entra ID (Azure AD)

idp:
  issuer: https://login.microsoftonline.com/YOUR_TENANT_ID/v2.0
  client_id: your-application-id
  client_secret: ${ENTRA_CLIENT_SECRET}
  scopes: openid profile email

In Azure Portal:

1. Register a new application in App registrations
2. Add the redirect URI: https://auth.yourcompany.com/oauth/callback
3. Create a client secret under Certificates & secrets

Google Workspace

idp:
  issuer: https://accounts.google.com
  client_id: your-client-id.apps.googleusercontent.com
  client_secret: ${GOOGLE_CLIENT_SECRET}
  scopes: openid profile email

In Google Cloud Console:

1. Create OAuth 2.0 credentials in the APIs & Services section
2. Set the authorized redirect URI to https://auth.yourcompany.com/oauth/callback
3. Restrict to your Google Workspace domain in the OAuth consent screen

Database configuration

SQLite (development only)

AUTHGENT_DB_DSN=sqlite:///data/authgent.db

SQLite stores everything in a single file. It works for development but doesn’t support concurrent writes — not suitable for production.

PostgreSQL (production)

# Basic connection
AUTHGENT_DB_DSN=postgres://authgent:password@localhost:5432/authgent

# With SSL
AUTHGENT_DB_DSN=postgres://authgent:password@db.yourcompany.com:5432/authgent?sslmode=require

# With connection pool settings
AUTHGENT_DB_DSN=postgres://authgent:password@localhost:5432/authgent?sslmode=require&pool_max_conns=20

Authgent runs database migrations automatically on startup. No manual migration steps are required.

Signing algorithm selection

Algorithm	Key type	Performance	Compatibility
ES256	EC P-256	Fast signing and verification	Supported by all modern JWT libraries
ES384	EC P-384	Slightly slower than ES256	Good for higher security requirements
RS256	RSA 2048+	Slower, larger tokens	Maximum compatibility with legacy systems

Recommendation: Use ES256 unless you have a specific requirement for RSA. EC keys are smaller (32 bytes vs 256+ bytes for RSA) and produce smaller JWTs.

Generate keys

# ES256 (recommended)
openssl ecparam -genkey -name prime256v1 -noout -out ec-private.pem

# ES384
openssl ecparam -genkey -name secp384r1 -noout -out ec-private.pem

# RS256
openssl genrsa -out rsa-private.pem 2048