Authentication and User Management

Author(s)

• Reshmi Karan

Last Updated Date

2024-11-14

---

SRS References

---

Version History

Version	Date	Changes	Author
1.0	2024-11-14	Initial draft	Reshmi Karan

---

Feature Overview

Objective:
The authentication service offers a secure and effective solution for user authentication and session management. It allows users to log in and out of the portal while utilizing a refresh token system for secure and uninterrupted session continuity. Also This feature is designed to establish a strong framework for managing scope-based permissions within roles, outlining scope distributions, permission control, and default fixed scopes.

The system will organize users and permissions within a structured hierarchy:

1. Headquarters: Represents the top level, containing departments.
2. Head Department: Each department is part of a headquarters.
3. Division: Contains multiple departments.
4. Department: Part of a division and can associate with multiple vendors.
5. Vendor: May supply multiple divisions, representing a many-to-many relationship.
6. Employee: Works under a specific vendor-division pair, representing a one-to-many relationship from vendor-division to employees.

Scope:
Headquarters can access all levels and associated head departments, such as Admin and IR departments. Each head department can oversee multiple divisions, and each division can contain multiple departments (e.g., Admin, IR). The IR department within a head department can only access IR departments within divisions.

Like Vendors's information can be access by head department, divisions and specific departments but are limited by vendor-specific records and designated scopes.

This feature encompasses:

1. User authentication and session management
2. Role-based access control (RBAC) for permissions and access levels
3. Scope and permission management with title, description, grouping, and sorting for each scope group
4. Default, unmodifiable scopes assigned at role creation
5. This hierarchical and scope-based approach ensures that permissions are consistently aligned with organizational structure and operational requirements.

Dependencies:

---

Requirements

1. Authentication Mechanism Implement refresh token-based authentication to ensure secure, continuous sessions without requiring repeated login.

2. Scope Management

• Multiple Scopes per Level: Allow each level (e.g., Headquarters, Head Department, Division, Department, Vendor, Employee) to have multiple scopes, with the flexibility to assign shared scopes (e.g., Vendor.view) across levels as needed.
• Department-Specific Scope Filtering: Enable specific scope assignments at the department level to restrict or filter access based on department associations. For example, a Head Admin department could have visibility limited to vendors connected only with the Division 1 Admin department, ensuring scope-based access is precise and relevant.
• Scope Details: Each scope should include a title and description to clearly communicate its purpose.
• Grouping: Organize scopes into logical groups with distinct names for improved clarity and management.
• Sorting: Implement a mechanism to order scopes within each group to streamline access and organization.

3. Role Management Dynamic Roles: Support multiple, dynamically assigned role types based on business needs. Role-Scopes Relationship: Allow each role to have multiple associated scopes (many-to-one relationship).

4. User Management User-Role Association: Maintain a one-to-one relationship between users and roles to ensure clarity in permissions and responsibilities.

---

Design Specifications

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

• UI/UX Design:
  (Include wireframes, mockups, or links to design files.)

