Brief introduction

We can start with the official definition given in the RFC 7519 document:

JSON Web Token (JWT) is a compact, URL-safe means of representing claims to be transferred between two parties. The claims in a JWT are encoded as a JSON object that is used as the payload of a JSON Web Signature (JWS) structure or as the plaintext of a JSON Web Encryption (JWE) structure, enabling the claims to be digitally signed or integrity protected with a Message Authentication Code (MAC) and/or encrypted.

So, in simple terms, JWT is an open standard that defines a way for transmitting information between two parties in the form of a JSON object. The information being transmitted is digitally signed to ensure its integrity and authenticity. This is why one of the main use cases of JWT is for authorisation purposes.

A prototypical JWT-based authentication flow would look something like this:

• A user logs in to a system and receives a JWT token.
• The user sends this token with every subsequent request to the server.
• The server verifies the token and grants access to the requested resource if the token is valid.
• If the token is invalid, the server denies access to the resource.

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

JWT Structure

A JWT is represented as a sequence of URL-safe parts separated by dots (.), with each part containing a base64url-encoded JSON object. The number of parts in the JWT can vary depending on the representation being used, either JWS (JSON Web Signature) RFC-7515 or JWE (JSON Web Encryption) RFC-7516. As of this point, we can assume we'll be using JWS, which is the most common representation for JWT tokens. In this case, a JWT token consists of three parts:

• Header: Contains metadata about the token and the cryptographic operations applied to it.
• Payload: Contains the claims (information) that the token is carrying.
• Signature: Ensures the integrity of the token and is used to verify that the sender of the token is who it claims to be.

Thus, the syntax of a prototypical JWS JSON using the flattened JWS JSON Serialization is as follows (for more info, see RFC-7515 Sec. 7.2.2):

{   "payload":"<payload contents>",   "header":<header contents>,   "signature":"<signature contents>"}

In the JWS Compact Serialization, the JTW is represented as the concatenation:

BASE64URL(UTF8(JWS Header)) || '.' || BASE64URL(JWS Payload) || '.' || BASE64URL(JWS Signature)

An example of a JWT token would look like this (taken from one of the Flama tests here):

eyJhbGciOiAiSFMyNTYiLCAidHlwIjogIkpXVCJ9.eyJkYXRhIjogeyJmb28iOiAiYmFyIn0sICJpYXQiOiAwfQ==.J3zdedMZSFNOimstjJat0V28rM_b1UU62XCp9dg_5kg=

Setting up the development environment

Our first step is to create our development environment, and install all required dependencies for this project. The good thing is that for this example we only need to install flama to have all the necessary tools to implement JWT authentication. We'll be using poetry to manage our dependencies, but you can also use pip if you prefer:

poetry add flama[full]

If you want to know how we typically organise our projects, have a look at our previous post here, where we explain in detail how to set up a python project with poetry, and the project folder structure we usually follow.

Base application

Let's start with a simple application that has a single public endpoint. This endpoint will return a brief description of the API.

from flama import Flama
app = Flama(    title="JWT protected API",    version="1.0.0",    description="JWT Authentication with Flama 🔥",    docs="/docs/",)
@app.get("/public/info/", name="public-info")def info():    """    tags:        - Public    summary:        Ping    description:        Returns a brief description of the API    responses:        200:            description:                Successful ping.    """    return {"title": app.schema.title, "description": app.schema.description, "public": True}

