.. 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 TQ Data Foundation must first **authenticate**, that is, provide some credentials (such as a login name and password) that Data Foundation recognizes. Data Foundation 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 Data Foundation APIs. Some methods may support both. Successful authentication provides Data Foundation 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 a Data Foundation 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 a Data Foundation 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, oauth2 * Communication between multiple Data Foundation 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 Data Foundation 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 Data Foundation ``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 Data Foundation application** itself. Security Roles and Rights Groups """""""""""""""""""""""""""""""" Some global privileges within Data Foundation 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 Data Foundation installation. Security roles in the Setup File """""""""""""""""""""""""""""""" All security roles to be used in Data Foundation must be listed in the :ref:`setup file ` (``edg-setup.properties``). IdP groups/roles not listed there will be ignored by Data Foundation. 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`.