• Data Models:

  public enum AccessType
  {
    SystemOwner = 1,
    HeadDepartment = 2,
    Division = 4,
    Department = 8,
    Vendor = 16,
    Employee = 32
  }
  public enum UserStatus
  {
    Active,
    Disabled,
    Uninitialized
  }
  public enum _OperationType
  {
    Insert,
    Update
  }
  public enum EmailType
  {
    Pass_Reset_Mail = 1
  }
  public class User
  {
    public string? FirstName { get; set; }
  
    public string? LastName { get; set; }
  
    [Required(ErrorMessage = "Password is required")]
    [DataType(DataType.Password)]
    public required string Password { get; set; } = string.Empty;
  
    [Required(ErrorMessage = "Email is required")]
    [EmailAddress]
    public required string Email { get; set; }
  
    [Phone]
    public string? Phone { get; set; }
  
    [Required(ErrorMessage = "User role is required")]
    public required Guid RoleId { get; set; }
  
    public Guid ParticipantId { get; init; }
  
    public AccessType AccessType { get; set; }
  
    public UserStatus Status { get; set; } = UserStatus.Uninitialized;
  
    [DataType(DataType.DateTime)]
    public DateTime? Created { get; set; } = DateTime.UtcNow;
  
    [DataType(DataType.DateTime)]
    public DateTime? Updated { get; set; } = DateTime.UtcNow;
  
    [System.Text.Json.Serialization.JsonIgnore]
    public int TotalNumber { get; set; }
  }
  public record LogInUser
  {
    [Required(ErrorMessage = "Username is required")]
    public required string Username { get; init; }
  
    [Required(ErrorMessage = "Password is required")]
    [DataType(DataType.Password)]
    public required string Password { get; init; }
  }
  
  public record ChangePasswordParam
  {
      public string? RequestHash { get; init; }
  
      [DataType(DataType.Password)]
      public string? OldPassword { get; init; }
  
      [Required(ErrorMessage = "New Password is required")]
      [DataType(DataType.Password)]
      public required string NewPassword { get; init; }
  }
  public record LoginAccess(string AccessToken, double ExpiresIn, string TokenType = "Bearer");
  public record Role
  {
     public Guid RoleID { get; set; }
     public required string RoleName { get; set; }
     public Guid ParticipantId { get; set; }
     public string? ParticipantName { get; set; }
     public string Description { get; set; } = string.Empty;
     public bool IsActive { get; set; }
     public AccessType AcessType { get; set; }//normal enum
  }
  public record Scope
  {
    public required string ScopeName { get; set; }
    public AccessType AccessType { get; set; }//bitmusk
    public List<DivisionDepartmentMapping>? DivisionDepartment { get; set; } // Jsonb fields can be represented as string or a  specific class if deserialized.
    public required string DisplayName { get; set; }
    public required string GroupName { get; set; }
    public int GroupSortOrder { get; set; }
  
  }
  [JsonObject(NamingStrategyType = typeof(CamelCaseNamingStrategy))]
  public record DivisionDepartmentMapping
  {
    public Guid DivisionId { get; set; }
    public string? DivisionName { get; set; }
    public Guid DepartmentId { get; set; }
    public string? DepartmentName { get; set; }
  }
  
  [JsonObject(NamingStrategyType = typeof(CamelCaseNamingStrategy))]
  public record RoleManager
  {
    public required Role Role { get; set; }
    public List<Scope> Scopes { get; set; } = new List<Scope>();
  }
  public class ResetPass : User
  {
    public string CacheKey { get; init; }
  }
   public record LoggedInSession
  {
     public Guid Id { get; init; } = Guid.NewGuid();
  
     public required string RefreshToken { get; set; }
  
     public required string Username { get; init; }
  
     public required DateTime Expires { get; init; }
  
     public DateTime Created { get; init; } = DateTime.UtcNow;
  
     public DateTime? LastUpdated { get; set; }
  
     public string? IpAddress { get; init; }
  
     public string? UserAgent { get; init; }
  
     public bool IsExpired => DateTime.UtcNow >= Expires;
  }
  public record UserRecord(string Email, Guid RoleID, AccessType LevelType, string? FirstName, string? LastName, string? Phone, UserStatus Status = UserStatus.Uninitialized)
  {
    [DataType(DataType.Password)]
    public string? Password { get; set; }
  
    [DataType(DataType.DateTime)]
    [System.Text.Json.Serialization.JsonIgnore]
    public DateTime? Created { get; set; } = DateTime.UtcNow;
  
    [DataType(DataType.DateTime)]
    [System.Text.Json.Serialization.JsonIgnore]
    public DateTime? Updated { get; set; } = DateTime.UtcNow;
  
    public Guid ConsumerId { get; init; }
  }
  public record Division
  {
     public Guid DivisionId { get; set; }
     public string DivisionCode { get; set; }
     public string DivisionName { get; set; }
     public string Type { get; set; }
     public Guid HeadQuarterId { get; set; }
     public string Name { get; set; }
     public string Email { get; set; }
     public UserStatus Status { get; set; }
     public DateTime? LogDts { get; set; }
     public string LogUserName { get; set; }
     public DateTime? CreatedAt { get; set; }
  }
  public record Department
  {
     public Guid DepartmentId { get; set; }
     public string DepartmentName { get; set; }
     public Guid DivisionId { get; set; }
     public string Type { get; set; }
     public Guid HeadDepartmentId { get; set; }
     public string Name { get; set; }
     public string Email { get; set; }
     public UserStatus Status { get; set; }
     public DateTime? LogDts { get; set; }
     public string LogUserName { get; set; }
  }
   public record SearchParam 
  {
     public Guid? ParticipantId { get; set; }
     public int PageNumber { get; set; }
     public int RowsPerPage { get; set; }
  }

