JWTConfig

JWT extends for JSON Web Token and it can be used with any middleware at your desire that implements the BaseAuthMiddleware.

Tip

More information about JWT here.

Requirements

Esmerald uses python-jose and passlib for this JWT integration. You can install by running:

$ pip install esmerald[jwt]

JWTConfig and application

To use the JWTConfig with a middleware.

from myapp.models import User
from starlette.middleware import Middleware as StarletteMiddleware

from esmerald import Esmerald, settings
from esmerald.config.jwt import JWTConfig
from esmerald.contrib.auth.tortoise.middleware import JWTAuthMiddleware

jwt_config = JWTConfig(
    signing_key=settings.secret_key,
)

auth_middleware = StarletteMiddleware(JWTAuthMiddleware, config=jwt_config, user_model=User)

app = Esmerald(middleware=[auth_middleware])

Info

The example uses a supported JWTAuthMiddleware from Esmerald with Saffier ORM.

Parameters

All the parameters and defaults are available in the JWTConfig Reference.

JWTConfig and application settings

The JWTConfig can be done directly via application instantiation but also via settings.

from typing import TYPE_CHECKING, List

from starlette.middleware import Middleware as StarletteMiddleware

from esmerald import EsmeraldAPISettings
from esmerald.config.jwt import JWTConfig
from esmerald.contrib.auth.saffier.middleware import JWTAuthMiddleware
from esmerald.utils.module_loading import import_string

if TYPE_CHECKING:
    from esmerald.types import Middleware


class CustomSettings(EsmeraldAPISettings):
    @property
    def jwt_config(self) -> JWTConfig:
        """
        A JWT object configuration to be passed to the application middleware
        """
        return JWTConfig(signing_key=self.secret_key, auth_header_types=["Bearer", "Token"])

    @property
    def middleware(self) -> List["Middleware"]:
        """
        Initial middlewares to be loaded on startup of the application.
        """
        return [
            StarletteMiddleware(
                JWTAuthMiddleware,
                config=self.jwt_config,
                user_model=import_string("myapp.models.User"),
            )
        ]

This will make sure you keep the settings clean, separated and without a bloated Esmerald instance.

Token model

Esmerald offers a pretty standard Token object that allows you to generate and decode tokens at ease.

from esmerald.security.jwt.token import Token

token = Token(exp=..., iat=..., sub=...)

The parameters are pretty standard from Python JOSE so you can feel confortable with.

Generate a Token (encode)

The token offers simple and standard operations to interact with python-jose.

from esmerald.security.jwt.token import Token
from esmerald.conf import settings

# Create the token model
token = Token(exp=..., iat=..., sub=...)

# Generate the JWT token
jwt_token = Token.encode(key=settings.secret_key, algorithm="HS256", **claims)

Decode a Token (encode)

The same decoding functionality is also provided.

from esmerald.security.jwt.token import Token
from esmerald.conf import settings

# Decodes the JWT token
jwt_token = Token.decode(token=..., key=settings.secret_key, algorithms=["HS256"])

The Token.decode returns a Token object.

Note

This functionality relies heavily on python-jose but it is not mandatory to use it in any way. You are free to use any library that suits your unique needs. Esmerald only offers some examples and alternatives.