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

.. _authentication_overview:

Authentication Overview
-----------------------

.. warning::

   TODO: This is almost all outdated or in the wrong section.
   Should discuss ``endUserAuthMethod``, ``apiAuthMethods``, ``authMethod``

.. index:: Authentication

An end-user or API client accessing EDG must first **authenticate**, that
is, provide some credentials (such as a login name and password) that
EDG recognizes.

EDG can be configured to use :ref:`a number of authentication methods <authentication_methods>`
that determine how authentication is performed. Some methods are only
available for end-user login. Others are available for authenticating
web service clients that access the EDG APIs. Some methods may support both.

Successful authentication provides EDG with the following
information about the client:

* **login name**
* zero or more **security roles**
* optionally, **extended user attributes** such as full display name and email address


End user authentication methods
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
* Authentication is initiated by an end user visiting an EDG page without prior authentication
* Only a single method can be enabled
* The method is selected in the setup file (``edg-setup.properties``). For example, to select
  OpenID Connect (OIDC)::

   endUserAuthMethod = oidc

* See individual methods under :ref:`authentication_methods` for more details

API client authentication methods
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
* Authentication is initiated by a client accessing an EDG URL with appropriate
  authentication information present in the request (usually in an HTTP header)
* Multiple methods can be enabled
* The methods are selected in the setup file (``edg-setup.properties``). For example, to
  enable HTTP Basic Authentication and OAuth 2.0::

   apiAuthMethods = basic, oauth

* See individual methods under :ref:`authentication_methods` for more details

Tomcat-based authentication methods
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
* A deprecated option; do not use in installations
* See :ref:`tomcat_authentication` for more details
* Selected in the setup file (``edg-setup.properties``) using the ``authMethod`` key
* Cannot be combined with ``endUserAuthMethod`` or ``apiAuthMethods``


.. _security_roles:

.. index:: pair: Access Control ; RBAC
.. index:: Security roles

Security roles
^^^^^^^^^^^^^^
Security roles determine a user's permissions within the EDG application
and can be used to implement **Role-Based Access Control (RBAC)**.

How users are assigned to roles depends on the authentication method.
In SSO setups, the assignment is made in the enterprise indentity
provider (IdP), for example by managing user groups.
In the authentication method specific configuration, the IdP attribute
containing role information must then be mapped to the EDG ``role``
attribute.

The full list of security roles to be used in EDG must be specified
in the setup file (``edg-setup.properties``), in the ``securityRoles``
key. For example::

   securityRoles = admin,poweruser,manager,editor,viewer

IdP groups/roles not listed here will be ignored by EDG.

At a minimum, one security role must be defined for each
:ref:`rights group <rights_groups>` that is applicable to the EDG
installation. Rights groups are assigned to security roles
in the :ref:`RightsManagementAdminPage`.