Basic Authentication
--------------------

Basic Authentication is the simplest form of authentication. It is a very well
used standard and usually will not require any modification. The ability to
modify this authenticator is included for completeness. Refer to the
:ref:`Basic Auth <basic-authenticator>` section on how to use the Basic
Authenticator.

Basic Authentication is a straightforward scheme where the client sends HTTP
requests with the Authorization header containing the word ``Basic`` followed by
a space and a base64-encoded string of ``username:password``. Since tokens are
not involved in its core operation, only specific hooks that manage secrets and
session modifications apply.

**Applicable Hooks**:

*   ``get_secret_keys``: To identify and mask the password or other sensitive
    fields in logs.
*   ``modify_session``: To customize the HTTP session, such as adding specific
    headers or handling proxy configurations for basic authentication requests.

**Examples**:

The following example show how to modify the Basic authenticator to support
HTTPDigest. It should be noted that both Basic Authentication and HTTPDigest are
supported by the ``requests`` package. For support of HTTPDigest the
``modify_session`` hook can be used to change the authentication method from
basic to digest. As Python Requests is used it is important to be familiar with
this package as specified in `Requests <https://requests.readthedocs.io/en/latest/>`_.

The first step is to create a new credential using the Low-code Tools credential
and set the authentication mechanism to basic authentication. Put in the user
name and password (In this example ``anyusername`` and ``anypassword`` is used.
Select a credential and in the ``Authentication Override`` field put in the name
of the authenticator (in this example its ``HTTPDigestAuth``) and save the
credential. Next step is to create a Dynamic Application with the snippet code as
follows:

Only the code between the ``User Editable`` lines is the code that is custom as the
rest of the code is the ``Default Snippet`` that is required in every Snippet
Framework Dynamic Application. See the :ref:`Default Snippet <default-snippet>`
section for more details.

This example leverages the existing Basic Authenticator. It will take the
username and password fields and use those to create a Basic Authenticator. The
first line in the hook creates an ``HTTPDigest`` authenticator (This is a
function imported from the ``requests`` package) and using the username and password
that is currently in the ``auth_info`` parameter. The next line then replace the
existing Basic Authenticator with the new ``HTTPDigest`` authenticator that was
created.

.. code-block:: python

    from silo.apps.errors import error_manager
    with error_manager(self):

        from silo.low_code import *
        from silo.apps.collection import create_collections, save_collections

        # =====================================
        # =========== User Editable ===========
        # =====================================
        # List any custom substitutions that need to occur within the snippet arguments
        from silo.auth import create_basic_authenticator
        from requests.auth import HTTPDigestAuth

        custom_substitution = {}

        def modify_session_hook(session, auth_info):
            auth=HTTPDigestAuth(auth_info.username,auth_info.password)
            session.auth=auth

        create_basic_authenticator(
            name="HTTPDigestAuth",
            description="An HTTP DIgest Authencticator.",
            modify_session=modify_session_hook
        )

        # =====================================
        # ========= End User Editable =========
        # =====================================


        collections = create_collections(self)
        snippet_framework(collections, custom_substitution, snippet_id, app=self)
        save_collections(collections, self)