Security.md

Security & Login

Documentation of security features and authentication options.

Enable Login

For production environments, it is strongly recommended to enable login requirement:

SECURITY_ENABLE_LOGIN=true

Initial Admin Credentials

SECURITY_INITIAL_LOGIN_USERNAME=admin
SECURITY_INITIAL_LOGIN_PASSWORD=  # Leave empty, generated by generate-secrets.sh

The initial password is only used on first startup. After that you can:

1. Change the password in the web interface
2. Create additional users

Generate Secrets

# With tools container
./tools/run.sh -s './scripts/generate-secrets.sh'

# Directly
./scripts/generate-secrets.sh

The script generates:

• SECURITY_INITIAL_LOGIN_PASSWORD: Secure admin password
• Optional API key

Login Methods

# all: Username/password + OAuth
# normal: Username/password only
# oauth2: OAuth only (after initial setup)
SECURITY_LOGIN_METHOD=all

Rate Limiting

Protection against brute-force attacks:

# Maximum login attempts (-1 = disabled, use fail2ban)
SECURITY_LOGIN_ATTEMPT_COUNT=5

# Lockout duration in minutes
SECURITY_LOGIN_RESET_TIME_MINUTES=120

CSRF Protection

# NEVER disable in production!
SECURITY_CSRF_DISABLED=false

OAuth 2.0 / SSO

Prerequisites

• SECURITY_ENABLE_LOGIN=true must be active
• OAuth provider must be configured

General Configuration

SECURITY_OAUTH2_ENABLED=true
SECURITY_OAUTH2_PROVIDER=keycloak  # google, github, keycloak, authentik

Keycloak / Generic OIDC

SECURITY_OAUTH2_ISSUER=https://your-idp.com/realms/your-realm
SECURITY_OAUTH2_CLIENT_ID=stirling-pdf
SECURITY_OAUTH2_CLIENT_SECRET=your-client-secret
SECURITY_OAUTH2_SCOPES=openid, profile, email
SECURITY_OAUTH2_USE_AS_USERNAME=preferred_username

Automatic User Creation

# Automatically create users on first OAuth login
SECURITY_OAUTH2_AUTO_CREATE_USER=true

Google OAuth

SECURITY_OAUTH2_PROVIDER=google
SECURITY_OAUTH2_CLIENT_ID=your-google-client-id
SECURITY_OAUTH2_CLIENT_SECRET=your-google-client-secret

GitHub OAuth

SECURITY_OAUTH2_PROVIDER=github
SECURITY_OAUTH2_CLIENT_ID=your-github-client-id
SECURITY_OAUTH2_CLIENT_SECRET=your-github-client-secret

API Authentication

Global API Key

SECURITY_CUSTOM_GLOBAL_API_KEY=your-secure-api-key

Usage:

curl -H "X-Api-Key: your-secure-api-key" \
  https://pdf.app.bauer-group.com/api/v1/info/status

User API Keys

Each user can create their own API key in the web interface:

1. Login to web interface
2. Open account settings
3. Generate API key

fail2ban Integration

For additional protection, fail2ban can be configured:

fail2ban Filter

# /etc/fail2ban/filter.d/stirling-pdf.conf
[Definition]
failregex = ^.*Invalid username or password.*client: <HOST>.*$
ignoreregex =

fail2ban Jail

# /etc/fail2ban/jail.d/stirling-pdf.conf
[stirling-pdf]
enabled = true
filter = stirling-pdf
logpath = /var/log/stirling-pdf/invalid-auths.log
maxretry = 5
bantime = 3600

Mount Log Path

volumes:
  - '/var/log/stirling-pdf:/logs'

Security Best Practices

Production Environment

1. Enable login: SECURITY_ENABLE_LOGIN=true
2. Keep CSRF enabled: SECURITY_CSRF_DISABLED=false
3. Use HTTPS: Always via reverse proxy with TLS
4. Strong passwords: Use generate-secrets.sh
5. Rate limiting: Enable or use fail2ban
6. Updates: Update regularly

Network

1. Only via reverse proxy: Don't expose port 8080 directly
2. Internal network: Container only in internal network
3. Firewall: Only open 80/443

Container

security_opt:
  - no-new-privileges:true
read_only: true  # Where possible

Session Management

# Session timeout (e.g., 30m, 1h)
SERVER_SESSION_TIMEOUT=30m

Security Logging

# For security debugging
LOGGING_LEVEL=DEBUG

# Debug OAuth issues
LOGGING_LEVEL_ORG_SPRINGFRAMEWORK_SECURITY_OAUTH2=DEBUG

Log Files

File	Content
/logs/stirling-pdf.log	General logs
/logs/invalid-auths.log	Failed login attempts

Further Documentation

• Installation
• Configuration
• API Documentation