| 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 |