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

.. _tomcat_authentication:

Tomcat-based authentication methods
-----------------------------------

.. warning::

   Tomcat-based authentication is **deprecated as of EDG 8.0** and will be removed in
   a future release.

With these authentication methods, authentication is handled by, and configured in,
the web application container (Tomcat). The container is responsible for account
management. Credentials are handled and verified only by the container. EDG is only
responsible for displaying the login form, login error messages, and logout link.


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

Tomcat-based authentication is **deprecated as of EDG 8.0** and will be removed in
a future release. It should not be used for new deployments.

There are two Tomcat-based authentication methods: ``form`` and ``basic``. They
are analogous to the EDG-native authentication methods :ref:`form_authentication`
and :ref:`basic_authentication`. These should be used instead, and existing
deployments should be migrated as soon as practical.
   
Note that the EDG-native methods can be combined, using ``form`` as the value for
``endUserAuthMethod`` and ``basic`` as the value for ``apiAuthMethods``.


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

To enable a Tomcat-based authentication method, add or uncomment in the :ref:`setup file <setup_file>` (``edg-setup.properties``):

.. code-block::

   # For Tomcat-based form authentication
   authMethod = form

.. code-block::

   # For Tomcat-based HTTP basic authentication
   authMethod = basic

Make sure that no ``endUserAuthMethod`` or ``apiAuthMethods`` are defined, as these
cannot be used together with Tomcat-based authentication.


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

User accounts are defined in ``tomcat-users.xml``, usually found in Tomcat's ``conf`` directory.

.. note::
   In **EDG Studio**, the file is found in ``conf/users.xml``.

An example is below:

.. code-block:: xml

 <role rolename="admin"/>
 <role rolename="manager"/>
 <role rolename="editor"/>
 <role rolename="viewer"/>
 <user username="Admin_user" password="password32" roles="admin,manager"/>
 <user username="Editor_user" password="password54" roles="editor"/>
 <user username="Guest" password="password76" roles="viewer"/>

The roles defined here must match those defined in the ``edg-setup.properties`` file under ``securityRoles``, case-sensitive.


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

Refer to the documentation for the equivalent EDG-native authentication
methods, :ref:`form_authentication` and :ref:`basic_authentication`,
for information on API client authentication.