If you want to run this application, you can save the code above in a file called main.py under the src folder, and then run the following command (remember to have the poetry environment activated, otherwise you'll need to prefix the command with poetryrun):

flama run --server-reload src.main:app
INFO:     Started server process [3267]INFO:     Waiting for application startup.INFO:     Application startup complete.INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

where the --server-reload flag is optional and is used to reload the server automatically when the code changes. This is very useful during development, but you can remove it if you don't need it. For a full list of the available options, you can run flamarun--help, or check the documentation.

Authentication: Flama JWT Component

Ok, now that we have our base application running, let's add a new endpoint that requires authentication. To do this, we'll need to use the following flama functionality:

• Components (specifically JWTComponent): They're the building blocks for dependency injection in flama.
• Middlewares (specifically AuthenticationMiddleware): They're used as a processing layer between the incoming requests from clients and the responses sent by the server.

Let's proceed and modify our base application to include the JWT authentication as intended, and then we'll explain the code in more detail.

import uuid
from flama import Flamafrom flama.authentication import AuthenticationMiddleware, JWTComponentfrom flama.middleware import Middleware
JWT_SECRET_KEY = uuid.UUID(int=0).bytes  # The secret key used to signed the tokenJWT_HEADER_KEY = "Authorization"  # Authorization header identifieJWT_HEADER_PREFIX = "Bearer"  # Bearer prefixJWT_ALGORITHM = "HS256"  # Algorithm used to sign the tokenJWT_TOKEN_EXPIRATION = 300  # 5 minutes in secondsJWT_REFRESH_EXPIRATION = 2592000  # 30 days in secondsJWT_ACCESS_COOKIE_KEY = "access_token"JWT_REFRESH_COOKIE_KEY = "refresh_token"
app = Flama(    title="JWT-protected API",    version="1.0.0",    description="JWT Authentication with Flama 🔥",    docs="/docs/",)
app.add_component(    JWTComponent(        secret=JWT_SECRET_KEY,        header_key=JWT_HEADER_KEY,        header_prefix=JWT_HEADER_PREFIX,        cookie_key=JWT_ACCESS_COOKIE_KEY,    ))
app.add_middleware(    Middleware(AuthenticationMiddleware),)
# The same code as before here# ...

Although we've decided to add the component and middleware after the initialisation of the app, you can also add them directly to the Flama constructor by passing the components and middlewares arguments:

app = Flama(    title="JWT-protected API",    version="1.0.0",    description="JWT Authentication with Flama 🔥",    docs="/docs/",    components=[        JWTComponent(            secret=JWT_SECRET_KEY,            header_key=JWT_HEADER_KEY,            header_prefix=JWT_HEADER_PREFIX,            cookie_key=JWT_ACCESS_COOKIE_KEY,        )    ],    middlewares=[        Middleware(AuthenticationMiddleware),    ])

This is just a matter of preference, and both ways are completely valid.

With the modifications introduced above, we can proceed to add a new (and JWT protected) endpoint. However, before we do that, let's briefly explain in more detail the functionality we've just introduced, namely components and middlewares.

Adding a protected endpoint

By now, we should have a pretty solid understanding on what our code does, and how it does it. Nevertheless, we still need to see what we have to do to add a protected endpoint to our application. Let's do it:

@app.get("/private/info/", name="private-info", tags={"permissions": ["my-permission-name"]})def protected_info():    """    tags:        - Private    summary:        Ping    description:        Returns a brief description of the API    responses:        200:            description:                Successful ping.    """    return {"title": app.schema.title, "description": app.schema.description, "public": False}

And that's it! We've added a new endpoint that requires authentication to access. The functionality is exactly the same as the previous endpoint, but this time we've added the tags parameter to the @app.get decorator. The tag parameter can be used to specify additional metadata for an endpoint. But, if we use the special key permissions whilst using the AuthenticationMiddleware, we can specify the permissions required to access the endpoint. In this case, we've set the permissions to ["my-permission-name"], which means that only users with the permission my-permission-name will be able to access this endpoint. If a user tries to access the endpoint without the required permission, they will receive a 403Forbidden response.

Running the application

If we put all the pieces together, we should have a fully functional application that has a public endpoint and a private endpoint that requires authentication. The full code should look something like this:

import uuid
from flama import Flamafrom flama.authentication import AuthenticationMiddleware, JWTComponentfrom flama.middleware import Middleware
JWT_SECRET_KEY = uuid.UUID(int=0).bytes  # The secret key used to signed the tokenJWT_HEADER_KEY = "Authorization"  # Authorization header identifieJWT_HEADER_PREFIX = "Bearer"  # Bearer prefixJWT_ALGORITHM = "HS256"  # Algorithm used to sign the tokenJWT_TOKEN_EXPIRATION = 300  # 5 minutes in secondsJWT_REFRESH_EXPIRATION = 2592000  # 30 days in secondsJWT_ACCESS_COOKIE_KEY = "access_token"JWT_REFRESH_COOKIE_KEY = "refresh_token"
app = Flama(    title="JWT-protected API",    version="1.0.0",    description="JWT Authentication with Flama 🔥",    docs="/docs/",)
app.add_component(    JWTComponent(        secret=JWT_SECRET_KEY,        header_key=JWT_HEADER_KEY,        header_prefix=JWT_HEADER_PREFIX,        cookie_key=JWT_ACCESS_COOKIE_KEY,    ))
app.add_middleware(    Middleware(AuthenticationMiddleware),)
@app.get("/public/info/", name="public-info")def info():    """    tags:        - Public    summary:        Info    description:        Returns a brief description of the API    responses:        200:            description:                Successful ping.    """    return {"title": app.schema.title, "description": app.schema.description, "public": True}

@app.get("/private/info/", name="private-info", tags={"permissions": ["my-permission-name"]})def protected_info():    """    tags:        - Private    summary:        Info    description:        Returns a brief description of the API    responses:        200:            description:                Successful ping.    """    return {"title": app.schema.title, "description": app.schema.description, "public": False}

Running the application as before, we should see the following output:

flama run --server-reload src.main:app
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)INFO:     Started reloader process [48145] using WatchFilesINFO:     Started server process [48149]INFO:     Waiting for application startup.INFO:     Application startup complete.

If we navigate with our favourite browser to http://127.0.0.1:8000/docs/ we should see the documentation of our API as shown below:

