This module secures the API backend by requiring users to register an account with the system and then to use that account to authenticate to the API by using a JWT token generated by login.
An account is separate to a user profile. In the context of the backend, the account contains only the user's username, email and password, i.e., the only information required for authentication. The users module provides user profile information and user role management.
All endpoints in this module begin with the path /api/auth. The endpoints are outlined below:
| Endpoint | Method | Description |
|---|---|---|
| /register | POST | This endpoint allows a user to create an account in the system if the account doesn't already exist |
| /# | POST | This endpoint allows authentication of an account to generate a JWT token |
| /account | GET | This endpoint allows the retrieval of an account |
| PUT | This endpoint allows a user to update the password of their own account. | |
| /account/confirmed | GET | This endpoint allows a user to check if their account is confirmed |
| /account/confirm | POST | This endpoint allows a user to confirm their account |
| /admin/account | PUT | This endpoint allows an admin to update the account of any user in the system. This should be locked by the users module with an Admin permission |
| /forgot-password | POST | This endpoint allows for the sending of a password reset token to the account's e-mail address |
| /reset-password | POST | This endpoint allows an account's password to be reset using a given token |
Note that all endpoints in the system (except for register, login, /account/confirmed and /account/confirm/) require the following header:
Authorization: Bearer <jwt-token>
The jwt-token is returned by a successful request to the login endpoint
The following configuration properties are provided by the authentication module in application.ethics.properties file:
auth.jwt.secret: This is a secret key that needs to be defined before the system is started initially. It needs to be at least 35 characters long. It should not be changed after the system is started, since JWT tokens will not be able to be parsedauth.jwt.token.validity: The number of hours the JWT tokens should be valid forauth.always-confirm: If true, new accounts are always confirmed and no requirement for email confirmation. Recommended to keep it false. Can be true for testingauth.confirmation-key: If this key is passed in with a registration request, the account is automatically confirmed. This key is used to facilitate testing if confirmation is enabledauth.scheduling.cron: A CRON expression for running scheduled auth operationsauth.unconfirmed-removal: Specifies the number of days after which unconfirmed accounts should be removedauth.reset-token-expiry: Specifies the number of hours after which password reset tokens should expire
Requires email confirmation messages to be sent if confirmation is enabled. See common module's properties for properties to enter the details of the email server account to send emails from