| 1 |
================================== |
| 2 |
Implementing Custom Authentication |
| 3 |
================================== |
| 4 |
|
| 5 |
Litestar exports :class:`~.middleware.authentication.AbstractAuthenticationMiddleware`, which is an |
| 6 |
:term:`abstract base class` (ABC) that implements the :class:`~.middleware.base.MiddlewareProtocol`. |
| 7 |
To add authentication to your app using this class as a basis, subclass it and implement the abstract method |
| 8 |
:meth:`~.middleware.authentication.AbstractAuthenticationMiddleware.authenticate_request`: |
| 9 |
|
| 10 |
.. code-block:: python |
| 11 |
:caption: Adding authentication to your app by subclassing |
| 12 |
:class:`~.middleware.authentication.AbstractAuthenticationMiddleware` |
| 13 |
|
| 14 |
from litestar.middleware import ( |
| 15 |
AbstractAuthenticationMiddleware, |
| 16 |
AuthenticationResult, |
| 17 |
) |
| 18 |
from litestar.connection import ASGIConnection |
| 19 |
|
| 20 |
|
| 21 |
class MyAuthenticationMiddleware(AbstractAuthenticationMiddleware): |
| 22 |
async def authenticate_request( |
| 23 |
self, connection: ASGIConnection |
| 24 |
) -> AuthenticationResult: |
| 25 |
# do something here. |
| 26 |
... |
| 27 |
|
| 28 |
As you can see, ``authenticate_request`` is an async function that receives a connection instance and is supposed to return |
| 29 |
an :class:`~.middleware.authentication.AuthenticationResult` instance, which is a |
| 30 |
:doc:`dataclass <python:library/dataclasses>` that has two attributes: |
| 31 |
|
| 32 |
1. ``user``: a non-optional value representing a user. It is typed as ``Any`` so it receives any value, |
| 33 |
including ``None``. |
| 34 |
2. ``auth``: an optional value representing the authentication scheme. Defaults to ``None``. |
| 35 |
|
| 36 |
These values are then set as part of the ``scope`` dictionary, and they are made available as |
| 37 |
:attr:`Request.user <.connection.ASGIConnection.user>` |
| 38 |
and :attr:`Request.auth <.connection.ASGIConnection.auth>` respectively, for HTTP route handlers, and |
| 39 |
:attr:`WebSocket.user <.connection.ASGIConnection.user>` and |
| 40 |
:attr:`WebSocket.auth <.connection.ASGIConnection.auth>` for websocket route handlers. |
| 41 |
|
| 42 |
Creating a Custom Authentication Middleware |
| 43 |
----------------------------------------------- |
| 44 |
|
| 45 |
Since the above is quite hard to grasp in the abstract, let us see an example. |
| 46 |
|
| 47 |
We start off by creating a user model. It can be implemented using msgspec, Pydantic, an ODM, ORM, etc. |
| 48 |
For the sake of this example here let us say it is a dataclass: |
| 49 |
|
| 50 |
.. literalinclude:: /examples/security/using_abstract_authentication_middleware.py |
| 51 |
:lines: 19-26 |
| 52 |
:language: python |
| 53 |
:caption: user and token models |
| 54 |
|
| 55 |
|
| 56 |
We can now create our authentication middleware: |
| 57 |
|
| 58 |
.. literalinclude:: /examples/security/using_abstract_authentication_middleware.py |
| 59 |
:lines: 29-43 |
| 60 |
:language: python |
| 61 |
:caption: authentication_middleware.py |
| 62 |
|
| 63 |
|
| 64 |
Finally, we need to pass our middleware to the Litestar constructor: |
| 65 |
|
| 66 |
|
| 67 |
.. literalinclude:: /examples/security/using_abstract_authentication_middleware.py |
| 68 |
:lines: 80-88 |
| 69 |
:language: python |
| 70 |
:caption: main.py |
| 71 |
|
| 72 |
|
| 73 |
That is it. ``CustomAuthenticationMiddleware`` will now run for every request, and we would be able to access these in a |
| 74 |
http route handler in the following way: |
| 75 |
|
| 76 |
.. literalinclude:: /examples/security/using_abstract_authentication_middleware.py |
| 77 |
:lines: 46-51 |
| 78 |
:language: python |
| 79 |
:caption: Accessing the user and auth in a http route handler with ``CustomAuthenticationMiddleware`` |
| 80 |
|
| 81 |
Or for a websocket route: |
| 82 |
|
| 83 |
.. literalinclude:: /examples/security/using_abstract_authentication_middleware.py |
| 84 |
:lines: 54-59 |
| 85 |
:language: python |
| 86 |
:caption: Accessing the user and auth in a websocket route handler with ``CustomAuthenticationMiddleware`` |
| 87 |
|
| 88 |
|
| 89 |
And if you would like to exclude individual routes outside those configured: |
| 90 |
|
| 91 |
|
| 92 |
.. literalinclude:: /examples/security/using_abstract_authentication_middleware.py |
| 93 |
:lines: 62-70 |
| 94 |
:language: python |
| 95 |
:caption: Excluding individual routes from ``CustomAuthenticationMiddleware`` |
| 96 |
|
| 97 |
And of course use the same kind of mechanism for dependencies: |
| 98 |
|
| 99 |
.. literalinclude:: /examples/security/using_abstract_authentication_middleware.py |
| 100 |
:lines: 73-77 |
| 101 |
:language: python |
| 102 |
:caption: Using ``CustomAuthenticationMiddleware`` in a dependency |