| 1 |
Excluding and including endpoints |
| 2 |
================================= |
| 3 |
|
| 4 |
Please make sure you read the :doc:`security backends documentation </usage/security/security-backends>` first for |
| 5 |
learning how to set up a security backend. This section focuses on configuring the ``exclude`` rule for those backends. |
| 6 |
|
| 7 |
There are multiple ways for including or excluding endpoints in the authentication flow. The default rules are |
| 8 |
configured in the ``Auth`` object used (subclass of :class:`~.security.base.AbstractSecurityConfig`). The examples |
| 9 |
below use :class:`~.security.session_auth.auth.SessionAuth` but it is the same for :class:`~.security.jwt.auth.JWTAuth` |
| 10 |
and :class:`~.security.jwt.auth.JWTCookieAuth`. |
| 11 |
|
| 12 |
Excluding routes |
| 13 |
-------------------- |
| 14 |
|
| 15 |
The ``exclude`` argument takes a :class:`string <str>` or :class:`list` of :class:`strings <str>` that are interpreted |
| 16 |
as regex patterns matched against the full path. Because the patterns are not implicitly anchored, a pattern like |
| 17 |
``/schema`` would match *any* path containing ``/schema``, not just paths that start with it. To match only paths that |
| 18 |
start with a given prefix, anchor the pattern with ``^``. For example, the configuration below would apply |
| 19 |
authentication to all endpoints except those where the route starts with ``/login``, ``/signup``, or ``/schema``. |
| 20 |
Thus, one does not have to exclude ``/schema/swagger`` as well — it is covered by the ``^/schema`` pattern. |
| 21 |
|
| 22 |
.. danger:: |
| 23 |
|
| 24 |
Passing ``/`` will disable authentication for all routes, since, as a regex, it |
| 25 |
matches *every* path. |
| 26 |
|
| 27 |
.. code-block:: python |
| 28 |
|
| 29 |
session_auth = SessionAuth[User, ServerSideSessionBackend]( |
| 30 |
retrieve_user_handler=retrieve_user_handler, |
| 31 |
# we must pass a config for a session backend. |
| 32 |
# all session backends are supported |
| 33 |
session_backend_config=ServerSideSessionConfig(), |
| 34 |
# exclude any URLs that should not have authentication. |
| 35 |
# We exclude the documentation URLs, signup and login. |
| 36 |
exclude=[r"^/login", r"^/signup", r"^/schema"], |
| 37 |
) |
| 38 |
... |
| 39 |
|
| 40 |
Including routes |
| 41 |
---------------- |
| 42 |
|
| 43 |
Since the exclusion rules are evaluated as regex, it is possible to pass a rule that inverts exclusion - meaning, no |
| 44 |
path but the one specified in the pattern will be protected by authentication. In the example below, only endpoints |
| 45 |
under the ``/secured`` route will require authentication - all other routes do not. |
| 46 |
|
| 47 |
.. code-block:: python |
| 48 |
|
| 49 |
... |
| 50 |
session_auth = SessionAuth[User, ServerSideSessionBackend]( |
| 51 |
retrieve_user_handler=retrieve_user_handler, |
| 52 |
# we must pass a config for a session backend. |
| 53 |
# all session backends are supported |
| 54 |
session_backend_config=ServerSideSessionConfig(), |
| 55 |
# exclude any URLs that should not have authentication. |
| 56 |
# We exclude the documentation URLs, signup and login. |
| 57 |
exclude=[r"^(?!.*\/secured$).*$"], |
| 58 |
) |
| 59 |
... |
| 60 |
|
| 61 |
Exclude from auth |
| 62 |
-------------------- |
| 63 |
Sometimes, you might want to apply authentication to all endpoints under a route but a few selected. In this case, you |
| 64 |
can pass ``exclude_from_auth=True`` to the route handler as shown below. |
| 65 |
|
| 66 |
.. code-block:: python |
| 67 |
|
| 68 |
... |
| 69 |
@get("/secured") |
| 70 |
def secured_route() -> Any: |
| 71 |
... |
| 72 |
|
| 73 |
@get("/unsecured", exclude_from_auth=True) |
| 74 |
def unsecured_route() -> Any: |
| 75 |
... |
| 76 |
... |
| 77 |
|
| 78 |
You can set an alternative option key in the security configuration, e.g., you can use ``no_auth`` instead of |
| 79 |
``exclude_from_auth``. |
| 80 |
|
| 81 |
.. code-block:: python |
| 82 |
|
| 83 |
... |
| 84 |
@get("/secured") |
| 85 |
def secured_route() -> Any: |
| 86 |
... |
| 87 |
|
| 88 |
@get("/unsecured", no_auth=True) |
| 89 |
def unsecured_route() -> Any: |
| 90 |
... |
| 91 |
|
| 92 |
session_auth = SessionAuth[User, ServerSideSessionBackend]( |
| 93 |
retrieve_user_handler=retrieve_user_handler, |
| 94 |
# we must pass a config for a session backend. |
| 95 |
# all session backends are supported |
| 96 |
session_backend_config=ServerSideSessionConfig(), |
| 97 |
# exclude any URLs that should not have authentication. |
| 98 |
# We exclude the documentation URLs, signup and login. |
| 99 |
exclude=[r"^/login", r"^/signup", r"^/schema"], |
| 100 |
exclude_opt_key="no_auth" # default value is `exclude_from_auth` |
| 101 |
) |
| 102 |
... |