Debian Codegraph @

docs/usage/security/excluding-and-including-endpoints.rst

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