-
-
Notifications
You must be signed in to change notification settings - Fork 375
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs: Add examples for auth
exclude
configuration (#3246)
* adding draft for security exclusion docs * adding section to security toctree * Update docs/usage/security/excluding-and-including-endpoints.rst * Update docs/usage/security/excluding-and-including-endpoints.rst * Update docs/usage/security/excluding-and-including-endpoints.rst --------- Co-authored-by: Jacob Coffee <jacob@z7x.org>
- Loading branch information
1 parent
96c59fe
commit a139156
Showing
2 changed files
with
87 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,86 @@ | ||
Excluding and including endpoints | ||
================================= | ||
|
||
Please make sure you read the :doc:`security backends documentation </usage/security/security-backends>` first for learning how to set up a security backend. This section focuses on configuring the ``exclude`` rule for those backends. | ||
|
||
There are multiple ways for including or excluding endpoints in the authentication flow. The default rules are configured in the ``Auth`` object used (subclass of :class:`~.security.base.AbstractSecurityConfig`). The examples below use :class:`~.security.session_auth.auth.SessionAuth` but it is the same for :class:`~.security.jwt.auth.JWTAuth` and :class:`~.security.jwt.auth.JWTCookieAuth`. | ||
|
||
Excluding routes | ||
-------------------- | ||
|
||
The ``exclude`` argument takes a :class:`string <str>` or :class:`list` of :class:`strings <str>` that are interpreted as regex patterns. For example, the configuration below would apply authentication to all endpoints except those where the route starts with ``/login``, ``/signup``, or ``/schema``. Thus, one does not have to exclude ``/schema/swagger`` as well - it is included in the ``/schema`` pattern. | ||
|
||
This also means that passing ``/`` will disable authentication for all routes. | ||
|
||
.. code-block:: python | ||
session_auth = SessionAuth[User, ServerSideSessionBackend]( | ||
retrieve_user_handler=retrieve_user_handler, | ||
# we must pass a config for a session backend. | ||
# all session backends are supported | ||
session_backend_config=ServerSideSessionConfig(), | ||
# exclude any URLs that should not have authentication. | ||
# We exclude the documentation URLs, signup and login. | ||
exclude=["/login", "/signup", "/schema"], | ||
) | ||
... | ||
Including routes | ||
---------------- | ||
|
||
Since the exclusion rules are evaluated as regex, it is possible to pass a rule that inverts exclusion - meaning, no path but the one specified in the pattern will be protected by authentication. In the example below, only endpoints under the ``/secured`` route will require authentication - all other routes do not. | ||
|
||
.. code-block:: python | ||
... | ||
session_auth = SessionAuth[User, ServerSideSessionBackend]( | ||
retrieve_user_handler=retrieve_user_handler, | ||
# we must pass a config for a session backend. | ||
# all session backends are supported | ||
session_backend_config=ServerSideSessionConfig(), | ||
# exclude any URLs that should not have authentication. | ||
# We exclude the documentation URLs, signup and login. | ||
exclude=[r"^(?!.*\/secured$).*$"], | ||
) | ||
... | ||
Exclude from auth | ||
-------------------- | ||
Sometimes, you might want to apply authentication to all endpoints under a route but a few selected. In this case, you can pass ``exclude_from_auth=True`` to the route handler as shown below. | ||
|
||
.. code-block:: python | ||
... | ||
@get("/secured") | ||
def secured_route() -> Any: | ||
... | ||
@get("/unsecured", exclude_from_auth=True) | ||
def unsecured_route() -> Any: | ||
... | ||
... | ||
You can set an alternative option key in the security configuration, e.g., you can use ``no_auth`` instead of ``exclude_from_auth``. | ||
|
||
.. code-block:: python | ||
... | ||
@get("/secured") | ||
def secured_route() -> Any: | ||
... | ||
@get("/unsecured", no_auth=True) | ||
def unsecured_route() -> Any: | ||
... | ||
session_auth = SessionAuth[User, ServerSideSessionBackend]( | ||
retrieve_user_handler=retrieve_user_handler, | ||
# we must pass a config for a session backend. | ||
# all session backends are supported | ||
session_backend_config=ServerSideSessionConfig(), | ||
# exclude any URLs that should not have authentication. | ||
# We exclude the documentation URLs, signup and login. | ||
exclude=["/login", "/signup", "/schema"], | ||
exclude_opt_key="no_auth" # default value is `exclude_from_auth` | ||
) | ||
... |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters