Connect Authentik / OIDC¶

BillTracker supports Authentik and other standards-compatible OIDC providers. Configure OIDC from Admin > Authentication Methods.

This page walks through creating the Authentik provider, the BillTracker fields to set, the env-var fallbacks, and the rollout checklist.

How do I create the Authentik provider?¶

Create an OAuth2/OpenID Provider with:

Client type: confidential
Redirect URI: https://bills.example.com/api/auth/oidc/callback
Scopes: openid email profile groups
A groups claim when admin role mapping is needed

The redirect URI must exactly match the value saved in BillTracker.

What fields does BillTracker need?¶

Field	Typical value
Provider name	`authentik`
Issuer URL	`https://auth.example.com/application/o/bill-tracker/`
Client ID	Provider-generated ID
Client secret	Provider-generated secret
Token endpoint auth method	`client_secret_basic` or `client_secret_post`
Redirect URI	`https://bills.example.com/api/auth/oidc/callback`
Scopes	`openid email profile groups`
Admin group	Authentik group allowed to become BillTracker admin
Auto-provision	Create a regular user after successful first login

OIDC users default to the regular user role. Admin mapping requires an explicit admin group.

What are the env-var fallbacks?¶

Database-backed Admin settings take precedence. Empty database values fall back to:

OIDC_PROVIDER_NAME=authentik
OIDC_ISSUER_URL=https://auth.example.com/application/o/bill-tracker/
OIDC_CLIENT_ID=<client-id>
OIDC_CLIENT_SECRET=<client-secret>
OIDC_TOKEN_AUTH_METHOD=client_secret_basic
OIDC_REDIRECT_URI=https://bills.example.com/api/auth/oidc/callback
OIDC_SCOPES="openid email profile groups"
OIDC_ADMIN_GROUP=bill-tracker-admins
OIDC_AUTO_PROVISION=true

How do I roll out OIDC safely?¶

Save the provider settings while local login remains enabled.
Use the Admin panel provider test.
Log out and complete a real OIDC login.
Verify admin-group mapping with a permitted account.
Disable local login only if that is your intended deployment posture.