.. 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 (Form-based)
.. _form_authentication:

Form Authentication
-------------------

With this authentication method, user accounts and passwords are managed in a **YAML configuration file**. Users authenticate by entering their login name and password into the **EDG login form**. Logout is supported.


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

Form authentication is a simple option that can be set up quickly and does not require integration with an external identity provider.

However, it is a generally a poor long-term solution. A system administrator must edit a configuration file to onboard or remove users or change passwords. When possible, implement an enterprise single sign-on (SSO) strategy with :ref:`SAML <saml_authentication>` or :ref:`OpenID Connect <oidc_authentication>` instead.

Form authentication is cumbersome for API clients. If form authentication is used, and API clients need access to the EDG APIs, then an additional API authentication method such as :ref:`basic_authentication` should be configured.


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

To enable form authentication, add or uncomment in the setup file (``edg-setup.properties``)::

   endUserAuthMethod = form


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

User accounts are defined in `users.yaml` as described here: :ref:`users_yaml`


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

While not recommended, it is possible for API clients to access EDG APIs using form authentication.
This involves obtaining an authenticated HTTP session cookie and including that cookie with subsequent
requests.

Assuming EDG is running at http://localhost:8083/, the general sequence is:

1. Send a GET request to http://localhost:8083/ to obtain a ``JSESSIONID`` cookie
2. Send a POST request to http://localhost:8083/j_security_check to authenticate,
   with login name in field `j_username` and password in `j_password`, using
   form-encoding. Include the ``JSESSIONID`` from the previous request, and
   note any updated value for that cookie in the server response
3. Make authenticated requests by including the updated ``JSESSIONID`` cookie with
   each request
4. Make an authenticated GET request to http://localhost:8083/logout to end the
   session and free resources

The following sections show these steps in detail with the ``curl`` HTTP command
line client.

1. Obtain a session cookie
""""""""""""""""""""""""""
.. code-block::

   # Obtains a session cookie and write it to cookies.txt
   curl -c cookies.txt http://localhost:8083/

2. Submit login name and password to authentication endpoint
""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""

.. code-block::

   # Send username and pw to auth endpoint
   # This uses cookies from cookies.txt and stores new session cookie in same file
   curl -i -b cookies.txt -c cookies.txt -d j_username=user1 -d j_password=mypassword http://localhost:8083/j_security_check

3. Make authenticated requests
""""""""""""""""""""""""""""""

.. code-block::

   # This request (to the SPARQL API) is authenticated
   curl -b cookies.txt -d "query=SELECT * { () teamwork:readableGraphsUnderTeamControl ?g }" http://localhost:8083/tbl/sparql

4. Log out to free seat
"""""""""""""""""""""""

.. code-block::

   curl -b cookies.txt http://localhost:8083/logout


See also
^^^^^^^^

* :ref:`Python example for API client authentication <112-form_based_authentication>`