Expertiza_Wiki - User contributions [en]

CSC/ECE 517 Fall 2024 - E2487. Reimplement authorization helper.rb

2024-12-03T22:25:49Z

Agupta85: /* Outcomes */

== Introduction ==
Expertiza currently uses session-based authentication in its AuthorizationHelper module. However, the new back-end reimplementation adopts JSON Web Token (JWT) for authentication. This transition is necessary to make the system more scalable, stateless, and secure. JWT-based authentication will replace session-based methods, requiring updates to the AuthorizationHelper module and associated methods.

== Background ==
The AuthorizationHelper module in Expertiza plays a critical role in managing user permissions and access control within the system. It provides methods to verify a user’s privileges based on their assigned roles, such as Super-Admin, Admin, Instructor, TA, or Student. These methods check if the user is authorized to perform actions like submitting assignments, reviewing work, or participating in quizzes. Additionally, it determines whether a user is involved in specific assignments, either as a participant, instructor, or through TA mappings.

==Problem Statement==

Expertiza currently uses session-based authentication in its [[https://github.com/expertiza/expertiza/blob/main/app/helpers/authorization_helper.rb AuthorizationHelper]] module. The [[https://github.com/expertiza/reimplementation-back-end reimplementation-back-end]] however, uses JWT (JSON Web Token) based authentication. This requires a reimplementation of an authorization concern module to accommodate JWT-based authentication

===Concerns===

A concern is a module that you extract to split the implementation of a class or module in coherent chunks, instead of having one big class body. Our new authorization module will be implemented as a concern which will work in tandem with the already-implemented [[https://github.com/expertiza/reimplementation-back-end/blob/main/app/controllers/concerns/jwt_token.rb JWT Concern]]

The following points need to be taken care of as per the requirement

* Role Management :
** Enable the system to process, verify, and decode roles from JWT Tokens.
** Use token role data to authenticate and authorize user actions.

* Privilege Verification :
** Update methods to validate user privileges using JWT claims.

* Testing and Documentation :
** Write comprehensive unit tests for all JWT-related methods.
** Include clear documentation and comments to aid future developers.

=Implemented Changes=

== JWT Token Overview ==

A JSON Web Token (JWT) is a compact, URL-safe token format commonly used for securely transmitting information between parties. It is widely used in web applications for authentication and authorization, as it allows information to be verified and trusted. In the context of our reimplemented AuthorizationHelper module, JWT tokens will replace session-based authentication, enabling stateless and more secure access control.

A JWT Token consists of three main parts:

*Header: Contains metadata about the token, such as the type (JWT) and the hashing algorithm used (e.g., HS256 or RS256).
*Payload: Includes claims, which are statements about an entity (typically, the user) and additional data like the user’s role and permissions.
*Signature: A cryptographic signature generated by encoding the header and payload with a secret key or private key, ensuring data integrity.
These three sections are separated by dots (.), forming a token that looks like this: <Header>.<Payload>.<Signature>

[[File:JWT-Workflow.png|500px|center]]

==Overall Flow==

[[File:Authorization_flow.png|500px|center]]

==Methods Implemented==

* has_required_role?(required_role):

<pre>

def has_required_role?(required_role)
required_role = Role.find_by_name(required_role) if required_role.is_a?(String)
current_user&.role&.all_privileges_of?(required_role) || false
end

</pre>

This function checks if the current user has the required role or higher privileges. The role name is passed down as a parameter in required_role which is the minimum required role level for an action

For example:

<pre>has_required_role?('Administrator') # Checks if user is an admin or higher</pre>

<pre>has_required_role?(Role::INSTRUCTOR) # Checks if user is an instructor or higher</pre>

For exact role requirements, we also have:
* is_role?(required_role):

<pre>

def is_role?(required_role)
required_role = required_role.name if required_role.is_a?(Role)
current_user&.role&.name == required_role
end

</pre>

which checks if the user has exactly the specified role. For example:

<pre>is_role?('Student') # True only if user is exactly a student </pre>

Finally, we have authorization methods which work with the ApplicationController as well as individual resource controllers:

<pre>
# Authorize all actions
def authorize
unless all_actions_allowed?
render json: {
error: "You are not authorized to #{params[:action]} this #{params[:controller]}"
}, status: :forbidden
end
end

# Check if all actions are allowed
def all_actions_allowed?
return true if has_required_role?('Administrator')
action_allowed?
end

# Base action_allowed? - allows everything by default
# Controllers should override this method to implement their authorization logic
def action_allowed?
true
end
</pre>

The individual resource controllers can then override the method 'action_allowed?' to manage access. For example:

<pre>
def action_allowed?
has_required_role?('Instructor')
end
</pre>

==Existing File Updates==

* [[https://github.com/expertiza/reimplementation-back-end/blob/main/app/controllers/application_controller.rb application_controller.rb]]

This file was updated to include the new authorization module

<pre>
class ApplicationController < ActionController::API
include Authorization
include JwtToken

before_action :authorize
end
</pre>

This ensures that the [[https://github.com/rarchitgupta/reimplementation-back-end/blob/jwt_authorization/app/controllers/concerns/authorization.rb 'has_required_role?']] method is available globally along with [[https://github.com/rarchitgupta/reimplementation-back-end/blob/jwt_authorization/app/controllers/concerns/authorization.rb 'is_role?']]. These methods can then be used to override 'action_allowed?' to override the base implementation and provide more granular control

* [[https://github.com/rarchitgupta/reimplementation-back-end/blob/jwt_authorization/app/controllers/api/v1/courses_controller.rb courses_controller.rb]]

To test the functionality, based on the old Expertiza, the method was also overridden in the courses_controller.rb file:

<pre>
class Api::V1::CoursesController < ApplicationController
before_action :set_course, only: %i[ show update destroy add_ta view_tas remove_ta copy ]
rescue_from ActiveRecord::RecordNotFound, with: :course_not_found
rescue_from ActionController::ParameterMissing, with: :parameter_missing

def action_allowed?
has_required_role?('Instructor')
end

...
</pre>

==Outcomes==
1. '''Modular Authentication and Authorization System'''
* Separate JwtToken and Authorization concerns with distinct responsibilities
* Integration through ApplicationController middleware
* Flexible role-based access control per controller
* Clean separation between authentication and authorization components
* Independent scaling and maintenance capability
2. '''Role-Based Access Control (RBAC)'''
* Hierarchical role system with administrator override
* Controller-specific role requirements through action-specific checks
* Granular permission control at the action level
* Fine-grained access control while maintaining system flexibility
* Custom role requirements for different resources
3. '''Secure Authentication Flow'''
* JWT-based stateless authentication
* Token verification precedes protected actions
* Automatic current user loading from verified tokens
* Protection against unauthorized access and token tampering
* Maintains stateless architecture for scalability
4. '''Standardized Error Handling'''
* Consistent HTTP status codes (401 for authentication, 403 for authorization)
* Clear error messages for debugging
* Uniform error response format across the application
* Improved debugging experience
* Standardized client-side error handling
4. '''Developer-Friendly Design'''
* Rails conventions and idioms throughout
* Clear, purpose-indicating method names
* Modular design with extension points
* Reduced learning curve for new developers
* Minimal configuration required for new controllers

== Design Principles ==
The redesign of the `AuthorizationHelper` module for JWT-based authentication will follow well-established design principles to ensure the solution is secure, maintainable, and scalable. Below are the key principles to be applied and how they will shape this redesign:

1. '''Single Responsibility Principle (SRP)'''
* '''Definition''': Each module or class should have one clear responsibility.
* '''Implementation''':
** JwtToken concern handles only authentication
** Authorization concern manages only authorization rules
* '''Benefit''': Changes to authentication logic don't affect authorization rules and vice versa

2. '''Open / Closed Principle'''
* '''Definition''': Software entities should be open for extension but closed for modification
* '''Implementation''':
<pre>
# Base authorization in Authorization concern
def action_allowed?
true # Base implementation
end

# Extended in CoursesController without modifying base
def action_allowed?
has_required_role?('Instructor')
end
</pre>

* '''Benefit''': New controllers can implement their own authorization rules without changing existing code

3. '''Inheritance and Polymorphism'''
* '''Definition''': Ability to present the same interface for different underlying forms (implementations)
* '''Implementation''':
** All controllers inherit from ApplicationController
** Each can override action_allowed? with its implementation
** System treats all action_allowed? calls polymorphically

* '''Benefit''': Consistent interface while allowing specialized behavior

4. '''Composition'''
* '''Implementation''':
<pre>
class ApplicationController < ActionController::API
include Authorization # Composition through modules
include JwtToken
end
</pre>

* '''Benefit''': More flexible than deep inheritance hierarchies, allows mixing in different behaviors

5. '''Don't Repeat Yourself (DRY)'''
* '''Definition''': Every piece of knowledge should have a single, unambiguous representation
* '''Implementation''':
** Common authentication logic in JwtToken
** Shared authorization behavior in Authorization
** Base controller provides default implementations

* '''Benefit''': Reduces code duplication and maintenance overhead

== Test Plan ==

=== Unit Tests ===
'''Definition''': Unit tests verify that individual methods work correctly in isolation under different scenarios.

==== Tests for jwt_verify_and_decode ====
'''Valid Token Test:'''
* '''Input''': A valid JWT token with claims like `id`, `role`, and `exp`.
* '''Expected Output''': Decoded payload as a `HashWithIndifferentAccess`.
* '''Validation''': Ensure the returned payload matches the expected data.

'''Expired Token Test:'''
* '''Input''': A token with an `exp` claim that has already passed.
* '''Expected Output''': `nil` with an appropriate error logged.
* '''Validation''': Confirm that the method gracefully handles expired tokens.

'''Invalid Token Test:'''
* '''Input''': A tampered JWT token with an invalid signature.
* '''Expected Output''': `nil`.
* '''Validation''': Ensure an appropriate error message is logged, and sensitive information is not exposed.

'''Missing Claims Test:'''
* '''Input''': A valid token missing critical claims like `role`.
* '''Expected Output''': `nil`.
* '''Validation''': Ensure the method flags the token as invalid due to missing data.

==== Tests for check_user_privileges ====
'''Sufficient Privileges Test:'''
* '''Input''': User info with `role` as `Admin` and a `required_privilege` of `Student`.
* '''Expected Output''': `true`.
* '''Validation''': Verify the method correctly interprets hierarchical roles.

'''Insufficient Privileges Test:'''
* '''Input''': User info with `role` as `Student` and a `required_privilege` of `Instructor`.
* '''Expected Output''': `false`.
* '''Validation''': Ensure the method denies access for insufficient privileges.

'''Missing Role Test:'''
* '''Input''': User info without a `role` claim.
* '''Expected Output''': `false`.
* '''Validation''': Ensure the method handles missing roles gracefully.

==== Tests for current_user_is_a? ====
'''Correct Role Test:'''
* '''Input''': Token with `role` as `Instructor` and `role_name` as `Instructor`.
* '''Expected Output''': `true`.
* '''Validation''': Verify the method returns `true` when roles match exactly.

'''Incorrect Role Test:'''
* '''Input''': Token with `role` as `TA` and `role_name` as `Instructor`.
* '''Expected Output''': `false`.
* '''Validation''': Ensure the method denies access when roles don’t match.

'''Missing Token Test:'''
* '''Input''': `nil` token.
* '''Expected Output''': `false`.
* '''Validation''': Confirm that the method handles missing tokens properly.

---

=== Integration Tests ===
'''Definition''': Integration tests validate that the `AuthorizationHelper` module functions correctly within the context of the overall system.

==== Approach Options ====
1. '''Creating a Dummy API''':
* A lightweight API will be created specifically for testing the `AuthorizationHelper` methods.
* This API will simulate requests requiring token authentication and privilege checks.
* '''Advantages''':
** Fully isolated testing environment.
** Flexibility to simulate different roles, tokens, and scenarios.
* '''Disadvantages''':
** Requires additional setup and may not reflect real-world behavior perfectly.

2. '''Implementing a New Controller in Expertiza''':
* A controller will be added to the existing Expertiza application that uses the refactored `AuthorizationHelper`.
* This ensures that tests occur in a real-world context, validating interactions with the actual system.
* '''Advantages''':
** Validates the actual behavior of the module within the system.
** Reflects real application workflows and edge cases.
* '''Disadvantages''':
** Potentially affects other parts of the application during testing.
** Requires effort to ensure test isolation.

==== Integration Test Cases ====
'''API Endpoint Authentication'''
* '''Valid Token Test''':
** '''Scenario''': Send a valid JWT token to a protected endpoint.
** '''Expected Outcome''': HTTP 200 OK with access granted.
** '''Validation''': Confirm the user is authenticated and receives the correct resource.

* '''Expired Token Test''':
** '''Scenario''': Send an expired JWT token to a protected endpoint.
** '''Expected Outcome''': HTTP 401 Unauthorized.
** '''Validation''': Ensure the system blocks access and provides a proper error message.

* '''Tampered Token Test''':
** '''Scenario''': Send a tampered token with an invalid signature.
** '''Expected Outcome''': HTTP 401 Unauthorized.
** '''Validation''': Confirm the system denies access and logs the attempt securely.

* '''Missing Token Test''':
** '''Scenario''': Make a request without providing a token.
** '''Expected Outcome''': HTTP 401 Unauthorized.
** '''Validation''': Verify that token authentication is strictly enforced.

== Team ==
===Mentor===
*Kashika Mallick (kmallick@ncsu.edu)

===Members===
*Shafa Hassan (shassa22@ncsu.edu)
*Archit Gupta (agupta85@ncsu.edu)
*Ansh Ganatra (aganatr@ncsu.edu)

CSC/ECE 517 Fall 2024 - E2487. Reimplement authorization helper.rb

2024-12-03T22:25:38Z

Agupta85: /* Anticipated Outcomes */

== Introduction ==
Expertiza currently uses session-based authentication in its AuthorizationHelper module. However, the new back-end reimplementation adopts JSON Web Token (JWT) for authentication. This transition is necessary to make the system more scalable, stateless, and secure. JWT-based authentication will replace session-based methods, requiring updates to the AuthorizationHelper module and associated methods.

== Background ==
The AuthorizationHelper module in Expertiza plays a critical role in managing user permissions and access control within the system. It provides methods to verify a user’s privileges based on their assigned roles, such as Super-Admin, Admin, Instructor, TA, or Student. These methods check if the user is authorized to perform actions like submitting assignments, reviewing work, or participating in quizzes. Additionally, it determines whether a user is involved in specific assignments, either as a participant, instructor, or through TA mappings.

==Problem Statement==

Expertiza currently uses session-based authentication in its [[https://github.com/expertiza/expertiza/blob/main/app/helpers/authorization_helper.rb AuthorizationHelper]] module. The [[https://github.com/expertiza/reimplementation-back-end reimplementation-back-end]] however, uses JWT (JSON Web Token) based authentication. This requires a reimplementation of an authorization concern module to accommodate JWT-based authentication

===Concerns===

A concern is a module that you extract to split the implementation of a class or module in coherent chunks, instead of having one big class body. Our new authorization module will be implemented as a concern which will work in tandem with the already-implemented [[https://github.com/expertiza/reimplementation-back-end/blob/main/app/controllers/concerns/jwt_token.rb JWT Concern]]

The following points need to be taken care of as per the requirement

* Role Management :
** Enable the system to process, verify, and decode roles from JWT Tokens.
** Use token role data to authenticate and authorize user actions.

* Privilege Verification :
** Update methods to validate user privileges using JWT claims.

* Testing and Documentation :
** Write comprehensive unit tests for all JWT-related methods.
** Include clear documentation and comments to aid future developers.

=Implemented Changes=

== JWT Token Overview ==

A JSON Web Token (JWT) is a compact, URL-safe token format commonly used for securely transmitting information between parties. It is widely used in web applications for authentication and authorization, as it allows information to be verified and trusted. In the context of our reimplemented AuthorizationHelper module, JWT tokens will replace session-based authentication, enabling stateless and more secure access control.

A JWT Token consists of three main parts:

*Header: Contains metadata about the token, such as the type (JWT) and the hashing algorithm used (e.g., HS256 or RS256).
*Payload: Includes claims, which are statements about an entity (typically, the user) and additional data like the user’s role and permissions.
*Signature: A cryptographic signature generated by encoding the header and payload with a secret key or private key, ensuring data integrity.
These three sections are separated by dots (.), forming a token that looks like this: <Header>.<Payload>.<Signature>

[[File:JWT-Workflow.png|500px|center]]

==Overall Flow==

[[File:Authorization_flow.png|500px|center]]

==Methods Implemented==

* has_required_role?(required_role):

<pre>

def has_required_role?(required_role)
required_role = Role.find_by_name(required_role) if required_role.is_a?(String)
current_user&.role&.all_privileges_of?(required_role) || false
end

</pre>

This function checks if the current user has the required role or higher privileges. The role name is passed down as a parameter in required_role which is the minimum required role level for an action

For example:

<pre>has_required_role?('Administrator') # Checks if user is an admin or higher</pre>

<pre>has_required_role?(Role::INSTRUCTOR) # Checks if user is an instructor or higher</pre>

For exact role requirements, we also have:
* is_role?(required_role):

<pre>

def is_role?(required_role)
required_role = required_role.name if required_role.is_a?(Role)
current_user&.role&.name == required_role
end

</pre>

which checks if the user has exactly the specified role. For example:

<pre>is_role?('Student') # True only if user is exactly a student </pre>

Finally, we have authorization methods which work with the ApplicationController as well as individual resource controllers:

<pre>
# Authorize all actions
def authorize
unless all_actions_allowed?
render json: {
error: "You are not authorized to #{params[:action]} this #{params[:controller]}"
}, status: :forbidden
end
end

# Check if all actions are allowed
def all_actions_allowed?
return true if has_required_role?('Administrator')
action_allowed?
end

# Base action_allowed? - allows everything by default
# Controllers should override this method to implement their authorization logic
def action_allowed?
true
end
</pre>

The individual resource controllers can then override the method 'action_allowed?' to manage access. For example:

<pre>
def action_allowed?
has_required_role?('Instructor')
end
</pre>

==Existing File Updates==

* [[https://github.com/expertiza/reimplementation-back-end/blob/main/app/controllers/application_controller.rb application_controller.rb]]

This file was updated to include the new authorization module

<pre>
class ApplicationController < ActionController::API
include Authorization
include JwtToken

before_action :authorize
end
</pre>

This ensures that the [[https://github.com/rarchitgupta/reimplementation-back-end/blob/jwt_authorization/app/controllers/concerns/authorization.rb 'has_required_role?']] method is available globally along with [[https://github.com/rarchitgupta/reimplementation-back-end/blob/jwt_authorization/app/controllers/concerns/authorization.rb 'is_role?']]. These methods can then be used to override 'action_allowed?' to override the base implementation and provide more granular control

* [[https://github.com/rarchitgupta/reimplementation-back-end/blob/jwt_authorization/app/controllers/api/v1/courses_controller.rb courses_controller.rb]]

To test the functionality, based on the old Expertiza, the method was also overridden in the courses_controller.rb file:

<pre>
class Api::V1::CoursesController < ApplicationController
before_action :set_course, only: %i[ show update destroy add_ta view_tas remove_ta copy ]
rescue_from ActiveRecord::RecordNotFound, with: :course_not_found
rescue_from ActionController::ParameterMissing, with: :parameter_missing

def action_allowed?
has_required_role?('Instructor')
end

...
</pre>

==Anticipated Outcomes==
1. '''Modular Authentication and Authorization System'''
* Separate JwtToken and Authorization concerns with distinct responsibilities
* Integration through ApplicationController middleware
* Flexible role-based access control per controller
* Clean separation between authentication and authorization components
* Independent scaling and maintenance capability
2. '''Role-Based Access Control (RBAC)'''
* Hierarchical role system with administrator override
* Controller-specific role requirements through action-specific checks
* Granular permission control at the action level
* Fine-grained access control while maintaining system flexibility
* Custom role requirements for different resources
3. '''Secure Authentication Flow'''
* JWT-based stateless authentication
* Token verification precedes protected actions
* Automatic current user loading from verified tokens
* Protection against unauthorized access and token tampering
* Maintains stateless architecture for scalability
4. '''Standardized Error Handling'''
* Consistent HTTP status codes (401 for authentication, 403 for authorization)
* Clear error messages for debugging
* Uniform error response format across the application
* Improved debugging experience
* Standardized client-side error handling
4. '''Developer-Friendly Design'''
* Rails conventions and idioms throughout
* Clear, purpose-indicating method names
* Modular design with extension points
* Reduced learning curve for new developers
* Minimal configuration required for new controllers

== Design Principles ==
The redesign of the `AuthorizationHelper` module for JWT-based authentication will follow well-established design principles to ensure the solution is secure, maintainable, and scalable. Below are the key principles to be applied and how they will shape this redesign:

1. '''Single Responsibility Principle (SRP)'''
* '''Definition''': Each module or class should have one clear responsibility.
* '''Implementation''':
** JwtToken concern handles only authentication
** Authorization concern manages only authorization rules
* '''Benefit''': Changes to authentication logic don't affect authorization rules and vice versa

2. '''Open / Closed Principle'''
* '''Definition''': Software entities should be open for extension but closed for modification
* '''Implementation''':
<pre>
# Base authorization in Authorization concern
def action_allowed?
true # Base implementation
end

# Extended in CoursesController without modifying base
def action_allowed?
has_required_role?('Instructor')
end
</pre>

* '''Benefit''': New controllers can implement their own authorization rules without changing existing code

3. '''Inheritance and Polymorphism'''
* '''Definition''': Ability to present the same interface for different underlying forms (implementations)
* '''Implementation''':
** All controllers inherit from ApplicationController
** Each can override action_allowed? with its implementation
** System treats all action_allowed? calls polymorphically

* '''Benefit''': Consistent interface while allowing specialized behavior

4. '''Composition'''
* '''Implementation''':
<pre>
class ApplicationController < ActionController::API
include Authorization # Composition through modules
include JwtToken
end
</pre>

* '''Benefit''': More flexible than deep inheritance hierarchies, allows mixing in different behaviors

5. '''Don't Repeat Yourself (DRY)'''
* '''Definition''': Every piece of knowledge should have a single, unambiguous representation
* '''Implementation''':
** Common authentication logic in JwtToken
** Shared authorization behavior in Authorization
** Base controller provides default implementations

* '''Benefit''': Reduces code duplication and maintenance overhead

== Test Plan ==

=== Unit Tests ===
'''Definition''': Unit tests verify that individual methods work correctly in isolation under different scenarios.

==== Tests for jwt_verify_and_decode ====
'''Valid Token Test:'''
* '''Input''': A valid JWT token with claims like `id`, `role`, and `exp`.
* '''Expected Output''': Decoded payload as a `HashWithIndifferentAccess`.
* '''Validation''': Ensure the returned payload matches the expected data.

'''Expired Token Test:'''
* '''Input''': A token with an `exp` claim that has already passed.
* '''Expected Output''': `nil` with an appropriate error logged.
* '''Validation''': Confirm that the method gracefully handles expired tokens.

'''Invalid Token Test:'''
* '''Input''': A tampered JWT token with an invalid signature.
* '''Expected Output''': `nil`.
* '''Validation''': Ensure an appropriate error message is logged, and sensitive information is not exposed.

'''Missing Claims Test:'''
* '''Input''': A valid token missing critical claims like `role`.
* '''Expected Output''': `nil`.
* '''Validation''': Ensure the method flags the token as invalid due to missing data.

==== Tests for check_user_privileges ====
'''Sufficient Privileges Test:'''
* '''Input''': User info with `role` as `Admin` and a `required_privilege` of `Student`.
* '''Expected Output''': `true`.
* '''Validation''': Verify the method correctly interprets hierarchical roles.

'''Insufficient Privileges Test:'''
* '''Input''': User info with `role` as `Student` and a `required_privilege` of `Instructor`.
* '''Expected Output''': `false`.
* '''Validation''': Ensure the method denies access for insufficient privileges.

'''Missing Role Test:'''
* '''Input''': User info without a `role` claim.
* '''Expected Output''': `false`.
* '''Validation''': Ensure the method handles missing roles gracefully.

==== Tests for current_user_is_a? ====
'''Correct Role Test:'''
* '''Input''': Token with `role` as `Instructor` and `role_name` as `Instructor`.
* '''Expected Output''': `true`.
* '''Validation''': Verify the method returns `true` when roles match exactly.

'''Incorrect Role Test:'''
* '''Input''': Token with `role` as `TA` and `role_name` as `Instructor`.
* '''Expected Output''': `false`.
* '''Validation''': Ensure the method denies access when roles don’t match.

'''Missing Token Test:'''
* '''Input''': `nil` token.
* '''Expected Output''': `false`.
* '''Validation''': Confirm that the method handles missing tokens properly.

---

=== Integration Tests ===
'''Definition''': Integration tests validate that the `AuthorizationHelper` module functions correctly within the context of the overall system.

==== Approach Options ====
1. '''Creating a Dummy API''':
* A lightweight API will be created specifically for testing the `AuthorizationHelper` methods.
* This API will simulate requests requiring token authentication and privilege checks.
* '''Advantages''':
** Fully isolated testing environment.
** Flexibility to simulate different roles, tokens, and scenarios.
* '''Disadvantages''':
** Requires additional setup and may not reflect real-world behavior perfectly.

2. '''Implementing a New Controller in Expertiza''':
* A controller will be added to the existing Expertiza application that uses the refactored `AuthorizationHelper`.
* This ensures that tests occur in a real-world context, validating interactions with the actual system.
* '''Advantages''':
** Validates the actual behavior of the module within the system.
** Reflects real application workflows and edge cases.
* '''Disadvantages''':
** Potentially affects other parts of the application during testing.
** Requires effort to ensure test isolation.

==== Integration Test Cases ====
'''API Endpoint Authentication'''
* '''Valid Token Test''':
** '''Scenario''': Send a valid JWT token to a protected endpoint.
** '''Expected Outcome''': HTTP 200 OK with access granted.
** '''Validation''': Confirm the user is authenticated and receives the correct resource.

* '''Expired Token Test''':
** '''Scenario''': Send an expired JWT token to a protected endpoint.
** '''Expected Outcome''': HTTP 401 Unauthorized.
** '''Validation''': Ensure the system blocks access and provides a proper error message.

* '''Tampered Token Test''':
** '''Scenario''': Send a tampered token with an invalid signature.
** '''Expected Outcome''': HTTP 401 Unauthorized.
** '''Validation''': Confirm the system denies access and logs the attempt securely.

* '''Missing Token Test''':
** '''Scenario''': Make a request without providing a token.
** '''Expected Outcome''': HTTP 401 Unauthorized.
** '''Validation''': Verify that token authentication is strictly enforced.

== Team ==
===Mentor===
*Kashika Mallick (kmallick@ncsu.edu)

===Members===
*Shafa Hassan (shassa22@ncsu.edu)
*Archit Gupta (agupta85@ncsu.edu)
*Ansh Ganatra (aganatr@ncsu.edu)

CSC/ECE 517 Fall 2024 - E2487. Reimplement authorization helper.rb

2024-12-03T22:17:38Z

Agupta85: /* Design Principles */

== Introduction ==
Expertiza currently uses session-based authentication in its AuthorizationHelper module. However, the new back-end reimplementation adopts JSON Web Token (JWT) for authentication. This transition is necessary to make the system more scalable, stateless, and secure. JWT-based authentication will replace session-based methods, requiring updates to the AuthorizationHelper module and associated methods.

== Background ==
The AuthorizationHelper module in Expertiza plays a critical role in managing user permissions and access control within the system. It provides methods to verify a user’s privileges based on their assigned roles, such as Super-Admin, Admin, Instructor, TA, or Student. These methods check if the user is authorized to perform actions like submitting assignments, reviewing work, or participating in quizzes. Additionally, it determines whether a user is involved in specific assignments, either as a participant, instructor, or through TA mappings.

==Problem Statement==

Expertiza currently uses session-based authentication in its [[https://github.com/expertiza/expertiza/blob/main/app/helpers/authorization_helper.rb AuthorizationHelper]] module. The [[https://github.com/expertiza/reimplementation-back-end reimplementation-back-end]] however, uses JWT (JSON Web Token) based authentication. This requires a reimplementation of an authorization concern module to accommodate JWT-based authentication

===Concerns===

A concern is a module that you extract to split the implementation of a class or module in coherent chunks, instead of having one big class body. Our new authorization module will be implemented as a concern which will work in tandem with the already-implemented [[https://github.com/expertiza/reimplementation-back-end/blob/main/app/controllers/concerns/jwt_token.rb JWT Concern]]

The following points need to be taken care of as per the requirement

* Role Management :
** Enable the system to process, verify, and decode roles from JWT Tokens.
** Use token role data to authenticate and authorize user actions.

* Privilege Verification :
** Update methods to validate user privileges using JWT claims.

* Testing and Documentation :
** Write comprehensive unit tests for all JWT-related methods.
** Include clear documentation and comments to aid future developers.

=Implemented Changes=

== JWT Token Overview ==

A JSON Web Token (JWT) is a compact, URL-safe token format commonly used for securely transmitting information between parties. It is widely used in web applications for authentication and authorization, as it allows information to be verified and trusted. In the context of our reimplemented AuthorizationHelper module, JWT tokens will replace session-based authentication, enabling stateless and more secure access control.

A JWT Token consists of three main parts:

*Header: Contains metadata about the token, such as the type (JWT) and the hashing algorithm used (e.g., HS256 or RS256).
*Payload: Includes claims, which are statements about an entity (typically, the user) and additional data like the user’s role and permissions.
*Signature: A cryptographic signature generated by encoding the header and payload with a secret key or private key, ensuring data integrity.
These three sections are separated by dots (.), forming a token that looks like this: <Header>.<Payload>.<Signature>

[[File:JWT-Workflow.png|500px|center]]

==Overall Flow==

[[File:Authorization_flow.png|500px|center]]

==Methods Implemented==

* has_required_role?(required_role):

<pre>

def has_required_role?(required_role)
required_role = Role.find_by_name(required_role) if required_role.is_a?(String)
current_user&.role&.all_privileges_of?(required_role) || false
end

</pre>

This function checks if the current user has the required role or higher privileges. The role name is passed down as a parameter in required_role which is the minimum required role level for an action

For example:

<pre>has_required_role?('Administrator') # Checks if user is an admin or higher</pre>

<pre>has_required_role?(Role::INSTRUCTOR) # Checks if user is an instructor or higher</pre>

For exact role requirements, we also have:
* is_role?(required_role):

<pre>

def is_role?(required_role)
required_role = required_role.name if required_role.is_a?(Role)
current_user&.role&.name == required_role
end

</pre>

which checks if the user has exactly the specified role. For example:

<pre>is_role?('Student') # True only if user is exactly a student </pre>

Finally, we have authorization methods which work with the ApplicationController as well as individual resource controllers:

<pre>
# Authorize all actions
def authorize
unless all_actions_allowed?
render json: {
error: "You are not authorized to #{params[:action]} this #{params[:controller]}"
}, status: :forbidden
end
end

# Check if all actions are allowed
def all_actions_allowed?
return true if has_required_role?('Administrator')
action_allowed?
end

# Base action_allowed? - allows everything by default
# Controllers should override this method to implement their authorization logic
def action_allowed?
true
end
</pre>

The individual resource controllers can then override the method 'action_allowed?' to manage access. For example:

<pre>
def action_allowed?
has_required_role?('Instructor')
end
</pre>

==Existing File Updates==

* [[https://github.com/expertiza/reimplementation-back-end/blob/main/app/controllers/application_controller.rb application_controller.rb]]

This file was updated to include the new authorization module

<pre>
class ApplicationController < ActionController::API
include Authorization
include JwtToken

before_action :authorize
end
</pre>

This ensures that the [[https://github.com/rarchitgupta/reimplementation-back-end/blob/jwt_authorization/app/controllers/concerns/authorization.rb 'has_required_role?']] method is available globally along with [[https://github.com/rarchitgupta/reimplementation-back-end/blob/jwt_authorization/app/controllers/concerns/authorization.rb 'is_role?']]. These methods can then be used to override 'action_allowed?' to override the base implementation and provide more granular control

* [[https://github.com/rarchitgupta/reimplementation-back-end/blob/jwt_authorization/app/controllers/api/v1/courses_controller.rb courses_controller.rb]]

To test the functionality, based on the old Expertiza, the method was also overridden in the courses_controller.rb file:

<pre>
class Api::V1::CoursesController < ApplicationController
before_action :set_course, only: %i[ show update destroy add_ta view_tas remove_ta copy ]
rescue_from ActiveRecord::RecordNotFound, with: :course_not_found
rescue_from ActionController::ParameterMissing, with: :parameter_missing

def action_allowed?
has_required_role?('Instructor')
end

...
</pre>

==Anticipated Outcomes==
1. Enhanced AuthorizationHelper Module with JWT Integration: 
Updated and operational AuthorizationHelper module that would use JWT-based authentication. The module would be restructured to incorporate token-based authentication checks, replacing prior session-based methods.

2. Updated Associated Methods: 
Methods within the module will have to be updated to leverage JWT claims, ensuring authentication and authorization are handled based on token data. This will allow the module to verify user roles and permissions effectively through JWT claims.

3. Comprehensive JWT Error Handling: 
Built-in error handling to manage potential JWT-related issues, such as token expiration, tampering, or invalid claims. This ensures that unauthorized access is
blocked, and clear error messages are provided when issues arise.

4. Robust Unit Tests for Validation: 
A full suite of unit tests covering various scenarios, including normal, boundary, and edge cases, to validate each method’s functionality and confirm that all
JWT-based authentication flows work reliably.

5. Detailed Documentation and Code Comments: 
In-depth documentation and comments would be added to each function, explaining purpose, usage, and JWT-related adjustments, aiding in code readability and future
maintenance.

== Design Principles ==
The redesign of the `AuthorizationHelper` module for JWT-based authentication will follow well-established design principles to ensure the solution is secure, maintainable, and scalable. Below are the key principles to be applied and how they will shape this redesign:

1. '''Single Responsibility Principle (SRP)'''
* '''Definition''': Each module or class should have one clear responsibility.
* '''Implementation''':
** JwtToken concern handles only authentication
** Authorization concern manages only authorization rules
* '''Benefit''': Changes to authentication logic don't affect authorization rules and vice versa

2. '''Open / Closed Principle'''
* '''Definition''': Software entities should be open for extension but closed for modification
* '''Implementation''':
<pre>
# Base authorization in Authorization concern
def action_allowed?
true # Base implementation
end

# Extended in CoursesController without modifying base
def action_allowed?
has_required_role?('Instructor')
end
</pre>

* '''Benefit''': New controllers can implement their own authorization rules without changing existing code

3. '''Inheritance and Polymorphism'''
* '''Definition''': Ability to present the same interface for different underlying forms (implementations)
* '''Implementation''':
** All controllers inherit from ApplicationController
** Each can override action_allowed? with its implementation
** System treats all action_allowed? calls polymorphically

* '''Benefit''': Consistent interface while allowing specialized behavior

4. '''Composition'''
* '''Implementation''':
<pre>
class ApplicationController < ActionController::API
include Authorization # Composition through modules
include JwtToken
end
</pre>

* '''Benefit''': More flexible than deep inheritance hierarchies, allows mixing in different behaviors

5. '''Don't Repeat Yourself (DRY)'''
* '''Definition''': Every piece of knowledge should have a single, unambiguous representation
* '''Implementation''':
** Common authentication logic in JwtToken
** Shared authorization behavior in Authorization
** Base controller provides default implementations

* '''Benefit''': Reduces code duplication and maintenance overhead

== Test Plan ==

=== Unit Tests ===
'''Definition''': Unit tests verify that individual methods work correctly in isolation under different scenarios.

==== Tests for jwt_verify_and_decode ====
'''Valid Token Test:'''
* '''Input''': A valid JWT token with claims like `id`, `role`, and `exp`.
* '''Expected Output''': Decoded payload as a `HashWithIndifferentAccess`.
* '''Validation''': Ensure the returned payload matches the expected data.

'''Expired Token Test:'''
* '''Input''': A token with an `exp` claim that has already passed.
* '''Expected Output''': `nil` with an appropriate error logged.
* '''Validation''': Confirm that the method gracefully handles expired tokens.

'''Invalid Token Test:'''
* '''Input''': A tampered JWT token with an invalid signature.
* '''Expected Output''': `nil`.
* '''Validation''': Ensure an appropriate error message is logged, and sensitive information is not exposed.

'''Missing Claims Test:'''
* '''Input''': A valid token missing critical claims like `role`.
* '''Expected Output''': `nil`.
* '''Validation''': Ensure the method flags the token as invalid due to missing data.

==== Tests for check_user_privileges ====
'''Sufficient Privileges Test:'''
* '''Input''': User info with `role` as `Admin` and a `required_privilege` of `Student`.
* '''Expected Output''': `true`.
* '''Validation''': Verify the method correctly interprets hierarchical roles.

'''Insufficient Privileges Test:'''
* '''Input''': User info with `role` as `Student` and a `required_privilege` of `Instructor`.
* '''Expected Output''': `false`.
* '''Validation''': Ensure the method denies access for insufficient privileges.

'''Missing Role Test:'''
* '''Input''': User info without a `role` claim.
* '''Expected Output''': `false`.
* '''Validation''': Ensure the method handles missing roles gracefully.

==== Tests for current_user_is_a? ====
'''Correct Role Test:'''
* '''Input''': Token with `role` as `Instructor` and `role_name` as `Instructor`.
* '''Expected Output''': `true`.
* '''Validation''': Verify the method returns `true` when roles match exactly.

'''Incorrect Role Test:'''
* '''Input''': Token with `role` as `TA` and `role_name` as `Instructor`.
* '''Expected Output''': `false`.
* '''Validation''': Ensure the method denies access when roles don’t match.

'''Missing Token Test:'''
* '''Input''': `nil` token.
* '''Expected Output''': `false`.
* '''Validation''': Confirm that the method handles missing tokens properly.

---

=== Integration Tests ===
'''Definition''': Integration tests validate that the `AuthorizationHelper` module functions correctly within the context of the overall system.

==== Approach Options ====
1. '''Creating a Dummy API''':
* A lightweight API will be created specifically for testing the `AuthorizationHelper` methods.
* This API will simulate requests requiring token authentication and privilege checks.
* '''Advantages''':
** Fully isolated testing environment.
** Flexibility to simulate different roles, tokens, and scenarios.
* '''Disadvantages''':
** Requires additional setup and may not reflect real-world behavior perfectly.

2. '''Implementing a New Controller in Expertiza''':
* A controller will be added to the existing Expertiza application that uses the refactored `AuthorizationHelper`.
* This ensures that tests occur in a real-world context, validating interactions with the actual system.
* '''Advantages''':
** Validates the actual behavior of the module within the system.
** Reflects real application workflows and edge cases.
* '''Disadvantages''':
** Potentially affects other parts of the application during testing.
** Requires effort to ensure test isolation.

==== Integration Test Cases ====
'''API Endpoint Authentication'''
* '''Valid Token Test''':
** '''Scenario''': Send a valid JWT token to a protected endpoint.
** '''Expected Outcome''': HTTP 200 OK with access granted.
** '''Validation''': Confirm the user is authenticated and receives the correct resource.

* '''Expired Token Test''':
** '''Scenario''': Send an expired JWT token to a protected endpoint.
** '''Expected Outcome''': HTTP 401 Unauthorized.
** '''Validation''': Ensure the system blocks access and provides a proper error message.

* '''Tampered Token Test''':
** '''Scenario''': Send a tampered token with an invalid signature.
** '''Expected Outcome''': HTTP 401 Unauthorized.
** '''Validation''': Confirm the system denies access and logs the attempt securely.

* '''Missing Token Test''':
** '''Scenario''': Make a request without providing a token.
** '''Expected Outcome''': HTTP 401 Unauthorized.
** '''Validation''': Verify that token authentication is strictly enforced.

== Team ==
===Mentor===
*Kashika Mallick (kmallick@ncsu.edu)

===Members===
*Shafa Hassan (shassa22@ncsu.edu)
*Archit Gupta (agupta85@ncsu.edu)
*Ansh Ganatra (aganatr@ncsu.edu)

CSC/ECE 517 Fall 2024 - E2487. Reimplement authorization helper.rb

2024-12-03T22:00:43Z

Agupta85: /* Overall Flow */

== Introduction ==
Expertiza currently uses session-based authentication in its AuthorizationHelper module. However, the new back-end reimplementation adopts JSON Web Token (JWT) for authentication. This transition is necessary to make the system more scalable, stateless, and secure. JWT-based authentication will replace session-based methods, requiring updates to the AuthorizationHelper module and associated methods.

== Background ==
The AuthorizationHelper module in Expertiza plays a critical role in managing user permissions and access control within the system. It provides methods to verify a user’s privileges based on their assigned roles, such as Super-Admin, Admin, Instructor, TA, or Student. These methods check if the user is authorized to perform actions like submitting assignments, reviewing work, or participating in quizzes. Additionally, it determines whether a user is involved in specific assignments, either as a participant, instructor, or through TA mappings.

==Problem Statement==

Expertiza currently uses session-based authentication in its [[https://github.com/expertiza/expertiza/blob/main/app/helpers/authorization_helper.rb AuthorizationHelper]] module. The [[https://github.com/expertiza/reimplementation-back-end reimplementation-back-end]] however, uses JWT (JSON Web Token) based authentication. This requires a reimplementation of an authorization concern module to accommodate JWT-based authentication

===Concerns===

A concern is a module that you extract to split the implementation of a class or module in coherent chunks, instead of having one big class body. Our new authorization module will be implemented as a concern which will work in tandem with the already-implemented [[https://github.com/expertiza/reimplementation-back-end/blob/main/app/controllers/concerns/jwt_token.rb JWT Concern]]

The following points need to be taken care of as per the requirement

* Role Management :
** Enable the system to process, verify, and decode roles from JWT Tokens.
** Use token role data to authenticate and authorize user actions.

* Privilege Verification :
** Update methods to validate user privileges using JWT claims.

* Testing and Documentation :
** Write comprehensive unit tests for all JWT-related methods.
** Include clear documentation and comments to aid future developers.

=Implemented Changes=

== JWT Token Overview ==

A JSON Web Token (JWT) is a compact, URL-safe token format commonly used for securely transmitting information between parties. It is widely used in web applications for authentication and authorization, as it allows information to be verified and trusted. In the context of our reimplemented AuthorizationHelper module, JWT tokens will replace session-based authentication, enabling stateless and more secure access control.

A JWT Token consists of three main parts:

*Header: Contains metadata about the token, such as the type (JWT) and the hashing algorithm used (e.g., HS256 or RS256).
*Payload: Includes claims, which are statements about an entity (typically, the user) and additional data like the user’s role and permissions.
*Signature: A cryptographic signature generated by encoding the header and payload with a secret key or private key, ensuring data integrity.
These three sections are separated by dots (.), forming a token that looks like this: <Header>.<Payload>.<Signature>

[[File:JWT-Workflow.png|500px|center]]

==Overall Flow==

[[File:Authorization_flow.png|500px|center]]

==Methods Implemented==

* has_required_role?(required_role):

<pre>

def has_required_role?(required_role)
required_role = Role.find_by_name(required_role) if required_role.is_a?(String)
current_user&.role&.all_privileges_of?(required_role) || false
end

</pre>

This function checks if the current user has the required role or higher privileges. The role name is passed down as a parameter in required_role which is the minimum required role level for an action

For example:

<pre>has_required_role?('Administrator') # Checks if user is an admin or higher</pre>

<pre>has_required_role?(Role::INSTRUCTOR) # Checks if user is an instructor or higher</pre>

For exact role requirements, we also have:
* is_role?(required_role):

<pre>

def is_role?(required_role)
required_role = required_role.name if required_role.is_a?(Role)
current_user&.role&.name == required_role
end

</pre>

which checks if the user has exactly the specified role. For example:

<pre>is_role?('Student') # True only if user is exactly a student </pre>

Finally, we have authorization methods which work with the ApplicationController as well as individual resource controllers:

<pre>
# Authorize all actions
def authorize
unless all_actions_allowed?
render json: {
error: "You are not authorized to #{params[:action]} this #{params[:controller]}"
}, status: :forbidden
end
end

# Check if all actions are allowed
def all_actions_allowed?
return true if has_required_role?('Administrator')
action_allowed?
end

# Base action_allowed? - allows everything by default
# Controllers should override this method to implement their authorization logic
def action_allowed?
true
end
</pre>

The individual resource controllers can then override the method 'action_allowed?' to manage access. For example:

<pre>
def action_allowed?
has_required_role?('Instructor')
end
</pre>

==Existing File Updates==

* [[https://github.com/expertiza/reimplementation-back-end/blob/main/app/controllers/application_controller.rb application_controller.rb]]

This file was updated to include the new authorization module

<pre>
class ApplicationController < ActionController::API
include Authorization
include JwtToken

before_action :authorize
end
</pre>

This ensures that the [[https://github.com/rarchitgupta/reimplementation-back-end/blob/jwt_authorization/app/controllers/concerns/authorization.rb 'has_required_role?']] method is available globally along with [[https://github.com/rarchitgupta/reimplementation-back-end/blob/jwt_authorization/app/controllers/concerns/authorization.rb 'is_role?']]. These methods can then be used to override 'action_allowed?' to override the base implementation and provide more granular control

* [[https://github.com/rarchitgupta/reimplementation-back-end/blob/jwt_authorization/app/controllers/api/v1/courses_controller.rb courses_controller.rb]]

To test the functionality, based on the old Expertiza, the method was also overridden in the courses_controller.rb file:

<pre>
class Api::V1::CoursesController < ApplicationController
before_action :set_course, only: %i[ show update destroy add_ta view_tas remove_ta copy ]
rescue_from ActiveRecord::RecordNotFound, with: :course_not_found
rescue_from ActionController::ParameterMissing, with: :parameter_missing

def action_allowed?
has_required_role?('Instructor')
end

...
</pre>

==Anticipated Outcomes==
1. Enhanced AuthorizationHelper Module with JWT Integration: 
Updated and operational AuthorizationHelper module that would use JWT-based authentication. The module would be restructured to incorporate token-based authentication checks, replacing prior session-based methods.

2. Updated Associated Methods: 
Methods within the module will have to be updated to leverage JWT claims, ensuring authentication and authorization are handled based on token data. This will allow the module to verify user roles and permissions effectively through JWT claims.

3. Comprehensive JWT Error Handling: 
Built-in error handling to manage potential JWT-related issues, such as token expiration, tampering, or invalid claims. This ensures that unauthorized access is
blocked, and clear error messages are provided when issues arise.

4. Robust Unit Tests for Validation: 
A full suite of unit tests covering various scenarios, including normal, boundary, and edge cases, to validate each method’s functionality and confirm that all
JWT-based authentication flows work reliably.

5. Detailed Documentation and Code Comments: 
In-depth documentation and comments would be added to each function, explaining purpose, usage, and JWT-related adjustments, aiding in code readability and future
maintenance.

== Design Principles ==
The redesign of the `AuthorizationHelper` module for JWT-based authentication will follow well-established design principles to ensure the solution is secure, maintainable, and scalable. Below are the key principles to be applied and how they will shape this redesign:

1. '''Single Responsibility Principle (SRP)'''
* '''Definition''': Each module or class should have one clear responsibility.
* '''How It’s Applied''': The `AuthorizationHelper` module focuses only on managing authentication and authorization, separating these concerns into distinct methods. For instance, `jwt_verify_and_decode` handles token verification, while `check_user_privileges` focuses on role-based checks. This keeps the code clean and easier to maintain.

2. '''Separation of Concerns'''
* '''Definition''': Different aspects of the system should be handled independently.
* '''How It’s Applied''': JWT-related tasks like token creation and decoding are delegated to the `JsonWebToken` class, while privilege checking and user role management remain within `AuthorizationHelper`. This modular approach ensures changes in one area don’t unnecessarily affect the other.

3. '''Security by Design'''
* '''Definition''': Security should be built into the system from the start, not as an afterthought.
* '''How It’s Applied''': JWT tokens are validated for expiry and tampering before any actions are authorized. Sensitive data like secret keys is securely stored in environment variables, and communication involving tokens is secured using HTTPS. The system also uses role-based access control (RBAC) to enforce fine-grained permissions.

4. '''Statelessness'''
* '''Definition''': The system should not depend on maintaining user-specific data on the server.
* '''How It’s Applied''': By using JWT, all necessary information about the user is encoded in the token itself. This removes the dependency on server-side session storage, making the system scalable and suitable for distributed architectures.

5. '''Testability'''
* '''Definition''': Code should be designed to make testing straightforward and effective.
* '''How It’s Applied''': Each method has a single responsibility, making it easier to write focused tests. The modular design allows us to test components like token verification and privilege checking independently, while mock tokens can simulate various scenarios (valid, expired, tampered).

---

== Test Plan ==

=== Unit Tests ===
'''Definition''': Unit tests verify that individual methods work correctly in isolation under different scenarios.

==== Tests for jwt_verify_and_decode ====
'''Valid Token Test:'''
* '''Input''': A valid JWT token with claims like `id`, `role`, and `exp`.
* '''Expected Output''': Decoded payload as a `HashWithIndifferentAccess`.
* '''Validation''': Ensure the returned payload matches the expected data.

'''Expired Token Test:'''
* '''Input''': A token with an `exp` claim that has already passed.
* '''Expected Output''': `nil` with an appropriate error logged.
* '''Validation''': Confirm that the method gracefully handles expired tokens.

'''Invalid Token Test:'''
* '''Input''': A tampered JWT token with an invalid signature.
* '''Expected Output''': `nil`.
* '''Validation''': Ensure an appropriate error message is logged, and sensitive information is not exposed.

'''Missing Claims Test:'''
* '''Input''': A valid token missing critical claims like `role`.
* '''Expected Output''': `nil`.
* '''Validation''': Ensure the method flags the token as invalid due to missing data.

==== Tests for check_user_privileges ====
'''Sufficient Privileges Test:'''
* '''Input''': User info with `role` as `Admin` and a `required_privilege` of `Student`.
* '''Expected Output''': `true`.
* '''Validation''': Verify the method correctly interprets hierarchical roles.

'''Insufficient Privileges Test:'''
* '''Input''': User info with `role` as `Student` and a `required_privilege` of `Instructor`.
* '''Expected Output''': `false`.
* '''Validation''': Ensure the method denies access for insufficient privileges.

'''Missing Role Test:'''
* '''Input''': User info without a `role` claim.
* '''Expected Output''': `false`.
* '''Validation''': Ensure the method handles missing roles gracefully.

==== Tests for current_user_is_a? ====
'''Correct Role Test:'''
* '''Input''': Token with `role` as `Instructor` and `role_name` as `Instructor`.
* '''Expected Output''': `true`.
* '''Validation''': Verify the method returns `true` when roles match exactly.

'''Incorrect Role Test:'''
* '''Input''': Token with `role` as `TA` and `role_name` as `Instructor`.
* '''Expected Output''': `false`.
* '''Validation''': Ensure the method denies access when roles don’t match.

'''Missing Token Test:'''
* '''Input''': `nil` token.
* '''Expected Output''': `false`.
* '''Validation''': Confirm that the method handles missing tokens properly.

---

=== Integration Tests ===
'''Definition''': Integration tests validate that the `AuthorizationHelper` module functions correctly within the context of the overall system.

==== Approach Options ====
1. '''Creating a Dummy API''':
* A lightweight API will be created specifically for testing the `AuthorizationHelper` methods.
* This API will simulate requests requiring token authentication and privilege checks.
* '''Advantages''':
** Fully isolated testing environment.
** Flexibility to simulate different roles, tokens, and scenarios.
* '''Disadvantages''':
** Requires additional setup and may not reflect real-world behavior perfectly.

2. '''Implementing a New Controller in Expertiza''':
* A controller will be added to the existing Expertiza application that uses the refactored `AuthorizationHelper`.
* This ensures that tests occur in a real-world context, validating interactions with the actual system.
* '''Advantages''':
** Validates the actual behavior of the module within the system.
** Reflects real application workflows and edge cases.
* '''Disadvantages''':
** Potentially affects other parts of the application during testing.
** Requires effort to ensure test isolation.

==== Integration Test Cases ====
'''API Endpoint Authentication'''
* '''Valid Token Test''':
** '''Scenario''': Send a valid JWT token to a protected endpoint.
** '''Expected Outcome''': HTTP 200 OK with access granted.
** '''Validation''': Confirm the user is authenticated and receives the correct resource.

* '''Expired Token Test''':
** '''Scenario''': Send an expired JWT token to a protected endpoint.
** '''Expected Outcome''': HTTP 401 Unauthorized.
** '''Validation''': Ensure the system blocks access and provides a proper error message.

* '''Tampered Token Test''':
** '''Scenario''': Send a tampered token with an invalid signature.
** '''Expected Outcome''': HTTP 401 Unauthorized.
** '''Validation''': Confirm the system denies access and logs the attempt securely.

* '''Missing Token Test''':
** '''Scenario''': Make a request without providing a token.
** '''Expected Outcome''': HTTP 401 Unauthorized.
** '''Validation''': Verify that token authentication is strictly enforced.

== Team ==
===Mentor===
*Kashika Mallick (kmallick@ncsu.edu)

===Members===
*Shafa Hassan (shassa22@ncsu.edu)
*Archit Gupta (agupta85@ncsu.edu)
*Ansh Ganatra (aganatr@ncsu.edu)

File:Authorization flow.png

2024-12-03T21:59:57Z

Agupta85:

File:Screenshot 2024-12-03 at 4.51.34 PM.png

2024-12-03T21:58:34Z

Agupta85:

CSC/ECE 517 Fall 2024 - E2487. Reimplement authorization helper.rb

2024-12-03T21:57:12Z

Agupta85: /* Implemented Changes */

== Introduction ==
Expertiza currently uses session-based authentication in its AuthorizationHelper module. However, the new back-end reimplementation adopts JSON Web Token (JWT) for authentication. This transition is necessary to make the system more scalable, stateless, and secure. JWT-based authentication will replace session-based methods, requiring updates to the AuthorizationHelper module and associated methods.

== Background ==
The AuthorizationHelper module in Expertiza plays a critical role in managing user permissions and access control within the system. It provides methods to verify a user’s privileges based on their assigned roles, such as Super-Admin, Admin, Instructor, TA, or Student. These methods check if the user is authorized to perform actions like submitting assignments, reviewing work, or participating in quizzes. Additionally, it determines whether a user is involved in specific assignments, either as a participant, instructor, or through TA mappings.

==Problem Statement==

Expertiza currently uses session-based authentication in its [[https://github.com/expertiza/expertiza/blob/main/app/helpers/authorization_helper.rb AuthorizationHelper]] module. The [[https://github.com/expertiza/reimplementation-back-end reimplementation-back-end]] however, uses JWT (JSON Web Token) based authentication. This requires a reimplementation of an authorization concern module to accommodate JWT-based authentication

===Concerns===

A concern is a module that you extract to split the implementation of a class or module in coherent chunks, instead of having one big class body. Our new authorization module will be implemented as a concern which will work in tandem with the already-implemented [[https://github.com/expertiza/reimplementation-back-end/blob/main/app/controllers/concerns/jwt_token.rb JWT Concern]]

The following points need to be taken care of as per the requirement

* Role Management :
** Enable the system to process, verify, and decode roles from JWT Tokens.
** Use token role data to authenticate and authorize user actions.

* Privilege Verification :
** Update methods to validate user privileges using JWT claims.

* Testing and Documentation :
** Write comprehensive unit tests for all JWT-related methods.
** Include clear documentation and comments to aid future developers.

=Implemented Changes=

== JWT Token Overview ==

A JSON Web Token (JWT) is a compact, URL-safe token format commonly used for securely transmitting information between parties. It is widely used in web applications for authentication and authorization, as it allows information to be verified and trusted. In the context of our reimplemented AuthorizationHelper module, JWT tokens will replace session-based authentication, enabling stateless and more secure access control.

A JWT Token consists of three main parts:

*Header: Contains metadata about the token, such as the type (JWT) and the hashing algorithm used (e.g., HS256 or RS256).
*Payload: Includes claims, which are statements about an entity (typically, the user) and additional data like the user’s role and permissions.
*Signature: A cryptographic signature generated by encoding the header and payload with a secret key or private key, ensuring data integrity.
These three sections are separated by dots (.), forming a token that looks like this: <Header>.<Payload>.<Signature>

[[File:JWT-Workflow.png|500px|center]]

==Overall Flow==

==Methods Implemented==

* has_required_role?(required_role):

<pre>

def has_required_role?(required_role)
required_role = Role.find_by_name(required_role) if required_role.is_a?(String)
current_user&.role&.all_privileges_of?(required_role) || false
end

</pre>

This function checks if the current user has the required role or higher privileges. The role name is passed down as a parameter in required_role which is the minimum required role level for an action

For example:

<pre>has_required_role?('Administrator') # Checks if user is an admin or higher</pre>

<pre>has_required_role?(Role::INSTRUCTOR) # Checks if user is an instructor or higher</pre>

For exact role requirements, we also have:
* is_role?(required_role):

<pre>

def is_role?(required_role)
required_role = required_role.name if required_role.is_a?(Role)
current_user&.role&.name == required_role
end

</pre>

which checks if the user has exactly the specified role. For example:

<pre>is_role?('Student') # True only if user is exactly a student </pre>

Finally, we have authorization methods which work with the ApplicationController as well as individual resource controllers:

<pre>
# Authorize all actions
def authorize
unless all_actions_allowed?
render json: {
error: "You are not authorized to #{params[:action]} this #{params[:controller]}"
}, status: :forbidden
end
end

# Check if all actions are allowed
def all_actions_allowed?
return true if has_required_role?('Administrator')
action_allowed?
end

# Base action_allowed? - allows everything by default
# Controllers should override this method to implement their authorization logic
def action_allowed?
true
end
</pre>

The individual resource controllers can then override the method 'action_allowed?' to manage access. For example:

<pre>
def action_allowed?
has_required_role?('Instructor')
end
</pre>

==Existing File Updates==

* [[https://github.com/expertiza/reimplementation-back-end/blob/main/app/controllers/application_controller.rb application_controller.rb]]

This file was updated to include the new authorization module

<pre>
class ApplicationController < ActionController::API
include Authorization
include JwtToken

before_action :authorize
end
</pre>

This ensures that the [[https://github.com/rarchitgupta/reimplementation-back-end/blob/jwt_authorization/app/controllers/concerns/authorization.rb 'has_required_role?']] method is available globally along with [[https://github.com/rarchitgupta/reimplementation-back-end/blob/jwt_authorization/app/controllers/concerns/authorization.rb 'is_role?']]. These methods can then be used to override 'action_allowed?' to override the base implementation and provide more granular control

* [[https://github.com/rarchitgupta/reimplementation-back-end/blob/jwt_authorization/app/controllers/api/v1/courses_controller.rb courses_controller.rb]]

To test the functionality, based on the old Expertiza, the method was also overridden in the courses_controller.rb file:

<pre>
class Api::V1::CoursesController < ApplicationController
before_action :set_course, only: %i[ show update destroy add_ta view_tas remove_ta copy ]
rescue_from ActiveRecord::RecordNotFound, with: :course_not_found
rescue_from ActionController::ParameterMissing, with: :parameter_missing

def action_allowed?
has_required_role?('Instructor')
end

...
</pre>

==Anticipated Outcomes==
1. Enhanced AuthorizationHelper Module with JWT Integration: 
Updated and operational AuthorizationHelper module that would use JWT-based authentication. The module would be restructured to incorporate token-based authentication checks, replacing prior session-based methods.

2. Updated Associated Methods: 
Methods within the module will have to be updated to leverage JWT claims, ensuring authentication and authorization are handled based on token data. This will allow the module to verify user roles and permissions effectively through JWT claims.

3. Comprehensive JWT Error Handling: 
Built-in error handling to manage potential JWT-related issues, such as token expiration, tampering, or invalid claims. This ensures that unauthorized access is
blocked, and clear error messages are provided when issues arise.

4. Robust Unit Tests for Validation: 
A full suite of unit tests covering various scenarios, including normal, boundary, and edge cases, to validate each method’s functionality and confirm that all
JWT-based authentication flows work reliably.

5. Detailed Documentation and Code Comments: 
In-depth documentation and comments would be added to each function, explaining purpose, usage, and JWT-related adjustments, aiding in code readability and future
maintenance.

== Design Principles ==
The redesign of the `AuthorizationHelper` module for JWT-based authentication will follow well-established design principles to ensure the solution is secure, maintainable, and scalable. Below are the key principles to be applied and how they will shape this redesign:

1. '''Single Responsibility Principle (SRP)'''
* '''Definition''': Each module or class should have one clear responsibility.
* '''How It’s Applied''': The `AuthorizationHelper` module focuses only on managing authentication and authorization, separating these concerns into distinct methods. For instance, `jwt_verify_and_decode` handles token verification, while `check_user_privileges` focuses on role-based checks. This keeps the code clean and easier to maintain.

2. '''Separation of Concerns'''
* '''Definition''': Different aspects of the system should be handled independently.
* '''How It’s Applied''': JWT-related tasks like token creation and decoding are delegated to the `JsonWebToken` class, while privilege checking and user role management remain within `AuthorizationHelper`. This modular approach ensures changes in one area don’t unnecessarily affect the other.

3. '''Security by Design'''
* '''Definition''': Security should be built into the system from the start, not as an afterthought.
* '''How It’s Applied''': JWT tokens are validated for expiry and tampering before any actions are authorized. Sensitive data like secret keys is securely stored in environment variables, and communication involving tokens is secured using HTTPS. The system also uses role-based access control (RBAC) to enforce fine-grained permissions.

4. '''Statelessness'''
* '''Definition''': The system should not depend on maintaining user-specific data on the server.
* '''How It’s Applied''': By using JWT, all necessary information about the user is encoded in the token itself. This removes the dependency on server-side session storage, making the system scalable and suitable for distributed architectures.

5. '''Testability'''
* '''Definition''': Code should be designed to make testing straightforward and effective.
* '''How It’s Applied''': Each method has a single responsibility, making it easier to write focused tests. The modular design allows us to test components like token verification and privilege checking independently, while mock tokens can simulate various scenarios (valid, expired, tampered).

---

== Test Plan ==

=== Unit Tests ===
'''Definition''': Unit tests verify that individual methods work correctly in isolation under different scenarios.

==== Tests for jwt_verify_and_decode ====
'''Valid Token Test:'''
* '''Input''': A valid JWT token with claims like `id`, `role`, and `exp`.
* '''Expected Output''': Decoded payload as a `HashWithIndifferentAccess`.
* '''Validation''': Ensure the returned payload matches the expected data.

'''Expired Token Test:'''
* '''Input''': A token with an `exp` claim that has already passed.
* '''Expected Output''': `nil` with an appropriate error logged.
* '''Validation''': Confirm that the method gracefully handles expired tokens.

'''Invalid Token Test:'''
* '''Input''': A tampered JWT token with an invalid signature.
* '''Expected Output''': `nil`.
* '''Validation''': Ensure an appropriate error message is logged, and sensitive information is not exposed.

'''Missing Claims Test:'''
* '''Input''': A valid token missing critical claims like `role`.
* '''Expected Output''': `nil`.
* '''Validation''': Ensure the method flags the token as invalid due to missing data.

==== Tests for check_user_privileges ====
'''Sufficient Privileges Test:'''
* '''Input''': User info with `role` as `Admin` and a `required_privilege` of `Student`.
* '''Expected Output''': `true`.
* '''Validation''': Verify the method correctly interprets hierarchical roles.

'''Insufficient Privileges Test:'''
* '''Input''': User info with `role` as `Student` and a `required_privilege` of `Instructor`.
* '''Expected Output''': `false`.
* '''Validation''': Ensure the method denies access for insufficient privileges.

'''Missing Role Test:'''
* '''Input''': User info without a `role` claim.
* '''Expected Output''': `false`.
* '''Validation''': Ensure the method handles missing roles gracefully.

==== Tests for current_user_is_a? ====
'''Correct Role Test:'''
* '''Input''': Token with `role` as `Instructor` and `role_name` as `Instructor`.
* '''Expected Output''': `true`.
* '''Validation''': Verify the method returns `true` when roles match exactly.

'''Incorrect Role Test:'''
* '''Input''': Token with `role` as `TA` and `role_name` as `Instructor`.
* '''Expected Output''': `false`.
* '''Validation''': Ensure the method denies access when roles don’t match.

'''Missing Token Test:'''
* '''Input''': `nil` token.
* '''Expected Output''': `false`.
* '''Validation''': Confirm that the method handles missing tokens properly.

---

=== Integration Tests ===
'''Definition''': Integration tests validate that the `AuthorizationHelper` module functions correctly within the context of the overall system.

==== Approach Options ====
1. '''Creating a Dummy API''':
* A lightweight API will be created specifically for testing the `AuthorizationHelper` methods.
* This API will simulate requests requiring token authentication and privilege checks.
* '''Advantages''':
** Fully isolated testing environment.
** Flexibility to simulate different roles, tokens, and scenarios.
* '''Disadvantages''':
** Requires additional setup and may not reflect real-world behavior perfectly.

2. '''Implementing a New Controller in Expertiza''':
* A controller will be added to the existing Expertiza application that uses the refactored `AuthorizationHelper`.
* This ensures that tests occur in a real-world context, validating interactions with the actual system.
* '''Advantages''':
** Validates the actual behavior of the module within the system.
** Reflects real application workflows and edge cases.
* '''Disadvantages''':
** Potentially affects other parts of the application during testing.
** Requires effort to ensure test isolation.

==== Integration Test Cases ====
'''API Endpoint Authentication'''
* '''Valid Token Test''':
** '''Scenario''': Send a valid JWT token to a protected endpoint.
** '''Expected Outcome''': HTTP 200 OK with access granted.
** '''Validation''': Confirm the user is authenticated and receives the correct resource.

* '''Expired Token Test''':
** '''Scenario''': Send an expired JWT token to a protected endpoint.
** '''Expected Outcome''': HTTP 401 Unauthorized.
** '''Validation''': Ensure the system blocks access and provides a proper error message.

* '''Tampered Token Test''':
** '''Scenario''': Send a tampered token with an invalid signature.
** '''Expected Outcome''': HTTP 401 Unauthorized.
** '''Validation''': Confirm the system denies access and logs the attempt securely.

* '''Missing Token Test''':
** '''Scenario''': Make a request without providing a token.
** '''Expected Outcome''': HTTP 401 Unauthorized.
** '''Validation''': Verify that token authentication is strictly enforced.

== Team ==
===Mentor===
*Kashika Mallick (kmallick@ncsu.edu)

===Members===
*Shafa Hassan (shassa22@ncsu.edu)
*Archit Gupta (agupta85@ncsu.edu)
*Ansh Ganatra (aganatr@ncsu.edu)

CSC/ECE 517 Fall 2024 - E2487. Reimplement authorization helper.rb

2024-12-03T21:47:04Z

Agupta85: /* Existing File Updates */

== Introduction ==
Expertiza currently uses session-based authentication in its AuthorizationHelper module. However, the new back-end reimplementation adopts JSON Web Token (JWT) for authentication. This transition is necessary to make the system more scalable, stateless, and secure. JWT-based authentication will replace session-based methods, requiring updates to the AuthorizationHelper module and associated methods.

== Background ==
The AuthorizationHelper module in Expertiza plays a critical role in managing user permissions and access control within the system. It provides methods to verify a user’s privileges based on their assigned roles, such as Super-Admin, Admin, Instructor, TA, or Student. These methods check if the user is authorized to perform actions like submitting assignments, reviewing work, or participating in quizzes. Additionally, it determines whether a user is involved in specific assignments, either as a participant, instructor, or through TA mappings.

==Problem Statement==

Expertiza currently uses session-based authentication in its [[https://github.com/expertiza/expertiza/blob/main/app/helpers/authorization_helper.rb AuthorizationHelper]] module. The [[https://github.com/expertiza/reimplementation-back-end reimplementation-back-end]] however, uses JWT (JSON Web Token) based authentication. This requires a reimplementation of an authorization concern module to accommodate JWT-based authentication

===Concerns===

A concern is a module that you extract to split the implementation of a class or module in coherent chunks, instead of having one big class body. Our new authorization module will be implemented as a concern which will work in tandem with the already-implemented [[https://github.com/expertiza/reimplementation-back-end/blob/main/app/controllers/concerns/jwt_token.rb JWT Concern]]

The following points need to be taken care of as per the requirement

* Role Management :
** Enable the system to process, verify, and decode roles from JWT Tokens.
** Use token role data to authenticate and authorize user actions.

* Privilege Verification :
** Update methods to validate user privileges using JWT claims.

* Testing and Documentation :
** Write comprehensive unit tests for all JWT-related methods.
** Include clear documentation and comments to aid future developers.

=Implemented Changes=

== JWT Token Overview ==

A JSON Web Token (JWT) is a compact, URL-safe token format commonly used for securely transmitting information between parties. It is widely used in web applications for authentication and authorization, as it allows information to be verified and trusted. In the context of our reimplemented AuthorizationHelper module, JWT tokens will replace session-based authentication, enabling stateless and more secure access control.

A JWT Token consists of three main parts:

*Header: Contains metadata about the token, such as the type (JWT) and the hashing algorithm used (e.g., HS256 or RS256).
*Payload: Includes claims, which are statements about an entity (typically, the user) and additional data like the user’s role and permissions.
*Signature: A cryptographic signature generated by encoding the header and payload with a secret key or private key, ensuring data integrity.
These three sections are separated by dots (.), forming a token that looks like this: <Header>.<Payload>.<Signature>

[[File:JWT-Workflow.png|500px|center]]

==Methods Implemented==

* has_required_role?(required_role):

<pre>

def has_required_role?(required_role)
required_role = Role.find_by_name(required_role) if required_role.is_a?(String)
current_user&.role&.all_privileges_of?(required_role) || false
end

</pre>

This function checks if the current user has the required role or higher privileges. The role name is passed down as a parameter in required_role which is the minimum required role level for an action

For example:

<pre>has_required_role?('Administrator') # Checks if user is an admin or higher</pre>

<pre>has_required_role?(Role::INSTRUCTOR) # Checks if user is an instructor or higher</pre>

For exact role requirements, we also have:
* is_role?(required_role):

<pre>

def is_role?(required_role)
required_role = required_role.name if required_role.is_a?(Role)
current_user&.role&.name == required_role
end

</pre>

which checks if the user has exactly the specified role. For example:

<pre>is_role?('Student') # True only if user is exactly a student </pre>

Finally, we have authorization methods which work with the ApplicationController as well as individual resource controllers:

<pre>
# Authorize all actions
def authorize
unless all_actions_allowed?
render json: {
error: "You are not authorized to #{params[:action]} this #{params[:controller]}"
}, status: :forbidden
end
end

# Check if all actions are allowed
def all_actions_allowed?
return true if has_required_role?('Administrator')
action_allowed?
end

# Base action_allowed? - allows everything by default
# Controllers should override this method to implement their authorization logic
def action_allowed?
true
end
</pre>

The individual resource controllers can then override the method 'action_allowed?' to manage access. For example:

<pre>
def action_allowed?
has_required_role?('Instructor')
end
</pre>

==Existing File Updates==

* [[https://github.com/expertiza/reimplementation-back-end/blob/main/app/controllers/application_controller.rb application_controller.rb]]

This file was updated to include the new authorization module

<pre>
class ApplicationController < ActionController::API
include Authorization
include JwtToken

before_action :authorize
end
</pre>

This ensures that the [[https://github.com/rarchitgupta/reimplementation-back-end/blob/jwt_authorization/app/controllers/concerns/authorization.rb 'has_required_role?']] method is available globally along with [[https://github.com/rarchitgupta/reimplementation-back-end/blob/jwt_authorization/app/controllers/concerns/authorization.rb 'is_role?']]. These methods can then be used to override 'action_allowed?' to override the base implementation and provide more granular control

* [[https://github.com/rarchitgupta/reimplementation-back-end/blob/jwt_authorization/app/controllers/api/v1/courses_controller.rb courses_controller.rb]]

To test the functionality, based on the old Expertiza, the method was also overridden in the courses_controller.rb file:

<pre>
class Api::V1::CoursesController < ApplicationController
before_action :set_course, only: %i[ show update destroy add_ta view_tas remove_ta copy ]
rescue_from ActiveRecord::RecordNotFound, with: :course_not_found
rescue_from ActionController::ParameterMissing, with: :parameter_missing

def action_allowed?
has_required_role?('Instructor')
end

...
</pre>

==Anticipated Outcomes==
1. Enhanced AuthorizationHelper Module with JWT Integration: 
Updated and operational AuthorizationHelper module that would use JWT-based authentication. The module would be restructured to incorporate token-based authentication checks, replacing prior session-based methods.

2. Updated Associated Methods: 
Methods within the module will have to be updated to leverage JWT claims, ensuring authentication and authorization are handled based on token data. This will allow the module to verify user roles and permissions effectively through JWT claims.

3. Comprehensive JWT Error Handling: 
Built-in error handling to manage potential JWT-related issues, such as token expiration, tampering, or invalid claims. This ensures that unauthorized access is
blocked, and clear error messages are provided when issues arise.

4. Robust Unit Tests for Validation: 
A full suite of unit tests covering various scenarios, including normal, boundary, and edge cases, to validate each method’s functionality and confirm that all
JWT-based authentication flows work reliably.

5. Detailed Documentation and Code Comments: 
In-depth documentation and comments would be added to each function, explaining purpose, usage, and JWT-related adjustments, aiding in code readability and future
maintenance.

== Design Principles ==
The redesign of the `AuthorizationHelper` module for JWT-based authentication will follow well-established design principles to ensure the solution is secure, maintainable, and scalable. Below are the key principles to be applied and how they will shape this redesign:

1. '''Single Responsibility Principle (SRP)'''
* '''Definition''': Each module or class should have one clear responsibility.
* '''How It’s Applied''': The `AuthorizationHelper` module focuses only on managing authentication and authorization, separating these concerns into distinct methods. For instance, `jwt_verify_and_decode` handles token verification, while `check_user_privileges` focuses on role-based checks. This keeps the code clean and easier to maintain.

2. '''Separation of Concerns'''
* '''Definition''': Different aspects of the system should be handled independently.
* '''How It’s Applied''': JWT-related tasks like token creation and decoding are delegated to the `JsonWebToken` class, while privilege checking and user role management remain within `AuthorizationHelper`. This modular approach ensures changes in one area don’t unnecessarily affect the other.

3. '''Security by Design'''
* '''Definition''': Security should be built into the system from the start, not as an afterthought.
* '''How It’s Applied''': JWT tokens are validated for expiry and tampering before any actions are authorized. Sensitive data like secret keys is securely stored in environment variables, and communication involving tokens is secured using HTTPS. The system also uses role-based access control (RBAC) to enforce fine-grained permissions.

4. '''Statelessness'''
* '''Definition''': The system should not depend on maintaining user-specific data on the server.
* '''How It’s Applied''': By using JWT, all necessary information about the user is encoded in the token itself. This removes the dependency on server-side session storage, making the system scalable and suitable for distributed architectures.

5. '''Testability'''
* '''Definition''': Code should be designed to make testing straightforward and effective.
* '''How It’s Applied''': Each method has a single responsibility, making it easier to write focused tests. The modular design allows us to test components like token verification and privilege checking independently, while mock tokens can simulate various scenarios (valid, expired, tampered).

---

== Test Plan ==

=== Unit Tests ===
'''Definition''': Unit tests verify that individual methods work correctly in isolation under different scenarios.

==== Tests for jwt_verify_and_decode ====
'''Valid Token Test:'''
* '''Input''': A valid JWT token with claims like `id`, `role`, and `exp`.
* '''Expected Output''': Decoded payload as a `HashWithIndifferentAccess`.
* '''Validation''': Ensure the returned payload matches the expected data.

'''Expired Token Test:'''
* '''Input''': A token with an `exp` claim that has already passed.
* '''Expected Output''': `nil` with an appropriate error logged.
* '''Validation''': Confirm that the method gracefully handles expired tokens.

'''Invalid Token Test:'''
* '''Input''': A tampered JWT token with an invalid signature.
* '''Expected Output''': `nil`.
* '''Validation''': Ensure an appropriate error message is logged, and sensitive information is not exposed.

'''Missing Claims Test:'''
* '''Input''': A valid token missing critical claims like `role`.
* '''Expected Output''': `nil`.
* '''Validation''': Ensure the method flags the token as invalid due to missing data.

==== Tests for check_user_privileges ====
'''Sufficient Privileges Test:'''
* '''Input''': User info with `role` as `Admin` and a `required_privilege` of `Student`.
* '''Expected Output''': `true`.
* '''Validation''': Verify the method correctly interprets hierarchical roles.

'''Insufficient Privileges Test:'''
* '''Input''': User info with `role` as `Student` and a `required_privilege` of `Instructor`.
* '''Expected Output''': `false`.
* '''Validation''': Ensure the method denies access for insufficient privileges.

'''Missing Role Test:'''
* '''Input''': User info without a `role` claim.
* '''Expected Output''': `false`.
* '''Validation''': Ensure the method handles missing roles gracefully.

==== Tests for current_user_is_a? ====
'''Correct Role Test:'''
* '''Input''': Token with `role` as `Instructor` and `role_name` as `Instructor`.
* '''Expected Output''': `true`.
* '''Validation''': Verify the method returns `true` when roles match exactly.

'''Incorrect Role Test:'''
* '''Input''': Token with `role` as `TA` and `role_name` as `Instructor`.
* '''Expected Output''': `false`.
* '''Validation''': Ensure the method denies access when roles don’t match.

'''Missing Token Test:'''
* '''Input''': `nil` token.
* '''Expected Output''': `false`.
* '''Validation''': Confirm that the method handles missing tokens properly.

---

=== Integration Tests ===
'''Definition''': Integration tests validate that the `AuthorizationHelper` module functions correctly within the context of the overall system.

==== Approach Options ====
1. '''Creating a Dummy API''':
* A lightweight API will be created specifically for testing the `AuthorizationHelper` methods.
* This API will simulate requests requiring token authentication and privilege checks.
* '''Advantages''':
** Fully isolated testing environment.
** Flexibility to simulate different roles, tokens, and scenarios.
* '''Disadvantages''':
** Requires additional setup and may not reflect real-world behavior perfectly.

2. '''Implementing a New Controller in Expertiza''':
* A controller will be added to the existing Expertiza application that uses the refactored `AuthorizationHelper`.
* This ensures that tests occur in a real-world context, validating interactions with the actual system.
* '''Advantages''':
** Validates the actual behavior of the module within the system.
** Reflects real application workflows and edge cases.
* '''Disadvantages''':
** Potentially affects other parts of the application during testing.
** Requires effort to ensure test isolation.

==== Integration Test Cases ====
'''API Endpoint Authentication'''
* '''Valid Token Test''':
** '''Scenario''': Send a valid JWT token to a protected endpoint.
** '''Expected Outcome''': HTTP 200 OK with access granted.
** '''Validation''': Confirm the user is authenticated and receives the correct resource.

* '''Expired Token Test''':
** '''Scenario''': Send an expired JWT token to a protected endpoint.
** '''Expected Outcome''': HTTP 401 Unauthorized.
** '''Validation''': Ensure the system blocks access and provides a proper error message.

* '''Tampered Token Test''':
** '''Scenario''': Send a tampered token with an invalid signature.
** '''Expected Outcome''': HTTP 401 Unauthorized.
** '''Validation''': Confirm the system denies access and logs the attempt securely.

* '''Missing Token Test''':
** '''Scenario''': Make a request without providing a token.
** '''Expected Outcome''': HTTP 401 Unauthorized.
** '''Validation''': Verify that token authentication is strictly enforced.

== Team ==
===Mentor===
*Kashika Mallick (kmallick@ncsu.edu)

===Members===
*Shafa Hassan (shassa22@ncsu.edu)
*Archit Gupta (agupta85@ncsu.edu)
*Ansh Ganatra (aganatr@ncsu.edu)

CSC/ECE 517 Fall 2024 - E2487. Reimplement authorization helper.rb

2024-12-03T21:43:39Z

Agupta85: /* Existing File Updates */

== Introduction ==
Expertiza currently uses session-based authentication in its AuthorizationHelper module. However, the new back-end reimplementation adopts JSON Web Token (JWT) for authentication. This transition is necessary to make the system more scalable, stateless, and secure. JWT-based authentication will replace session-based methods, requiring updates to the AuthorizationHelper module and associated methods.

== Background ==
The AuthorizationHelper module in Expertiza plays a critical role in managing user permissions and access control within the system. It provides methods to verify a user’s privileges based on their assigned roles, such as Super-Admin, Admin, Instructor, TA, or Student. These methods check if the user is authorized to perform actions like submitting assignments, reviewing work, or participating in quizzes. Additionally, it determines whether a user is involved in specific assignments, either as a participant, instructor, or through TA mappings.

==Problem Statement==

Expertiza currently uses session-based authentication in its [[https://github.com/expertiza/expertiza/blob/main/app/helpers/authorization_helper.rb AuthorizationHelper]] module. The [[https://github.com/expertiza/reimplementation-back-end reimplementation-back-end]] however, uses JWT (JSON Web Token) based authentication. This requires a reimplementation of an authorization concern module to accommodate JWT-based authentication

===Concerns===

A concern is a module that you extract to split the implementation of a class or module in coherent chunks, instead of having one big class body. Our new authorization module will be implemented as a concern which will work in tandem with the already-implemented [[https://github.com/expertiza/reimplementation-back-end/blob/main/app/controllers/concerns/jwt_token.rb JWT Concern]]

The following points need to be taken care of as per the requirement

* Role Management :
** Enable the system to process, verify, and decode roles from JWT Tokens.
** Use token role data to authenticate and authorize user actions.

* Privilege Verification :
** Update methods to validate user privileges using JWT claims.

* Testing and Documentation :
** Write comprehensive unit tests for all JWT-related methods.
** Include clear documentation and comments to aid future developers.

=Implemented Changes=

== JWT Token Overview ==

A JSON Web Token (JWT) is a compact, URL-safe token format commonly used for securely transmitting information between parties. It is widely used in web applications for authentication and authorization, as it allows information to be verified and trusted. In the context of our reimplemented AuthorizationHelper module, JWT tokens will replace session-based authentication, enabling stateless and more secure access control.

A JWT Token consists of three main parts:

*Header: Contains metadata about the token, such as the type (JWT) and the hashing algorithm used (e.g., HS256 or RS256).
*Payload: Includes claims, which are statements about an entity (typically, the user) and additional data like the user’s role and permissions.
*Signature: A cryptographic signature generated by encoding the header and payload with a secret key or private key, ensuring data integrity.
These three sections are separated by dots (.), forming a token that looks like this: <Header>.<Payload>.<Signature>

[[File:JWT-Workflow.png|500px|center]]

==Methods Implemented==

* has_required_role?(required_role):

<pre>

def has_required_role?(required_role)
required_role = Role.find_by_name(required_role) if required_role.is_a?(String)
current_user&.role&.all_privileges_of?(required_role) || false
end

</pre>

This function checks if the current user has the required role or higher privileges. The role name is passed down as a parameter in required_role which is the minimum required role level for an action

For example:

<pre>has_required_role?('Administrator') # Checks if user is an admin or higher</pre>

<pre>has_required_role?(Role::INSTRUCTOR) # Checks if user is an instructor or higher</pre>

For exact role requirements, we also have:
* is_role?(required_role):

<pre>

def is_role?(required_role)
required_role = required_role.name if required_role.is_a?(Role)
current_user&.role&.name == required_role
end

</pre>

which checks if the user has exactly the specified role. For example:

<pre>is_role?('Student') # True only if user is exactly a student </pre>

Finally, we have authorization methods which work with the ApplicationController as well as individual resource controllers:

<pre>
# Authorize all actions
def authorize
unless all_actions_allowed?
render json: {
error: "You are not authorized to #{params[:action]} this #{params[:controller]}"
}, status: :forbidden
end
end

# Check if all actions are allowed
def all_actions_allowed?
return true if has_required_role?('Administrator')
action_allowed?
end

# Base action_allowed? - allows everything by default
# Controllers should override this method to implement their authorization logic
def action_allowed?
true
end
</pre>

The individual resource controllers can then override the method 'action_allowed?' to manage access. For example:

<pre>
def action_allowed?
has_required_role?('Instructor')
end
</pre>

==Existing File Updates==

* [[https://github.com/expertiza/reimplementation-back-end/blob/main/app/controllers/application_controller.rb application_controller.rb]]

This file was updated to include the new authorization module

<pre>
class ApplicationController < ActionController::API
include Authorization
include JwtToken

before_action :authorize
end
</pre>

This ensures that the [[https://github.com/rarchitgupta/reimplementation-back-end/blob/jwt_authorization/app/controllers/concerns/authorization.rb 'has_required_role?']] method is available globally along with [[https://github.com/rarchitgupta/reimplementation-back-end/blob/jwt_authorization/app/controllers/concerns/authorization.rb 'is_role?']]. These methods can then be used to override 'action_allowed?' to override the base implementation and provide more granular control

==Anticipated Outcomes==
1. Enhanced AuthorizationHelper Module with JWT Integration: 
Updated and operational AuthorizationHelper module that would use JWT-based authentication. The module would be restructured to incorporate token-based authentication checks, replacing prior session-based methods.

2. Updated Associated Methods: 
Methods within the module will have to be updated to leverage JWT claims, ensuring authentication and authorization are handled based on token data. This will allow the module to verify user roles and permissions effectively through JWT claims.

3. Comprehensive JWT Error Handling: 
Built-in error handling to manage potential JWT-related issues, such as token expiration, tampering, or invalid claims. This ensures that unauthorized access is
blocked, and clear error messages are provided when issues arise.

4. Robust Unit Tests for Validation: 
A full suite of unit tests covering various scenarios, including normal, boundary, and edge cases, to validate each method’s functionality and confirm that all
JWT-based authentication flows work reliably.

5. Detailed Documentation and Code Comments: 
In-depth documentation and comments would be added to each function, explaining purpose, usage, and JWT-related adjustments, aiding in code readability and future
maintenance.

== Design Principles ==
The redesign of the `AuthorizationHelper` module for JWT-based authentication will follow well-established design principles to ensure the solution is secure, maintainable, and scalable. Below are the key principles to be applied and how they will shape this redesign:

1. '''Single Responsibility Principle (SRP)'''
* '''Definition''': Each module or class should have one clear responsibility.
* '''How It’s Applied''': The `AuthorizationHelper` module focuses only on managing authentication and authorization, separating these concerns into distinct methods. For instance, `jwt_verify_and_decode` handles token verification, while `check_user_privileges` focuses on role-based checks. This keeps the code clean and easier to maintain.

2. '''Separation of Concerns'''
* '''Definition''': Different aspects of the system should be handled independently.
* '''How It’s Applied''': JWT-related tasks like token creation and decoding are delegated to the `JsonWebToken` class, while privilege checking and user role management remain within `AuthorizationHelper`. This modular approach ensures changes in one area don’t unnecessarily affect the other.

3. '''Security by Design'''
* '''Definition''': Security should be built into the system from the start, not as an afterthought.
* '''How It’s Applied''': JWT tokens are validated for expiry and tampering before any actions are authorized. Sensitive data like secret keys is securely stored in environment variables, and communication involving tokens is secured using HTTPS. The system also uses role-based access control (RBAC) to enforce fine-grained permissions.

4. '''Statelessness'''
* '''Definition''': The system should not depend on maintaining user-specific data on the server.
* '''How It’s Applied''': By using JWT, all necessary information about the user is encoded in the token itself. This removes the dependency on server-side session storage, making the system scalable and suitable for distributed architectures.

5. '''Testability'''
* '''Definition''': Code should be designed to make testing straightforward and effective.
* '''How It’s Applied''': Each method has a single responsibility, making it easier to write focused tests. The modular design allows us to test components like token verification and privilege checking independently, while mock tokens can simulate various scenarios (valid, expired, tampered).

---

== Test Plan ==

=== Unit Tests ===
'''Definition''': Unit tests verify that individual methods work correctly in isolation under different scenarios.

==== Tests for jwt_verify_and_decode ====
'''Valid Token Test:'''
* '''Input''': A valid JWT token with claims like `id`, `role`, and `exp`.
* '''Expected Output''': Decoded payload as a `HashWithIndifferentAccess`.
* '''Validation''': Ensure the returned payload matches the expected data.

'''Expired Token Test:'''
* '''Input''': A token with an `exp` claim that has already passed.
* '''Expected Output''': `nil` with an appropriate error logged.
* '''Validation''': Confirm that the method gracefully handles expired tokens.

'''Invalid Token Test:'''
* '''Input''': A tampered JWT token with an invalid signature.
* '''Expected Output''': `nil`.
* '''Validation''': Ensure an appropriate error message is logged, and sensitive information is not exposed.

'''Missing Claims Test:'''
* '''Input''': A valid token missing critical claims like `role`.
* '''Expected Output''': `nil`.
* '''Validation''': Ensure the method flags the token as invalid due to missing data.

==== Tests for check_user_privileges ====
'''Sufficient Privileges Test:'''
* '''Input''': User info with `role` as `Admin` and a `required_privilege` of `Student`.
* '''Expected Output''': `true`.
* '''Validation''': Verify the method correctly interprets hierarchical roles.

'''Insufficient Privileges Test:'''
* '''Input''': User info with `role` as `Student` and a `required_privilege` of `Instructor`.
* '''Expected Output''': `false`.
* '''Validation''': Ensure the method denies access for insufficient privileges.

'''Missing Role Test:'''
* '''Input''': User info without a `role` claim.
* '''Expected Output''': `false`.
* '''Validation''': Ensure the method handles missing roles gracefully.

==== Tests for current_user_is_a? ====
'''Correct Role Test:'''
* '''Input''': Token with `role` as `Instructor` and `role_name` as `Instructor`.
* '''Expected Output''': `true`.
* '''Validation''': Verify the method returns `true` when roles match exactly.

'''Incorrect Role Test:'''
* '''Input''': Token with `role` as `TA` and `role_name` as `Instructor`.
* '''Expected Output''': `false`.
* '''Validation''': Ensure the method denies access when roles don’t match.

'''Missing Token Test:'''
* '''Input''': `nil` token.
* '''Expected Output''': `false`.
* '''Validation''': Confirm that the method handles missing tokens properly.

---

=== Integration Tests ===
'''Definition''': Integration tests validate that the `AuthorizationHelper` module functions correctly within the context of the overall system.

==== Approach Options ====
1. '''Creating a Dummy API''':
* A lightweight API will be created specifically for testing the `AuthorizationHelper` methods.
* This API will simulate requests requiring token authentication and privilege checks.
* '''Advantages''':
** Fully isolated testing environment.
** Flexibility to simulate different roles, tokens, and scenarios.
* '''Disadvantages''':
** Requires additional setup and may not reflect real-world behavior perfectly.

2. '''Implementing a New Controller in Expertiza''':
* A controller will be added to the existing Expertiza application that uses the refactored `AuthorizationHelper`.
* This ensures that tests occur in a real-world context, validating interactions with the actual system.
* '''Advantages''':
** Validates the actual behavior of the module within the system.
** Reflects real application workflows and edge cases.
* '''Disadvantages''':
** Potentially affects other parts of the application during testing.
** Requires effort to ensure test isolation.

==== Integration Test Cases ====
'''API Endpoint Authentication'''
* '''Valid Token Test''':
** '''Scenario''': Send a valid JWT token to a protected endpoint.
** '''Expected Outcome''': HTTP 200 OK with access granted.
** '''Validation''': Confirm the user is authenticated and receives the correct resource.

* '''Expired Token Test''':
** '''Scenario''': Send an expired JWT token to a protected endpoint.
** '''Expected Outcome''': HTTP 401 Unauthorized.
** '''Validation''': Ensure the system blocks access and provides a proper error message.

* '''Tampered Token Test''':
** '''Scenario''': Send a tampered token with an invalid signature.
** '''Expected Outcome''': HTTP 401 Unauthorized.
** '''Validation''': Confirm the system denies access and logs the attempt securely.

* '''Missing Token Test''':
** '''Scenario''': Make a request without providing a token.
** '''Expected Outcome''': HTTP 401 Unauthorized.
** '''Validation''': Verify that token authentication is strictly enforced.

== Team ==
===Mentor===
*Kashika Mallick (kmallick@ncsu.edu)

===Members===
*Shafa Hassan (shassa22@ncsu.edu)
*Archit Gupta (agupta85@ncsu.edu)
*Ansh Ganatra (aganatr@ncsu.edu)

CSC/ECE 517 Fall 2024 - E2487. Reimplement authorization helper.rb

2024-12-03T21:37:56Z

Agupta85: /* Existing File Updates */

== Introduction ==
Expertiza currently uses session-based authentication in its AuthorizationHelper module. However, the new back-end reimplementation adopts JSON Web Token (JWT) for authentication. This transition is necessary to make the system more scalable, stateless, and secure. JWT-based authentication will replace session-based methods, requiring updates to the AuthorizationHelper module and associated methods.

== Background ==
The AuthorizationHelper module in Expertiza plays a critical role in managing user permissions and access control within the system. It provides methods to verify a user’s privileges based on their assigned roles, such as Super-Admin, Admin, Instructor, TA, or Student. These methods check if the user is authorized to perform actions like submitting assignments, reviewing work, or participating in quizzes. Additionally, it determines whether a user is involved in specific assignments, either as a participant, instructor, or through TA mappings.

==Problem Statement==

Expertiza currently uses session-based authentication in its [[https://github.com/expertiza/expertiza/blob/main/app/helpers/authorization_helper.rb AuthorizationHelper]] module. The [[https://github.com/expertiza/reimplementation-back-end reimplementation-back-end]] however, uses JWT (JSON Web Token) based authentication. This requires a reimplementation of an authorization concern module to accommodate JWT-based authentication

===Concerns===

A concern is a module that you extract to split the implementation of a class or module in coherent chunks, instead of having one big class body. Our new authorization module will be implemented as a concern which will work in tandem with the already-implemented [[https://github.com/expertiza/reimplementation-back-end/blob/main/app/controllers/concerns/jwt_token.rb JWT Concern]]

The following points need to be taken care of as per the requirement

* Role Management :
** Enable the system to process, verify, and decode roles from JWT Tokens.
** Use token role data to authenticate and authorize user actions.

* Privilege Verification :
** Update methods to validate user privileges using JWT claims.

* Testing and Documentation :
** Write comprehensive unit tests for all JWT-related methods.
** Include clear documentation and comments to aid future developers.

=Implemented Changes=

== JWT Token Overview ==

A JSON Web Token (JWT) is a compact, URL-safe token format commonly used for securely transmitting information between parties. It is widely used in web applications for authentication and authorization, as it allows information to be verified and trusted. In the context of our reimplemented AuthorizationHelper module, JWT tokens will replace session-based authentication, enabling stateless and more secure access control.

A JWT Token consists of three main parts:

*Header: Contains metadata about the token, such as the type (JWT) and the hashing algorithm used (e.g., HS256 or RS256).
*Payload: Includes claims, which are statements about an entity (typically, the user) and additional data like the user’s role and permissions.
*Signature: A cryptographic signature generated by encoding the header and payload with a secret key or private key, ensuring data integrity.
These three sections are separated by dots (.), forming a token that looks like this: <Header>.<Payload>.<Signature>

[[File:JWT-Workflow.png|500px|center]]

==Methods Implemented==

* has_required_role?(required_role):

<pre>

def has_required_role?(required_role)
required_role = Role.find_by_name(required_role) if required_role.is_a?(String)
current_user&.role&.all_privileges_of?(required_role) || false
end

</pre>

This function checks if the current user has the required role or higher privileges. The role name is passed down as a parameter in required_role which is the minimum required role level for an action

For example:

<pre>has_required_role?('Administrator') # Checks if user is an admin or higher</pre>

<pre>has_required_role?(Role::INSTRUCTOR) # Checks if user is an instructor or higher</pre>

For exact role requirements, we also have:
* is_role?(required_role):

<pre>

def is_role?(required_role)
required_role = required_role.name if required_role.is_a?(Role)
current_user&.role&.name == required_role
end

</pre>

which checks if the user has exactly the specified role. For example:

<pre>is_role?('Student') # True only if user is exactly a student </pre>

Finally, we have authorization methods which work with the ApplicationController as well as individual resource controllers:

<pre>
# Authorize all actions
def authorize
unless all_actions_allowed?
render json: {
error: "You are not authorized to #{params[:action]} this #{params[:controller]}"
}, status: :forbidden
end
end

# Check if all actions are allowed
def all_actions_allowed?
return true if has_required_role?('Administrator')
action_allowed?
end

# Base action_allowed? - allows everything by default
# Controllers should override this method to implement their authorization logic
def action_allowed?
true
end
</pre>

The individual resource controllers can then override the method 'action_allowed?' to manage access. For example:

<pre>
def action_allowed?
has_required_role?('Instructor')
end
</pre>

==Existing File Updates==

* current_user_is_a?(role_name):
<pre>
def current_user_is_a?(role_name)
current_user_and_role_exist? && session[:user].role.name == role_name
end
</pre>

Currently this method relies on the session variable which is populated at the time of login to determine the role of a user. This would have to be updated to decode the user's role from the JWT payload

* user_logged_in?:
<pre>
def user_logged_in?
!session[:user].nil?
end
</pre>
This method will have to be updated to check the user's login status based on JWT validity

* current_user_has_privileges_of?(role_name)
<pre>
def current_user_has_privileges_of?(role_name)
current_user_and_role_exist? && session[:user].role.has_all_privileges_of?(Role.find_by(name: role_name))
end
</pre>

Needs to remove dependency on session variable and get user information from the JWT's decoded payload

* current_user_and_role_exist?
<pre>
def current_user_and_role_exist?
user_logged_in? && !session[:user].role.nil?
end
</pre>

Similarly, the role here needs to be checked from the JWT payload
Similarly methods like current_user_has_id?(id) will also have to be updated to remove dependencies from the session object, which are all part of the [[https://github.com/expertiza/expertiza/blob/main/app/helpers/authorization_helper.rb| AuthorizationHelper]] module

==Anticipated Outcomes==
1. Enhanced AuthorizationHelper Module with JWT Integration: 
Updated and operational AuthorizationHelper module that would use JWT-based authentication. The module would be restructured to incorporate token-based authentication checks, replacing prior session-based methods.

2. Updated Associated Methods: 
Methods within the module will have to be updated to leverage JWT claims, ensuring authentication and authorization are handled based on token data. This will allow the module to verify user roles and permissions effectively through JWT claims.

3. Comprehensive JWT Error Handling: 
Built-in error handling to manage potential JWT-related issues, such as token expiration, tampering, or invalid claims. This ensures that unauthorized access is
blocked, and clear error messages are provided when issues arise.

4. Robust Unit Tests for Validation: 
A full suite of unit tests covering various scenarios, including normal, boundary, and edge cases, to validate each method’s functionality and confirm that all
JWT-based authentication flows work reliably.

5. Detailed Documentation and Code Comments: 
In-depth documentation and comments would be added to each function, explaining purpose, usage, and JWT-related adjustments, aiding in code readability and future
maintenance.

== Design Principles ==
The redesign of the `AuthorizationHelper` module for JWT-based authentication will follow well-established design principles to ensure the solution is secure, maintainable, and scalable. Below are the key principles to be applied and how they will shape this redesign:

1. '''Single Responsibility Principle (SRP)'''
* '''Definition''': Each module or class should have one clear responsibility.
* '''How It’s Applied''': The `AuthorizationHelper` module focuses only on managing authentication and authorization, separating these concerns into distinct methods. For instance, `jwt_verify_and_decode` handles token verification, while `check_user_privileges` focuses on role-based checks. This keeps the code clean and easier to maintain.

2. '''Separation of Concerns'''
* '''Definition''': Different aspects of the system should be handled independently.
* '''How It’s Applied''': JWT-related tasks like token creation and decoding are delegated to the `JsonWebToken` class, while privilege checking and user role management remain within `AuthorizationHelper`. This modular approach ensures changes in one area don’t unnecessarily affect the other.

3. '''Security by Design'''
* '''Definition''': Security should be built into the system from the start, not as an afterthought.
* '''How It’s Applied''': JWT tokens are validated for expiry and tampering before any actions are authorized. Sensitive data like secret keys is securely stored in environment variables, and communication involving tokens is secured using HTTPS. The system also uses role-based access control (RBAC) to enforce fine-grained permissions.

4. '''Statelessness'''
* '''Definition''': The system should not depend on maintaining user-specific data on the server.
* '''How It’s Applied''': By using JWT, all necessary information about the user is encoded in the token itself. This removes the dependency on server-side session storage, making the system scalable and suitable for distributed architectures.

5. '''Testability'''
* '''Definition''': Code should be designed to make testing straightforward and effective.
* '''How It’s Applied''': Each method has a single responsibility, making it easier to write focused tests. The modular design allows us to test components like token verification and privilege checking independently, while mock tokens can simulate various scenarios (valid, expired, tampered).

---

== Test Plan ==

=== Unit Tests ===
'''Definition''': Unit tests verify that individual methods work correctly in isolation under different scenarios.

==== Tests for jwt_verify_and_decode ====
'''Valid Token Test:'''
* '''Input''': A valid JWT token with claims like `id`, `role`, and `exp`.
* '''Expected Output''': Decoded payload as a `HashWithIndifferentAccess`.
* '''Validation''': Ensure the returned payload matches the expected data.

'''Expired Token Test:'''
* '''Input''': A token with an `exp` claim that has already passed.
* '''Expected Output''': `nil` with an appropriate error logged.
* '''Validation''': Confirm that the method gracefully handles expired tokens.

'''Invalid Token Test:'''
* '''Input''': A tampered JWT token with an invalid signature.
* '''Expected Output''': `nil`.
* '''Validation''': Ensure an appropriate error message is logged, and sensitive information is not exposed.

'''Missing Claims Test:'''
* '''Input''': A valid token missing critical claims like `role`.
* '''Expected Output''': `nil`.
* '''Validation''': Ensure the method flags the token as invalid due to missing data.

==== Tests for check_user_privileges ====
'''Sufficient Privileges Test:'''
* '''Input''': User info with `role` as `Admin` and a `required_privilege` of `Student`.
* '''Expected Output''': `true`.
* '''Validation''': Verify the method correctly interprets hierarchical roles.

'''Insufficient Privileges Test:'''
* '''Input''': User info with `role` as `Student` and a `required_privilege` of `Instructor`.
* '''Expected Output''': `false`.
* '''Validation''': Ensure the method denies access for insufficient privileges.

'''Missing Role Test:'''
* '''Input''': User info without a `role` claim.
* '''Expected Output''': `false`.
* '''Validation''': Ensure the method handles missing roles gracefully.

==== Tests for current_user_is_a? ====
'''Correct Role Test:'''
* '''Input''': Token with `role` as `Instructor` and `role_name` as `Instructor`.
* '''Expected Output''': `true`.
* '''Validation''': Verify the method returns `true` when roles match exactly.

'''Incorrect Role Test:'''
* '''Input''': Token with `role` as `TA` and `role_name` as `Instructor`.
* '''Expected Output''': `false`.
* '''Validation''': Ensure the method denies access when roles don’t match.

'''Missing Token Test:'''
* '''Input''': `nil` token.
* '''Expected Output''': `false`.
* '''Validation''': Confirm that the method handles missing tokens properly.

---

=== Integration Tests ===
'''Definition''': Integration tests validate that the `AuthorizationHelper` module functions correctly within the context of the overall system.

==== Approach Options ====
1. '''Creating a Dummy API''':
* A lightweight API will be created specifically for testing the `AuthorizationHelper` methods.
* This API will simulate requests requiring token authentication and privilege checks.
* '''Advantages''':
** Fully isolated testing environment.
** Flexibility to simulate different roles, tokens, and scenarios.
* '''Disadvantages''':
** Requires additional setup and may not reflect real-world behavior perfectly.

2. '''Implementing a New Controller in Expertiza''':
* A controller will be added to the existing Expertiza application that uses the refactored `AuthorizationHelper`.
* This ensures that tests occur in a real-world context, validating interactions with the actual system.
* '''Advantages''':
** Validates the actual behavior of the module within the system.
** Reflects real application workflows and edge cases.
* '''Disadvantages''':
** Potentially affects other parts of the application during testing.
** Requires effort to ensure test isolation.

==== Integration Test Cases ====
'''API Endpoint Authentication'''
* '''Valid Token Test''':
** '''Scenario''': Send a valid JWT token to a protected endpoint.
** '''Expected Outcome''': HTTP 200 OK with access granted.
** '''Validation''': Confirm the user is authenticated and receives the correct resource.

* '''Expired Token Test''':
** '''Scenario''': Send an expired JWT token to a protected endpoint.
** '''Expected Outcome''': HTTP 401 Unauthorized.
** '''Validation''': Ensure the system blocks access and provides a proper error message.

* '''Tampered Token Test''':
** '''Scenario''': Send a tampered token with an invalid signature.
** '''Expected Outcome''': HTTP 401 Unauthorized.
** '''Validation''': Confirm the system denies access and logs the attempt securely.

* '''Missing Token Test''':
** '''Scenario''': Make a request without providing a token.
** '''Expected Outcome''': HTTP 401 Unauthorized.
** '''Validation''': Verify that token authentication is strictly enforced.

== Team ==
===Mentor===
*Kashika Mallick (kmallick@ncsu.edu)

===Members===
*Shafa Hassan (shassa22@ncsu.edu)
*Archit Gupta (agupta85@ncsu.edu)
*Ansh Ganatra (aganatr@ncsu.edu)

CSC/ECE 517 Fall 2024 - E2487. Reimplement authorization helper.rb

2024-12-03T21:36:55Z

Agupta85: /* Methods Implemented */

== Introduction ==
Expertiza currently uses session-based authentication in its AuthorizationHelper module. However, the new back-end reimplementation adopts JSON Web Token (JWT) for authentication. This transition is necessary to make the system more scalable, stateless, and secure. JWT-based authentication will replace session-based methods, requiring updates to the AuthorizationHelper module and associated methods.

== Background ==
The AuthorizationHelper module in Expertiza plays a critical role in managing user permissions and access control within the system. It provides methods to verify a user’s privileges based on their assigned roles, such as Super-Admin, Admin, Instructor, TA, or Student. These methods check if the user is authorized to perform actions like submitting assignments, reviewing work, or participating in quizzes. Additionally, it determines whether a user is involved in specific assignments, either as a participant, instructor, or through TA mappings.

==Problem Statement==

Expertiza currently uses session-based authentication in its [[https://github.com/expertiza/expertiza/blob/main/app/helpers/authorization_helper.rb AuthorizationHelper]] module. The [[https://github.com/expertiza/reimplementation-back-end reimplementation-back-end]] however, uses JWT (JSON Web Token) based authentication. This requires a reimplementation of an authorization concern module to accommodate JWT-based authentication

===Concerns===

A concern is a module that you extract to split the implementation of a class or module in coherent chunks, instead of having one big class body. Our new authorization module will be implemented as a concern which will work in tandem with the already-implemented [[https://github.com/expertiza/reimplementation-back-end/blob/main/app/controllers/concerns/jwt_token.rb JWT Concern]]

The following points need to be taken care of as per the requirement

* Role Management :
** Enable the system to process, verify, and decode roles from JWT Tokens.
** Use token role data to authenticate and authorize user actions.

* Privilege Verification :
** Update methods to validate user privileges using JWT claims.

* Testing and Documentation :
** Write comprehensive unit tests for all JWT-related methods.
** Include clear documentation and comments to aid future developers.

=Implemented Changes=

== JWT Token Overview ==

A JSON Web Token (JWT) is a compact, URL-safe token format commonly used for securely transmitting information between parties. It is widely used in web applications for authentication and authorization, as it allows information to be verified and trusted. In the context of our reimplemented AuthorizationHelper module, JWT tokens will replace session-based authentication, enabling stateless and more secure access control.

A JWT Token consists of three main parts:

*Header: Contains metadata about the token, such as the type (JWT) and the hashing algorithm used (e.g., HS256 or RS256).
*Payload: Includes claims, which are statements about an entity (typically, the user) and additional data like the user’s role and permissions.
*Signature: A cryptographic signature generated by encoding the header and payload with a secret key or private key, ensuring data integrity.
These three sections are separated by dots (.), forming a token that looks like this: <Header>.<Payload>.<Signature>

[[File:JWT-Workflow.png|500px|center]]

==Methods Implemented==

* has_required_role?(required_role):

<pre>

def has_required_role?(required_role)
required_role = Role.find_by_name(required_role) if required_role.is_a?(String)
current_user&.role&.all_privileges_of?(required_role) || false
end

</pre>

This function checks if the current user has the required role or higher privileges. The role name is passed down as a parameter in required_role which is the minimum required role level for an action

For example:

<pre>has_required_role?('Administrator') # Checks if user is an admin or higher</pre>

<pre>has_required_role?(Role::INSTRUCTOR) # Checks if user is an instructor or higher</pre>

For exact role requirements, we also have:
* is_role?(required_role):

<pre>

def is_role?(required_role)
required_role = required_role.name if required_role.is_a?(Role)
current_user&.role&.name == required_role
end

</pre>

which checks if the user has exactly the specified role. For example:

<pre>is_role?('Student') # True only if user is exactly a student </pre>

Finally, we have authorization methods which work with the ApplicationController as well as individual resource controllers:

<pre>
# Authorize all actions
def authorize
unless all_actions_allowed?
render json: {
error: "You are not authorized to #{params[:action]} this #{params[:controller]}"
}, status: :forbidden
end
end

# Check if all actions are allowed
def all_actions_allowed?
return true if has_required_role?('Administrator')
action_allowed?
end

# Base action_allowed? - allows everything by default
# Controllers should override this method to implement their authorization logic
def action_allowed?
true
end
</pre>

The individual resource controllers can then override the method 'action_allowed?' to manage access. For example:

<pre>
def action_allowed?
has_required_role?('Instructor')
end
</pre>

==Existing Methods to update==

* current_user_is_a?(role_name):
<pre>
def current_user_is_a?(role_name)
current_user_and_role_exist? && session[:user].role.name == role_name
end
</pre>

Currently this method relies on the session variable which is populated at the time of login to determine the role of a user. This would have to be updated to decode the user's role from the JWT payload

* user_logged_in?:
<pre>
def user_logged_in?
!session[:user].nil?
end
</pre>
This method will have to be updated to check the user's login status based on JWT validity

* current_user_has_privileges_of?(role_name)
<pre>
def current_user_has_privileges_of?(role_name)
current_user_and_role_exist? && session[:user].role.has_all_privileges_of?(Role.find_by(name: role_name))
end
</pre>

Needs to remove dependency on session variable and get user information from the JWT's decoded payload

* current_user_and_role_exist?
<pre>
def current_user_and_role_exist?
user_logged_in? && !session[:user].role.nil?
end
</pre>

Similarly, the role here needs to be checked from the JWT payload
Similarly methods like current_user_has_id?(id) will also have to be updated to remove dependencies from the session object, which are all part of the [[https://github.com/expertiza/expertiza/blob/main/app/helpers/authorization_helper.rb| AuthorizationHelper]] module

==Anticipated Outcomes==
1. Enhanced AuthorizationHelper Module with JWT Integration: 
Updated and operational AuthorizationHelper module that would use JWT-based authentication. The module would be restructured to incorporate token-based authentication checks, replacing prior session-based methods.

2. Updated Associated Methods: 
Methods within the module will have to be updated to leverage JWT claims, ensuring authentication and authorization are handled based on token data. This will allow the module to verify user roles and permissions effectively through JWT claims.

3. Comprehensive JWT Error Handling: 
Built-in error handling to manage potential JWT-related issues, such as token expiration, tampering, or invalid claims. This ensures that unauthorized access is
blocked, and clear error messages are provided when issues arise.

4. Robust Unit Tests for Validation: 
A full suite of unit tests covering various scenarios, including normal, boundary, and edge cases, to validate each method’s functionality and confirm that all
JWT-based authentication flows work reliably.

5. Detailed Documentation and Code Comments: 
In-depth documentation and comments would be added to each function, explaining purpose, usage, and JWT-related adjustments, aiding in code readability and future
maintenance.

== Design Principles ==
The redesign of the `AuthorizationHelper` module for JWT-based authentication will follow well-established design principles to ensure the solution is secure, maintainable, and scalable. Below are the key principles to be applied and how they will shape this redesign:

1. '''Single Responsibility Principle (SRP)'''
* '''Definition''': Each module or class should have one clear responsibility.
* '''How It’s Applied''': The `AuthorizationHelper` module focuses only on managing authentication and authorization, separating these concerns into distinct methods. For instance, `jwt_verify_and_decode` handles token verification, while `check_user_privileges` focuses on role-based checks. This keeps the code clean and easier to maintain.

2. '''Separation of Concerns'''
* '''Definition''': Different aspects of the system should be handled independently.
* '''How It’s Applied''': JWT-related tasks like token creation and decoding are delegated to the `JsonWebToken` class, while privilege checking and user role management remain within `AuthorizationHelper`. This modular approach ensures changes in one area don’t unnecessarily affect the other.

3. '''Security by Design'''
* '''Definition''': Security should be built into the system from the start, not as an afterthought.
* '''How It’s Applied''': JWT tokens are validated for expiry and tampering before any actions are authorized. Sensitive data like secret keys is securely stored in environment variables, and communication involving tokens is secured using HTTPS. The system also uses role-based access control (RBAC) to enforce fine-grained permissions.

4. '''Statelessness'''
* '''Definition''': The system should not depend on maintaining user-specific data on the server.
* '''How It’s Applied''': By using JWT, all necessary information about the user is encoded in the token itself. This removes the dependency on server-side session storage, making the system scalable and suitable for distributed architectures.

5. '''Testability'''
* '''Definition''': Code should be designed to make testing straightforward and effective.
* '''How It’s Applied''': Each method has a single responsibility, making it easier to write focused tests. The modular design allows us to test components like token verification and privilege checking independently, while mock tokens can simulate various scenarios (valid, expired, tampered).

---

== Test Plan ==

=== Unit Tests ===
'''Definition''': Unit tests verify that individual methods work correctly in isolation under different scenarios.

==== Tests for jwt_verify_and_decode ====
'''Valid Token Test:'''
* '''Input''': A valid JWT token with claims like `id`, `role`, and `exp`.
* '''Expected Output''': Decoded payload as a `HashWithIndifferentAccess`.
* '''Validation''': Ensure the returned payload matches the expected data.

'''Expired Token Test:'''
* '''Input''': A token with an `exp` claim that has already passed.
* '''Expected Output''': `nil` with an appropriate error logged.
* '''Validation''': Confirm that the method gracefully handles expired tokens.

'''Invalid Token Test:'''
* '''Input''': A tampered JWT token with an invalid signature.
* '''Expected Output''': `nil`.
* '''Validation''': Ensure an appropriate error message is logged, and sensitive information is not exposed.

'''Missing Claims Test:'''
* '''Input''': A valid token missing critical claims like `role`.
* '''Expected Output''': `nil`.
* '''Validation''': Ensure the method flags the token as invalid due to missing data.

==== Tests for check_user_privileges ====
'''Sufficient Privileges Test:'''
* '''Input''': User info with `role` as `Admin` and a `required_privilege` of `Student`.
* '''Expected Output''': `true`.
* '''Validation''': Verify the method correctly interprets hierarchical roles.

'''Insufficient Privileges Test:'''
* '''Input''': User info with `role` as `Student` and a `required_privilege` of `Instructor`.
* '''Expected Output''': `false`.
* '''Validation''': Ensure the method denies access for insufficient privileges.

'''Missing Role Test:'''
* '''Input''': User info without a `role` claim.
* '''Expected Output''': `false`.
* '''Validation''': Ensure the method handles missing roles gracefully.

==== Tests for current_user_is_a? ====
'''Correct Role Test:'''
* '''Input''': Token with `role` as `Instructor` and `role_name` as `Instructor`.
* '''Expected Output''': `true`.
* '''Validation''': Verify the method returns `true` when roles match exactly.

'''Incorrect Role Test:'''
* '''Input''': Token with `role` as `TA` and `role_name` as `Instructor`.
* '''Expected Output''': `false`.
* '''Validation''': Ensure the method denies access when roles don’t match.

'''Missing Token Test:'''
* '''Input''': `nil` token.
* '''Expected Output''': `false`.
* '''Validation''': Confirm that the method handles missing tokens properly.

---

=== Integration Tests ===
'''Definition''': Integration tests validate that the `AuthorizationHelper` module functions correctly within the context of the overall system.

==== Approach Options ====
1. '''Creating a Dummy API''':
* A lightweight API will be created specifically for testing the `AuthorizationHelper` methods.
* This API will simulate requests requiring token authentication and privilege checks.
* '''Advantages''':
** Fully isolated testing environment.
** Flexibility to simulate different roles, tokens, and scenarios.
* '''Disadvantages''':
** Requires additional setup and may not reflect real-world behavior perfectly.

2. '''Implementing a New Controller in Expertiza''':
* A controller will be added to the existing Expertiza application that uses the refactored `AuthorizationHelper`.
* This ensures that tests occur in a real-world context, validating interactions with the actual system.
* '''Advantages''':
** Validates the actual behavior of the module within the system.
** Reflects real application workflows and edge cases.
* '''Disadvantages''':
** Potentially affects other parts of the application during testing.
** Requires effort to ensure test isolation.

==== Integration Test Cases ====
'''API Endpoint Authentication'''
* '''Valid Token Test''':
** '''Scenario''': Send a valid JWT token to a protected endpoint.
** '''Expected Outcome''': HTTP 200 OK with access granted.
** '''Validation''': Confirm the user is authenticated and receives the correct resource.

* '''Expired Token Test''':
** '''Scenario''': Send an expired JWT token to a protected endpoint.
** '''Expected Outcome''': HTTP 401 Unauthorized.
** '''Validation''': Ensure the system blocks access and provides a proper error message.

* '''Tampered Token Test''':
** '''Scenario''': Send a tampered token with an invalid signature.
** '''Expected Outcome''': HTTP 401 Unauthorized.
** '''Validation''': Confirm the system denies access and logs the attempt securely.

* '''Missing Token Test''':
** '''Scenario''': Make a request without providing a token.
** '''Expected Outcome''': HTTP 401 Unauthorized.
** '''Validation''': Verify that token authentication is strictly enforced.

== Team ==
===Mentor===
*Kashika Mallick (kmallick@ncsu.edu)

===Members===
*Shafa Hassan (shassa22@ncsu.edu)
*Archit Gupta (agupta85@ncsu.edu)
*Ansh Ganatra (aganatr@ncsu.edu)

CSC/ECE 517 Fall 2024 - E2487. Reimplement authorization helper.rb

2024-12-03T21:29:57Z

Agupta85: /* Methods to implement */

== Introduction ==
Expertiza currently uses session-based authentication in its AuthorizationHelper module. However, the new back-end reimplementation adopts JSON Web Token (JWT) for authentication. This transition is necessary to make the system more scalable, stateless, and secure. JWT-based authentication will replace session-based methods, requiring updates to the AuthorizationHelper module and associated methods.

== Background ==
The AuthorizationHelper module in Expertiza plays a critical role in managing user permissions and access control within the system. It provides methods to verify a user’s privileges based on their assigned roles, such as Super-Admin, Admin, Instructor, TA, or Student. These methods check if the user is authorized to perform actions like submitting assignments, reviewing work, or participating in quizzes. Additionally, it determines whether a user is involved in specific assignments, either as a participant, instructor, or through TA mappings.

==Problem Statement==

Expertiza currently uses session-based authentication in its [[https://github.com/expertiza/expertiza/blob/main/app/helpers/authorization_helper.rb AuthorizationHelper]] module. The [[https://github.com/expertiza/reimplementation-back-end reimplementation-back-end]] however, uses JWT (JSON Web Token) based authentication. This requires a reimplementation of an authorization concern module to accommodate JWT-based authentication

===Concerns===

A concern is a module that you extract to split the implementation of a class or module in coherent chunks, instead of having one big class body. Our new authorization module will be implemented as a concern which will work in tandem with the already-implemented [[https://github.com/expertiza/reimplementation-back-end/blob/main/app/controllers/concerns/jwt_token.rb JWT Concern]]

The following points need to be taken care of as per the requirement

* Role Management :
** Enable the system to process, verify, and decode roles from JWT Tokens.
** Use token role data to authenticate and authorize user actions.

* Privilege Verification :
** Update methods to validate user privileges using JWT claims.

* Testing and Documentation :
** Write comprehensive unit tests for all JWT-related methods.
** Include clear documentation and comments to aid future developers.

=Implemented Changes=

== JWT Token Overview ==

A JSON Web Token (JWT) is a compact, URL-safe token format commonly used for securely transmitting information between parties. It is widely used in web applications for authentication and authorization, as it allows information to be verified and trusted. In the context of our reimplemented AuthorizationHelper module, JWT tokens will replace session-based authentication, enabling stateless and more secure access control.

A JWT Token consists of three main parts:

*Header: Contains metadata about the token, such as the type (JWT) and the hashing algorithm used (e.g., HS256 or RS256).
*Payload: Includes claims, which are statements about an entity (typically, the user) and additional data like the user’s role and permissions.
*Signature: A cryptographic signature generated by encoding the header and payload with a secret key or private key, ensuring data integrity.
These three sections are separated by dots (.), forming a token that looks like this: <Header>.<Payload>.<Signature>

[[File:JWT-Workflow.png|500px|center]]

==Methods Implemented==

* has_required_role?(required_role):

<pre>

def has_required_role?(required_role)
required_role = Role.find_by_name(required_role) if required_role.is_a?(String)
current_user&.role&.all_privileges_of?(required_role) || false
end

</pre>

This function checks if the current user has the required role or higher privileges. The role name is passed down as a parameter in required_role which is the minimum required role level for an action

For example:

<pre>has_required_role?('Administrator') # Checks if user is an admin or higher</pre>

<pre>has_required_role?(Role::INSTRUCTOR) # Checks if user is an instructor or higher</pre>

For exact role requirements, we also have:
* is_role?(required_role):

<pre>

def is_role?(required_role)
required_role = required_role.name if required_role.is_a?(Role)
current_user&.role&.name == required_role
end

</pre>

which checks if the user has exactly the specified role. For example:

<pre>is_role?('Student') # True only if user is exactly a student </pre>

==Existing Methods to update==

* current_user_is_a?(role_name):
<pre>
def current_user_is_a?(role_name)
current_user_and_role_exist? && session[:user].role.name == role_name
end
</pre>

Currently this method relies on the session variable which is populated at the time of login to determine the role of a user. This would have to be updated to decode the user's role from the JWT payload

* user_logged_in?:
<pre>
def user_logged_in?
!session[:user].nil?
end
</pre>
This method will have to be updated to check the user's login status based on JWT validity

* current_user_has_privileges_of?(role_name)
<pre>
def current_user_has_privileges_of?(role_name)
current_user_and_role_exist? && session[:user].role.has_all_privileges_of?(Role.find_by(name: role_name))
end
</pre>

Needs to remove dependency on session variable and get user information from the JWT's decoded payload

* current_user_and_role_exist?
<pre>
def current_user_and_role_exist?
user_logged_in? && !session[:user].role.nil?
end
</pre>

Similarly, the role here needs to be checked from the JWT payload
Similarly methods like current_user_has_id?(id) will also have to be updated to remove dependencies from the session object, which are all part of the [[https://github.com/expertiza/expertiza/blob/main/app/helpers/authorization_helper.rb| AuthorizationHelper]] module

==Anticipated Outcomes==
1. Enhanced AuthorizationHelper Module with JWT Integration: 
Updated and operational AuthorizationHelper module that would use JWT-based authentication. The module would be restructured to incorporate token-based authentication checks, replacing prior session-based methods.

2. Updated Associated Methods: 
Methods within the module will have to be updated to leverage JWT claims, ensuring authentication and authorization are handled based on token data. This will allow the module to verify user roles and permissions effectively through JWT claims.

3. Comprehensive JWT Error Handling: 
Built-in error handling to manage potential JWT-related issues, such as token expiration, tampering, or invalid claims. This ensures that unauthorized access is
blocked, and clear error messages are provided when issues arise.

4. Robust Unit Tests for Validation: 
A full suite of unit tests covering various scenarios, including normal, boundary, and edge cases, to validate each method’s functionality and confirm that all
JWT-based authentication flows work reliably.

5. Detailed Documentation and Code Comments: 
In-depth documentation and comments would be added to each function, explaining purpose, usage, and JWT-related adjustments, aiding in code readability and future
maintenance.

== Design Principles ==
The redesign of the `AuthorizationHelper` module for JWT-based authentication will follow well-established design principles to ensure the solution is secure, maintainable, and scalable. Below are the key principles to be applied and how they will shape this redesign:

1. '''Single Responsibility Principle (SRP)'''
* '''Definition''': Each module or class should have one clear responsibility.
* '''How It’s Applied''': The `AuthorizationHelper` module focuses only on managing authentication and authorization, separating these concerns into distinct methods. For instance, `jwt_verify_and_decode` handles token verification, while `check_user_privileges` focuses on role-based checks. This keeps the code clean and easier to maintain.

2. '''Separation of Concerns'''
* '''Definition''': Different aspects of the system should be handled independently.
* '''How It’s Applied''': JWT-related tasks like token creation and decoding are delegated to the `JsonWebToken` class, while privilege checking and user role management remain within `AuthorizationHelper`. This modular approach ensures changes in one area don’t unnecessarily affect the other.

3. '''Security by Design'''
* '''Definition''': Security should be built into the system from the start, not as an afterthought.
* '''How It’s Applied''': JWT tokens are validated for expiry and tampering before any actions are authorized. Sensitive data like secret keys is securely stored in environment variables, and communication involving tokens is secured using HTTPS. The system also uses role-based access control (RBAC) to enforce fine-grained permissions.

4. '''Statelessness'''
* '''Definition''': The system should not depend on maintaining user-specific data on the server.
* '''How It’s Applied''': By using JWT, all necessary information about the user is encoded in the token itself. This removes the dependency on server-side session storage, making the system scalable and suitable for distributed architectures.

5. '''Testability'''
* '''Definition''': Code should be designed to make testing straightforward and effective.
* '''How It’s Applied''': Each method has a single responsibility, making it easier to write focused tests. The modular design allows us to test components like token verification and privilege checking independently, while mock tokens can simulate various scenarios (valid, expired, tampered).

---

== Test Plan ==

=== Unit Tests ===
'''Definition''': Unit tests verify that individual methods work correctly in isolation under different scenarios.

==== Tests for jwt_verify_and_decode ====
'''Valid Token Test:'''
* '''Input''': A valid JWT token with claims like `id`, `role`, and `exp`.
* '''Expected Output''': Decoded payload as a `HashWithIndifferentAccess`.
* '''Validation''': Ensure the returned payload matches the expected data.

'''Expired Token Test:'''
* '''Input''': A token with an `exp` claim that has already passed.
* '''Expected Output''': `nil` with an appropriate error logged.
* '''Validation''': Confirm that the method gracefully handles expired tokens.

'''Invalid Token Test:'''
* '''Input''': A tampered JWT token with an invalid signature.
* '''Expected Output''': `nil`.
* '''Validation''': Ensure an appropriate error message is logged, and sensitive information is not exposed.

'''Missing Claims Test:'''
* '''Input''': A valid token missing critical claims like `role`.
* '''Expected Output''': `nil`.
* '''Validation''': Ensure the method flags the token as invalid due to missing data.

==== Tests for check_user_privileges ====
'''Sufficient Privileges Test:'''
* '''Input''': User info with `role` as `Admin` and a `required_privilege` of `Student`.
* '''Expected Output''': `true`.
* '''Validation''': Verify the method correctly interprets hierarchical roles.

'''Insufficient Privileges Test:'''
* '''Input''': User info with `role` as `Student` and a `required_privilege` of `Instructor`.
* '''Expected Output''': `false`.
* '''Validation''': Ensure the method denies access for insufficient privileges.

'''Missing Role Test:'''
* '''Input''': User info without a `role` claim.
* '''Expected Output''': `false`.
* '''Validation''': Ensure the method handles missing roles gracefully.

==== Tests for current_user_is_a? ====
'''Correct Role Test:'''
* '''Input''': Token with `role` as `Instructor` and `role_name` as `Instructor`.
* '''Expected Output''': `true`.
* '''Validation''': Verify the method returns `true` when roles match exactly.

'''Incorrect Role Test:'''
* '''Input''': Token with `role` as `TA` and `role_name` as `Instructor`.
* '''Expected Output''': `false`.
* '''Validation''': Ensure the method denies access when roles don’t match.

'''Missing Token Test:'''
* '''Input''': `nil` token.
* '''Expected Output''': `false`.
* '''Validation''': Confirm that the method handles missing tokens properly.

---

=== Integration Tests ===
'''Definition''': Integration tests validate that the `AuthorizationHelper` module functions correctly within the context of the overall system.

==== Approach Options ====
1. '''Creating a Dummy API''':
* A lightweight API will be created specifically for testing the `AuthorizationHelper` methods.
* This API will simulate requests requiring token authentication and privilege checks.
* '''Advantages''':
** Fully isolated testing environment.
** Flexibility to simulate different roles, tokens, and scenarios.
* '''Disadvantages''':
** Requires additional setup and may not reflect real-world behavior perfectly.

2. '''Implementing a New Controller in Expertiza''':
* A controller will be added to the existing Expertiza application that uses the refactored `AuthorizationHelper`.
* This ensures that tests occur in a real-world context, validating interactions with the actual system.
* '''Advantages''':
** Validates the actual behavior of the module within the system.
** Reflects real application workflows and edge cases.
* '''Disadvantages''':
** Potentially affects other parts of the application during testing.
** Requires effort to ensure test isolation.

==== Integration Test Cases ====
'''API Endpoint Authentication'''
* '''Valid Token Test''':
** '''Scenario''': Send a valid JWT token to a protected endpoint.
** '''Expected Outcome''': HTTP 200 OK with access granted.
** '''Validation''': Confirm the user is authenticated and receives the correct resource.

* '''Expired Token Test''':
** '''Scenario''': Send an expired JWT token to a protected endpoint.
** '''Expected Outcome''': HTTP 401 Unauthorized.
** '''Validation''': Ensure the system blocks access and provides a proper error message.

* '''Tampered Token Test''':
** '''Scenario''': Send a tampered token with an invalid signature.
** '''Expected Outcome''': HTTP 401 Unauthorized.
** '''Validation''': Confirm the system denies access and logs the attempt securely.

* '''Missing Token Test''':
** '''Scenario''': Make a request without providing a token.
** '''Expected Outcome''': HTTP 401 Unauthorized.
** '''Validation''': Verify that token authentication is strictly enforced.

== Team ==
===Mentor===
*Kashika Mallick (kmallick@ncsu.edu)

===Members===
*Shafa Hassan (shassa22@ncsu.edu)
*Archit Gupta (agupta85@ncsu.edu)
*Ansh Ganatra (aganatr@ncsu.edu)

CSC/ECE 517 Fall 2024 - E2487. Reimplement authorization helper.rb

2024-12-03T21:08:34Z

Agupta85: /* Implemented Changes */

== Introduction ==
Expertiza currently uses session-based authentication in its AuthorizationHelper module. However, the new back-end reimplementation adopts JSON Web Token (JWT) for authentication. This transition is necessary to make the system more scalable, stateless, and secure. JWT-based authentication will replace session-based methods, requiring updates to the AuthorizationHelper module and associated methods.

== Background ==
The AuthorizationHelper module in Expertiza plays a critical role in managing user permissions and access control within the system. It provides methods to verify a user’s privileges based on their assigned roles, such as Super-Admin, Admin, Instructor, TA, or Student. These methods check if the user is authorized to perform actions like submitting assignments, reviewing work, or participating in quizzes. Additionally, it determines whether a user is involved in specific assignments, either as a participant, instructor, or through TA mappings.

==Problem Statement==

Expertiza currently uses session-based authentication in its [[https://github.com/expertiza/expertiza/blob/main/app/helpers/authorization_helper.rb AuthorizationHelper]] module. The [[https://github.com/expertiza/reimplementation-back-end reimplementation-back-end]] however, uses JWT (JSON Web Token) based authentication. This requires a reimplementation of an authorization concern module to accommodate JWT-based authentication

===Concerns===

A concern is a module that you extract to split the implementation of a class or module in coherent chunks, instead of having one big class body. Our new authorization module will be implemented as a concern which will work in tandem with the already-implemented [[https://github.com/expertiza/reimplementation-back-end/blob/main/app/controllers/concerns/jwt_token.rb JWT Concern]]

The following points need to be taken care of as per the requirement

* Role Management :
** Enable the system to process, verify, and decode roles from JWT Tokens.
** Use token role data to authenticate and authorize user actions.

* Privilege Verification :
** Update methods to validate user privileges using JWT claims.

* Testing and Documentation :
** Write comprehensive unit tests for all JWT-related methods.
** Include clear documentation and comments to aid future developers.

=Implemented Changes=

== JWT Token Overview ==

A JSON Web Token (JWT) is a compact, URL-safe token format commonly used for securely transmitting information between parties. It is widely used in web applications for authentication and authorization, as it allows information to be verified and trusted. In the context of our reimplemented AuthorizationHelper module, JWT tokens will replace session-based authentication, enabling stateless and more secure access control.

A JWT Token consists of three main parts:

*Header: Contains metadata about the token, such as the type (JWT) and the hashing algorithm used (e.g., HS256 or RS256).
*Payload: Includes claims, which are statements about an entity (typically, the user) and additional data like the user’s role and permissions.
*Signature: A cryptographic signature generated by encoding the header and payload with a secret key or private key, ensuring data integrity.
These three sections are separated by dots (.), forming a token that looks like this: <Header>.<Payload>.<Signature>

[[File:JWT-Workflow.png|500px|center]]

==Methods to implement==

* jwt_verify_and_decode(token): This method will verify and decode a JWT token and return the user's information, including role and claims. Successful verification of the token signature with the secret key will be followed by extraction of the payload which will contain important information about the user and their role for authentication and authorization.
* check_user_privileges(user_info, required_privilege): extract the user's roles or permissions from user_info (e.g., from the decoded JWT payload). Then, check if required_privilege exists within the user's permissions, returning true if it does and false otherwise to control access accordingly.

==Existing Methods to update==

* current_user_is_a?(role_name):
<pre>
def current_user_is_a?(role_name)
current_user_and_role_exist? && session[:user].role.name == role_name
end
</pre>

Currently this method relies on the session variable which is populated at the time of login to determine the role of a user. This would have to be updated to decode the user's role from the JWT payload

* user_logged_in?:
<pre>
def user_logged_in?
!session[:user].nil?
end
</pre>
This method will have to be updated to check the user's login status based on JWT validity

* current_user_has_privileges_of?(role_name)
<pre>
def current_user_has_privileges_of?(role_name)
current_user_and_role_exist? && session[:user].role.has_all_privileges_of?(Role.find_by(name: role_name))
end
</pre>

Needs to remove dependency on session variable and get user information from the JWT's decoded payload

* current_user_and_role_exist?
<pre>
def current_user_and_role_exist?
user_logged_in? && !session[:user].role.nil?
end
</pre>

Similarly, the role here needs to be checked from the JWT payload
Similarly methods like current_user_has_id?(id) will also have to be updated to remove dependencies from the session object, which are all part of the [[https://github.com/expertiza/expertiza/blob/main/app/helpers/authorization_helper.rb| AuthorizationHelper]] module

==Anticipated Outcomes==
1. Enhanced AuthorizationHelper Module with JWT Integration: 
Updated and operational AuthorizationHelper module that would use JWT-based authentication. The module would be restructured to incorporate token-based authentication checks, replacing prior session-based methods.

2. Updated Associated Methods: 
Methods within the module will have to be updated to leverage JWT claims, ensuring authentication and authorization are handled based on token data. This will allow the module to verify user roles and permissions effectively through JWT claims.

3. Comprehensive JWT Error Handling: 
Built-in error handling to manage potential JWT-related issues, such as token expiration, tampering, or invalid claims. This ensures that unauthorized access is
blocked, and clear error messages are provided when issues arise.

4. Robust Unit Tests for Validation: 
A full suite of unit tests covering various scenarios, including normal, boundary, and edge cases, to validate each method’s functionality and confirm that all
JWT-based authentication flows work reliably.

5. Detailed Documentation and Code Comments: 
In-depth documentation and comments would be added to each function, explaining purpose, usage, and JWT-related adjustments, aiding in code readability and future
maintenance.

== Design Principles ==
The redesign of the `AuthorizationHelper` module for JWT-based authentication will follow well-established design principles to ensure the solution is secure, maintainable, and scalable. Below are the key principles to be applied and how they will shape this redesign:

1. '''Single Responsibility Principle (SRP)'''
* '''Definition''': Each module or class should have one clear responsibility.
* '''How It’s Applied''': The `AuthorizationHelper` module focuses only on managing authentication and authorization, separating these concerns into distinct methods. For instance, `jwt_verify_and_decode` handles token verification, while `check_user_privileges` focuses on role-based checks. This keeps the code clean and easier to maintain.

2. '''Separation of Concerns'''
* '''Definition''': Different aspects of the system should be handled independently.
* '''How It’s Applied''': JWT-related tasks like token creation and decoding are delegated to the `JsonWebToken` class, while privilege checking and user role management remain within `AuthorizationHelper`. This modular approach ensures changes in one area don’t unnecessarily affect the other.

3. '''Security by Design'''
* '''Definition''': Security should be built into the system from the start, not as an afterthought.
* '''How It’s Applied''': JWT tokens are validated for expiry and tampering before any actions are authorized. Sensitive data like secret keys is securely stored in environment variables, and communication involving tokens is secured using HTTPS. The system also uses role-based access control (RBAC) to enforce fine-grained permissions.

4. '''Statelessness'''
* '''Definition''': The system should not depend on maintaining user-specific data on the server.
* '''How It’s Applied''': By using JWT, all necessary information about the user is encoded in the token itself. This removes the dependency on server-side session storage, making the system scalable and suitable for distributed architectures.

5. '''Testability'''
* '''Definition''': Code should be designed to make testing straightforward and effective.
* '''How It’s Applied''': Each method has a single responsibility, making it easier to write focused tests. The modular design allows us to test components like token verification and privilege checking independently, while mock tokens can simulate various scenarios (valid, expired, tampered).

---

== Test Plan ==

=== Unit Tests ===
'''Definition''': Unit tests verify that individual methods work correctly in isolation under different scenarios.

==== Tests for jwt_verify_and_decode ====
'''Valid Token Test:'''
* '''Input''': A valid JWT token with claims like `id`, `role`, and `exp`.
* '''Expected Output''': Decoded payload as a `HashWithIndifferentAccess`.
* '''Validation''': Ensure the returned payload matches the expected data.

'''Expired Token Test:'''
* '''Input''': A token with an `exp` claim that has already passed.
* '''Expected Output''': `nil` with an appropriate error logged.
* '''Validation''': Confirm that the method gracefully handles expired tokens.

'''Invalid Token Test:'''
* '''Input''': A tampered JWT token with an invalid signature.
* '''Expected Output''': `nil`.
* '''Validation''': Ensure an appropriate error message is logged, and sensitive information is not exposed.

'''Missing Claims Test:'''
* '''Input''': A valid token missing critical claims like `role`.
* '''Expected Output''': `nil`.
* '''Validation''': Ensure the method flags the token as invalid due to missing data.

==== Tests for check_user_privileges ====
'''Sufficient Privileges Test:'''
* '''Input''': User info with `role` as `Admin` and a `required_privilege` of `Student`.
* '''Expected Output''': `true`.
* '''Validation''': Verify the method correctly interprets hierarchical roles.

'''Insufficient Privileges Test:'''
* '''Input''': User info with `role` as `Student` and a `required_privilege` of `Instructor`.
* '''Expected Output''': `false`.
* '''Validation''': Ensure the method denies access for insufficient privileges.

'''Missing Role Test:'''
* '''Input''': User info without a `role` claim.
* '''Expected Output''': `false`.
* '''Validation''': Ensure the method handles missing roles gracefully.

==== Tests for current_user_is_a? ====
'''Correct Role Test:'''
* '''Input''': Token with `role` as `Instructor` and `role_name` as `Instructor`.
* '''Expected Output''': `true`.
* '''Validation''': Verify the method returns `true` when roles match exactly.

'''Incorrect Role Test:'''
* '''Input''': Token with `role` as `TA` and `role_name` as `Instructor`.
* '''Expected Output''': `false`.
* '''Validation''': Ensure the method denies access when roles don’t match.

'''Missing Token Test:'''
* '''Input''': `nil` token.
* '''Expected Output''': `false`.
* '''Validation''': Confirm that the method handles missing tokens properly.

---

=== Integration Tests ===
'''Definition''': Integration tests validate that the `AuthorizationHelper` module functions correctly within the context of the overall system.

==== Approach Options ====
1. '''Creating a Dummy API''':
* A lightweight API will be created specifically for testing the `AuthorizationHelper` methods.
* This API will simulate requests requiring token authentication and privilege checks.
* '''Advantages''':
** Fully isolated testing environment.
** Flexibility to simulate different roles, tokens, and scenarios.
* '''Disadvantages''':
** Requires additional setup and may not reflect real-world behavior perfectly.

2. '''Implementing a New Controller in Expertiza''':
* A controller will be added to the existing Expertiza application that uses the refactored `AuthorizationHelper`.
* This ensures that tests occur in a real-world context, validating interactions with the actual system.
* '''Advantages''':
** Validates the actual behavior of the module within the system.
** Reflects real application workflows and edge cases.
* '''Disadvantages''':
** Potentially affects other parts of the application during testing.
** Requires effort to ensure test isolation.

==== Integration Test Cases ====
'''API Endpoint Authentication'''
* '''Valid Token Test''':
** '''Scenario''': Send a valid JWT token to a protected endpoint.
** '''Expected Outcome''': HTTP 200 OK with access granted.
** '''Validation''': Confirm the user is authenticated and receives the correct resource.

* '''Expired Token Test''':
** '''Scenario''': Send an expired JWT token to a protected endpoint.
** '''Expected Outcome''': HTTP 401 Unauthorized.
** '''Validation''': Ensure the system blocks access and provides a proper error message.

* '''Tampered Token Test''':
** '''Scenario''': Send a tampered token with an invalid signature.
** '''Expected Outcome''': HTTP 401 Unauthorized.
** '''Validation''': Confirm the system denies access and logs the attempt securely.

* '''Missing Token Test''':
** '''Scenario''': Make a request without providing a token.
** '''Expected Outcome''': HTTP 401 Unauthorized.
** '''Validation''': Verify that token authentication is strictly enforced.

== Team ==
===Mentor===
*Kashika Mallick (kmallick@ncsu.edu)

===Members===
*Shafa Hassan (shassa22@ncsu.edu)
*Archit Gupta (agupta85@ncsu.edu)
*Ansh Ganatra (aganatr@ncsu.edu)

CSC/ECE 517 Fall 2024 - E2487. Reimplement authorization helper.rb

2024-12-03T20:58:26Z

Agupta85: /* Problem Statement */

== Introduction ==
Expertiza currently uses session-based authentication in its AuthorizationHelper module. However, the new back-end reimplementation adopts JSON Web Token (JWT) for authentication. This transition is necessary to make the system more scalable, stateless, and secure. JWT-based authentication will replace session-based methods, requiring updates to the AuthorizationHelper module and associated methods.

== Background ==
The AuthorizationHelper module in Expertiza plays a critical role in managing user permissions and access control within the system. It provides methods to verify a user’s privileges based on their assigned roles, such as Super-Admin, Admin, Instructor, TA, or Student. These methods check if the user is authorized to perform actions like submitting assignments, reviewing work, or participating in quizzes. Additionally, it determines whether a user is involved in specific assignments, either as a participant, instructor, or through TA mappings.

==Problem Statement==

Expertiza currently uses session-based authentication in its [[https://github.com/expertiza/expertiza/blob/main/app/helpers/authorization_helper.rb AuthorizationHelper]] module. The [[https://github.com/expertiza/reimplementation-back-end reimplementation-back-end]] however, uses JWT (JSON Web Token) based authentication. This requires a reimplementation of an authorization concern module to accommodate JWT-based authentication

===Concerns===

A concern is a module that you extract to split the implementation of a class or module in coherent chunks, instead of having one big class body. Our new authorization module will be implemented as a concern which will work in tandem with the already-implemented [[https://github.com/expertiza/reimplementation-back-end/blob/main/app/controllers/concerns/jwt_token.rb JWT Concern]]

The following points need to be taken care of as per the requirement

* Role Management :
** Enable the system to process, verify, and decode roles from JWT Tokens.
** Use token role data to authenticate and authorize user actions.

* Privilege Verification :
** Update methods to validate user privileges using JWT claims.

* Testing and Documentation :
** Write comprehensive unit tests for all JWT-related methods.
** Include clear documentation and comments to aid future developers.

=Proposed Changes=

== JWT Token Overview ==

A JSON Web Token (JWT) is a compact, URL-safe token format commonly used for securely transmitting information between parties. It is widely used in web applications for authentication and authorization, as it allows information to be verified and trusted. In the context of our reimplemented AuthorizationHelper module, JWT tokens will replace session-based authentication, enabling stateless and more secure access control.

A JWT Token consists of three main parts:

*Header: Contains metadata about the token, such as the type (JWT) and the hashing algorithm used (e.g., HS256 or RS256).
*Payload: Includes claims, which are statements about an entity (typically, the user) and additional data like the user’s role and permissions.
*Signature: A cryptographic signature generated by encoding the header and payload with a secret key or private key, ensuring data integrity.
These three sections are separated by dots (.), forming a token that looks like this: <Header>.<Payload>.<Signature>

[[File:JWT-Workflow.png|500px|center]]

==Methods to implement==

* jwt_verify_and_decode(token): This method will verify and decode a JWT token and return the user's information, including role and claims. Successful verification of the token signature with the secret key will be followed by extraction of the payload which will contain important information about the user and their role for authentication and authorization.
* check_user_privileges(user_info, required_privilege): extract the user's roles or permissions from user_info (e.g., from the decoded JWT payload). Then, check if required_privilege exists within the user's permissions, returning true if it does and false otherwise to control access accordingly.

==Existing Methods to update==

* current_user_is_a?(role_name):
<pre>
def current_user_is_a?(role_name)
current_user_and_role_exist? && session[:user].role.name == role_name
end
</pre>

Currently this method relies on the session variable which is populated at the time of login to determine the role of a user. This would have to be updated to decode the user's role from the JWT payload

* user_logged_in?:
<pre>
def user_logged_in?
!session[:user].nil?
end
</pre>
This method will have to be updated to check the user's login status based on JWT validity

* current_user_has_privileges_of?(role_name)
<pre>
def current_user_has_privileges_of?(role_name)
current_user_and_role_exist? && session[:user].role.has_all_privileges_of?(Role.find_by(name: role_name))
end
</pre>

Needs to remove dependency on session variable and get user information from the JWT's decoded payload

* current_user_and_role_exist?
<pre>
def current_user_and_role_exist?
user_logged_in? && !session[:user].role.nil?
end
</pre>

Similarly, the role here needs to be checked from the JWT payload
Similarly methods like current_user_has_id?(id) will also have to be updated to remove dependencies from the session object, which are all part of the [[https://github.com/expertiza/expertiza/blob/main/app/helpers/authorization_helper.rb| AuthorizationHelper]] module

==Anticipated Outcomes==
1. Enhanced AuthorizationHelper Module with JWT Integration: 
Updated and operational AuthorizationHelper module that would use JWT-based authentication. The module would be restructured to incorporate token-based authentication checks, replacing prior session-based methods.

2. Updated Associated Methods: 
Methods within the module will have to be updated to leverage JWT claims, ensuring authentication and authorization are handled based on token data. This will allow the module to verify user roles and permissions effectively through JWT claims.

3. Comprehensive JWT Error Handling: 
Built-in error handling to manage potential JWT-related issues, such as token expiration, tampering, or invalid claims. This ensures that unauthorized access is
blocked, and clear error messages are provided when issues arise.

4. Robust Unit Tests for Validation: 
A full suite of unit tests covering various scenarios, including normal, boundary, and edge cases, to validate each method’s functionality and confirm that all
JWT-based authentication flows work reliably.

5. Detailed Documentation and Code Comments: 
In-depth documentation and comments would be added to each function, explaining purpose, usage, and JWT-related adjustments, aiding in code readability and future
maintenance.

== Design Principles ==
The redesign of the `AuthorizationHelper` module for JWT-based authentication will follow well-established design principles to ensure the solution is secure, maintainable, and scalable. Below are the key principles to be applied and how they will shape this redesign:

1. '''Single Responsibility Principle (SRP)'''
* '''Definition''': Each module or class should have one clear responsibility.
* '''How It’s Applied''': The `AuthorizationHelper` module focuses only on managing authentication and authorization, separating these concerns into distinct methods. For instance, `jwt_verify_and_decode` handles token verification, while `check_user_privileges` focuses on role-based checks. This keeps the code clean and easier to maintain.

2. '''Separation of Concerns'''
* '''Definition''': Different aspects of the system should be handled independently.
* '''How It’s Applied''': JWT-related tasks like token creation and decoding are delegated to the `JsonWebToken` class, while privilege checking and user role management remain within `AuthorizationHelper`. This modular approach ensures changes in one area don’t unnecessarily affect the other.

3. '''Security by Design'''
* '''Definition''': Security should be built into the system from the start, not as an afterthought.
* '''How It’s Applied''': JWT tokens are validated for expiry and tampering before any actions are authorized. Sensitive data like secret keys is securely stored in environment variables, and communication involving tokens is secured using HTTPS. The system also uses role-based access control (RBAC) to enforce fine-grained permissions.

4. '''Statelessness'''
* '''Definition''': The system should not depend on maintaining user-specific data on the server.
* '''How It’s Applied''': By using JWT, all necessary information about the user is encoded in the token itself. This removes the dependency on server-side session storage, making the system scalable and suitable for distributed architectures.

5. '''Testability'''
* '''Definition''': Code should be designed to make testing straightforward and effective.
* '''How It’s Applied''': Each method has a single responsibility, making it easier to write focused tests. The modular design allows us to test components like token verification and privilege checking independently, while mock tokens can simulate various scenarios (valid, expired, tampered).

---

== Test Plan ==

=== Unit Tests ===
'''Definition''': Unit tests verify that individual methods work correctly in isolation under different scenarios.

==== Tests for jwt_verify_and_decode ====
'''Valid Token Test:'''
* '''Input''': A valid JWT token with claims like `id`, `role`, and `exp`.
* '''Expected Output''': Decoded payload as a `HashWithIndifferentAccess`.
* '''Validation''': Ensure the returned payload matches the expected data.

'''Expired Token Test:'''
* '''Input''': A token with an `exp` claim that has already passed.
* '''Expected Output''': `nil` with an appropriate error logged.
* '''Validation''': Confirm that the method gracefully handles expired tokens.

'''Invalid Token Test:'''
* '''Input''': A tampered JWT token with an invalid signature.
* '''Expected Output''': `nil`.
* '''Validation''': Ensure an appropriate error message is logged, and sensitive information is not exposed.

'''Missing Claims Test:'''
* '''Input''': A valid token missing critical claims like `role`.
* '''Expected Output''': `nil`.
* '''Validation''': Ensure the method flags the token as invalid due to missing data.

==== Tests for check_user_privileges ====
'''Sufficient Privileges Test:'''
* '''Input''': User info with `role` as `Admin` and a `required_privilege` of `Student`.
* '''Expected Output''': `true`.
* '''Validation''': Verify the method correctly interprets hierarchical roles.

'''Insufficient Privileges Test:'''
* '''Input''': User info with `role` as `Student` and a `required_privilege` of `Instructor`.
* '''Expected Output''': `false`.
* '''Validation''': Ensure the method denies access for insufficient privileges.

'''Missing Role Test:'''
* '''Input''': User info without a `role` claim.
* '''Expected Output''': `false`.
* '''Validation''': Ensure the method handles missing roles gracefully.

==== Tests for current_user_is_a? ====
'''Correct Role Test:'''
* '''Input''': Token with `role` as `Instructor` and `role_name` as `Instructor`.
* '''Expected Output''': `true`.
* '''Validation''': Verify the method returns `true` when roles match exactly.

'''Incorrect Role Test:'''
* '''Input''': Token with `role` as `TA` and `role_name` as `Instructor`.
* '''Expected Output''': `false`.
* '''Validation''': Ensure the method denies access when roles don’t match.

'''Missing Token Test:'''
* '''Input''': `nil` token.
* '''Expected Output''': `false`.
* '''Validation''': Confirm that the method handles missing tokens properly.

---

=== Integration Tests ===
'''Definition''': Integration tests validate that the `AuthorizationHelper` module functions correctly within the context of the overall system.

==== Approach Options ====
1. '''Creating a Dummy API''':
* A lightweight API will be created specifically for testing the `AuthorizationHelper` methods.
* This API will simulate requests requiring token authentication and privilege checks.
* '''Advantages''':
** Fully isolated testing environment.
** Flexibility to simulate different roles, tokens, and scenarios.
* '''Disadvantages''':
** Requires additional setup and may not reflect real-world behavior perfectly.

2. '''Implementing a New Controller in Expertiza''':
* A controller will be added to the existing Expertiza application that uses the refactored `AuthorizationHelper`.
* This ensures that tests occur in a real-world context, validating interactions with the actual system.
* '''Advantages''':
** Validates the actual behavior of the module within the system.
** Reflects real application workflows and edge cases.
* '''Disadvantages''':
** Potentially affects other parts of the application during testing.
** Requires effort to ensure test isolation.

==== Integration Test Cases ====
'''API Endpoint Authentication'''
* '''Valid Token Test''':
** '''Scenario''': Send a valid JWT token to a protected endpoint.
** '''Expected Outcome''': HTTP 200 OK with access granted.
** '''Validation''': Confirm the user is authenticated and receives the correct resource.

* '''Expired Token Test''':
** '''Scenario''': Send an expired JWT token to a protected endpoint.
** '''Expected Outcome''': HTTP 401 Unauthorized.
** '''Validation''': Ensure the system blocks access and provides a proper error message.

* '''Tampered Token Test''':
** '''Scenario''': Send a tampered token with an invalid signature.
** '''Expected Outcome''': HTTP 401 Unauthorized.
** '''Validation''': Confirm the system denies access and logs the attempt securely.

* '''Missing Token Test''':
** '''Scenario''': Make a request without providing a token.
** '''Expected Outcome''': HTTP 401 Unauthorized.
** '''Validation''': Verify that token authentication is strictly enforced.

== Team ==
===Mentor===
*Kashika Mallick (kmallick@ncsu.edu)

===Members===
*Shafa Hassan (shassa22@ncsu.edu)
*Archit Gupta (agupta85@ncsu.edu)
*Ansh Ganatra (aganatr@ncsu.edu)

CSC/ECE 517 Fall 2024 - E2487. Reimplement authorization helper.rb

2024-11-12T22:57:07Z

Agupta85:

== Background ==
The AuthorizationHelper module in Expertiza plays a critical role in managing user permissions and access control within the system. It provides methods to verify a user’s privileges based on their assigned roles, such as Super-Admin, Admin, Instructor, TA, or Student. These methods check if the user is authorized to perform actions like submitting assignments, reviewing work, or participating in quizzes. Additionally, it determines whether a user is involved in specific assignments, either as a participant, instructor, or through TA mappings.

==Problem Statement==

Expertiza currently uses session-based authentication in its [[https://github.com/expertiza/expertiza/blob/main/app/helpers/authorization_helper.rb| AuthorizationHelper]] module. The [[https://github.com/expertiza/reimplementation-back-end| reimplementation-back-end]] however, uses JWT (JSON Web Token) based authentication. This requires a redesign of the AuthorizationHelper module to accommodate JWT-based authentication.

The following points need to be taken care of as per the requirement

* JWT Creation : Make sure that a valid JSON Web Token is created which stores necessary details about the user and their role
* Token expiry and revocation : Token expiry and refresh mechanisms need to be implemented as well as a strategy for token revocation
* Remove dependency on session : The system has to be refactored, configured and tested thoroughly to ensure that having migrated to JWT, there is no dependency on Rails' session
* Writing rspec test cases for all JWT authentication helper methods to ensure proper exception and error handling

==Methods to implement==

* jwt_verify_and_decode(token): This method will verify and decode a JWT token and return the user's information, including role and claims. Successful verification of the token signature with the secret key will be followed by extraction of the payload which will contain important information about the user and their role for authentication and authorization.
* check_user_privileges(user_info, required_privilege): extract the user's roles or permissions from user_info (e.g., from the decoded JWT payload). Then, check if required_privilege exists within the user's permissions, returning true if it does and false otherwise to control access accordingly.

==Existing Methods to update==

* current_user_is_a?(role_name):
<pre>
def current_user_is_a?(role_name)
current_user_and_role_exist? && session[:user].role.name == role_name
end
</pre>

Currently this method relies on the session variable which is populated at the time of login to determine the role of a user. This would have to be updated to decode the user's role from the JWT payload

* user_logged_in?:
<pre>
def user_logged_in?
!session[:user].nil?
end
</pre>
This method will have to be updated to check the user's login status based on JWT validity

* current_user_has_privileges_of?(role_name)
<pre>
def current_user_has_privileges_of?(role_name)
current_user_and_role_exist? && session[:user].role.has_all_privileges_of?(Role.find_by(name: role_name))
end
</pre>

Needs to remove dependency on session variable and get user information from the JWT's decoded payload

* current_user_and_role_exist?
<pre>
def current_user_and_role_exist?
user_logged_in? && !session[:user].role.nil?
end
</pre>

Similarly, the role here needs to be checked from the JWT payload
Similarly methods like current_user_has_id?(id) will also have to be updated to remove dependencies from the session object, which are all part of the [[https://github.com/expertiza/expertiza/blob/main/app/helpers/authorization_helper.rb| AuthorizationHelper]] module

== JWT Token Overview ==

A JSON Web Token (JWT) is a compact, URL-safe token format commonly used for securely transmitting information between parties. It is widely used in web applications for authentication and authorization, as it allows information to be verified and trusted. In the context of our reimplemented AuthorizationHelper module, JWT tokens will replace session-based authentication, enabling stateless and more secure access control.

Structure of a JWT
A JWT consists of three main parts:

*Header: Contains metadata about the token, such as the type (JWT) and the hashing algorithm used (e.g., HS256 or RS256).
*Payload: Includes claims, which are statements about an entity (typically, the user) and additional data like the user’s role and permissions.
*Signature: A cryptographic signature generated by encoding the header and payload with a secret key or private key, ensuring data integrity.
These three sections are separated by dots (.), forming a token that looks like this: <Header>.<Payload>.<Signature>

[[File:JWT-Workflow.png|500px|center]]

==Anticipated Outcomes==
1. Enhanced AuthorizationHelper Module with JWT Integration: 
Updated and operational AuthorizationHelper module that would use JWT-based authentication. The module would be restructured to incorporate token-based authentication checks, replacing prior session-based methods.

2. Updated Associated Methods: 
Methods within the module will have to be updated to leverage JWT claims, ensuring authentication and authorization are handled based on token data. This will allow the module to verify user roles and permissions effectively through JWT claims.

3. Comprehensive JWT Error Handling: 
Built-in error handling to manage potential JWT-related issues, such as token expiration, tampering, or invalid claims. This ensures that unauthorized access is
blocked, and clear error messages are provided when issues arise.

4. Robust Unit Tests for Validation: 
A full suite of unit tests covering various scenarios, including normal, boundary, and edge cases, to validate each method’s functionality and confirm that all
JWT-based authentication flows work reliably.

5. Detailed Documentation and Code Comments: 
In-depth documentation and comments would be added to each function, explaining purpose, usage, and JWT-related adjustments, aiding in code readability and future
maintenance.

== Test Plan ==

== Team ==
===Mentor===
*Kashika Mallick (kmallick@ncsu.edu)

===Members===
*Shafa Hassan (shassa22@ncsu.edu)
*Archit Gupta (agupta85@ncsu.edu)
*Ansh Ganatra (aganatr@ncsu.edu)

CSC/ECE 517 Fall 2024 - E2487. Reimplement authorization helper.rb

2024-11-12T20:16:22Z

Agupta85:

== Background ==
The AuthorizationHelper module in Expertiza plays a critical role in managing user permissions and access control within the system. It provides methods to verify a user’s privileges based on their assigned roles, such as Super-Admin, Admin, Instructor, TA, or Student. These methods check if the user is authorized to perform actions like submitting assignments, reviewing work, or participating in quizzes. Additionally, it determines whether a user is involved in specific assignments, either as a participant, instructor, or through TA mappings.

==Problem Statement==

Expertiza currently uses session-based authentication in its [[https://github.com/expertiza/expertiza/blob/main/app/helpers/authorization_helper.rb| AuthorizationHelper]] module. The [[https://github.com/expertiza/reimplementation-back-end| reimplementation-back-end]] however, uses JWT (JSON Web Token) based authentication. This requires a redesign of the AuthorizationHelper module to accommodate JWT-based authentication.

The following points need to be taken care of as per the requirement

* JWT Creation : Make sure that a valid JSON Web Token is created which stores necessary details about the user and their role
* Token expiry and revocation : Token expiry and refresh mechanisms need to be implemented as well as a strategy for token revocation
* Remove dependency on session : The system has to be refactored, configured and tested thoroughly to ensure that having migrated to JWT, there is no dependency on Rails' session
* Writing rspec test cases for all JWT authentication helper methods to ensure proper exception and error handling

==Methods to implement==

* jwt_verify_and_decode(token): This method will verify and decode a JWT token and return the user's information, including role and claims. Successful verification of the token signature with the secret key will be followed by extraction of the payload which will contain important information about the user and their role for authentication and authorization.
* check_user_privileges(user_info, required_privilege): extract the user's roles or permissions from user_info (e.g., from the decoded JWT payload). Then, check if required_privilege exists within the user's permissions, returning true if it does and false otherwise to control access accordingly.

==Existing Methods to update==

* current_user_is_a?(role_name):
<pre>
def current_user_is_a?(role_name)
current_user_and_role_exist? && session[:user].role.name == role_name
end
</pre>

Currently this method relies on the session variable which is populated at the time of login to determine the role of a user. This would have to be updated to decode the user's role from the JWT payload

* user_logged_in?:
<pre>
def user_logged_in?
!session[:user].nil?
end
</pre>
This method will have to be updated to check the user's login status based on JWT validity

Similarly methods like current_user_has_privileges_of?(role_name) and current_user_has_id?(id) will also have to be updated to remove dependencies from the session object, which are all part of the [[https://github.com/expertiza/expertiza/blob/main/app/helpers/authorization_helper.rb| AuthorizationHelper]] module

== JWT Token Overview ==

A JSON Web Token (JWT) is a compact, URL-safe token format commonly used for securely transmitting information between parties. It is widely used in web applications for authentication and authorization, as it allows information to be verified and trusted. In the context of our reimplemented AuthorizationHelper module, JWT tokens will replace session-based authentication, enabling stateless and more secure access control.

Structure of a JWT
A JWT consists of three main parts:

*Header: Contains metadata about the token, such as the type (JWT) and the hashing algorithm used (e.g., HS256 or RS256).
*Payload: Includes claims, which are statements about an entity (typically, the user) and additional data like the user’s role and permissions.
*Signature: A cryptographic signature generated by encoding the header and payload with a secret key or private key, ensuring data integrity.
These three sections are separated by dots (.), forming a token that looks like this: <Header>.<Payload>.<Signature>

[[File:JWT-Workflow.png|500px|center]]

==Anticipated Outcomes==
1. Enhanced AuthorizationHelper Module with JWT Integration: 
Updated and operational AuthorizationHelper module that would use JWT-based authentication. The module would be restructured to incorporate token-based authentication checks, replacing prior session-based methods.

2. Updated Associated Methods: 
Methods within the module will have to be updated to leverage JWT claims, ensuring authentication and authorization are handled based on token data. This will allow the module to verify user roles and permissions effectively through JWT claims.

3. Comprehensive JWT Error Handling: 
Built-in error handling to manage potential JWT-related issues, such as token expiration, tampering, or invalid claims. This ensures that unauthorized access is
blocked, and clear error messages are provided when issues arise.

4. Robust Unit Tests for Validation: 
A full suite of unit tests covering various scenarios, including normal, boundary, and edge cases, to validate each method’s functionality and confirm that all
JWT-based authentication flows work reliably.

5. Detailed Documentation and Code Comments: 
In-depth documentation and comments would be added to each function, explaining purpose, usage, and JWT-related adjustments, aiding in code readability and future
maintenance.

== Test Plan ==

== Team ==
===Mentor===
*Kashika Mallick (kmallick@ncsu.edu)

===Members===
*Shafa Hassan (shassa22@ncsu.edu)
*Archit Gupta (agupta85@ncsu.edu)
*Ansh Ganatra (aganatr@ncsu.edu)

CSC/ECE 517 Fall 2024 - E2487. Reimplement authorization helper.rb

2024-11-12T19:56:35Z

Agupta85:

== Background ==
The AuthorizationHelper module in Expertiza plays a critical role in managing user permissions and access control within the system. It provides methods to verify a user’s privileges based on their assigned roles, such as Super-Admin, Admin, Instructor, TA, or Student. These methods check if the user is authorized to perform actions like submitting assignments, reviewing work, or participating in quizzes. Additionally, it determines whether a user is involved in specific assignments, either as a participant, instructor, or through TA mappings.

==Problem Statement==

Expertiza currently uses session-based authentication in its [[https://github.com/expertiza/expertiza/blob/main/app/helpers/authorization_helper.rb| AuthorizationHelper]] module. The [[https://github.com/expertiza/reimplementation-back-end| reimplementation-back-end]] however, uses JWT (JSON Web Token) based authentication. This requires a redesign of the AuthorizationHelper module to accommodate JWT-based authentication.

The following points need to be taken care of as per the requirement

* JWT Creation : Make sure that a valid JSON Web Token is created which stores necessary details about the user and their role
* Token expiry and revocation : Token expiry and refresh mechanisms need to be implemented as well as a strategy for token revocation
* Remove dependency on session : The system has to be refactored, configured and tested thoroughly to ensure that having migrated to JWT, there is no dependency on Rails' session
* Writing rspec test cases for all JWT authentication helper methods to ensure proper exception and error handling

==Methods to implement==

* jwt_verify_and_decode(token): This method will verify and decode a JWT token and return the user's information, including role and claims. Successful verification of the token signature with the secret key will be followed by extraction of the payload which will contain important information about the user and their role for authentication and authorization.
* check_user_privileges(user_info, required_privilege): extract the user's roles or permissions from user_info (e.g., from the decoded JWT payload). Then, check if required_privilege exists within the user's permissions, returning true if it does and false otherwise to control access accordingly.

Further, the already existing methods need to be updated and need to be refactored to account for the new authentication system

== JWT Token Overview ==

A JSON Web Token (JWT) is a compact, URL-safe token format commonly used for securely transmitting information between parties. It is widely used in web applications for authentication and authorization, as it allows information to be verified and trusted. In the context of our reimplemented AuthorizationHelper module, JWT tokens will replace session-based authentication, enabling stateless and more secure access control.

Structure of a JWT
A JWT consists of three main parts:

*Header: Contains metadata about the token, such as the type (JWT) and the hashing algorithm used (e.g., HS256 or RS256).
*Payload: Includes claims, which are statements about an entity (typically, the user) and additional data like the user’s role and permissions.
*Signature: A cryptographic signature generated by encoding the header and payload with a secret key or private key, ensuring data integrity.
These three sections are separated by dots (.), forming a token that looks like this: <Header>.<Payload>.<Signature>

[[File:JWT-Workflow.png|500px|center]]

==Anticipated Outcomes==
1. Enhanced AuthorizationHelper Module with JWT Integration: 
Updated and operational AuthorizationHelper module that would use JWT-based authentication. The module would be restructured to incorporate token-based authentication checks, replacing prior session-based methods.

2. Updated Associated Methods: 
Methods within the module will have to be updated to leverage JWT claims, ensuring authentication and authorization are handled based on token data. This will allow the module to verify user roles and permissions effectively through JWT claims.

3. Comprehensive JWT Error Handling: 
Built-in error handling to manage potential JWT-related issues, such as token expiration, tampering, or invalid claims. This ensures that unauthorized access is
blocked, and clear error messages are provided when issues arise.

4. Robust Unit Tests for Validation: 
A full suite of unit tests covering various scenarios, including normal, boundary, and edge cases, to validate each method’s functionality and confirm that all
JWT-based authentication flows work reliably.

5. Detailed Documentation and Code Comments: 
In-depth documentation and comments would be added to each function, explaining purpose, usage, and JWT-related adjustments, aiding in code readability and future
maintenance.

== Test Plan ==

== Team ==
===Mentor===
*Kashika Mallick (kmallick@ncsu.edu)

===Members===
*Shafa Hassan (shassa22@ncsu.edu)
*Archit Gupta (agupta85@ncsu.edu)
*Ansh Ganatra (aganatr@ncsu.edu)

CSC/ECE 517 Fall 2024 - E2487. Reimplement authorization helper.rb

2024-11-12T01:04:50Z

Agupta85:

==Problem Statement==

Expertiza currently uses session-based authentication in its [[https://github.com/expertiza/expertiza/blob/main/app/helpers/authorization_helper.rb| AuthorizationHelper]] module. The [[https://github.com/expertiza/reimplementation-back-end| reimplementation-back-end]] however, uses JWT (JSON Web Token) based authentication. This requires a redesign of the AuthorizationHelper module to accommodate JWT-based authentication.

The following points need to be taken care of as per the requirement

* JWT Creation : Make sure that a valid JSON Web Token is created which stores necessary details about the user and their role
* Token expiry and revocation : Token expiry and refresh mechanisms need to be implemented as well as a strategy for token revocation
* Remove dependency on session : The system has to be refactored, configured and tested thoroughly to ensure that having migrated to JWT, there is no dependency on Rails' session
* Writing rspec test cases for all JWT authentication helper methods to ensure proper exception and error handling

==Methods to implement==

* jwt_verify_and_decode(token): This method will verify and decode a JWT token and return the user's information, including role and claims. Successful verification of the token signature with the secret key will be followed by extraction of the payload which will contain important information about the user and their role for authentication and authorization.
* check_user_privileges(user_info, required_privilege): extract the user's roles or permissions from user_info (e.g., from the decoded JWT payload). Then, check if required_privilege exists within the user's permissions, returning true if it does and false otherwise to control access accordingly.

Further, the already existing methods need to be updated and need to be refactored to account for the new authentication system

CSC/ECE 517 Fall 2024 - E2469. Reimplement grades/view team

2024-10-30T00:47:33Z

Agupta85: /* Reimplementation and Improvements */

== Background ==
Expertiza is an open-source learning management system developed with Ruby on Rails, facilitating assignment creation, team management, and a structured peer review process. Designed for educational settings, Expertiza offers instructors tools to assign topics, manage teams, and allow students to collaborate on various assignment formats, including URLs and wiki pages. Its peer review functionality encourages students to provide feedback, promoting a collaborative learning experience.

==Problem Statement ==
This project focuses on reimplementing the grades/view_team page in Expertiza. The current interface lacks modern design aesthetics and usability standards making it challenging for users to access and understand grading data efficiently. Our objective is to develop a fully functional and visually cohesive front end for the Grades View page. By enhancing visual consistency, simplifying information display, improving responsiveness, giving users freedom to select views, and intuitive layout, this redesign aims to provide an improved user experience.

== Reimplementation and Improvements ==
=== Enhanced Peer Review and Author Feedback Filtering ===
 
==== I) Existing Design ====
[[File:ShowReviews Feedback.png|500px|center]]
 
==== II) Modified Design ====
[[File:GradesView2.png|500px|center]]
 
==== III) Files Changed for this Modification ====
 
1. [https://github.com/rarchitgupta/reimplementation-front-end/blob/feature/review-table-improvements/src/pages/ViewTeamGrades/Statistics.tsx Statistics.tsx]
 
2. [https://github.com/rarchitgupta/reimplementation-front-end/blob/feature/review-table-improvements/src/pages/ViewTeamGrades/Filters.tsx Filters.tsx]
 
3. [https://github.com/rarchitgupta/reimplementation-front-end/blob/feature/review-table-improvements/src/pages/ViewTeamGrades/ShowReviews.tsx ShowReviews.tsx]
 
 
The requirement in the statistic section of the grade page was to make changes to show dropdown selection menu for "Author Feedback" or "Reviews" and further add filtering based on the rounds (Round 1 or Round 2 or All) for "Author Feedback" or "Reviews".

To carry out the changes on first selection menu, we had toggle reviews and toggle feedback event listeners defined in statistics based on which we displayed the data using ShowReviews react componenet. These event listeners were passed to Filters component and which had drop down UI component for "Author Feedback" or "Reviews". Based on the option selected either toggleShowReviews or toggleAuthorFeedback were invoked.

To do make further changes to display data according to rounds, first in the Statistics component of react application we defined the state "roundSelected" and also defined listener function to update round (selectRound). This event listener function was passed to Filter react component which had the UI element for second drop down for rounds selection. Based on the round selected from the dropdown, we invoked selectRound event listener function. When this event listener function is invoked we update the state variable "roundSelected". And then this state variable is passed as props to ShowReviews react component which is responsible for iterating over "Author Feedback" or "Reviews" data and added the logic to show data with rounds based on the prop.

 
==== IV) Rationale ====
 
The "Show Reviews" and "Show Author Feedback" link displays all the peer reviews from Round 1 and Round 2 and author's feedback from both rounds in a single view. This forces the users to scroll all the rounds' reviews and feedback sequentially which can be overwhelming when users wish to view feedback from a specific round. Also, users don't have the freedom and control to choose to view all rounds' reviews/feedbacks or specific rounds' reviews/feedbacks. Additionally, a single view adds visual clutter and increases cognitive load.

With the 2 dropdowns users have more control over which reviews they would like to view. The first dropdown lets them choose from viewing reviews or author's feedback for the reviews provided, while the second dropdown allows them to select specific rounds (Round 1, Round 2, or both). This gives users the flexibility to focus on specific rounds as needed. Separating the reviews/author feedback based on a round filter reduces clutter, creating a cleaner, more organized layout. Users can now view reviews and feedback in a more structured way, which simplifies navigation and enhances readability and improves satisfaction.

 

=== Replaced the disorganized display of scores for submitted work, author feedback, and teammate reviews with a Structured Scorecard table for clearer presentation. ===
 
==== I) Existing Design ====
[[File:OldScorecard.png|500px|center]]
 
==== II) Modified Design ====
[[File:NewScorecard.png|500px|center]]
 
==== III) Files Changed for this Modification ====
 
1. [https://github.com/rarchitgupta/reimplementation-front-end/blob/feature/review-table-improvements/src/pages/ViewTeamGrades/Statistics.tsx Statistics.tsx]
 

The Statistics.tsx file was modified to implement the new tabular format for the grades summary. We removed the earlier code for the UI which showed the scores in a tabular format. However, the existing table was difficult to read without borders around the table. The modified table gets rid of unnecessary statistics like "contributor" and removes the toggles to show reviews and author feedback. This ensures that the section does not repeat links and present information not required

==== IV) Rationale ====
 
The previous display of scores for submitted work, author feedback, and teammate reviews was fragmented and lacked clarity, making it difficult for users to interpret performance metrics at a glance. By introducing a structured scorecard table, we present all relevant data in a clear, organized format, enabling users to easily compare and understand scores across different rounds. This redesign improves usability by offering a more intuitive layout and better visibility of grading information.

 

=== Removed the names of reviewers as they are supposed to remain anonymous. ===
 
==== I) Existing Design ====
[[File:ReviewerNameChange.png|500px|center]]
 
==== II) Modified Design ====
[[File:ReviewerNameChange2.png|500px|center]]
 
==== III) Rationale ====
 
The reason for this change is to shift focus more on quality and content of feedback and reviews rather than identity of reviewers. Anonymity encourages the reviewers to provide constructive criticism as reviewers will review without concern for any issues or repercussions.

 

=== Styling of Review Table ===
 
==== I) Existing Design ====
[Image to be Added]
 
==== II) Modified Design ====
[Image to be Added]
 
==== III) [Design pattern/solid/dry][TODO] ====
 
==== IV) [Code Snippet][TODO] ====
 
==== V) Rationale ====

 
=== Fixed styling Toggle Question List ===
 
==== I) Existing Design ====
[[File:ToggleChange1.png|500px|center]]
 
==== II) Modified Design ====
[[File:ToggleChange.png|500px|center]]
 
==== III) [Design pattern/solid/dry][TODO] ====
 
==== IV) [Code Snippet][TODO] ====
 
==== V) Rationale ====
 
The "Toggle Question List" styling was refined for better alignment and readability, enhancing the clarity of the page’s interactive elements.

 
=== Unified Review Rounds Button and Interface Styling Update ===
 
==== I) Existing Design ====
[[File:ReviewTableSeparateView.png|500px|center]]
 
==== II) Modified Design ====
[[File:UnifiedReviewTable.png|500px|center]]
 
==== III) [Design pattern/solid/dry][TODO] ====
 
==== IV) [Code Snippet][TODO] ====
 
==== V) Rationale ====
 
Addition of “All Rounds’’ Button: The new "All Rounds" button allows users to view reviews from multiple rounds in a single table. This eliminates the need to switch between individual rounds, giving users a comprehensive view of the feedback across all rounds at once.
Color and Style Consistency: The colors and styles of the buttons were updated to match Expertiza’s established color scheme, ensuring a cohesive and professional look across the platform. This consistency aids in navigation, making the interface feel more intuitive and visually appealing.

 
=== Expanded Submission Links Display ===
 
==== I) Existing Design ====
[[File:ToggleSubmission.png|500px|center]]
 
==== II) Modified Design ====
[[File:ExpandedSubmissions.png|500px|center]]
 
==== III) [Design pattern/solid/dry][TODO] ====
 
==== IV) [Code Snippet][TODO] ====
 
==== V) Rationale ====
 
The change enhances usability by directly presenting all relevant submission links to users without requiring additional interaction to show or hide them. This expanded view allows for quicker access to project resources and a more streamlined experience, improving efficiency and clarity in the peer review process on the grades/view_team page.
 

== Testing ==
We have conducted comprehensive manual testing to verify the functionality, usability, and visual consistency of the reimplemented features.

1. Peer Review and Feedback Filter: Tested the dropdown options to confirm that users can correctly view specific rounds of peer reviews or author feedback as selected.
 
2. Scorecard Table: Checked that the Scorecard table displays relevant scores in an organized manner and ensured that the scoring data is correctly calculated.
 
3 Submission Links: Verified that the submission links were directly displayed, without the need to toggle them. Each link was tested individually to ensure it opens the correct resource without errors.
 
4. Styling Consistency: We compared the new styling of buttons, dropdowns, and tables with the rest of Expertiza's interface to ensure a cohesive look.
 
5. Anonymity of Reviewers: Verified that reviewers’ names were properly hidden, preserving anonymity throughout the review display
 
6. All Rounds Button: Tested the "All Rounds" button by viewing multiple rounds of reviews in a single table to confirm that users can easily access and interpret cumulative feedback without toggling between views.
 
== Repository Links ==
[https://github.com/rarchitgupta/reimplementation-front-end FrontEnd]

[https://github.com/expertiza/reimplementation-back-end Backend]

[https://github.com/expertiza/reimplementation-front-end/pull/62 Pull Request]
 
== Project Mentor ==
Kashika Mallick (kmallick@ncsu.edu)

 
== Team Members ==
Shafa Hassan (shassa22@ncsu.edu)
 
Archit Gupta (agupta85@ncsu.edu)
 
Ansh Ganatra (aganatr@ncsu.edu)

CSC/ECE 517 Fall 2024 - E2469. Reimplement grades/view team

2024-10-30T00:40:47Z

Agupta85: /* Removed the names of reviewers as they are supposed to remain anonymous. */

== Background ==
Expertiza is an open-source learning management system developed with Ruby on Rails, facilitating assignment creation, team management, and a structured peer review process. Designed for educational settings, Expertiza offers instructors tools to assign topics, manage teams, and allow students to collaborate on various assignment formats, including URLs and wiki pages. Its peer review functionality encourages students to provide feedback, promoting a collaborative learning experience.

==Problem Statement ==
This project focuses on reimplementing the grades/view_team page in Expertiza. The current interface lacks modern design aesthetics and usability standards making it challenging for users to access and understand grading data efficiently. Our objective is to develop a fully functional and visually cohesive front end for the Grades View page. By enhancing visual consistency, simplifying information display, improving responsiveness, giving users freedom to select views, and intuitive layout, this redesign aims to provide an improved user experience.

== Reimplementation and Improvements ==
=== Enhanced Peer Review and Author Feedback Filtering ===
 
==== I) Existing Design ====
[[File:ShowReviews Feedback.png|500px|center]]
 
==== II) Modified Design ====
[[File:GradesView2.png|500px|center]]
 
==== III) Files Changed for this Modification ====
 
1. [https://github.com/rarchitgupta/reimplementation-front-end/blob/feature/review-table-improvements/src/pages/ViewTeamGrades/Statistics.tsx Statistics.tsx]
 
2. [https://github.com/rarchitgupta/reimplementation-front-end/blob/feature/review-table-improvements/src/pages/ViewTeamGrades/Filters.tsx Filters.tsx]
 
3. [https://github.com/rarchitgupta/reimplementation-front-end/blob/feature/review-table-improvements/src/pages/ViewTeamGrades/ShowReviews.tsx ShowReviews.tsx]
 
 
The requirement in the statistic section of the grade page was to make changes to show dropdown selection menu for "Author Feedback" or "Reviews" and further add filtering based on the rounds (Round 1 or Round 2 or All) for "Author Feedback" or "Reviews".

To carry out the changes on first selection menu, we had toggle reviews and toggle feedback event listeners defined in statistics based on which we displayed the data using ShowReviews react componenet. These event listeners were passed to Filters component and which had drop down UI component for "Author Feedback" or "Reviews". Based on the option selected either toggleShowReviews or toggleAuthorFeedback were invoked.

To do make further changes to display data according to rounds, first in the Statistics component of react application we defined the state "roundSelected" and also defined listener function to update round (selectRound). This event listener function was passed to Filter react component which had the UI element for second drop down for rounds selection. Based on the round selected from the dropdown, we invoked selectRound event listener function. When this event listener function is invoked we update the state variable "roundSelected". And then this state variable is passed as props to ShowReviews react component which is responsible for iterating over "Author Feedback" or "Reviews" data and added the logic to show data with rounds based on the prop.

 
==== IV) Rationale ====
 
The "Show Reviews" and "Show Author Feedback" link displays all the peer reviews from Round 1 and Round 2 and author's feedback from both rounds in a single view. This forces the users to scroll all the rounds' reviews and feedback sequentially which can be overwhelming when users wish to view feedback from a specific round. Also, users don't have the freedom and control to choose to view all rounds' reviews/feedbacks or specific rounds' reviews/feedbacks. Additionally, a single view adds visual clutter and increases cognitive load.

With the 2 dropdowns users have more control over which reviews they would like to view. The first dropdown lets them choose from viewing reviews or author's feedback for the reviews provided, while the second dropdown allows them to select specific rounds (Round 1, Round 2, or both). This gives users the flexibility to focus on specific rounds as needed. Separating the reviews/author feedback based on a round filter reduces clutter, creating a cleaner, more organized layout. Users can now view reviews and feedback in a more structured way, which simplifies navigation and enhances readability and improves satisfaction.

 

=== Replaced the disorganized display of scores for submitted work, author feedback, and teammate reviews with a Structured Scorecard table for clearer presentation. ===
 
==== I) Existing Design ====
[[File:OldScorecard.png|500px|center]]
 
==== II) Modified Design ====
[[File:NewScorecard.png|500px|center]]
 
==== III) Files Changed for this Modification ====
 
1. [https://github.com/rarchitgupta/reimplementation-front-end/blob/feature/review-table-improvements/src/pages/ViewTeamGrades/Statistics.tsx Statistics.tsx]
 

The Statistics.tsx file was modified to implement the new tabular format for the grades summary. We removed the earlier code for the UI which showed the scores in a tabular format. However, the existing table was difficult to read without borders around the table. The modified table gets rid of unnecessary statistics like "contributor" and removes the toggles to show reviews and author feedback. This ensures that the section does not repeat links and present information not required

==== IV) Rationale ====
 
The previous display of scores for submitted work, author feedback, and teammate reviews was fragmented and lacked clarity, making it difficult for users to interpret performance metrics at a glance. By introducing a structured scorecard table, we present all relevant data in a clear, organized format, enabling users to easily compare and understand scores across different rounds. This redesign improves usability by offering a more intuitive layout and better visibility of grading information.

 

=== Removed the names of reviewers as they are supposed to remain anonymous. ===
 
==== I) Existing Design ====
[[File:ReviewerNameChange.png|500px|center]]
 
==== II) Modified Design ====
[[File:ReviewerNameChange2.png|500px|center]]
 
==== III) Rationale ====
 
The reason for this change is to shift focus more on quality and content of feedback and reviews rather than identity of reviewers. Anonymity encourages the reviewers to provide constructive criticism as reviewers will review without concern for any issues or repercussions.

 

=== Removed information that didn’t add value ===
 
==== I) Existing Design ====
[[File:Contributer RangeRemoved.png|500px|center]]
 
==== II) [Design pattern/solid/dry][TODO] ====
 
==== IV) [Code Snippet][TODO] ====
 
==== V) Rationale ====
 
Contributor Name: The displayed contributor name only indicated the team member who submitted the work, which could cause confusion, as all team members contribute to the assignment. Additionally, team members' names are already displayed at the top of the page, making this information redundant. Removing it reduces visual clutter, focusing the user's attention on relevant grading information.
Score Range: The score range provided minimal value in understanding the overall grade, as the average score alone conveys a clearer summary of performance. By removing the range, the layout is simplified, helping users to focus on meaningful metrics without unnecessary data.

 
=== Styling of Review Table ===
 
==== I) Existing Design ====
[Image to be Added]
 
==== II) Modified Design ====
[Image to be Added]
 
==== III) [Design pattern/solid/dry][TODO] ====
 
==== IV) [Code Snippet][TODO] ====
 
==== V) Rationale ====

 
=== Fixed styling Toggle Question List ===
 
==== I) Existing Design ====
[[File:ToggleChange1.png|500px|center]]
 
==== II) Modified Design ====
[[File:ToggleChange.png|500px|center]]
 
==== III) [Design pattern/solid/dry][TODO] ====
 
==== IV) [Code Snippet][TODO] ====
 
==== V) Rationale ====
 
The "Toggle Question List" styling was refined for better alignment and readability, enhancing the clarity of the page’s interactive elements.

 
=== Unified Review Rounds Button and Interface Styling Update ===
 
==== I) Existing Design ====
[[File:ReviewTableSeparateView.png|500px|center]]
 
==== II) Modified Design ====
[[File:UnifiedReviewTable.png|500px|center]]
 
==== III) [Design pattern/solid/dry][TODO] ====
 
==== IV) [Code Snippet][TODO] ====
 
==== V) Rationale ====
 
Addition of “All Rounds’’ Button: The new "All Rounds" button allows users to view reviews from multiple rounds in a single table. This eliminates the need to switch between individual rounds, giving users a comprehensive view of the feedback across all rounds at once.
Color and Style Consistency: The colors and styles of the buttons were updated to match Expertiza’s established color scheme, ensuring a cohesive and professional look across the platform. This consistency aids in navigation, making the interface feel more intuitive and visually appealing.

 
=== Expanded Submission Links Display ===
 
==== I) Existing Design ====
[[File:ToggleSubmission.png|500px|center]]
 
==== II) Modified Design ====
[[File:ExpandedSubmissions.png|500px|center]]
 
==== III) [Design pattern/solid/dry][TODO] ====
 
==== IV) [Code Snippet][TODO] ====
 
==== V) Rationale ====
 
The change enhances usability by directly presenting all relevant submission links to users without requiring additional interaction to show or hide them. This expanded view allows for quicker access to project resources and a more streamlined experience, improving efficiency and clarity in the peer review process on the grades/view_team page.
 
== Testing ==
We have conducted comprehensive manual testing to verify the functionality, usability, and visual consistency of the reimplemented features.

1. Peer Review and Feedback Filter: Tested the dropdown options to confirm that users can correctly view specific rounds of peer reviews or author feedback as selected.
 
2. Scorecard Table: Checked that the Scorecard table displays relevant scores in an organized manner and ensured that the scoring data is correctly calculated.
 
3 Submission Links: Verified that the submission links were directly displayed, without the need to toggle them. Each link was tested individually to ensure it opens the correct resource without errors.
 
4. Styling Consistency: We compared the new styling of buttons, dropdowns, and tables with the rest of Expertiza's interface to ensure a cohesive look.
 
5. Anonymity of Reviewers: Verified that reviewers’ names were properly hidden, preserving anonymity throughout the review display
 
6. All Rounds Button: Tested the "All Rounds" button by viewing multiple rounds of reviews in a single table to confirm that users can easily access and interpret cumulative feedback without toggling between views.
 
== Repository Links ==
[https://github.com/rarchitgupta/reimplementation-front-end FrontEnd]

[https://github.com/expertiza/reimplementation-back-end Backend]

[https://github.com/expertiza/reimplementation-front-end/pull/62 Pull Request]
 
== Project Mentor ==
Kashika Mallick (kmallick@ncsu.edu)

 
== Team Members ==
Shafa Hassan (shassa22@ncsu.edu)
 
Archit Gupta (agupta85@ncsu.edu)
 
Ansh Ganatra (aganatr@ncsu.edu)

CSC/ECE 517 Fall 2024 - E2469. Reimplement grades/view team

2024-10-30T00:32:36Z

Agupta85: /* Replaced the disorganized display of scores for submitted work, author feedback, and teammate reviews with a Structured Scorecard table for clearer presentation. */

== Background ==
Expertiza is an open-source learning management system developed with Ruby on Rails, facilitating assignment creation, team management, and a structured peer review process. Designed for educational settings, Expertiza offers instructors tools to assign topics, manage teams, and allow students to collaborate on various assignment formats, including URLs and wiki pages. Its peer review functionality encourages students to provide feedback, promoting a collaborative learning experience.

==Problem Statement ==
This project focuses on reimplementing the grades/view_team page in Expertiza. The current interface lacks modern design aesthetics and usability standards making it challenging for users to access and understand grading data efficiently. Our objective is to develop a fully functional and visually cohesive front end for the Grades View page. By enhancing visual consistency, simplifying information display, improving responsiveness, giving users freedom to select views, and intuitive layout, this redesign aims to provide an improved user experience.

== Reimplementation and Improvements ==
=== Enhanced Peer Review and Author Feedback Filtering ===
 
==== I) Existing Design ====
[[File:ShowReviews Feedback.png|500px|center]]
 
==== II) Modified Design ====
[[File:GradesView2.png|500px|center]]
 
==== III) Files Changed for this Modification ====
 
1. [https://github.com/rarchitgupta/reimplementation-front-end/blob/feature/review-table-improvements/src/pages/ViewTeamGrades/Statistics.tsx Statistics.tsx]
 
2. [https://github.com/rarchitgupta/reimplementation-front-end/blob/feature/review-table-improvements/src/pages/ViewTeamGrades/Filters.tsx Filters.tsx]
 
3. [https://github.com/rarchitgupta/reimplementation-front-end/blob/feature/review-table-improvements/src/pages/ViewTeamGrades/ShowReviews.tsx ShowReviews.tsx]
 
 
The requirement in the statistic section of the grade page was to make changes to show dropdown selection menu for "Author Feedback" or "Reviews" and further add filtering based on the rounds (Round 1 or Round 2 or All) for "Author Feedback" or "Reviews".

To carry out the changes on first selection menu, we had toggle reviews and toggle feedback event listeners defined in statistics based on which we displayed the data using ShowReviews react componenet. These event listeners were passed to Filters component and which had drop down UI component for "Author Feedback" or "Reviews". Based on the option selected either toggleShowReviews or toggleAuthorFeedback were invoked.

To do make further changes to display data according to rounds, first in the Statistics component of react application we defined the state "roundSelected" and also defined listener function to update round (selectRound). This event listener function was passed to Filter react component which had the UI element for second drop down for rounds selection. Based on the round selected from the dropdown, we invoked selectRound event listener function. When this event listener function is invoked we update the state variable "roundSelected". And then this state variable is passed as props to ShowReviews react component which is responsible for iterating over "Author Feedback" or "Reviews" data and added the logic to show data with rounds based on the prop.

 
==== IV) Rationale ====
 
The "Show Reviews" and "Show Author Feedback" link displays all the peer reviews from Round 1 and Round 2 and author's feedback from both rounds in a single view. This forces the users to scroll all the rounds' reviews and feedback sequentially which can be overwhelming when users wish to view feedback from a specific round. Also, users don't have the freedom and control to choose to view all rounds' reviews/feedbacks or specific rounds' reviews/feedbacks. Additionally, a single view adds visual clutter and increases cognitive load.

With the 2 dropdowns users have more control over which reviews they would like to view. The first dropdown lets them choose from viewing reviews or author's feedback for the reviews provided, while the second dropdown allows them to select specific rounds (Round 1, Round 2, or both). This gives users the flexibility to focus on specific rounds as needed. Separating the reviews/author feedback based on a round filter reduces clutter, creating a cleaner, more organized layout. Users can now view reviews and feedback in a more structured way, which simplifies navigation and enhances readability and improves satisfaction.

 

=== Replaced the disorganized display of scores for submitted work, author feedback, and teammate reviews with a Structured Scorecard table for clearer presentation. ===
 
==== I) Existing Design ====
[[File:OldScorecard.png|500px|center]]
 
==== II) Modified Design ====
[[File:NewScorecard.png|500px|center]]
 
==== III) Files Changed for this Modification ====
 
1. [https://github.com/rarchitgupta/reimplementation-front-end/blob/feature/review-table-improvements/src/pages/ViewTeamGrades/Statistics.tsx Statistics.tsx]
 

The Statistics.tsx file was modified to implement the new tabular format for the grades summary. We removed the earlier code for the UI which showed the scores in a tabular format. However, the existing table was difficult to read without borders around the table. The modified table gets rid of unnecessary statistics like "contributor" and removes the toggles to show reviews and author feedback. This ensures that the section does not repeat links and present information not required

==== IV) Rationale ====
 
The previous display of scores for submitted work, author feedback, and teammate reviews was fragmented and lacked clarity, making it difficult for users to interpret performance metrics at a glance. By introducing a structured scorecard table, we present all relevant data in a clear, organized format, enabling users to easily compare and understand scores across different rounds. This redesign improves usability by offering a more intuitive layout and better visibility of grading information.

 

=== Removed the names of reviewers as they are supposed to remain anonymous. ===
 
==== I) Existing Design ====
[[File:ReviewerNameChange.png|500px|center]]
 
==== II) Modified Design ====
[[File:ReviewerNameChange2.png|500px|center]]
 
==== III) [Design pattern/solid/dry][TODO] ====
 
==== IV) [Code Snippet][TODO] ====
 
==== V) Rationale ====
 
The reason for this change is to shift focus more on quality and content of feedback and reviews rather than identity of reviewers. Anonymity encourages the reviewers to provide constructive criticism as reviewers will review without concern for any issues or repercussions.

 
=== Removed information that didn’t add value ===
 
==== I) Existing Design ====
[[File:Contributer RangeRemoved.png|500px|center]]
 
==== II) [Design pattern/solid/dry][TODO] ====
 
==== IV) [Code Snippet][TODO] ====
 
==== V) Rationale ====
 
Contributor Name: The displayed contributor name only indicated the team member who submitted the work, which could cause confusion, as all team members contribute to the assignment. Additionally, team members' names are already displayed at the top of the page, making this information redundant. Removing it reduces visual clutter, focusing the user's attention on relevant grading information.
Score Range: The score range provided minimal value in understanding the overall grade, as the average score alone conveys a clearer summary of performance. By removing the range, the layout is simplified, helping users to focus on meaningful metrics without unnecessary data.

 
=== Styling of Review Table ===
 
==== I) Existing Design ====
[Image to be Added]
 
==== II) Modified Design ====
[Image to be Added]
 
==== III) [Design pattern/solid/dry][TODO] ====
 
==== IV) [Code Snippet][TODO] ====
 
==== V) Rationale ====

 
=== Fixed styling Toggle Question List ===
 
==== I) Existing Design ====
[[File:ToggleChange1.png|500px|center]]
 
==== II) Modified Design ====
[[File:ToggleChange.png|500px|center]]
 
==== III) [Design pattern/solid/dry][TODO] ====
 
==== IV) [Code Snippet][TODO] ====
 
==== V) Rationale ====
 
The "Toggle Question List" styling was refined for better alignment and readability, enhancing the clarity of the page’s interactive elements.

 
=== Unified Review Rounds Button and Interface Styling Update ===
 
==== I) Existing Design ====
[[File:ReviewTableSeparateView.png|500px|center]]
 
==== II) Modified Design ====
[[File:UnifiedReviewTable.png|500px|center]]
 
==== III) [Design pattern/solid/dry][TODO] ====
 
==== IV) [Code Snippet][TODO] ====
 
==== V) Rationale ====
 
Addition of “All Rounds’’ Button: The new "All Rounds" button allows users to view reviews from multiple rounds in a single table. This eliminates the need to switch between individual rounds, giving users a comprehensive view of the feedback across all rounds at once.
Color and Style Consistency: The colors and styles of the buttons were updated to match Expertiza’s established color scheme, ensuring a cohesive and professional look across the platform. This consistency aids in navigation, making the interface feel more intuitive and visually appealing.

 
=== Expanded Submission Links Display ===
 
==== I) Existing Design ====
[[File:ToggleSubmission.png|500px|center]]
 
==== II) Modified Design ====
[[File:ExpandedSubmissions.png|500px|center]]
 
==== III) [Design pattern/solid/dry][TODO] ====
 
==== IV) [Code Snippet][TODO] ====
 
==== V) Rationale ====
 
The change enhances usability by directly presenting all relevant submission links to users without requiring additional interaction to show or hide them. This expanded view allows for quicker access to project resources and a more streamlined experience, improving efficiency and clarity in the peer review process on the grades/view_team page.
 
== Testing ==
We have conducted comprehensive manual testing to verify the functionality, usability, and visual consistency of the reimplemented features.

1. Peer Review and Feedback Filter: Tested the dropdown options to confirm that users can correctly view specific rounds of peer reviews or author feedback as selected.
 
2. Scorecard Table: Checked that the Scorecard table displays relevant scores in an organized manner and ensured that the scoring data is correctly calculated.
 
3 Submission Links: Verified that the submission links were directly displayed, without the need to toggle them. Each link was tested individually to ensure it opens the correct resource without errors.
 
4. Styling Consistency: We compared the new styling of buttons, dropdowns, and tables with the rest of Expertiza's interface to ensure a cohesive look.
 
5. Anonymity of Reviewers: Verified that reviewers’ names were properly hidden, preserving anonymity throughout the review display
 
6. All Rounds Button: Tested the "All Rounds" button by viewing multiple rounds of reviews in a single table to confirm that users can easily access and interpret cumulative feedback without toggling between views.
 
== Repository Links ==
[https://github.com/rarchitgupta/reimplementation-front-end FrontEnd]

[https://github.com/expertiza/reimplementation-back-end Backend]

[https://github.com/expertiza/reimplementation-front-end/pull/62 Pull Request]
 
== Project Mentor ==
Kashika Mallick (kmallick@ncsu.edu)

 
== Team Members ==
Shafa Hassan (shassa22@ncsu.edu)
 
Archit Gupta (agupta85@ncsu.edu)
 
Ansh Ganatra (aganatr@ncsu.edu)

CSC/ECE 517 Fall 2024 - E2469. Reimplement grades/view team

2024-10-30T00:23:51Z

Agupta85: /* III) [Files Changed for this modification] */

== Background ==
Expertiza is an open-source learning management system developed with Ruby on Rails, facilitating assignment creation, team management, and a structured peer review process. Designed for educational settings, Expertiza offers instructors tools to assign topics, manage teams, and allow students to collaborate on various assignment formats, including URLs and wiki pages. Its peer review functionality encourages students to provide feedback, promoting a collaborative learning experience.

==Problem Statement ==
This project focuses on reimplementing the grades/view_team page in Expertiza. The current interface lacks modern design aesthetics and usability standards making it challenging for users to access and understand grading data efficiently. Our objective is to develop a fully functional and visually cohesive front end for the Grades View page. By enhancing visual consistency, simplifying information display, improving responsiveness, giving users freedom to select views, and intuitive layout, this redesign aims to provide an improved user experience.

== Reimplementation and Improvements ==
=== Enhanced Peer Review and Author Feedback Filtering ===
 
==== I) Existing Design ====
[[File:ShowReviews Feedback.png|500px|center]]
 
==== II) Modified Design ====
[[File:GradesView2.png|500px|center]]
 
==== III) Files Changed for this Modification ====
 
1. [https://github.com/rarchitgupta/reimplementation-front-end/blob/feature/review-table-improvements/src/pages/ViewTeamGrades/Statistics.tsx Statistics.tsx]
 
2. [https://github.com/rarchitgupta/reimplementation-front-end/blob/feature/review-table-improvements/src/pages/ViewTeamGrades/Filters.tsx Filters.tsx]
 
3. [https://github.com/rarchitgupta/reimplementation-front-end/blob/feature/review-table-improvements/src/pages/ViewTeamGrades/ShowReviews.tsx ShowReviews.tsx]
 
 
The requirement in the statistic section of the grade page was to make changes to show dropdown selection menu for "Author Feedback" or "Reviews" and further add filtering based on the rounds (Round 1 or Round 2 or All) for "Author Feedback" or "Reviews".

To carry out the changes on first selection menu, we had toggle reviews and toggle feedback event listeners defined in statistics based on which we displayed the data using ShowReviews react componenet. These event listeners were passed to Filters component and which had drop down UI component for "Author Feedback" or "Reviews". Based on the option selected either toggleShowReviews or toggleAuthorFeedback were invoked.

To do make further changes to display data according to rounds, first in the Statistics component of react application we defined the state "roundSelected" and also defined listener function to update round (selectRound). This event listener function was passed to Filter react component which had the UI element for second drop down for rounds selection. Based on the round selected from the dropdown, we invoked selectRound event listener function. When this event listener function is invoked we update the state variable "roundSelected". And then this state variable is passed as props to ShowReviews react component which is responsible for iterating over "Author Feedback" or "Reviews" data and added the logic to show data with rounds based on the prop.

 
==== IV) Rationale ====
 
The "Show Reviews" and "Show Author Feedback" link displays all the peer reviews from Round 1 and Round 2 and author's feedback from both rounds in a single view. This forces the users to scroll all the rounds' reviews and feedback sequentially which can be overwhelming when users wish to view feedback from a specific round. Also, users don't have the freedom and control to choose to view all rounds' reviews/feedbacks or specific rounds' reviews/feedbacks. Additionally, a single view adds visual clutter and increases cognitive load.

With the 2 dropdowns users have more control over which reviews they would like to view. The first dropdown lets them choose from viewing reviews or author's feedback for the reviews provided, while the second dropdown allows them to select specific rounds (Round 1, Round 2, or both). This gives users the flexibility to focus on specific rounds as needed. Separating the reviews/author feedback based on a round filter reduces clutter, creating a cleaner, more organized layout. Users can now view reviews and feedback in a more structured way, which simplifies navigation and enhances readability and improves satisfaction.

 

=== Replaced the disorganized display of scores for submitted work, author feedback, and teammate reviews with a Structured Scorecard table for clearer presentation. ===
 
==== I) Existing Design ====
[[File:OldScorecard.png|500px|center]]
 
==== II) Modified Design ====
[[File:NewScorecard.png|500px|center]]
 
==== III) [Design pattern/solid/dry][TODO] ====
 
==== III) Files Changed for this Modification ====
 
1. [https://github.com/rarchitgupta/reimplementation-front-end/blob/feature/review-table-improvements/src/pages/ViewTeamGrades/Statistics.tsx Statistics.tsx]
 

The Statistics.tsx file was modified to implement the new tabular format for the grades summary. We removed the earlier code for the UI which showed the scores in a tabular format. However, the existing table was difficult to read without borders around the table. The modified table gets rid of unnecessary statistics like "contributor" and removes the toggles to show reviews and author feedback. This ensures that the section does not repeat links and present information not required

==== V) Rationale ====
 
The previous display of scores for submitted work, author feedback, and teammate reviews was fragmented and lacked clarity, making it difficult for users to interpret performance metrics at a glance. By introducing a structured scorecard table, we present all relevant data in a clear, organized format, enabling users to easily compare and understand scores across different rounds. This redesign improves usability by offering a more intuitive layout and better visibility of grading information.

 
=== Removed the names of reviewers as they are supposed to remain anonymous. ===
 
==== I) Existing Design ====
[[File:ReviewerNameChange.png|500px|center]]
 
==== II) Modified Design ====
[[File:ReviewerNameChange2.png|500px|center]]
 
==== III) [Design pattern/solid/dry][TODO] ====
 
==== IV) [Code Snippet][TODO] ====
 
==== V) Rationale ====
 
The reason for this change is to shift focus more on quality and content of feedback and reviews rather than identity of reviewers. Anonymity encourages the reviewers to provide constructive criticism as reviewers will review without concern for any issues or repercussions.

 
=== Removed information that didn’t add value ===
 
==== I) Existing Design ====
[[File:Contributer RangeRemoved.png|500px|center]]
 
==== II) [Design pattern/solid/dry][TODO] ====
 
==== IV) [Code Snippet][TODO] ====
 
==== V) Rationale ====
 
Contributor Name: The displayed contributor name only indicated the team member who submitted the work, which could cause confusion, as all team members contribute to the assignment. Additionally, team members' names are already displayed at the top of the page, making this information redundant. Removing it reduces visual clutter, focusing the user's attention on relevant grading information.
Score Range: The score range provided minimal value in understanding the overall grade, as the average score alone conveys a clearer summary of performance. By removing the range, the layout is simplified, helping users to focus on meaningful metrics without unnecessary data.

 
=== Styling of Review Table ===
 
==== I) Existing Design ====
[Image to be Added]
 
==== II) Modified Design ====
[Image to be Added]
 
==== III) [Design pattern/solid/dry][TODO] ====
 
==== IV) [Code Snippet][TODO] ====
 
==== V) Rationale ====

 
=== Fixed styling Toggle Question List ===
 
==== I) Existing Design ====
[[File:ToggleChange1.png|500px|center]]
 
==== II) Modified Design ====
[[File:ToggleChange.png|500px|center]]
 
==== III) [Design pattern/solid/dry][TODO] ====
 
==== IV) [Code Snippet][TODO] ====
 
==== V) Rationale ====
 
The "Toggle Question List" styling was refined for better alignment and readability, enhancing the clarity of the page’s interactive elements.

 
=== Unified Review Rounds Button and Interface Styling Update ===
 
==== I) Existing Design ====
[[File:ReviewTableSeparateView.png|500px|center]]
 
==== II) Modified Design ====
[[File:UnifiedReviewTable.png|500px|center]]
 
==== III) [Design pattern/solid/dry][TODO] ====
 
==== IV) [Code Snippet][TODO] ====
 
