.. include:: /includes.rst.txt

.. comments - headings

   # with overline, for parts
   * with overline, for chapters
   = for sections
   - for subsections
   ^ for subsubsections
   " for paragraphs
   * for H5
   + for H6

.. index:: Authentication (Basic)
.. _basic_authentication:

HTTP Basic Authentication
-------------------------

With this authentication method, user accounts and passwords are managed
in a **YAML configuration file**. When used to authenticate API clients,
the client sends their login name and password in an **HTTP header**.
When used for end-users authentication, users enter their login name and
password into a **browser popup dialog**. End-user logout is not fully
supported.


Considerations
^^^^^^^^^^^^^^

HTTP Basic Authentication is a simple option for authenticating API clients.

Service accounts for API clients are defined in a configuration file.
If management of service accounts in an enterprise identity provider is desired,
consider :ref:`oauth_authentication` instead.

Basic authentication is rarely used for end-user authentication
because the only way a user can log out is to shut down their browser.
:ref:`form_authentication` is almost always a better choice here.
Both can be enabled at the same time, and share the same user accounts.


Configuring
^^^^^^^^^^^

For API client authentication
"""""""""""""""""""""""""""""

To enable basic authentication for API clients, add or uncomment in the :ref:`setup file <setup_file>` (``edg-setup.properties``)::

   apiAuthMethods = basic

Note that multiple API authentications methods may be listed, separated by commas.

For end user authentication (not recommended)
"""""""""""""""""""""""""""""""""""""""""""""

To enable form authentication for end users, add or uncomment in the :ref:`setup file <setup_file>` (``edg-setup.properties``)::

   endUserAuthMethod = basic

Realm name
""""""""""
See :ref:`authRealm setup field <setup_authRealm>`.

User management
^^^^^^^^^^^^^^^

Login names and credentials are defined in ``users.yaml`` as described here: :ref:`users_yaml`.


Authenticating API requests
^^^^^^^^^^^^^^^^^^^^^^^^^^^

This section describes how API clients can authenticate with HTTP basic authentication.

Basic authentication relies on the ``Authorization`` HTTP header whose value consists of the word ``Basic``
followed by a space followed by the Base64-encoded ``name:password``. 

.. note::
   Some HTTP client implementations expect the server to issue an *authentication
   challenge* consisting of an HTTP 401 status code and ``WWW-Authenticate`` header
   before the client will send the ``Authorization`` header.
   
   API clients connecting to EDG must proactively send the ``Authorization`` header
   without relying on a prior challenge. This is sometimes known as *preemptive HTTP basic
   authentication*.

Here's an example using the ``curl`` HTTP command line client to send a query to
the SPARQL endpoint, assuming EDG is running at http://localhost:8083/:

.. code-block:: bash

  curl -H "Authorization: Basic c2NvdHQ6MTIzNDU=" -d "query=SELECT * { () teamwork:readableGraphsUnderTeamControl ?g }" http://localhost:8083/tbl/sparql

The Base-64 string in the header translates to the ``user:password`` string ``scott:12345``.


See also
^^^^^^^^

* :ref:`Python example for API client authentication <1-basic_authentication>`