Debian Codegraph @

docs/usage/security/abstract-authentication-middleware.rst

raw
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