Skip to content

User management

This page explains how users, authentication, and permissions work across the platform.

User types

Django users

All users have a base Django user account with: - Username and email - Password authentication - Basic profile information - Staff/superuser flags

Extended profiles

Users may have additional profile data depending on their role:

Profile Purpose Link
MunicipalityUser Municipal staff One-to-one with User

Anonymous users

Some platform features are accessible without authentication: - Public occurrence submission - Public occupancy dashboards - Read-only API endpoints (if configured)

Authentication methods

Username/password

Standard Django authentication: - Login via Django Admin or API - Password reset via email - Session-based authentication

API authentication

For programmatic access: - Token authentication (DRF) - JWT tokens (if configured) - API keys for service accounts

Social authentication

If configured (django-allauth): - OAuth providers (Google, Microsoft, etc.) - SAML for enterprise SSO

Role hierarchy

Platform roles

Role Scope Capabilities
Superuser Platform-wide All operations, all municipalities
Platform Admin Platform-wide Module configuration, user management

Municipality roles

Role Scope Capabilities
Municipality Admin Single municipality Full control within municipality
Manager Single municipality Configure workflows, manage staff
Operator Single municipality Work on records, day-to-day operations
Viewer Single municipality Read-only access

Role assignment

  1. Create Django user account
  2. Set staff flag if needed for admin access
  3. Create MunicipalityUser profile with role
  4. Assign to department (optional)
  5. Set category restrictions (optional)

Permissions system

Module-level permissions

Controlled via MODULE_PERMISSIONS in settings:

MODULE_PERMISSIONS = {
    'occurrences': {
        'view': ['public', 'staff', 'manager', 'admin'],
        'create': ['public', 'staff', 'admin'],
        ...
    },
}

Object-level permissions

Fine-grained control via: - Municipality ownership (users see their municipality's data) - Department permissions (which occurrence types) - Category restrictions (MunicipalityUser.allowed_occurrence_types)

Permission checking

In views/APIs:

from apps.utils.module_registry import user_can_access_module

if user_can_access_module(request.user, 'equipment', 'create'):
    # Allow creation

Creating users

Via Django Admin

  1. Navigate to Users → Users
  2. Click Add User
  3. Set username and password
  4. Save, then edit to add:
  5. Email and name
  6. Staff/superuser flags
  7. Groups (if using)

Via API (if enabled)

POST /api/users/
{
  "username": "jsmith",
  "email": "jsmith@municipality.gov",
  "password": "secure_password",
  "first_name": "John",
  "last_name": "Smith"
}

Self-registration

If enabled, citizens can register: 1. Visit registration page 2. Provide email and password 3. Verify email (if required) 4. Account created with basic permissions

Staff onboarding

Process

  1. Create user account (or have them self-register)
  2. Create MunicipalityUser profile:
  3. Assign to correct municipality
  4. Set appropriate role
  5. Assign department (if applicable)
  6. Set permissions:
  7. Category restrictions (if needed)
  8. Department permissions
  9. Approve the user (set is_approved = True)
  10. Notify the user of their access

Checklist

  • [ ] Django user created
  • [ ] MunicipalityUser profile created
  • [ ] Role assigned
  • [ ] Department assigned (optional)
  • [ ] Category restrictions set (if needed)
  • [ ] User approved
  • [ ] Welcome email sent

User approval workflow

For municipalities requiring approval before staff can work:

  1. User registers or is created
  2. MunicipalityUser created with is_approved = False
  3. Administrator reviews the request
  4. Administrator sets is_approved = True
  5. User can now access staff functions

Checking approval

municipality_user = request.user.municipality_profile
if not municipality_user.is_approved:
    # Deny access to staff functions

Deactivating users

Temporary deactivation

  1. Set is_active = False on MunicipalityUser
  2. User cannot access municipality functions
  3. Django user account remains active

Full deactivation

  1. Set is_active = False on Django User
  2. User cannot log in at all
  3. Data and history preserved

Permanent removal

Generally not recommended. Instead: - Deactivate the user - Remove sensitive data if required - Maintain audit trail

Audit and logging

User actions are tracked: - Login/logout events - Record modifications (via audit models) - API access (if logging enabled)

View audit information in: - Django Admin audit logs - Record history (created_by, updated_by fields) - API access logs

Behind the scenes (grounded in code)

  • User model: apps/users/models.py (extends Django User)
  • Municipality profile: apps/municipalities/models.py → MunicipalityUser
  • Permission checking: apps/utils/module_registry.py
  • Authentication: config/settings/base.py (AUTH settings)
  • API authentication: DRF TokenAuthentication or JWT
  • Admin: apps/users/admin.py