As we can already expect, if we send a request to the public endpoint /public/info/ we should receive a successful response:

curl --request GET \  --url http://localhost:8000/public/info/ \  --header 'Accept: application/json'{"title":"JWT protected API","description":"JWT Authentication with Flama 🔥","public":true}

However, if we try to access the private endpoint /private/info/ without providing a valid JWT token, we should receive a 401Unauthorized response:

curl --request GET \  --url http://localhost:8000/private/info/ \  --header 'Accept: application/json'{"status_code":401,"detail":"Unauthorized","error":null}%

Thus, we can say that the JWT authentication is working as expected, and only users with a valid JWT token will be able to access the private endpoint.

Adding the login endpoint

As we've just seen, we have a private endpoint which requires a valid JWT token to be accessed. But, how do we get this token? The answer is simple: we need to create a login endpoint that will authenticate the user and return a valid JWT token. To do this, we're going to define the schemas for the input and output of the login endpoint (feel free to use your own schemas if you prefer, for instance, adding more fields to the input schema such as username or email):

import uuidimport typingimport pydantic
class User(pydantic.BaseModel):    id: uuid.UUID    password: typing.Optional[str] = None

class UserToken(pydantic.BaseModel):    id: uuid.UUID    token: str

Now, let's add the login endpoint to our application:

import http
from flama import typesfrom flama.authentication.jwt import JWTfrom flama.http import APIResponse
@app.post("/auth/", name="signin")def signin(user: types.Schema[User]) -> types.Schema[UserToken]:    """    tags:        - Public    summary:        Authenticate    description:        Returns a user token to access protected endpoints    responses:        200:            description:                Successful ping.    """    token = (        JWT(            header={"alg": JWT_ALGORITHM},            payload={                "iss": "vortico",                "data": {"id": str(user["id"]), "permissions": ["my-permission-name"]},            },        )        .encode(JWT_SECRET_KEY)        .decode()    )
    return APIResponse(        status_code=http.HTTPStatus.OK, schema=types.Schema[UserToken], content={"id": str(user["id"]), "token": token}    )

In this code snippet, we've defined a new endpoint /auth/ that receives a User object as input and returns a UserToken object as output. The User object contains the id of the user and the password (which is optional for this example, since we're not going to be comparing it with any stored password). The UserToken object contains the id of the user and the generated token that will be used to authenticate the user in the private endpoints. The token is generated using the JWT class, and contains the permissions granted to the user, in this case, the permission my-permission-name, which will allow the user to access the private endpoint /private/info/.

Now, let's test the login endpoint to see if it's working as expected. For this, we can proceed via the /docs/ page:

Or, we can use curl to send a request to the login endpoint:

curl --request POST \  --url http://localhost:8000/auth/ \  --header 'Accept: application/json' \  --header 'Content-Type: application/json' \  --data '{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "password": "string"}'

which should return a response similar to this:

{"id":"497f6eca-6276-4993-bfeb-53cbbbba6f08","token":"eyJhbGciOiAiSFMyNTYiLCAidHlwIjogIkpXVCJ9.eyJkYXRhIjogeyJpZCI6ICI0OTdmNmVjYS02Mjc2LTQ5OTMtYmZlYi01M2NiYmJiYTZmMDgiLCAicGVybWlzc2lvbnMiOiBbIm15LXBlcm1pc3Npb24tbmFtZSJdfSwgImlhdCI6IDE3MjU5ODk5NzQsICJpc3MiOiAidm9ydGljbyJ9.vwwgqahgtALckMAzQHWpNDNwhS8E4KAGwNiFcqEZ_04="}

That string is the JWT token that we can use to authenticate the user in the private endpoint. Let's try to access the private endpoint using the token:

curl --request GET \  --url http://localhost:8000/private/info/ \  --header 'Accept: application/json' \  --header 'Authorization: Bearer eyJhbGciOiAiSFMyNTYiLCAidHlwIjogIkpXVCJ9.eyJkYXRhIjogeyJpZCI6ICI0OTdmNmVjYS02Mjc2LTQ5OTMtYmZlYi01M2NiYmJiYTZmMDgiLCAicGVybWlzc2lvbnMiOiBbIm15LXBlcm1pc3Npb24tbmFtZSJdfSwgImlhdCI6IDE3MjU5ODk5NzQsICJpc3MiOiAidm9ydGljbyJ9.vwwgqahgtALckMAzQHWpNDNwhS8E4KAGwNiFcqEZ_04='

which now returns a successful response:

{"title":"JWT protected API","description":"JWT Authentication with Flama 🔥","public":false}

And that's it! We've successfully implemented JWT authentication in our Flama application. We now have a public endpoint that can be accessed without authentication, a private endpoint that requires a valid JWT token to be accessed, and a login endpoint that generates a valid JWT token for the user.