User Permissions Management Guide

Overview

The BNSD1 system uses Django's built-in permissions framework to control user access to different features and data. As a system administrator, you can grant or revoke permissions to individual users or groups.

Understanding Permissions

Permission Types

Each model in the system has four default permissions:

View (view_*) - View records in the admin interface
Add (add_*) - Create new records
Change (change_*) - Edit existing records
Delete (delete_*) - Delete records

Key Permissions in BNSD1

Companies & Persons: - companies.view_companies - View company records - companies.add_companies - Show "+ Add Company" button - companies.change_companies - Allow editing companies via clickable IDs - companies.delete_companies - Delete companies - companies.view_persons - View person records - companies.add_persons - Show "+ Add Person" button - companies.change_persons - Allow editing persons via clickable IDs - companies.delete_persons - Delete persons

Projects: - projects.view_project - View project records - projects.add_project - Show "+ Add Project" button - projects.change_project - Allow editing projects via clickable IDs - projects.delete_project - Delete projects - projects.view_projectcategories - View project-category mappings - projects.add_projectcategories - Show "+ Add Mapping" button - projects.change_projectcategories - Allow editing project-category mappings - projects.delete_projectcategories - Delete mappings

Questions: - questions.view_question - View questions - questions.add_question - Create new questions - questions.change_question - Edit questions in Manage Questions view - questions.delete_question - Delete questions - questions.view_questioncategories - View question categories - questions.add_questioncategories - Add question categories - questions.change_questioncategories - Edit question categories - questions.delete_questioncategories - Delete categories

Pre-Configured Permission Groups

The system includes pre-configured groups for common access patterns. These groups are created using management commands and provide consistent permission sets.

Admin Groups (Full Access)

These groups have complete CRUD (Create, Read, Update, Delete) permissions:

Admin Projects - projects.view_project - projects.add_project - projects.change_project - projects.delete_project

Admin Project Categories - projects.view_projectcategories - projects.add_projectcategories - projects.change_projectcategories - projects.delete_projectcategories

Admin Companies - companies.view_companies - companies.add_companies - companies.change_companies - companies.delete_companies

Admin Persons - companies.view_persons - companies.add_persons - companies.change_persons - companies.delete_persons

Admin Questions - questions.view_questions - questions.add_questions - questions.change_questions - questions.delete_questions

Admin Question Types - questions.view_questiontypes - questions.add_questiontypes - questions.change_questiontypes - questions.delete_questiontypes

Admin Question Roles - questions.view_questionroles - questions.add_questionroles - questions.change_questionroles - questions.delete_questionroles

Admin Question Categories - questions.view_questioncategories - questions.add_questioncategories - questions.change_questioncategories - questions.delete_questioncategories

Usage: Assign these groups to department administrators, data entry staff, and project managers who need full control.

View Groups (Read-Only Access)

These groups only have view permissions:

View Projects - projects.view_project

View Project Categories - projects.view_projectcategories

View Companies - companies.view_companies

View Persons - companies.view_persons

View Questions - questions.view_questions

View Question Types - questions.view_questiontypes

View Question Roles - questions.view_questionroles

View Question Categories - questions.view_questioncategories

Usage: Assign these groups to external stakeholders, auditors, reporting staff, and anyone who needs to see data but not modify it.

Creating Pre-Configured Groups

Run these management commands to create all groups:

python manage.py create_project_groups
python manage.py create_project_category_groups
python manage.py create_company_groups
python manage.py create_person_groups
python manage.py create_question_groups
python manage.py create_question_type_groups
python manage.py create_question_role_groups
python manage.py create_question_category_groups

See Permission-Based Views Guide for detailed information about how these groups control UI behavior.

Granting Permissions to Individual Users

Method 1: Via Django Admin

Access Django Admin
Navigate to: http://your-domain.com/admin/
Login with superuser credentials
Select User
Click Authentication and Authorization → Users
Click on the username you want to modify
Assign Permissions
Scroll to the Permissions section
Find User permissions field (multi-select box)
Select permissions by:
- Holding Ctrl (Windows/Linux) or Cmd (Mac)
- Clicking each permission you want to grant
Move selected permissions from "Available" to "Chosen" using the arrow buttons
Save Changes
Scroll to bottom and click Save

