Social Login and 2FA Setup

Configure OAuth/OIDC sign-in and optional two-factor authentication for your self-hosted BillManager deployment.

Optional Feature

Social login is optional. BillManager works with username/password authentication when all providers are disabled.

How Social Login Works

1. Register BillManager as an OAuth/OIDC client with the identity provider.
2. Add the provider credentials to your BillManager environment.
3. Users see the enabled provider buttons on the login page.
4. On first provider login, BillManager creates an account if OAUTH_AUTO_REGISTER=true.

Callback URL

Every provider needs this redirect URI:

https://your-billmanager-url.com/auth/callback

Replace your-billmanager-url.com with your APP_URL host. The scheme and path must match exactly.

Global OAuth Settings

Variable	Description	Default
APP_URL	Public BillManager URL used for redirects	http://localhost:5000
OAUTH_AUTO_REGISTER	Create users on first provider login	true in self-hosted mode

Supported Providers

Google

1. Open Google Cloud Console.
2. Create OAuth client credentials for a web application.
3. Add redirect URI: ${APP_URL}/auth/callback.
4. Set environment variables and restart BillManager.

environment:
  - OAUTH_GOOGLE_ENABLED=true
  - OAUTH_GOOGLE_CLIENT_ID=123456789-abc.apps.googleusercontent.com
  - OAUTH_GOOGLE_CLIENT_SECRET=GOCSPX-your-secret

Apple

1. Create an Apple Service ID for your app domain.
2. Enable Sign in with Apple for the Service ID.
3. Configure return URL: ${APP_URL}/auth/callback.
4. Generate a Sign in with Apple key and capture Team ID, Key ID, and private key.
5. Set environment variables and restart BillManager.

environment:
  - OAUTH_APPLE_ENABLED=true
  - OAUTH_APPLE_CLIENT_ID=com.yourdomain.billmanager
  - OAUTH_APPLE_TEAM_ID=ABCDE12345
  - OAUTH_APPLE_KEY_ID=KEY123456
  - OAUTH_APPLE_PRIVATE_KEY=-----BEGIN PRIVATE KEY-----\nMIGT...your-key...\n-----END PRIVATE KEY-----

Apple Private Key

The private key must be the full PEM content. In Docker Compose, use \n for newlines or mount it as a file. In Coolify/Portainer, paste it directly into the environment variable field.

Microsoft

1. Open Microsoft Entra admin center.
2. Register a web app.
3. Add redirect URI: ${APP_URL}/auth/callback.
4. Create a client secret.
5. Use common for personal plus organizational accounts, or a tenant GUID to restrict to one tenant.
6. Set environment variables and restart BillManager.

environment:
  - OAUTH_MICROSOFT_ENABLED=true
  - OAUTH_MICROSOFT_CLIENT_ID=your-microsoft-client-id
  - OAUTH_MICROSOFT_CLIENT_SECRET=your-microsoft-client-secret
  - OAUTH_MICROSOFT_TENANT_ID=common

Generic OIDC

Use generic OIDC for providers such as Authelia, Authentik, Keycloak, Zitadel, or another OpenID Connect IdP.

environment:
  - OAUTH_OIDC_ENABLED=true
  - OAUTH_OIDC_CLIENT_ID=your-oidc-client-id
  - OAUTH_OIDC_CLIENT_SECRET=your-oidc-client-secret
  - OAUTH_OIDC_DISCOVERY_URL=https://sso.yourdomain.com/.well-known/openid-configuration
  - OAUTH_OIDC_TOKEN_AUTH_METHOD=client_secret_post
  - OAUTH_OIDC_DISPLAY_NAME=Company SSO
  - OAUTH_OIDC_SCOPES=openid email profile

Variable	Description	Default
OAUTH_OIDC_ENABLED	Enable generic OIDC login	false
OAUTH_OIDC_CLIENT_ID	OIDC client ID	None
OAUTH_OIDC_CLIENT_SECRET	OIDC client secret, unless using public-client auth	None
OAUTH_OIDC_DISCOVERY_URL	Provider discovery URL	None
OAUTH_OIDC_TOKEN_AUTH_METHOD	client_secret_post, client_secret_basic, none, or auto	client_secret_post
OAUTH_OIDC_SCOPES	OAuth scopes string	openid email profile
OAUTH_OIDC_DISPLAY_NAME	Label shown on the login button	SSO
OAUTH_OIDC_ICON	Icon key shown in the UI	lock
OAUTH_OIDC_EMAIL_CLAIM	Claim used for email	email
OAUTH_OIDC_USERNAME_CLAIM	Claim used for username fallback	preferred_username
OAUTH_OIDC_NAME_CLAIM	Claim used for display name	name
OAUTH_OIDC_SKIP_EMAIL_VERIFICATION	Skip email_verified requirement	false