==== V) Rationale ====
 
Addition of “All Rounds’’ Button: The new "All Rounds" button allows users to view reviews from multiple rounds in a single table. This eliminates the need to switch between individual rounds, giving users a comprehensive view of the feedback across all rounds at once.
Color and Style Consistency: The colors and styles of the buttons were updated to match Expertiza’s established color scheme, ensuring a cohesive and professional look across the platform. This consistency aids in navigation, making the interface feel more intuitive and visually appealing.

 
=== Expanded Submission Links Display ===
 
==== I) Existing Design ====
[[File:ToggleSubmission.png|500px|center]]
 
==== II) Modified Design ====
[[File:ExpandedSubmissions.png|500px|center]]
 
==== III) [Design pattern/solid/dry][TODO] ====
 
==== IV) [Code Snippet][TODO] ====
 
==== V) Rationale ====
 
The change enhances usability by directly presenting all relevant submission links to users without requiring additional interaction to show or hide them. This expanded view allows for quicker access to project resources and a more streamlined experience, improving efficiency and clarity in the peer review process on the grades/view_team page.
 
== Testing ==
We have conducted comprehensive manual testing to verify the functionality, usability, and visual consistency of the reimplemented features.

1. Peer Review and Feedback Filter: Tested the dropdown options to confirm that users can correctly view specific rounds of peer reviews or author feedback as selected.
 
2. Scorecard Table: Checked that the Scorecard table displays relevant scores in an organized manner and ensured that the scoring data is correctly calculated.
 
3 Submission Links: Verified that the submission links were directly displayed, without the need to toggle them. Each link was tested individually to ensure it opens the correct resource without errors.
 
4. Styling Consistency: We compared the new styling of buttons, dropdowns, and tables with the rest of Expertiza's interface to ensure a cohesive look.
 
5. Anonymity of Reviewers: Verified that reviewers’ names were properly hidden, preserving anonymity throughout the review display
 
6. All Rounds Button: Tested the "All Rounds" button by viewing multiple rounds of reviews in a single table to confirm that users can easily access and interpret cumulative feedback without toggling between views.
 
== Repository Links ==
[https://github.com/rarchitgupta/reimplementation-front-end FrontEnd]

[https://github.com/expertiza/reimplementation-back-end Backend]

[https://github.com/expertiza/reimplementation-front-end/pull/62 Pull Request]
 
== Project Mentor ==
Kashika Mallick (kmallick@ncsu.edu)

 
== Team Members ==
Shafa Hassan (shassa22@ncsu.edu)
 
Archit Gupta (agupta85@ncsu.edu)
 
Ansh Ganatra (aganatr@ncsu.edu)