User Management System

Author(s)

• Sanket Mal
• Ayan Ghosh

Last Updated Date

2025-07-21

---

SRS References

• 2.1.2

---

Version History

Version	Date	Changes	Author
1.0	2025-07-21	Initial draft with complete features	Sanket Mal, Ayan Ghosh

---

Feature Overview

Objective:
Implement a comprehensive user management system that supports three distinct user types (Admin, Dealer, Customer) with hierarchical access control, entity-level isolation, and role-based permissions. The system ensures secure user operations while maintaining strict boundaries between different entity levels.

Scope:

1. User Types and Hierarchy:

   • Admin: Single entity with multiple roles and users
   • Dealer: Multiple entities, each with multiple roles and users
   • Customer: One entity per customer, one user per entity with a default role

2. Limitations:

   • Customers can only update and view their own details
   • Users can only manage users within their own entity
   • Customer user creation only during register
   • No cross-entity access allowed
   • Admin can create, update and view users under Admin entity
   • Any dealer can create, update and view users under that dealership
   • When dealer and admin will create any user at that time it will in PendingActivation status and that user will get a mail to change password and active user account.

Dependencies:

• JWT authentication
• Email service for notifications

---

Requirements

Functional Requirements

1. User Management

   • Create users with specified user type (Admin/Dealer/Customer)
   • Update user details within entity boundaries
   • List users with pagination and filtering
   • Disable or activate users

2. Role Management

   • Create and update roles for Admin and Dealer entities
   • Assign scopes to roles
   • List roles with pagination and filtering
   • Get role suggestions based on entity and user type

3. Scope Management

   • Get scope suggestions based on user type
   • Associate scopes with roles
   • Validate scope access for operations

4. Entity Isolation

   • Enforce entity-level access control
   • Prevent cross-entity operations
   • Validate entity context from JWT

---

Design Specifications

(Provide detailed design specifications, including UI/UX designs, API interfaces, and any other relevant architectural details.)

• UI/UX Design:

• Data Models:
  Below are the core data models that form the backbone of the user management system:

    public record RoleFilter
    {
        public required string RoleName { get; init; }
        public Guid EntityId { get; init; }
        public bool IsActive { get; init; }
        public int? RowsPerPage { get; set; }=10;
        public int? PageNumber { get; set; }=1;
    };
  
    public class ServerPaginatedData<T>
    {
        public List<T>? Data { get; set; }
        public long Totalnumber { get; set; }
    }
  
    public record UserMinimalInfo
    {
        [Required(ErrorMessage = "First name is required")]
        public required string FirstName { get; init; }
  
        [Required(ErrorMessage = "Last name is required")]
        public required string LastName { get; init; }
  
        [EmailAddress(ErrorMessage = "Invalid email address")]
        public required string Email { get; init; }
  
        [Phone(ErrorMessage = "Invalid phone number")]
        public string? Phone { get; init; }
  
        public string? Password { get; set; }
  
        public Guid? RoleId { get; set; }
    }
    public record UserFilter
    {
        public int RowsPerPage { get; set; }
        public int PageNumber { get; set; }
        public string? FirstName { get; set; }
        public string? LastName { get; set; }
        public string? Email { get; set; }
        public string? Phone { get; set; }
    }
    public record UserDetails
    {
        public required string FirstName { get; init; }
        public required string LastName { get; init; }
        public string? Email { get; init; }
        public string? Phone { get; init; }
        public DateTime CreatedAt { get; init; }
        public DateTime UpdatedAt { get; init; }
        public UserType UserType { get; init; }
        public UserStatus Status { get; init; } = UserStatus.Active;
        public string? EntityName { get; init; }
    }
    public record Scope
    {
        public Guid ScopeId { get; init; }
        public required string ScopeName { get; init; }
        public int AccessType { get; init; }
        public required string DisplayName { get; init; }
        public string? Description { get; init; }
        public required string GroupName { get; init; }
        public int GroupSortOrder { get; init; }
        public int ScopeSortOrder { get; init; }
        public string? Description {get; init; }
    }
    public record User
    {
        public Guid? UserId { get; set; }
        public string FirstName { get; set; } = string.Empty;
        public string LastName { get; set; } = string.Empty;
        public string? Email { get; set; }
        public string? Phone { get; set; }
        public string Password { get; set; } = string.Empty;
        public Guid RoleId { get; set; }
        public Guid? EntityId { get; set; }
        public UserType? UserType { get; set; }
        public UserStatus? Status { get; set; }
        public DateTime? CreatedAt { get; set; }
        public DateTime? UpdatedAt { get; set; }
    }
    public record Role
    {
        public Guid RoleId { get; init; }
        public required string RoleName { get; init; }
        public string? Description { get; init; }
        public UserType UserType { get; init; }
        public Guid EntityId { get; init; }
        public bool IsActive { get; init; }
        public string? LogUsername { get; set; }
        public DateTime LogDts { get; set; } = DateTime.UtcNow;
    }
    public enum OperationType
    {
        Create = 1,
        Update = 2
    }

