Social Login Setup (Google and Apple)

Configure social login so your users can sign in with Google or Apple.

More Providers Coming Soon

Support for additional social login providers will be added in a future release.

Optional Feature

Social login is entirely optional. All providers are disabled by default. BillManager works perfectly fine with just username/password authentication.

How It Works

You register BillManager as an application (OAuth client) with the identity provider
You add the provider's credentials to your BillManager environment variables
Users see "Sign in with ..." buttons on the login page
On first social login, a BillManager account is automatically created (if OAUTH_AUTO_REGISTER is enabled)

Callback URL

Every provider will ask for a redirect URI (also called callback URL). Use:

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

Replace your-billmanager-url.com with your actual APP_URL. This must match exactly — including the scheme (https://) and no trailing slash.

Provider Setup

Google

Go to the Google Cloud Console
Create a new project (or select an existing one)
Go to APIs & Services → Credentials
Click Create Credentials → OAuth client ID
Select Web application
Add your callback URL under Authorized redirect URIs:
```
https://your-billmanager-url.com/auth/callback
```
Copy the Client ID and Client secret

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

Apple

Go to Apple Developer Account
Register an App ID with "Sign In with Apple" capability
Create a Services ID (this becomes your Client ID)
Configure the Return URL (your callback URL)
Create a Key with "Sign In with Apple" enabled — download the .p8 file

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.

More Providers

This page will be expanded as additional providers are added.

Auto-Registration

When a user signs in via a social provider for the first time, BillManager can automatically create an account for them.

Variable	Description	Default
`OAUTH_AUTO_REGISTER`	Create accounts for new social login users	`false`

When enabled:

A new user account is created using the provider's email
The username is derived from the email (before the @)
The user is assigned the default user role (not admin)
They still need a Bill Group assignment from an admin to see any bills

When disabled:

Only existing users can link social accounts from Admin Panel → Security
New users must be created by an admin first, then they can link a social provider

Two-Factor Authentication

BillManager supports two-factor authentication (2FA) with email OTP codes, passkeys (WebAuthn), and recovery codes.

Enabling 2FA

environment:
  - ENABLE_2FA=true

This allows users to optionally enable 2FA on their accounts via Admin Panel → Security. It does not force 2FA — each user chooses whether to enable it.

Enabling Passkeys

Passkeys require additional configuration for WebAuthn:

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`	Your domain name (no scheme, no port)	`bills.yourdomain.com`
`WEBAUTHN_RP_NAME`	Display name shown in browser prompts	`BillManager`
`WEBAUTHN_ORIGIN`	Full origin URL (scheme + domain, 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. If users visit https://bills.example.com, set it to bills.example.com. Passkey registration and authentication will silently fail if this doesn't match.

Recovery Codes

Recovery codes are automatically generated when a user enables 2FA. Each user gets a set of one-time-use codes that work if they lose access to their email or passkey. No additional configuration is needed.

Environment Variable Reference

OAuth Providers

Variable	Required	Description
`OAUTH_GOOGLE_ENABLED`	No	Enable Google login (`true`/`false`)
`OAUTH_GOOGLE_CLIENT_ID`	If enabled	Google OAuth client ID
`OAUTH_GOOGLE_CLIENT_SECRET`	If enabled	Google OAuth client secret
`OAUTH_APPLE_ENABLED`	No	Enable Apple login
`OAUTH_APPLE_CLIENT_ID`	If enabled	Apple Services ID
`OAUTH_APPLE_TEAM_ID`	If enabled	Apple Developer Team ID
`OAUTH_APPLE_KEY_ID`	If enabled	Apple Sign In key ID
`OAUTH_APPLE_PRIVATE_KEY`	If enabled	Apple Sign In private key (PEM)

Auto-Registration & 2FA

Variable	Default	Description
`OAUTH_AUTO_REGISTER`	`false`	Auto-create accounts for social login users
`ENABLE_2FA`	`false`	Allow users to enable two-factor authentication
`ENABLE_PASSKEYS`	`false`	Allow passkey/WebAuthn as a 2FA method
`WEBAUTHN_RP_ID`	Derived from `APP_URL`	WebAuthn Relying Party ID (your domain)
`WEBAUTHN_RP_NAME`	`BillManager`	Display name in browser passkey prompts
`WEBAUTHN_ORIGIN`	`APP_URL`	Full origin URL for WebAuthn

Full Example

Here's a complete docker-compose.yml with Google/Apple login and 2FA with passkeys:

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 (required for 2FA email OTP and invitations)
      - RESEND_API_KEY=${RESEND_KEY}
      - [email protected]
      # Google OAuth
      - OAUTH_GOOGLE_ENABLED=true
      - OAUTH_GOOGLE_CLIENT_ID=${GOOGLE_CLIENT_ID}
      - OAUTH_GOOGLE_CLIENT_SECRET=${GOOGLE_CLIENT_SECRET}
      # Apple OAuth
      - OAUTH_APPLE_ENABLED=true
      - OAUTH_APPLE_CLIENT_ID=${APPLE_SERVICES_ID}
      - OAUTH_APPLE_TEAM_ID=${APPLE_TEAM_ID}
      - OAUTH_APPLE_KEY_ID=${APPLE_KEY_ID}
      - OAUTH_APPLE_PRIVATE_KEY=${APPLE_PRIVATE_KEY}
      # 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:

How It Works​

Callback URL​

Provider Setup​

Google​

Apple​

Auto-Registration​

Two-Factor Authentication​

Enabling 2FA​

Enabling Passkeys​

Recovery Codes​

Environment Variable Reference​

OAuth Providers​

Auto-Registration & 2FA​

Full Example​