Generic OIDC Compatibility

BillManager can use the userinfo endpoint when the ID token does not include every profile claim. Use the claim mapping variables when your provider uses custom claim names.

Trusted Providers Only

Only set OAUTH_OIDC_SKIP_EMAIL_VERIFICATION=true for a self-hosted provider you control and trust to verify user email addresses.

Auto-Registration

When OAUTH_AUTO_REGISTER=true, a first-time provider login can create a BillManager account automatically.

For self-hosted deployments, the default is true. Disable it when admins should create every account manually:

environment:
  - OAUTH_AUTO_REGISTER=false

When enabled:

• A new user account is created from the provider email.
• The username is derived from provider claims or the email address.
• The user still needs Bill Group access from an admin to see existing bills.

When disabled:

• Only existing users can sign in or link providers.
• New users must be created by an admin first.

Two-Factor Authentication

BillManager supports email OTP codes, passkeys (WebAuthn), and recovery codes.

Enable 2FA

environment:
  - ENABLE_2FA=true

This allows users to enable 2FA from Security settings. It does not force every user to enable 2FA.

Email OTP requires outbound email. See Email Setup.

Enable Passkeys

Passkeys require WebAuthn relying party settings:

environment:
  - ENABLE_2FA=true
  - ENABLE_PASSKEYS=true
  - WEBAUTHN_RP_ID=bills.yourdomain.com
  - WEBAUTHN_RP_NAME=BillManager
  - WEBAUTHN_ORIGIN=https://bills.yourdomain.com

Variable	Description	Example
WEBAUTHN_RP_ID	Domain name only, no scheme or port	bills.yourdomain.com
WEBAUTHN_RP_NAME	Display name shown in browser prompts	BillManager
WEBAUTHN_ORIGIN	Full origin URL, no trailing slash	https://bills.yourdomain.com

RP ID Must Match Your Domain

WEBAUTHN_RP_ID must exactly match the domain users access BillManager from. Passkey registration and authentication fail when this does not match.

Recovery Codes

Recovery codes are generated when a user enables 2FA. Each code is single-use and helps recover access if the user loses email or passkey access.

Full Example

services:
  billmanager:
    image: ghcr.io/brdweb/billmanager:latest
    ports:
      - "5000:5000"
    environment:
      - DEPLOYMENT_MODE=self-hosted
      - DATABASE_URL=postgresql://billsuser:${DB_PASSWORD}@db:5432/billmanager
      - FLASK_SECRET_KEY=${FLASK_SECRET}
      - JWT_SECRET_KEY=${JWT_SECRET}
      - APP_URL=https://bills.yourdomain.com

      # Email for invitations, password reset, and email OTP
      - EMAIL_PROVIDER=smtp
      - SMTP_HOST=smtp.example.com
      - SMTP_PORT=587
      - SMTP_USERNAME=${SMTP_USERNAME}
      - SMTP_PASSWORD=${SMTP_PASSWORD}
      - SMTP_USE_TLS=true
      - [email protected]

      # Generic OIDC
      - OAUTH_OIDC_ENABLED=true
      - OAUTH_OIDC_CLIENT_ID=${OIDC_CLIENT_ID}
      - OAUTH_OIDC_CLIENT_SECRET=${OIDC_CLIENT_SECRET}
      - OAUTH_OIDC_DISCOVERY_URL=https://sso.yourdomain.com/.well-known/openid-configuration
      - OAUTH_OIDC_TOKEN_AUTH_METHOD=client_secret_post
      - OAUTH_OIDC_DISPLAY_NAME=Company SSO

      # Two-factor authentication
      - ENABLE_2FA=true
      - ENABLE_PASSKEYS=true
      - WEBAUTHN_RP_ID=bills.yourdomain.com
      - WEBAUTHN_RP_NAME=BillManager
      - WEBAUTHN_ORIGIN=https://bills.yourdomain.com
    depends_on:
      - db
    restart: unless-stopped

  db:
    image: postgres:16-alpine
    environment:
      - POSTGRES_USER=billsuser
      - POSTGRES_PASSWORD=${DB_PASSWORD}
      - POSTGRES_DB=billmanager
    volumes:
      - postgres_data:/var/lib/postgresql/data
    restart: unless-stopped

volumes:
  postgres_data:

Validation Checklist

• APP_URL uses the public HTTPS domain.
• Provider redirect URI exactly matches ${APP_URL}/auth/callback.
• Enabled providers include all required credentials.
• Generic OIDC discovery URL is reachable from the BillManager container.
• Login page shows expected provider buttons.
• New provider users are handled according to OAUTH_AUTO_REGISTER.
• Email OTP is only enabled after outbound email is configured.