Debian Codegraph @

docs/usage/security/jwt.rst

raw
1 JWT Security Backends
2 =====================
3
4 Litestar offers optional JWT based security backends. To use these make sure to install the
5 `pyjwt <https://pyjwt.readthedocs.io/en/stable/>`_ and `cryptography <https://github.com/pyca/cryptography>`_
6 packages, or simply install Litestar with the ``jwt``
7 `extra <https://packaging.python.org/en/latest/specifications/dependency-specifiers/#extras>`_:
8
9 .. code-block:: shell
10 :caption: Install Litestar with JWT extra
11
12 pip install 'litestar[jwt]'
13
14 :class:`JWT Auth <.security.jwt.JWTAuth>` Backend
15 -------------------------------------------------
16
17 This is the base JWT Auth backend. You can read about its particular API in the :class:`~.security.jwt.JWTAuth`.
18 It sends the JWT token using a header - and it expects requests to send the JWT token using the same header key.
19
20 .. dropdown:: Click to see the code
21
22 .. literalinclude:: /examples/security/jwt/using_jwt_auth.py
23 :language: python
24 :caption: Using JWT Auth
25
26 :class:`JWT Cookie Auth <.security.jwt.JWTCookieAuth>` Backend
27 --------------------------------------------------------------
28
29 This backend inherits from the :class:`~.security.jwt.JWTAuth` backend, with the difference being
30 that instead of using a header for the JWT Token, it uses a cookie.
31
32 .. dropdown:: Click to see the code
33
34 .. literalinclude:: /examples/security/jwt/using_jwt_cookie_auth.py
35 :language: python
36 :caption: Using JWT Cookie Auth
37
38 :class:`OAuth2 Bearer <.security.jwt.auth.OAuth2PasswordBearerAuth>` Password Flow
39 ----------------------------------------------------------------------------------
40
41 The :class:`~.security.jwt.auth.OAuth2PasswordBearerAuth` backend inherits from the :class:`~.security.jwt.JWTCookieAuth`
42 backend. It works similarly to the :class:`~.security.jwt.JWTCookieAuth` backend, but is meant to be used for
43 OAuth 2.0 Bearer password flows.
44
45 .. dropdown:: Click to see the code
46
47 .. literalinclude:: /examples/security/jwt/using_oauth2_password_bearer.py
48 :language: python
49 :caption: Using OAUTH2 Bearer Password
50
51
52 Using a custom token class
53 --------------------------
54
55 The token class used can be customized with arbitrary fields, by creating a subclass of
56 :class:`~.security.jwt.Token`, and specifying it on the backend:
57
58 .. literalinclude:: /examples/security/jwt/custom_token_cls.py
59 :language: python
60 :caption: Using a custom token
61
62
63 The token will be converted from JSON into the appropriate type, including basic type
64 conversions.
65
66 .. important::
67 Complex type conversions, especially those including third libraries such as
68 Pydantic or attrs, as well as any custom ``type_decoders`` are not available for
69 converting the token. To support more complex conversions, the
70 :meth:`~.security.jwt.Token.encode` and :meth:`~.security.jwt.Token.decode` methods
71 must be overwritten in the subclass.
72
73
74 Verifying issuer and audience
75 -----------------------------
76
77 To verify the JWT ``iss`` (*issuer*) and ``aud`` (*audience*) claim, a list of accepted
78 issuers or audiences can bet set on the authentication backend. When a JWT is decoded,
79 the issuer or audience on the token is compared to the list of accepted issuers /
80 audiences. If the value in the token does not match any value in the respective list,
81 a :exc:`NotAuthorizedException` will be raised, returning a response with a
82 ``401 Unauthorized`` status.
83
84
85 .. literalinclude:: /examples/security/jwt/verify_issuer_audience.py
86 :language: python
87 :caption: Verifying issuer and audience
88
89
90 Customizing token validation
91 ----------------------------
92
93 Token decoding / validation can be further customized by overriding the
94 :meth:`~.security.jwt.Token.decode_payload` method. It will be called by
95 :meth:`~.security.jwt.Token.decode` with the encoded token string, and must return a
96 dictionary representing the decoded payload, which will then used by
97 :meth:`~.security.jwt.Token.decode` to construct an instance of the token class.
98
99
100 .. literalinclude:: /examples/security/jwt/custom_decode_payload.py
101 :language: python
102 :caption: Customizing payload decoding
103
104
105 Using token revocation
106 ----------------------
107 Token revocation can be implemented by maintaining a list of revoked tokens and checking against this list during authentication.
108 When a token is revoked, it should be added to the list, and any subsequent requests with that token should be denied.
109
110 .. dropdown:: Click to see the code
111
112 .. literalinclude:: /examples/security/jwt/using_token_revocation.py
113 :language: python
114 :caption: Implementing token revocation