Skip to main content

Social Login

BillManager supports OIDC social login in the web app.

Supported Providers​

  • Google
  • Apple
  • Microsoft (Azure AD / Microsoft Entra ID)
  • Generic OIDC (for providers like Keycloak, Authentik, Okta, and others)

User Login Flow​

  1. User selects a social login provider on the login page
  2. BillManager redirects to the provider's authorization page
  3. Provider redirects back to BillManager callback
  4. BillManager verifies state, nonce, and ID token signature
  5. User is signed in (or prompted for 2FA if enabled)

Security Behavior​

  • PKCE (S256) is used during authorization code flow
  • OAuth state tokens include replay protection
  • ID token signatures are validated against provider JWKS keys
  • Provider claims are validated before account linking or account creation

Account Linking​

Users can link multiple providers to one BillManager account from linked account settings.

  • Link a provider to an existing account
  • Unlink providers later
  • Keep a local username/password if you want a fallback login method

Two-Factor Authentication​

If 2FA is enabled, social login still requires the second factor after provider authentication.

Auto-Registration​

When OAUTH_AUTO_REGISTER=true, first-time social login can create a new account automatically.

  • Self-hosted default: enabled
  • SaaS default: disabled

Current Platform Scope​

Social login is currently available in the web app flow. Mobile OAuth is planned separately.

Setup Guide​

For environment variables and provider setup, see Self-Hosted Social Login.