Adding a New Role to SecureHealth

This guide explains the step-by-step process for adding a new role to the SecureHealth application.

Overview

The role system in SecureHealth controls access to patient data and system features. Roles are defined in multiple places throughout the application and must be updated consistently.

Prerequisites

SecureHealth installation
Admin access to the system
Understanding of Symfony security components

Step 1: Update Security Configuration

File: config/packages/security.yaml

1.1 Add Role to Access Control

Add access control rules for your new role in the access_control section:

config/packages/security.yaml
access_control:
    # Example: Allow new role to access specific endpoints
    - { path: ^/api/patients, methods: [GET], roles: [ROLE_DOCTOR, ROLE_NURSE, ROLE_RECEPTIONIST, ROLE_NEW_ROLE] }

1.2 Update Role Hierarchy (Optional)

If your role should inherit permissions from another role, add it to the role_hierarchy section:

config/packages/security.yaml
role_hierarchy:
    ROLE_DOCTOR: [ROLE_NURSE, ROLE_RECEPTIONIST, ROLE_ADMIN]
    ROLE_NURSE: [ROLE_RECEPTIONIST]
    # Add your new role here if it should inherit permissions
    ROLE_NEW_ROLE: [ROLE_RECEPTIONIST]

Step 2: Update Patient Document

File: src/Document/Patient.php

2.1 Add Role-Based Data Access

In the toArray() method (around line 230-250), add a new conditional block for your role:

src/Document/Patient.php
// After existing role checks...
elseif (in_array('ROLE_NEW_ROLE', $roles)) {
    // Define what data this role can access
    $data['diagnosis'] = $this->getDiagnosis();
    $data['medications'] = $this->getMedications();
    // Add or remove fields based on role requirements
}

Data Access Examples

Basic info: firstName, lastName, email, phoneNumber, birthDate, createdAt
Medical data: ssn, diagnosis, medications, notes, notesHistory
Administrative: insuranceDetails, primaryDoctorId

Step 3: Update Security Voter

File: src/Security/Voter/PatientVoter.php

3.1 Add Role to Permission Checks

Update the checkPermission() method to include your new role in permission checks:

src/Security/Voter/PatientVoter.php
case self::VIEW:
    // Add your role to appropriate permission checks
    return in_array('ROLE_DOCTOR', $roles) || 
           in_array('ROLE_NURSE', $roles) || 
           in_array('ROLE_RECEPTIONIST', $roles) ||
           in_array('ROLE_NEW_ROLE', $roles);

case self::VIEW_DIAGNOSIS:
case self::VIEW_MEDICATIONS:
    // Control medical data access
    return in_array('ROLE_DOCTOR', $roles) || 
           in_array('ROLE_NURSE', $roles) ||
           in_array('ROLE_NEW_ROLE', $roles);

Available Permission Constants

PATIENT_VIEW - View basic patient info
PATIENT_CREATE - Create new patients
PATIENT_EDIT - Edit patient records
PATIENT_DELETE - Delete patients
PATIENT_VIEW_DIAGNOSIS - View diagnosis
PATIENT_EDIT_DIAGNOSIS - Edit diagnosis
PATIENT_VIEW_MEDICATIONS - View medications
PATIENT_EDIT_MEDICATIONS - Edit medications
PATIENT_VIEW_SSN - View SSN
PATIENT_VIEW_INSURANCE - View insurance
PATIENT_EDIT_INSURANCE - Edit insurance
PATIENT_VIEW_NOTES - View notes
PATIENT_EDIT_NOTES - Edit notes
PATIENT_ADD_NOTE - Add new notes
PATIENT_UPDATE_NOTE - Update notes
PATIENT_DELETE_NOTE - Delete notes

Step 4: Update PatientController Serialization

File: src/Controller/Api/PatientController.php

Add your new role to the role detection logic (around line 75-88):

src/Controller/Api/PatientController.php
if ($user) {
    $userRoles = $user->getRoles();
    if (in_array('ROLE_DOCTOR', $userRoles)) {
        $userRole = 'ROLE_DOCTOR';
    } elseif (in_array('ROLE_NURSE', $userRoles)) {
        $userRole = 'ROLE_NURSE';
    } elseif (in_array('ROLE_ADMIN', $userRoles)) {
        $userRole = 'ROLE_ADMIN';
    } elseif (in_array('ROLE_RECEPTIONIST', $userRoles)) {
        $userRole = 'ROLE_RECEPTIONIST';
    } elseif (in_array('ROLE_NEW_ROLE', $userRoles)) {
        $userRole = 'ROLE_NEW_ROLE';
    }
}