Method 2: Staff Status & Superuser

Staff status (is_staff): Allows login to Django Admin
Superuser status (is_superuser): Grants ALL permissions automatically

To grant superuser: 1. Edit user in Django Admin 2. Check Superuser status checkbox 3. Save

Using Groups for Permission Management

Groups allow you to assign permissions to multiple users at once.

Creating a Group

Navigate to Groups
Django Admin → Authentication and Authorization → Groups
Click Add Group
Name the Group
Examples: "Editors", "Viewers", "Project Managers", "Read Only"
Assign Permissions
Select permissions from the multi-select box
Click arrow to move to "Chosen permissions"
Click Save

Common Group Examples

Admin Groups (Pre-Configured): - Admin Projects - Full CRUD on projects - Admin Project Categories - Full CRUD on project-category mappings - Admin Companies - Full CRUD on companies - Admin Persons - Full CRUD on persons

View Groups (Pre-Configured): - View Projects - Read-only access to projects - View Project Categories - Read-only access to mappings - View Companies - Read-only access to companies - View Persons - Read-only access to persons

Custom Group Examples:

Read Only Users (All Modules): Add user to all four View groups: - View Projects - View Project Categories - View Companies - View Persons

Editors (All Modules): Add user to all four Admin groups: - Admin Projects - Admin Project Categories - Admin Companies - Admin Persons

Data Entry (Companies/Persons Only): Add user to: - Admin Companies - Admin Persons - View Projects (read-only) - View Project Categories (read-only)

Project Managers: Add user to: - Admin Projects - Admin Project Categories - View Companies (read-only) - View Persons (read-only) - questions.view_question (individual permission)

Assigning Users to Groups

Edit User in Django Admin
Navigate to user's edit page
Assign Groups
Scroll to Permissions section
Find Groups field
Select one or more groups
Move to "Chosen groups"
Save
User inherits all group permissions

Permission Hierarchy

Superuser - Has all permissions automatically (highest)
Group Permissions - User inherits from all groups they belong to
User Permissions - Individual permissions assigned directly
Anonymous/Logged Out - No access (lowest)

A user's final permissions are the union of all sources above.

Testing Permissions

Check User Permissions

Login as the user (or use Incognito/Private browsing)
Navigate to manage pages:
/companies/companies/manage/ - Check if "+ Add Company" button appears
Click an ID - Check if edit dialog opens
If button missing → user lacks add_* permission
If ID not clickable → user lacks change_* permission

Python Shell Testing

# From terminal in backend directory
python manage.py shell

# Check permissions for a user
from django.contrib.auth.models import User
user = User.objects.get(username='johndoe')

# Check specific permission
user.has_perm('companies.add_companies')  # Returns True/False

# List all user permissions
user.get_all_permissions()

Best Practices

Security Recommendations

Use Groups - Easier to manage than individual permissions
Principle of Least Privilege - Grant only necessary permissions
Separate Roles - Create distinct groups for different job functions
Limit Superusers - Only grant to trusted administrators
Regular Audits - Review permissions quarterly

Recommended Group Structure

Administrators - Superuser status
Editors - Add, Change, View (no Delete)
Contributors - Add, Change own records
Viewers - View only
External - Limited view permissions for clients

Permission Naming Convention

Django uses: <app_label>.<permission_codename>

Examples: - companies.add_companies - projects.change_project - questions.delete_question

Common Scenarios

Scenario 1: New Employee (Editor)

Create user account in Django Admin
Set Staff status = Yes
Add to Editors group
User can now add/edit Companies, Persons, Projects

Scenario 2: Read-Only Auditor

Create user account
Set Staff status = Yes (for admin access)
Add to Viewers group
User can view all data but cannot modify

Scenario 3: Client Portal User

Create user account
Do NOT set Staff status
Grant only:
projects.view_project
questions.view_question
User can view assigned project data only

Scenario 4: Data Entry Clerk

Create user account
Set Staff status = Yes
Grant specific permissions:
companies.add_companies
companies.change_companies
companies.add_persons
companies.change_persons
User can only work with Companies/Persons data

