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

Use generic OIDC for self-hosted identity providers such as Authelia, Authentik, Keycloak, Zitadel, or other OpenID Connect providers.

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, unless using OAUTH_OIDC_TOKEN_AUTH_METHOD=none
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_TOKEN_AUTH_METHOD	Token endpoint auth method: client_secret_post, client_secret_basic, none, or auto	client_secret_post
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

Provider Notes

Provider	Typical discovery URL	Token auth method notes
Authelia	https://auth.yourdomain.com/.well-known/openid-configuration	Usually client_secret_post
Authentik	https://sso.yourdomain.com/application/o/billmanager/.well-known/openid-configuration	Usually client_secret_post
Keycloak	https://sso.yourdomain.com/realms/<realm>/.well-known/openid-configuration	Often client_secret_post or client_secret_basic
Public/no-secret OIDC clients	Provider-specific	Use none only when the provider is configured for a public client

Minimal ID Tokens

Some self-hosted providers keep ID tokens small and return profile data from the userinfo endpoint. BillManager falls back to userinfo and supports claim mapping through OAUTH_OIDC_EMAIL_CLAIM, OAUTH_OIDC_USERNAME_CLAIM, and OAUTH_OIDC_NAME_CLAIM.

Email Verification Bypass

Set OAUTH_OIDC_SKIP_EMAIL_VERIFICATION=true only for a trusted self-hosted provider where you control account verification. Leave it false for public providers.

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_TOKEN_AUTH_METHOD=client_secret_post
      - OAUTH_OIDC_DISPLAY_NAME=Company SSO
      - OAUTH_OIDC_EMAIL_CLAIM=email
      - OAUTH_OIDC_USERNAME_CLAIM=preferred_username
      - OAUTH_OIDC_NAME_CLAIM=name

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
• Generic OIDC providers expose the requested scopes and expected claims
• OAUTH_OIDC_SKIP_EMAIL_VERIFICATION is only enabled for trusted providers