Authentication

Authentication Flow

A prototypical JWT-based authentication flow looks like this:

• A user logs in to a system (providing credentials) and receives a JWT token.
• The user sends this token with every subsequent request to the server, typically in the Authorization or access_token header.
• The server verifies the token's signature and grants access to the requested resource if the token is valid.
• If the token is invalid or lacks the required permissions, the server denies access.

JWT tokens are not only useful to identify users; they can also be used to share information between different services securely via the payload. Because the signature is calculated using the header and the payload, the receiver can verify the integrity of the token and ensure it hasn't been altered in transit.

Anatomy of a JWT

A JWT is represented as a sequence of URL-safe parts separated by dots (.), with each part containing a base64url-encoded JSON object. Assuming we are using JWS (JSON Web Signature)—which is the most common representation—a JWT consists of three parts:

Dependency injection and components

As an application grows, so does the need to add more dependencies to it. Without Dependency Injection (DI), the Flama application class would have to create and manage all its dependencies internally, making it tightly coupled and harder to test. With DI, dependencies are provided from the outside.

In Flama, a Component is a building block for dependency injection. It encapsulates logic that determines how specific dependencies should be resolved when the application runs.

For authentication, we use the AccessTokenComponent. This component contains all the information and logic necessary for:

1. Extracting a JWT from either the headers or cookies of an incoming request.
2. Decoding the base64url-encoded strings.
3. Validating its authenticity against your application's secret key.

Authentication Middleware

Middleware is a crucial concept that acts as a processing layer between the incoming requests from clients and the responses sent by the server. It functions as a gatekeeper that can inspect, modify, or act on requests before they reach your core application logic.

To handle JWTs, we use the built-in AuthenticationMiddleware. It is designed to ensure that only authorised users can access certain parts of your application. Here is exactly how it works under the hood:

• Handling Requests: Every time a request is made, the middleware intercepts it and checks if the route the request is trying to access requires any specific permissions.
• Permission Check: It extracts the required permissions from the route's tags. If no permissions are required, the request passes through freely.
• Resolution: If permissions are required, the middleware attempts to resolve a JWT token from the request using the AccessTokenComponent we registered.
• Validating Permissions: Once resolved, the middleware checks the permissions embedded inside the token's payload against those required by the route. If the user’s permissions match or exceed the requirements, the request proceeds.
• Handling Errors: If the JWT token is missing, invalid, or lacks sufficient permissions, the middleware catches the exception and returns an appropriate error response (401 Unauthorized or 403 Forbidden).

Initialisation

First, we create our development environment by instantiating the Flama object. We must provide our secret key to the AccessTokenComponent and register the AuthenticationMiddleware.

import uuidfrom flama import Flamafrom flama.middleware import Middlewarefrom flama.authentication import AccessTokenComponent, AuthenticationMiddleware
# The secret key used to sign and verify the tokens. Keep this safe!SECRET_KEY = uuid.UUID(int=0).bytes
app = Flama(    components=[AccessTokenComponent(secret=SECRET_KEY)],    middleware=[Middleware(AuthenticationMiddleware)],)

Generating tokens

To authenticate users, we need a login endpoint. Once a user provides valid credentials, we generate a JWT.

Flama provides the flama.authentication.jwt.jwt.JWT class to easily construct these tokens. For the AuthenticationMiddleware to automatically read the permissions, your custom claims must be placed inside a data dictionary within the payload.

from flama.authentication.jwt import jwt
@app.route("/login/", methods=["POST"])async def login():    # In a real app, verify user credentials (e.g., password hash) here.    # Create the token structure    jwt_token = jwt.JWT(        header={"alg": "HS256", "typ": "JWT"},        payload={            "data": {                "user_id": 123,                # The permissions this user is granted:                "permissions": ["read:secure"],             },            "iat": 0, # Issued At        },    )
    # Encode and digitally sign the token using our SECRET_KEY    token_string = jwt_token.encode(SECRET_KEY).decode()
    return {"token": token_string}

Protecting endpoints

With our middleware in place and tokens being generated, protecting an endpoint is remarkably simple. We use the tags argument in the route decorator and pass a list of required permissions.

@app.route("/secure/", methods=["GET"], tags={"permissions": ["read:secure"]})async def secure_info():    """    The AuthenticationMiddleware blocks any request that lacks     a valid token with the 'read:secure' permission.    """    return {"message": "You have accessed the secure vault!"}

Accessing token data

Often, your business logic needs to know the identity of the user making the request. Because we registered the AccessTokenComponent, we can utilise dependency injection to request the AccessToken directly in our route handler's signature.

Flama will automatically parse the token and inject the object into your function.

from flama.authentication import AccessToken
@app.route("/me/", methods=["GET"], tags={"permissions": ["read:secure"]})async def current_user(token: AccessToken):    # token.to_dict() returns the decoded header and payload dictionaries    return {"your_token_data": token.to_dict()}