• API Interfaces:
  (Define the APIs required for this feature, including endpoints, methods, request/response formats.)

  Endpoint	Method	Parameters	Response	Response Status Codes
  /api/iam/scope-suggestion	GET		List<Scope>	200, 204, 500
  /api/iam/role?operationType={operationType}	POST	RoleWithScopeIds	CommonResponse	201,200, 204, 500
  /api/iam/role	POST	RoleFilter	ServerPaginatedData<RoleDetails>	200, 204, 500
  /api/iam/role-suggestion	GET		List<Role>	200, 204, 500
  /api/iam/user?operationType={operationType}	POST	User	CommonResponse	201,200, 204, 500
  /api/iam/user	POST	UserFilter	ServerPaginatedData<UserDetails>	200, 204, 500

• Third-Party Integrations:

• Workflow:

  1. User Authentication Flow:

     • User logs in and receives JWT with userType and entityId
     • All subsequent requests include JWT for validation
     • System validates entity context and permissions

  2. Admin/Dealer User Management:

     • Create/update users within their entity
     • Manage roles and scope assignments
     • View and filter user lists

  3. Customer Self-Service:

     • Update personal profile information
     • View only own profile details

---

Development Tasks & Estimates

No	Task Name	Estimate (Hours)	Dependencies	Notes
1	Implement & Test /api/iam/scope-suggestion	4	DB Models	Get scopes based on userType
2	Implement & Test /api/iam/role?operationType={}	4	Scope Suggestion API	Create/update roles with scope assignment
3	Implement & Test /api/iam/role (List)	4	DB Models	List roles with filtering/pagination
4	Implement & Test /api/iam/role-suggestion	4	DB Models	Get roles for entity/userType
5	Implement & Test /api/iam/user?operationType={}	5	Role APIs	Create/update users with role assignment
6	Implement & Test /api/iam/user (List)	4	DB Models	List users with filtering/pagination
7	Integration Tests	4	All APIs	End-to-end testing
8	Documentation for User Management	2	All APIs	API documentation and usage guide
9	Planing for User Management	4	All APIs	Review JWT validation and permissions
Frontend
10	Implement & Test Role create & update	7
11	Implement & Test User create & update.	7
	Total	49

---

Testing & Quality Assurance

• Unit Tests:

  1. Scope Suggestion Tests:

     • Verify correct scopes returned for each user type
     • Test empty results handling
     • Test invalid user type scenarios

  2. Role Management Tests:

     • Test role creation with scopes
     • Verify role updates within entity
     • Test role listing and filtering
     • Validate role suggestions

  3. User Management Tests:

     • Test user creation with roles
     • Verify entity isolation
     • Test user listing and filtering
     • Validate customer self-update restrictions

• Integration Tests:

  1. End-to-End Flows:

     • Admin user management workflow
     • Dealer user management workflow
     • Customer self-service workflow
     • Role and scope assignment workflow

  2. Security Tests:

     • JWT validation
     • Entity isolation
     • Cross-entity access prevention
     • Permission validation

• Acceptance Criteria:

  1. User Management:

     • Users can only be created within proper entity
     • Customers can only update their own profile
     • User listing respects entity boundaries
     • Password rules are enforced

  2. Role Management:

     • Roles are properly scoped to entities
     • Scope assignments are validated
     • Role suggestions match user context

  3. Security:

     • No cross-entity access possible
     • JWT validation working
     • Proper error handling
     • Audit logging implemented

• Testing Tools:

  • xUnit for unit testing
  • Postman and Swagger for API testing

---

Deployment Considerations

• Configuration Changes:

  • Migration scripts will be added in Database Service

---

Risks & Mitigations

Risk	Impact	Likelihood	Mitigation Strategy
Cross-entity access vulnerability	High	Low	- Strict JWT validation

---

Review & Approval

• Reviewers: Abhishak Kumar Roy

• Approval Date: 2025-07-25

---

Notes