Overview - Aligheri/jwt-owasp-based-starter GitHub Wiki

Overview

The jwt-owasp-based-starter implements authentication mechanism that follows the OWASP JWT Cheat Sheet and provides secure user authentication using two JSON Web Token (JWT) and cookie session values.

Key Features:

  • JWT-Based Authentication: The system uses JSON Web Tokens (JWT) for secure user authentication, following the OWASP JWT Cheat Sheet guidelines.

  • Cookie: A unique cookie is generated for each user. This feature ensures a high level of user uniqueness by creating a random value linked to the user. In this documentation, we will refer to this feature as a "fingerprint."

  • AES-256-GCM Encryption: To ensure the security and protection of our clients' information, all tokens are encrypted using AES-256-GCM encryption via Google Tink, safeguarding their data from unauthorised access, modification, or disclosure.

  • Token Revocation Mechanism: Token Revocation Mechanism: The system supports token revocation, which prevents unauthorised access after a user logs out by adding a token to the denylist.

Workflow Overview

Untitled Diagram drawio

  • User registration: First, the user provides the following credentials: username, email, and password. The server then creates an instance of the user, stores it in the database and send One-Time Password (OTP) . Then user must proceed to the activation account page. On this page, the user is prompted to provide the OTP that was sent to the email address provided during registration.

  • Login: The user is prompted to enter their credentials — username and password.The server then generates a random value of the user identifier (fingerprint) and encodes it in HEX, storing its other value. The server creates Cookie using fingerprint and a JWT token using the user details and the HEX encoded fingerprint value. Following the completion of the login process, the server encrypts the JWT and generates a response that contains the user's details , ciphered JWT and Cookie . The following requests to the secure page must contain the user's ciphered JWT and the Cookie with the fingerprint value.

  • Session validation process : At this point, the user is required to present their ciphered JWT and Cookie with a fingerprint value. When the user is sending an authenticated request, the server first verifies the presence of the JWT token in request and the user in the database. The server then deciphers the token and checks if it has been revoked. Next, the server verifies the presence of the cookie. Following the completion of these steps, the server verifies the attributes of the token. The token must contain an "issuer ID," a "HEX-encoded fingerprint value" (the original fingerprint value is HEX-encoded and compared with the JWT fingerprint attribute), and a signature with the same "secret key."

  • Log out: The server sets the cookie expiration date to zero, which automatically deletes the cookie. Then, the server revokes the JWT by deciphering and storing its digest in the revocation table of the database.