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 honeypot fields. Configure it under Extensions → Antispam.

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

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.