Social Login (OIDC)

Configure social sign-in providers for your self-hosted BillManager deployment.

Required Base Settings

Set APP_URL to your public web app URL. OAuth redirect URIs must match exactly.

Global OAuth Settings

Variable	Description	Default
OAUTH_AUTO_REGISTER	Allow first-time OAuth users to auto-create accounts	true (self-hosted)

Shared Redirect URI

Use this redirect URI for Google, Microsoft, and generic OIDC providers:

${APP_URL}/auth/callback

Example:

https://bills.yourdomain.com/auth/callback

Apple can return with form_post mode and BillManager bridges that back to the SPA callback route.

Google Setup

Environment Variables

Variable	Description
OAUTH_GOOGLE_ENABLED	Enable Google login (true/false)
OAUTH_GOOGLE_CLIENT_ID	Google OAuth client ID
OAUTH_GOOGLE_CLIENT_SECRET	Google OAuth client secret

Provider Console Steps

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

Apple Setup

Environment Variables

Variable	Description
OAUTH_APPLE_ENABLED	Enable Apple login (true/false)
OAUTH_APPLE_CLIENT_ID	Apple Service ID
OAUTH_APPLE_TEAM_ID	Apple Developer Team ID
OAUTH_APPLE_KEY_ID	Apple Sign In key ID
OAUTH_APPLE_PRIVATE_KEY	Apple private key PEM content

Provider Console Steps

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

Microsoft Setup

Environment Variables

Variable	Description	Default
OAUTH_MICROSOFT_ENABLED	Enable Microsoft login (true/false)	false
OAUTH_MICROSOFT_CLIENT_ID	Azure app (client) ID	None
OAUTH_MICROSOFT_CLIENT_SECRET	Azure client secret	None
OAUTH_MICROSOFT_TENANT_ID	Tenant ID or common	common

Tenant ID Guidance

• common: allow personal + organizational Microsoft accounts
• Specific tenant GUID: restrict login to one Azure tenant

Provider Console Steps

1. Open Microsoft Entra admin center
2. Register an app for web sign-in
3. Add redirect URI: ${APP_URL}/auth/callback
4. Create a client secret
5. Set OAUTH_MICROSOFT_TENANT_ID to common or your tenant GUID
6. Set environment variables and restart BillManager

Generic OIDC Setup

Required Variables

Variable	Description
OAUTH_OIDC_ENABLED	Enable generic OIDC login (true/false)
OAUTH_OIDC_CLIENT_ID	OIDC client ID
OAUTH_OIDC_CLIENT_SECRET	OIDC client secret
OAUTH_OIDC_DISCOVERY_URL	OIDC discovery URL (.well-known/openid-configuration)

Optional Variables

Variable	Description	Default
OAUTH_OIDC_SCOPES	OAuth scopes string	openid email profile
OAUTH_OIDC_DISPLAY_NAME	Label shown on 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

Provider Console Steps

1. Create an OIDC client in your provider
2. Set redirect URI: ${APP_URL}/auth/callback
3. Copy client ID and secret
4. Copy provider discovery URL
5. Set environment variables and restart BillManager

Docker Compose Example

services:
  billmanager:
    image: ghcr.io/brdweb/billmanager:latest
    environment:
      - APP_URL=https://bills.yourdomain.com
      - OAUTH_AUTO_REGISTER=true

      # Microsoft
      - 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 (example)
      - 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_DISPLAY_NAME=Company SSO

Validation Checklist

• APP_URL uses your public HTTPS domain
• Provider redirect URI exactly matches ${APP_URL}/auth/callback
• Enabled providers include all required credentials
• Login page shows expected provider buttons
• New OAuth users are handled according to OAUTH_AUTO_REGISTER