.. 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 ----------------------- .. 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 ` 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 :ref:`setup file ` (``edg-setup.properties``), with the :ref:`endUserAuthMethod ` field. 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 :ref:`setup file ` (``edg-setup.properties``), with the :ref:`apiAuthMethods ` field. For example, to enable HTTP Basic Authentication and OAuth 2.0:: apiAuthMethods = basic, oauth * Communication between multiple EDG instances (:ref:`topbraid_explorer`, :ref:`Send Projects to Another Server `, etc.) requires that an API authentication method is enabled and configured on the target instance * 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 :ref:`setup file ` (``edg-setup.properties``), with the deprecated :ref:`authMethod ` field. * 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)**. Assigning users to Security Roles """"""""""""""""""""""""""""""""" How users are assigned to security roles depends on the authentication method (see :ref:`authentication_methods` for details): * In SSO setups, the assignment is made in the enterprise identity 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. * With setups where user accounts are defined in the :ref:`users.yaml configuration file `, users' security roles are also defined in that file. .. note:: It is **not possible** to assign users to security roles **within the EDG application** itself. Security Roles and Rights Groups """""""""""""""""""""""""""""""" Some global privileges within EDG are repesented as :ref:`Rights Groups `: *Administrator*, *Power User*, *Manager* and *Explorer User*. Users receive these privileges by having a security role that is associated with the rights group. Therefore, at a minimum, one security role should be defined for each rights group that is applicable to the EDG installation. Security roles in the Setup File """""""""""""""""""""""""""""""" All security roles to be used in EDG must be listed in the :ref:`setup file ` (``edg-setup.properties``). IdP groups/roles not listed there will be ignored by EDG. For example: .. code-block:: properties adminSecurityRoles = admin powerUserSecurityRoles = poweruser managerSecurityRoles = manager explorerSecurityRoles = explorer serviceAccountSecurityRoles = api securityRoles = user This defines a number of security roles (``admin``, ``poweruser``, ``manager``, ``explorer``, and ``api``) and adds them to the respective rights groups. Another security role ``user`` is defined without being added to a specific rights group. See :ref:`Rights Groups ` for more information on the individual groups and :ref:`the setup field reference ` for more details about the setup fields. **Alternatively**, all security roles can be listed without rights groups, using only the :ref:`securityRoles field `: .. code-block:: properties securityRoles = admin,poweruser,manager,explorer,user In this case, an administrator must assign the security roles to rights groups interactively on the :ref:`RightsManagementAdminPage`. Either way, after installation, the list of security roles and their assignment to rights groups can be reviewed and modified on the :ref:`RightsManagementAdminPage`.