This module contains the controllers for handling user authentication, including login, signup, password reset, super admin activation, and deactivation routes.
The following routes are handled by this module and their corresponding functions:
POST /auth/login POST /auth/signup POST /auth/addadmin GET /auth/superadmin/reqactivation/:email POST /auth/superadmin/activate GET /auth/superadmin/reqdeactivation/:email POST /auth/superadmin/deactivate POST /auth/user/activate/:email POST /auth/user/deactivate/:email l POST /auth/forgotpassword POST /auth/resetpassword POST /auth/googlesignin GET /auth/github GET /auth/github/callback POST /auth/google/callback GET /auth/verifyemail/:token
Methods
# static activateSuperAdminAccount(req, res, next) → {Object|boolean|Object|string}
Activates a super admin account.
This function activates a super admin account on the MOOCs platform. The function requires three activation codes to complete the account activation process. These activation codes are generated when the super admin requests for account activation. This function is used by the super admin to activate the account.
Parameters:
| Name | Type | Description |
|---|---|---|
req |
Object
|
The request object. |
res |
Object
|
The response object. |
next |
function
|
The next middleware function. |
req.body.activation_code1 |
string
|
The first activation code sent to the new super admin. |
req.body.activation_code2 |
string
|
The second activation code sent to the project hosts. |
req.body.activation_code3 |
string
|
The third activation code sent to the project hosts. |
- See:
-
- module:controllers/auth~requestSuperAdminAccountActivation for generating the activation codes.
View Source API/src/controllers/auth.controllers.js, line 491
If any of the activation codes are missing.
BadRequestError
If the user making the request is not a super admin.
BadRequestError
If the activation code is invalid.
BadRequestError
If the activation code has expired.
BadRequestError
If any other error occurs.
Error
The response object containing a status field and a success message.
Object
response.success - The status of the request, which is always true.
boolean
response.data - The data returned by the function.
Object
response.data.message - The success message, which is "Super admin account activated".
string
# static activateUserAccount(req, res, next) → {object|boolean|object|string}
Activates a user account if the account exists and it's not already active.
Parameters:
| Name | Type | Description |
|---|---|---|
req |
object
|
The HTTP request object |
params |
object
|
The request parameters object |
params.email |
string
|
The email address of the user to activate |
res |
object
|
The HTTP response object |
next |
function
|
The next middleware function |
- If the email parameter is missing or invalid
BadRequestError
- If the user account does not exist
BadRequestError
- If the user account is already active
BadRequestError
- If the user is a super admin (super admin accounts cannot be activated)
ForbiddenError
- If an unexpected error occurs
Error
- The HTTP response object
object
success - Indicates if the request was successful
boolean
data - An object containing the success message
object
data.message - A message indicating the user account was activated
string
# static addAdmin(req, res, next) → {Promise.<Object>}
Create a new admin account and send a verification email to the user.
This function is only accessible to the superadmin to create a new admin account.
Parameters:
| Name | Type | Description |
|---|---|---|
req |
Object
|
Express request object |
body |
Object
|
Request body containing user details |
body.email |
string
|
User email |
body.password |
string
|
User password |
body.passwordConfirm |
string
|
User password confirmation |
body.firstname |
string
|
User firstname |
body.lastname |
string
|
User lastname |
res |
Object
|
Express response object |
next |
function
|
Express next middleware function |
If email or password is not provided or incorrect.
BadRequestError
If an error occurs while creating the user or sending the verification email.
Error
- Returns a promise that resolves to an object with the following properties:
- user: Mongoose user object
- token: JWT token
- status: Status of the request
Promise.<Object>
# static deactivateSuperAdminAccount(deactivation_code1, deactivation_code2, deactivation_code3) → {string}
Deactivates super admin account if all activation codes are correct
Parameters:
| Name | Type | Description |
|---|---|---|
deactivation_code1 |
string
|
deactivation code 1 sent to new super admin |
deactivation_code2 |
string
|
deactivation code 2 sent to project hosts |
deactivation_code3 |
string
|
deactivation code 3 sent to project hosts |
- See:
-
- module:controllers/auth~requestSuperAdminAccountDeactivation for requesting for a deactivation code.
View Source API/src/controllers/auth.controllers.js, line 621
if activation codes are not provided
BadRequestError
if token is invalid or token has expired
BadRequestError
if token is blacklisted
BadRequestError
if error occurs
Note: To obtain the deactivation code,
a request must first be made to the requestSuperAdminAccountDeactivation() route.
This route sends an email with the codes to the new
super admin and two other emails with parts of the code to the project hosts.
Error
status - Status of the request
string
# static deactivateUserAccount(email) → {Object|boolean|Object|string}
Deactivates user account if user account exists and it's active
Parameters:
| Name | Type | Description |
|---|---|---|
email |
string
|
User email |
If user account does not exist or is already deactivated
BadRequestError
If user is a SuperAdmin account
ForbiddenError
If an unexpected error occurs
Error
response - The HTTP response
Object
response.success - Indicates if the request was successful
boolean
response.data - The response data
Object
response.data.message - A message indicating the status of the request
string
# static forgetPassword(email) → {Object}
Sends a password reset code to a user's email.
Parameters:
| Name | Type | Description |
|---|---|---|
email |
string
|
User's email address. |
If the required parameter is missing in the request body.
BadRequestError
If the user does not exist.
BadRequestError
An object containing a success message and an access token.
Object
# static getLoggedInUser(req, res) → {Object|string|Object|Object}
Get data for the currently logged in user.
Parameters:
| Name | Type | Description |
|---|---|---|
req |
Object
|
The request object. |
user |
Object
|
The user object set by the |
user.id |
string
|
The ID of the currently logged in user. |
res |
Object
|
The response object. |
if an error occurs while fetching the user data.
Error
- The response object containing the user data.
Object
.status - The status of the response, either "success" or "error".
string
.data - The data returned by the response.
Object
.data.user - The user object containing the data for the currently logged in user.
Object
# static googleSignin(req) → {Object|string|string|string}
Sign in a user using their Google account.
Parameters:
| Name | Type | Description |
|---|---|---|
req |
Object
|
The request object. |
headers.authorization |
string
|
The authorization header containing the Google auth code. |
If an error occurs during the sign-in process.
Error
If the required parameter is missing from the request body.
BadRequestError
If the user does not exist.
BadRequestError
If the user is not verified.
BadRequestError
An object containing the status of the request, the access token, and the refresh token.
Object
status - The status of the request.
string
access_token - The access token.
string
refresh_token - The refresh token.
string
# static login(req, res, next) → {object}
Login a user and return a JWT token.
This function logs in a user with their email and password, and returns two JWT tokens: an access token and a refresh token. The access token is used to authenticate the user on subsequent requests, and expires after 15 minutes. The refresh token is used to refresh the access token, and expires after 2 days.
Parameters:
| Name | Type | Description |
|---|---|---|
req |
object
|
The HTTP request object. |
res |
object
|
The HTTP response object. |
next |
function
|
The next middleware function. |
req.body.email |
string
|
The user's email address. |
req.body.password |
string
|
The user's password. |
- If the email or password is missing or incorrect, or if the email is not verified or the account is not activated.
CustomAPIError
- If an error occurs.
Error
- The HTTP response object containing a success flag, the user object, an access token, and a refresh token.
object
# static requestSuperAdminAccountActivation(email) → {Object}
This function allows the super admin to request for account activation.
The super admin account is not activated by default for security reasons. This function generates two activation codes - one for the super admin and one for the project hosts. The new super admin uses the first activation code to activate the account, and the project hosts use the second activation code to activate the account.
Once the activation codes are generated, they are sent to the super admin and the project hosts via email. The activation codes will be required to complete the account activation process.
Parameters:
| Name | Type | Description |
|---|---|---|
email |
string
|
Super admin email. |
If the super admin account does not exist.
CustomAPIError
If the super admin account is already active.
CustomAPIError
If an error occurs during the request.
Error
The status of the request and access token if successful.
Object
# static requestSuperAdminAccountDeactivation(email) → {string}
If a super admin account is deactivated, all project hosts will be notified. This function generates three deactivation codes and sends them to the super admin and two project hosts via email.
Parameters:
| Name | Type | Description |
|---|---|---|
email |
string
|
Super admin email |
- See:
-
- module:controllers/auth~deactivateSuperAdminAccount for deactivating the super admin account.
View Source API/src/controllers/auth.controllers.js, line 551
if super admin account does not exist
CustomAPIError
if super admin account is already active
CustomAPIError
if error occurs
Error
status - Status of the request
string
# static resetPassword(req) → {Object|boolean|Object|string}
Resets the password of the authenticated user if the provided password reset code is valid.
Note: A request has to be made to the forgetPassword endpoint to get a password reset code. Then the password reset code is sent to the user's email address. This endpoint is used to reset the password using the password reset code.
Parameters:
| Name | Type | Description |
|---|---|---|
req |
Object
|
Express request object. |
body |
Object
|
Request body. |
body.new_password |
string
|
New password. |
body.password_reset_code |
string
|
Password reset code. |
user |
Object
|
Authenticated user object. |
user.id |
string
|
User ID. |
- See:
-
- forgetPassword for more information on how to get a password reset code.
View Source API/src/controllers/auth.controllers.js, line 835
If the required parameters are missing in the request body.
BadRequestError
If the user does not exist.
BadRequestError
If the password reset code is invalid.
BadRequestError
If the password reset code has expired.
BadRequestError
If the access token has expired or is invalid.
UnauthorizedError
If any other error occurs.
Error
Response object.
Object
Response.success - Indicates if the request was successful.
boolean
Response.data - Response data.
Object
Response.data.message - Success message.
string
# static signup(role, email, password, passwordConfirm, firstname, lastname) → {object}
This function creates a new user and sends a verification email to the user.
The user is created using the User model, and the user's password is hashed using the bcrypt library. The user is created with the status of unverified, which means that the user cannot login until their email address is verified.
Each user account has a status document linked to it, which holds two data fields: isVerified and isActive. By default, isVerified is set to false, which means that the user cannot login until their email address is verified. isActive is set to true for EndUsers, which means that the user account is active.
For Superadmin accounts, it has to be activated using the superadmin activation route.
Parameters:
| Name | Type | Description |
|---|---|---|
role |
string
|
User role (EndUser, Admin, SuperAdmin) |
email |
string
|
User email |
password |
string
|
User password |
passwordConfirm |
string
|
User password confirmation |
firstname |
string
|
User firstname |
lastname |
string
|
User lastname |
- See:
-
- module:controllers/auth~activateSuperAdmin
View Source API/src/controllers/auth.controllers.js, line 207
if passwordConfirm is not provided
BadRequestError
if an error occurs
Error
Object containing the new user object, JWT token, and the status of the request
// TODO: Add super admin signup
object
# static verifyEmail(req, res, next) → {object}
Verify a user's email.
This function verifies a user's email using a JWT token. If the token is valid and not blacklisted, the user's email is marked as verified in the database. Otherwise, an error is returned.
Parameters:
| Name | Type | Description |
|---|---|---|
req |
object
|
The HTTP request object. |
res |
object
|
The HTTP response object. |
next |
function
|
The next middleware function. |
- If the token is invalid or expired.
CustomAPIError
- If an error occurs.
Error
- The HTTP response object containing a success flag and a message.
object
# inner handleExistingUser(user) → {function}
It sends new verification email to user if the existing user is unverified
Parameters:
| Name | Type | Description |
|---|---|---|
user |
MongooseObject
|
Mongoose user object |
- If user is already verified
BadRequestError
- Express middleware function
function
# inner handleUnverifiedUser(user) → {string}
Ssends new verification email to user if the existing user is unverified
Inside the email, there is a link that the user can click to verify their email address, this link contains a JWT token that is used to verify the user's email address, the token has an expiry date of 1 hour
The token is generated using the getAuthTokens function
Parameters:
| Name | Type | Description |
|---|---|---|
user |
MongooseObject
|
Mongoose user object |
access_token, refresh_token - JWT tokens
string