Troubleshooting

User Cannot See Admin

Problem: User redirected when accessing /admin/

Solution: - Ensure Staff status checkbox is enabled - User must have is_staff=True

User Cannot Edit Records

Problem: ID numbers not clickable, no edit dialog

Solution: - Grant change_* permission for that model - Example: companies.change_companies

User Cannot See Add Button

Problem: "+ Add Company" button missing

Solution: - Grant add_* permission for that model - Example: companies.add_companies

Permission Changes Not Applying

Problem: Granted permissions but user still cannot access

Solution: - Ask user to logout and login again - Permissions are cached in session - Or restart Django development server

API Permissions

The DRF API endpoints also enforce permissions:

Viewing - Requires authentication (IsAuthenticated)
Creating - Checked via POST permission
Updating - Checked via PATCH/PUT permission
Deleting - Checked via DELETE permission

API permissions are enforced server-side in ViewSets automatically.

Advanced: Custom Permissions

If you need custom permissions beyond the default ones:

Define in Model

class Companies(BaseModel):
    class Meta:
        permissions = [
            ("approve_company", "Can approve company applications"),
            ("export_company_data", "Can export company data"),
        ]

Check in Code

if request.user.has_perm('companies.approve_company'):
    # Allow approval
    pass

Grant in Admin

Custom permissions appear in the permissions list alongside default ones.

Getting Help

Django Admin Documentation: Click Documentation link in admin header
System Issues: Contact technical support
Permission Requests: Submit via internal ticketing system

Quick Reference

Task	Permission Required
Companies
View companies	`companies.view_companies`
Add new company	`companies.add_companies`
Edit company details	`companies.change_companies`
Delete company	`companies.delete_companies`
Persons
View persons	`companies.view_persons`
Add new person	`companies.add_persons`
Edit person details	`companies.change_persons`
Delete person	`companies.delete_persons`
Projects
View projects	`projects.view_project`
Add new project	`projects.add_project`
Edit project details	`projects.change_project`
Delete project	`projects.delete_project`
Project Categories
View mappings	`projects.view_projectcategories`
Map project to category	`projects.add_projectcategories`
Edit project-category mapping	`projects.change_projectcategories`
Delete mapping	`projects.delete_projectcategories`
Questions
View questions	`questions.view_question`
Add new question	`questions.add_question`
Edit question	`questions.change_question`
Delete question	`questions.delete_question`
Question Types
View question types	`questions.view_questiontypes`
Add question type	`questions.add_questiontypes`
Edit question type	`questions.change_questiontypes`
Delete question type	`questions.delete_questiontypes`
Question Roles
View question roles	`questions.view_questionroles`
Add question role	`questions.add_questionroles`
Edit question role	`questions.change_questionroles`
Delete question role	`questions.delete_questionroles`
Question Categories
View question categories	`questions.view_questioncategories`
Add question category	`questions.add_questioncategories`
Edit question category	`questions.change_questioncategories`
Delete question category	`questions.delete_questioncategories`
Admin Access
Access Django Admin	`is_staff = True`
All permissions	`is_superuser = True`

Pre-Configured Groups Quick Reference

Group Name	Permissions	Use Case
Admin Projects	view, add, change, delete projects	Project managers, administrators
View Projects	view projects only	Read-only stakeholders
Admin Project Categories	view, add, change, delete mappings	Project administrators
View Project Categories	view mappings only	Read-only stakeholders
Admin Companies	view, add, change, delete companies	Company data managers
View Companies	view companies only	External auditors
Admin Persons	view, add, change, delete persons	HR, data entry staff
View Persons	view persons only	Reporting staff
Admin Questions	view, add, change, delete questions	Question managers
View Questions	view questions only	Read-only users
Admin Question Types	view, add, change, delete types	Question administrators
View Question Types	view types only	Read-only users
Admin Question Roles	view, add, change, delete roles	Question administrators
View Question Roles	view roles only	Read-only users
Admin Question Categories	view, add, change, delete categories	Question administrators
View Question Categories	view categories only	Read-only users

Last Updated: January 2025
Version: 2.0
Related: Permission-Based Views Guide

← Back to Home