Important

Repeat this pattern in all methods that serialize patient data: index(), show(), create(), update().

Step 5: Create Default User (Optional)

File: src/Command/CreateUsersCommand.php

Add a default user for the new role in the $users array (around line 46-72):

src/Command/CreateUsersCommand.php
$users = [
    // ... existing users ...
    [
        'email' => 'newrole@example.com',
        'username' => 'New Role User',
        'password' => 'password',
        'roles' => ['ROLE_NEW_ROLE']
    ]
];

Run the command to create the user:

php bin/console app:create-users --force

Step 6: Update Frontend (Optional)

If your new role needs specific UI features:

File: public/assets/js/navbar.js

Add role-specific navigation items based on the user's role.

6.2 Update Role Documentation

File: public/role-documentation.html

Add documentation for the new role's capabilities and responsibilities.

Key Principles

Security Principles

Least Privilege: Only grant access to data that the role needs to perform its duties
Data Segregation: Medical data (diagnosis, medications, notes) should be separate from administrative data (insurance, demographics)
Consistency: Update all relevant files to maintain system integrity
Testing: Test the new role with sample users to ensure proper access control

Example: Adding ROLE_PHARMACIST

A pharmacist role that can view medications and allergies but not full diagnosis:

Example Implementation
// 1. security.yaml: Add to access control for medication endpoints
// 2. Patient.php: 
elseif (in_array('ROLE_PHARMACIST', $roles)) {
    $data['medications'] = $this->getMedications();
    $data['diagnosis'] = $this->getDiagnosis(); // Limited view
}
// 3. PatientVoter.php: Add to VIEW_MEDICATIONS permission
// 4. PatientController.php: Add to role detection chain
// 5. CreateUsersCommand.php: Add default pharmacist user

Testing Checklist

:::checklist Testing Requirements

User can log in with new role
User can access permitted endpoints
User is denied access to restricted data
Role hierarchy works correctly (if applicable)
Audit logs record the role's actions
Frontend displays appropriate UI for the role :::

Additional Files to Consider

When adding a new role, you may also need to update:

Controllers

src/Controller/Api/DashboardController.php - Add role-specific dashboard data
src/Controller/Api/AuditLogController.php - Control audit log access
src/Controller/Api/AppointmentController.php - Appointment management permissions

Services

src/Service/PatientVerificationService.php - Role-based verification requirements
src/Service/RAGChatbotService.php - AI chatbot access control

Tests

tests/Security/Voter/PatientVoterTest.php - Add tests for new role permissions
tests/Integration/ - Integration tests for role-specific workflows

Frontend

public/assets/js/dashboard.js - Dashboard functionality for the role
public/assets/js/navbar.js - Navigation menu items
public/patients.html - Patient management interface
public/role-documentation.html - Role-specific documentation

Security Considerations

Security Requirements

Always follow the principle of least privilege
Test thoroughly with sample users
Ensure audit logging captures all role-based actions
Consider HIPAA compliance implications for each role
Document the role's purpose and data access requirements
Review and update access controls regularly

Common Pitfalls

Common Mistakes

Forgetting to update all relevant files - The role system spans multiple files
Inconsistent permission logic - Ensure voter and controller logic match
Missing frontend updates - UI should reflect role capabilities
Inadequate testing - Test both positive and negative access scenarios
Poor documentation - Document what each role can and cannot do

Overview​

Step 1: Update Security Configuration​

1.1 Add Role to Access Control​

1.2 Update Role Hierarchy (Optional)​

Step 2: Update Patient Document​

2.1 Add Role-Based Data Access​

Step 3: Update Security Voter​

3.1 Add Role to Permission Checks​

Step 4: Update PatientController Serialization​

Step 5: Create Default User (Optional)​

Step 6: Update Frontend (Optional)​

6.1 Update Navigation​

6.2 Update Role Documentation​

Key Principles​

Example: Adding ROLE_PHARMACIST​

Testing Checklist​

Additional Files to Consider​

Controllers​

Services​

Tests​

Frontend​

Security Considerations​

Common Pitfalls​