Tokens and Authorisation

Because the CSESoc authentication system is not set up yet, this website is currently using its own authentication system based on tokens (we opted to not use the existing system that verified students based on their zIDs, because we wanted to encourage people outside of UNSW to participate in this competition as well).

What are tokens?

Tokens are one of two ways of making sure a user is who they say they are (the other one being sessions). Once a user is registered or logged in, they are given a token by the server, and the user can use that token to verify their identity without needing to provide their username and password every single request (which can be time-consuming and potentially insecure).

If a website's authentication system is seen as a secret bar with a secret password, then tokens are essentially a "VIP pass" - by showing the pass to the security guard and having them verify both the pass's authenticity and whether the pass actually belongs to you, you can get through without needing a password at all.

The main difference between tokens and sessions is that sessions are essentially random strings that correspond to some data stored in the backend, while tokens are self-containing bits of data that contain all the relevant information needed to verify a user's identity. Sessions require a lot of storage in the backend as the website gets more and more users, while with tokens, all of that data is stored on the user's browser. This makes token-based authentication systems trivially easy to scale up (since tokens require no extra storage on the server as more users are added), so we have decided to use tokens here.

If you want to know more about tokens and how they work (and how they're being used in this website), here are some resources:

• The difference between session- and token-based authentication
• An in-depth guide into how JWT tokens work
• The code in auth/jwt.py and common/plugins.py, which contain some code that interacts with the flask_jwt_extended package

How to use tokens

In the specification, a lot of the backend routes specify that a token is needed. In order to make sure that a request is "protected" such that only logged-in users (i.e. users with a token given by the website) are allowed to access it, we can use the @jwt_required decorator from the flask_jwt_extended package:

from flask_jwt_extended import jwt_required

puzzle = Blueprint("puzzle", __name__)

@puzzle.add_route("/foo", methods=["GET"])
@jwt_required
def foo():
    # A token is required to access this route. If no token is found in the user's cookies (which is automatically
    # done when a user logs in or registers), a 401 Unauthorised error is raised.
    pass

We might also need the user's other details from the token, like their user ID or their email address. This can be accessed through the get_jwt_identity() function, which is also provided in flask_jwt_extended (and its features written in common/plugins.py). You can then get the rest of the user's data via the utility function User.get from auth.user:

from flask_jwt_extended import get_jwt_identity

from auth.user import User

def foo():
    id = get_jwt_identity()
    # If you need more than the user's ID:
    user_data = User.get(id)

    # Do whatever you need with the user's data