Skip to content

User Management

Guide for managing user accounts, authentication, and security settings in Bifolk.

Target Audience: System administrators, organization owners

User Registration

Self-Registration

When ALLOW_SELF_REGISTRATION=True (the default):

  1. Users register through the signup page at /register/
  2. They provide a username, email address, and password
  3. If REQUIRE_EMAIL_VERIFICATION=True, they must verify their email before logging in
  4. After verification (or immediately if verification is disabled), they can log in
  5. A personal organization is automatically created for the new user
  6. The browser language is detected and saved as the user's language preference

Admin-Created Accounts

When ALLOW_SELF_REGISTRATION=False, only administrators can create users:

  1. Go to the Django admin interface (/admin/)
  2. Navigate to Users > Add User
  3. Set username, email, and password
  4. Save

A profile is automatically created for each new user.

Invitation-Based Registration

Organization admins can invite users regardless of the self-registration setting:

  1. Go to the organization's detail page
  2. Click Invite Member
  3. Enter the person's email and select a role
  4. The person receives an invitation email
  5. They register (if new) or accept (if existing user)

Invitations expire after 7 days by default.

Note

Invited users can always register, even when self-registration is disabled. The invitation link bypasses the registration restriction.

User Profiles

Each user has a profile that is created automatically at registration. The profile includes:

  • Profile Picture: Uploaded by the user, automatically resized to 300x300 pixels
  • Language: English or German (auto-detected from browser at registration)
  • Theme Preference: Light, Dark, or System (default: System)
  • Default Report Date Range: Current Year or Last 365 Days (default: Current Year)
  • Last Seen Version: Tracks which application version the user last acknowledged (used for changelog notifications)

Users manage their own profile at /profile/.

Managing Users via Django Admin

Viewing Users

  1. Go to /admin/
  2. Navigate to Authentication and Authorization > Users
  3. Use search and filters to find users

Viewing Profiles

  1. Go to /admin/
  2. Navigate to Users > Profiles
  3. Profiles can be searched by username or email
  4. Profiles can be filtered by language

Editing a User

  1. Click on a user in the admin list
  2. Edit fields:
  3. Username, email, first name, last name
  4. Active status (controls login ability)
  5. Staff status (grants Django admin access)
  6. Superuser status (grants full access to all features)
  7. Save

Deactivating a User

  1. Edit the user in Django admin
  2. Uncheck Active
  3. Save

Deactivated users cannot log in but their data is preserved. This is the recommended approach instead of deleting user accounts.

Resetting a Password

  1. Edit the user in Django admin
  2. Click the change password link at the top of the form
  3. Set a new password
  4. Communicate the temporary password to the user securely

Authentication Methods

Username/Password

The default authentication method. Users can log in with either their username or email address. Authentication is handled by django-allauth.

Single Sign-On (OIDC)

When configured, users can log in via an external identity provider (e.g., Authentik, Keycloak). See Configuration for OIDC settings.

Setting Default Description
OIDC_CLIENT_ID (empty) Client ID from your identity provider. OIDC is only active when this is set
OIDC_CLIENT_SECRET (empty) Client secret from your identity provider
OIDC_SERVER_URL (empty) OpenID Connect server URL
OIDC_PROVIDER_ID authentik Internal provider identifier, used in callback URLs
OIDC_PROVIDER_NAME Single Sign-On Display name shown on the login page button
DISABLE_STANDARD_LOGIN False When True, hides the username/password form and shows only the SSO button

Two-Factor Authentication (MFA)

Bifolk supports TOTP-based two-factor authentication via authenticator apps.

Setting Default Description
MFA_REQUIRED none MFA enforcement: none (optional), staff (staff users only), or all (all users)
MFA_GRACE_PERIOD_DAYS 7 Days users have to set up MFA before being locked out
MFA_TOTP_ISSUER Bifolk Issuer name shown in authenticator apps

When MFA is required:

  • Users are reminded to set up MFA during the grace period
  • After the grace period, users are forced to set up MFA before accessing other pages
  • Users cannot delete their last authenticator if MFA is required for them
  • 10 recovery codes are generated during setup for emergency access

Organization-level MFA policies can also be configured. If any of a user's organizations require MFA, the user cannot remove their last authenticator.

Registration Settings

Setting Default Description
ALLOW_SELF_REGISTRATION True Allow users to register themselves
REQUIRE_EMAIL_VERIFICATION True Require email verification before login

When email verification is enabled:

  • Confirmation emails are valid for 3 days
  • Users are automatically logged in after confirming their email

Session Management

Setting Default Description
SESSION_TOKEN_LIFETIME_HOURS 168 (7 days) How long users stay logged in

Common values:

  • 24 (1 day) - High security environments
  • 168 (7 days) - Recommended default
  • 336 (14 days) - Moderate security
  • 720 (30 days) - Convenience-focused

Sessions persist beyond browser close. The session cookie is HTTP-only and uses secure cookies in production.