Securing FOSSBilling

This page covers the application-level settings you should review after installation. Pair these with the broader infrastructure guidance in Best Practices.

Configuration Options

These settings live in your config.php file and control FOSSBilling's built-in security behavior.

Security Options

Property	Default	Options	Description
mode	strict	strict or regular	In strict mode, cookies use SameSite=Strict and HttpOnly. regular mode uses default cookie properties but still sets HttpOnly.
force_https	true	bool	When enabled, FOSSBilling redirects all requests to HTTPS and forces cookies to be sent only over secure connections.
session_lifespan	7200	int	How long sessions remain valid (in seconds). Default is 2 hours. After this, sessions expire and are destroyed.
session_regeneration_grace_period	300	int	Grace period (seconds) before a regenerated session ID takes full effect.
perform_session_fingerprinting	true	bool	Verify browser fingerprint on each request to help prevent session hijacking.
debug_fingerprint	false	bool	Log fingerprint checks for debugging (enable temporarily only).

'security' => [
    'mode' => 'strict',
    'force_https' => true,
    'session_lifespan' => 7200,
    'session_regeneration_grace_period' => 300,
    'perform_session_fingerprinting' => true,
    'debug_fingerprint' => false,
],

Trusted Proxies

Configure reverse-proxy support so FOSSBilling correctly detects the visitor's IP and protocol:

'security' => [
    'trusted_proxies' => [
        'enabled' => false,
        'proxies' => [],
        'headers' => 'x_forwarded',
    ],
],

Setting	Default	Description
trusted_proxies.enabled	false	Enable trusted proxy detection
trusted_proxies.proxies	[]	List of trusted proxy IPs or CIDR ranges
trusted_proxies.headers	x_forwarded	Header type: x_forwarded (standard) or forwarded (RFC 7239)

If you are running behind a reverse proxy, configure the trusted_proxies setting in your config (see above) so request metadata is interpreted correctly.

API Security

Property	Default	Options	Description
CSRFPrevention	true	bool	Enables CSRF protection for session-authenticated browser API calls. Keep this enabled unless it is causing a specific compatibility issue.

'api' => [
    'CSRFPrevention' => true,
],

The bundled JavaScript API wrapper sends the CSRF token automatically. External API calls authenticated with an API key do not need a CSRF token.

Rate Limiter

Rate limiting is configured under the rate_limiter block, replacing the old api.rate_* keys:

'rate_limiter' => [
    'enabled' => true,
    'whitelist_ips' => [],
    'policies' => [],
],

Setting	Default	Description
rate_limiter.enabled	true	Enable or disable the rate limiter entirely
rate_limiter.whitelist_ips	[]	IPs that bypass rate limiting
rate_limiter.policies	[]	Custom rate-limit policies (advanced). Leave empty for sensible defaults covering login and API endpoints.

Antispam

The Antispam module (replaces the old Spamchecker module) provides built-in spam protection including CAPTCHA, IP blocking, disposable email detection, Stop Forum Spam lookups, and honeypot fields. See Anti-Spam for setup and troubleshooting.

Cloudflare

If you're using Cloudflare, enable IP Geolocation under your site's Network settings. This allows FOSSBilling to use the visitor's country information to strengthen some session checks.

Reverse Proxies

Auto-Detection

FOSSBilling can detect when it is running behind a reverse proxy. If forwarded headers (such as X-Forwarded-For or Forwarded) are present during installation, the installer shows a proxy configuration step with:

• The detected proxy IP address
• Whether the address is private/local
• The detected header format
• A suggested public URL derived from the forwarded headers

You can enable trust directly in the installer or configure it later in config.php using the trusted_proxies setting.

HTTPS Detection

Reverse proxies often make FOSSBilling think it is being accessed over HTTP even when the visitor is using HTTPS. To avoid that, make sure your proxy forwards X-Forwarded-Proto: https.