• API Interfaces:

  Endpoint	Method	Parameters	Response	Response Status Codes
  /api/auth/login	POST	LogInUser	200 OK, 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 500 Internal Server Error
  /api/auth/token/refresh	GET	None	200 OK, 401 Unauthorized, 404 Not Found, 500 Internal Server Error
  /api/auth/logout	GET	None	200 OK, 401 Unauthorized, 500 Internal Server Error
  /api/user/userProfile	GET	None	User	200 OK, 401 Unauthorized, 403 Forbidden, 500 Internal Server Error
  /api/user/users	GET	None	List of User	200 OK, 401 Unauthorized, 403 Forbidden, 500 Internal Server Error
  /api/user/createorupdate	POST	[Required] OperationType, UserRecord	204 No Content, 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 409 Conflict, 500 Internal Server Error
  /api/user/delete	DELETE	None	uuid emailId uuid ParticipantId	200 OK, 401 Unauthorized, 403 Forbidden, 500 Internal Server Error
  /api/role/get/roles	GET	SearchParam	List Of RoleManager	200 OK, 401 Unauthorized, 403 Forbidden, 500 Internal Server Error
  /api/get/allscopes	GET	None	List Of Scope	200 OK, 400 Bad Request, 401 Unauthorized, 403 Forbidden, 500 Internal Server Error
  /api/auth/add/role	POST	RoleManager	200 OK, 400 Bad Request, 401 Unauthorized, 403 Forbidden, 500 Internal Server Error
  /api/auth/update/role	PUT	RoleManager	204 No Content, 400 Bad Request, 401 Unauthorized, 403 Forbidden, 500 Internal Server Error
  /api/auth/delete/role	DELETE	Guid roleId	204 No Content, 400 Bad Request, 401 Unauthorized, 403 Forbidden, 500 Internal Server Error
  /api/division	GET	None	List of Division	200 OK, 401 Unauthorized, 403 Forbidden, 500 Internal Server Error
  /api/Department	GET	None	List of Department	200 OK, 401 Unauthorized, 403 Forbidden, 500 Internal Server Error

• Third-Party Integrations:

• Workflow:

  

---

Development Tasks & Estimates

No	Task Name	Estimate (Hours)	Dependencies	Notes
1	Scope Management System with division and department	4 hours	None	Get
2	Role Management System with CRUD operation	6 hours	1	get set update delete
3	User Management System with CRUD operation	6 hours	2	get set update delete
4	Introduce Login & Logout	4 hours	1,2,3	login, logout, refreshtoken, reset password
5	Total	20 hours

---

Testing & Quality Assurance

• Unit Tests:

1. Scope Management:

• Verify retrieval of division and department data.
• Test edge cases such as empty departments or invalid division IDs.

2. Role Management:

• Test CRUD operations for roles (create, read, update, delete).
• Check for role validation, such as unique role names and required fields.

3. User Management:

• Validate CRUD operations, ensuring proper error handling and data integrity.
• Test field validations, such as email format, unique username, etc.

4. Login & Logout:

• Test login functionality with valid and invalid credentials.

• Verify refresh token generation and expiration.

• Ensure reset password functionality correctly validates and processes requests.

• Integration Tests:
  (Describe how integration testing will be conducted.)

• Acceptance Criteria:
  (Define the criteria that must be met for the feature to be considered complete.)

• Testing Tools:
  (List any tools that will be used for testing.)

---

Deployment Considerations

