Security Configuration Guide

What You'll Learn

• How to configure and tighten your password policy
• How to connect a corporate identity provider (SAML or OIDC)
• How SSO changes the user management behavior of the platform
• How to enforce two-factor authentication for specific users
• Security best practices for production deployments

Overview

Billerang delegates authentication to Keycloak. The security configuration endpoints in the connect component let you manage Keycloak realm settings for your organization without needing direct Keycloak admin access.

Security settings live at /api/portal/security/*. All require the api.security.view or api.security.manage role.

---

Password Policy

Password policy applies when users authenticate with a username and password — that is, when SSO is not active or for local accounts that exist alongside an SSO integration.

Current policy

curl "https://connect.billerang.com/api/portal/security/password-policy" \
  -H "Cookie: $SESSION_COOKIE"

Response:

{
  "minLength": 8,
  "requireUppercase": true,
  "requireLowercase": true,
  "requireDigits": true,
  "requireSpecialChars": true,
  "passwordHistory": 3,
  "maxAgeDays": 90,
  "notUsername": true,
  "ssoActive": false
}

What each setting means

Setting	Description
minLength	Minimum number of characters. Recommended: 12 for production.
requireUppercase	At least one A-Z character
requireLowercase	At least one a-z character
requireDigits	At least one 0-9 character
requireSpecialChars	At least one special character (!@#$%^&* etc.)
passwordHistory	Number of previous passwords remembered; users cannot reuse them. 0 disables history checking.
maxAgeDays	Days before a password expires and the user must change it. 0 disables expiry.
notUsername	If true, the password cannot be the same as the username
ssoActive	Read-only indicator. When true, this policy is informational — the IdP enforces its own rules.

Updating the policy

curl -X PUT "https://connect.billerang.com/api/portal/security/password-policy" \
  -H "Cookie: $SESSION_COOKIE" \
  -H "Content-Type: application/json" \
  -d '{
    "minLength": 12,
    "requireUppercase": true,
    "requireLowercase": true,
    "requireDigits": true,
    "requireSpecialChars": true,
    "passwordHistory": 5,
    "maxAgeDays": 60,
    "notUsername": true
  }'

Policy changes apply to the next password creation or change. Existing passwords are not retroactively invalidated.

Recommended production settings

For most deployments: minLength: 12, all complexity rules enabled, passwordHistory: 5, maxAgeDays: 90. Stricter requirements increase support burden — balance security with usability.

---

SSO Setup

Single Sign-On lets your users authenticate with your corporate identity provider (Azure AD, Okta, Google Workspace, or any SAML/OIDC-compatible IdP) instead of managing separate Billerang passwords.

Before you start

You need:

• Admin access to your identity provider (to register Billerang as a service provider)
• The api.security.manage role in Billerang

Step 1: Check current SSO status

curl "https://connect.billerang.com/api/portal/security/sso" \
  -H "Cookie: $SESSION_COOKIE"

If SSO is not yet configured: { "enabled": false, "providers": [] }

Step 2: Register Billerang in your IdP

Before configuring the provider in Billerang, register it as a Service Provider (SP) in your IdP's admin console.

For SAML:

• SP Entity ID: https://auth.billerang.com/realms/billerang
• ACS URL (Assertion Consumer Service): https://auth.billerang.com/realms/billerang/broker/{alias}/endpoint
• NameID format: emailAddress recommended

For OIDC:

• Redirect URI: https://auth.billerang.com/realms/billerang/broker/{alias}/endpoint
• Grant type: Authorization Code

Replace {alias} with the alias you will use when creating the provider in step 3.

Step 3: Add the SSO provider

SAML example (Azure AD, ADFS, Okta SAML)

curl -X POST "https://connect.billerang.com/api/portal/security/sso" \
  -H "Cookie: $SESSION_COOKIE" \
  -H "Content-Type: application/json" \
  -d '{
    "alias": "corporate-saml",
    "displayName": "Corporate SSO",
    "providerId": "saml",
    "enabled": true,
    "config": {
      "singleSignOnServiceUrl": "https://idp.corp.com/saml/sso",
      "singleLogoutServiceUrl": "https://idp.corp.com/saml/slo",
      "nameIDPolicyFormat": "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
      "signingCertificate": "MIIBkTCB..."
    }
  }'

OIDC example (Okta OIDC, Google Workspace, Azure AD OIDC)

curl -X POST "https://connect.billerang.com/api/portal/security/sso" \
  -H "Cookie: $SESSION_COOKIE" \
  -H "Content-Type: application/json" \
  -d '{
    "alias": "corporate-oidc",
    "displayName": "Corporate SSO",
    "providerId": "oidc",
    "enabled": true,
    "config": {
      "authorizationUrl": "https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/authorize",
      "tokenUrl": "https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token",
      "clientId": "billerang-prod",
      "clientSecret": "your-client-secret",
      "defaultScope": "openid email profile"
    }
  }'

Step 4: Test the integration

1. Open a private browser window.
2. Navigate to the Billerang portal.
3. You should see a "Sign in with [displayName]" button on the login page.
4. Complete the SSO flow.
5. Confirm that the user appears in the portal with the correct groups.

Step 5: Assign groups to SSO users

SSO users arrive in Keycloak with no groups by default. You have two options:

Option A — Manual assignment (simple): After an SSO user logs in for the first time, navigate to Users, find them, and update their group membership.

Option B — Attribute mapping (recommended for large teams): Configure Keycloak to map IdP groups or roles to Billerang groups automatically. This requires configuring mappers in Keycloak's identity provider settings (outside the scope of this guide).

Updating an SSO provider

To update configuration — for example, when rotating a signing certificate:

curl -X PUT "https://connect.billerang.com/api/portal/security/sso/corporate-saml" \
  -H "Cookie: $SESSION_COOKIE" \
  -H "Content-Type: application/json" \
  -d '{
    "config": {
      "signingCertificate": "MIIBnew..."
    }
  }'

Removing an SSO provider

Removing the SSO provider reverts to username/password authentication. Existing SSO users will lose the ability to log in until you either re-add the provider or set passwords for those accounts.

curl -X DELETE "https://connect.billerang.com/api/portal/security/sso/corporate-saml" \
  -H "Cookie: $SESSION_COOKIE"

---

What Changes When SSO Is Active

Behavior	SSO not active	SSO active
User creation	Admin creates or invites via portal	Automatic on first IdP login
Invitation flow	Available	Disabled (returns 400)
Password policy	Enforced by Billerang/Keycloak	Informational only (IdP manages passwords)
Password reset	Users request reset via portal	Managed by IdP
Existing local users	Log in with password	Can still log in until disabled
invitationStatus	pending / accepted / expired	Always accepted

The transition to SSO is safe: existing local accounts continue to work in parallel. You can migrate gradually by disabling local accounts once users have successfully authenticated via SSO.

---

Two-Factor Authentication

Check 2FA status across all users

curl "https://connect.billerang.com/api/portal/security/2fa" \
  -H "Cookie: $SESSION_COOKIE"

Response:

{
  "results": [
    {
      "username": "nabyl.lazraq",
      "email": "nabyl@billerang.com",
      "has2FA": true,
      "credentialType": "otp"
    },
    {
      "username": "john.doe",
      "email": "john@company.com",
      "has2FA": false,
      "credentialType": null
    }
  ]
}

Enforce 2FA for a specific user

This sets a Keycloak required action: the next time the user logs in, they will be prompted to configure an authenticator app (TOTP — Google Authenticator, Authy, etc.) before they can access the platform.

curl -X POST "https://connect.billerang.com/api/portal/security/2fa/john.doe/enforce" \
  -H "Cookie: $SESSION_COOKIE"

Response:

{ "status": "OK", "message": "2FA enforcement set for user john.doe" }

2FA and SSO

When SSO is active, 2FA is typically managed by your identity provider. Enforcing 2FA via Billerang affects Keycloak's own login flow, which may be bypassed when users authenticate through SSO. Check your IdP's MFA configuration for SSO users.

---

Security Best Practices

Enforce 2FA for Platform Admins

Platform Admins can manage users, configure SSO, and change security settings. Enforce 2FA for every account in the Platform Admin group.

Review SSO configuration after certificate rotation

SAML signing certificates expire. Set a calendar reminder to update signingCertificate in the SSO provider configuration before your IdP rotates its certificate. A mismatch causes all SSO logins to fail with a signature validation error.

Use short-lived sessions for privileged users

Keycloak session TTL can be configured per realm or per client. Consider shorter session lifetimes (2-4 hours) for Platform Admin and Finance Manager accounts.

Do not share service account credentials

Service accounts using the Client Credentials flow have roles assigned via group membership, just like human users. Create a dedicated service account per integration with only the roles that integration needs. Never reuse credentials across systems.

Audit SSO attribute mapping regularly

If you use Keycloak's IdP attribute mappers to auto-assign groups, review the mapping configuration whenever your IdP group structure changes. A misconfigured mapper can silently grant or remove access.

Keep the Platform Admin group small

Every additional Platform Admin is an additional attack surface. Aim for 2-3 Platform Admins maximum; use the Billing Manager group for day-to-day billing operations.