• Configuration Changes:

  CREATE TABLE  tblsession
  (
      id uuid NOT NULL,
      token text NOT NULL,
      username text NOT NULL,
      created TIMESTAMPTZ,
      lastupdated TIMESTAMPTZ,
      expires TIMESTAMPTZ NOT NULL,
      ipaddress text,
      useragent text,
      CONSTRAINT tblsession_pkey PRIMARY KEY (id)
  );
  CREATE TABLE tblloginhistory
  (
      username text NOT NULL,
      logintime TIMESTAMPTZ,
      logouttime TIMESTAMPTZ,
      loginip text
  );
  
  CREATE TABLE tblrole
  (
      role_id uuid NOT NULL,
      role_name character varying(255) NOT NULL,
      participant_id  uuid NOT NULL,
      description text,
      isactive boolean,
      acesstype  text,
      logdts TIMESTAMPTZ,
      logusername text,
      CONSTRAINT tblrole_pkey PRIMARY KEY (participant_id,  role_name),
      CONSTRAINT unique_role_id UNIQUE (role_id)
  );
  CREATE TABLE tblscope
  (
      scope_id uuid NOT NULL,
      scope_name character varying(255) NOT NULL,
      accesstype integer NOT NULL,
  	division_department jsonb,
  	displayname text NOT NULL,
  	groupname text NOT NULL,
  	groupsortorder integer,
  	scopesortorder integer,
      logdts TIMESTAMPTZ,
      CONSTRAINT tblscope_pkey PRIMARY KEY (scope_id),
      CONSTRAINT tblscope_scope_name_key UNIQUE (scope_name)
  );
  CREATE TABLE  tblrolepermissionmapping
  (
      role_id uuid NOT NULL,
      role_name text NOT NULL,
      scope_id uuid NOT NULL,
      scope_name text NOT NULL,
      logusername text,
      logdts TIMESTAMPTZ,
      CONSTRAINT tblrolepermissionmapping_pkey PRIMARY KEY  (role_id, scope_id),
      CONSTRAINT tblrolepermissionmapping_role_id_fkey FOREIGN  KEY (role_id)
          REFERENCES  tblrole (role_id),
      CONSTRAINT tblrolepermissionmapping_scopeid_fkey FOREIGN  KEY (scope_id)
          REFERENCES tblscope (scope_id)
  );
  CREATE TABLE  tbluser
  (
      participant_id  uuid NOT NULL,
      email text NOT NULL,
      phone text,
      password text NOT NULL,
      firstname text,
      lastname text,
      role_id uuid NOT NULL,
      created_on TIMESTAMPTZ NOT NULL,
      updated_on TIMESTAMPTZ,
      status text,
      accesstype text,
      username text,
      CONSTRAINT tbluser_email_key PRIMARY KEY (email),
      CONSTRAINT tbluser_phone_key UNIQUE (phone),
      CONSTRAINT tbluser_fkey FOREIGN KEY (role_id)
          REFERENCES tblrole (role_id)
  );
  
  CREATE Table tbldivision 
  (
      division_id uuid,
      division_code text unique,
      division_name text,
      type text,--(HQ or Division)
      hq_id uuid not null default   '00000000-0000-0000-0000-000000000000',
      name text,
      email text,
      status text,--active or disable
      logdts TIMESTAMPTZ,
      logusername TEXT,
      created_at TIMESTAMPTZ,
      CONSTRAINT tbldivision_pkey PRIMARY KEY (division_id)
  );
  
  CREATE Table tbldepartment
  (
      department_id uuid,
      department_name text,
      division_id uuid,
      type text,--head dept or dept
      headdepartment_id uuid,
      name text,
      email text,
      logdts TIMESTAMPTZ,
      logusername TEXT,
      CONSTRAINT tbldepartment_pkey PRIMARY KEY   (department_id),
      CONSTRAINT tbldepartment_divisionid_fkey FOREIGN KEY  (division_id)
          REFERENCES tbldivision (division_id)
  );
  ```sql

• Rollout Plan:

---

Risks & Mitigations

(Identify potential risks and the strategies to mitigate them.)

Risk	Impact	Likelihood	Mitigation Strategy

---

Review & Approval

(Include a section for review and approval by stakeholders.)

• Reviewer:
  Abhishak Kumar Roy

• Approval Date:
  2024-11-15

---

Notes
(Add any additional notes or considerations related to the feature development here.)