.. 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 .. _oidc_authentication: Authentication with OpenID Connect (OIDC) ----------------------------------------- This section describes how to configure an EDG server to use OpenID Connect (OIDC) authentication. EDG supports authentication with OIDC using OAuth 2.0 Authorization Code flow. With SSO, users attempting to log in to EDG are forwarded to an enterprise Authorization Server. The Authorization Server is responsible for verifying the user's identity, usually by asking the user to log in with a username and password. Some Authorization Servers support two-factor authentication. On success, the Authorization Server informs EDG of the user's identity, and redirects them back to EDG. The Authorization Server may provide EDG with additional information such as the user's roles, email address and full (display) name. .. _oidc_considerations: Considerations ^^^^^^^^^^^^^^ Implementing SSO is highly recommended, and preferred over alternatives where user accounts are managed in EDG. Aside from OIDC, EDG also supports SSO with :ref:`Security Assertion Markup Lanuage (SAML) `. While SAML is a mature standard, OpenID Connect is sometimes considered a more modern and lighweight alternative that provides at least equal levels of security. API clients *cannot* use OIDC SSO. Likewise, EDG cannot use OIDC SSO when sending projects to another EDG instance or publishing to Explorer. Therefore, an additional API authentication method such as :ref:`basic_authentication` or :ref:`oauth_authentication` should be configured. Prerequisites ^^^^^^^^^^^^^ * The Tomcat instance running EDG must use HTTPS * The ID token issued by the Authorization server must provide an attribute to be used as the user's unique identifier * The ID token issued by the Authorization server must provide an attribute to be used as the user's role within EDG * The EDG administrator must obtain a client ID and client secret from the Authorization Server. * The ``redirectUri`` (see below) must be pre-registered on the Authorization Server. Configuring ^^^^^^^^^^^ .. note:: When configuring this method of authentication, it is helpful to have a technical resource familiar with the OIDC Authorization Server to assist with the configuration. TopQuadrant is unable to assist with specific configuration options for each customer's Authorization Server. To enable OIDC authentication, add or uncomment in the :ref:`setup file ` (``edg-setup.properties``):: endUserAuthMethod = oidc Also, create an ``oidc.yaml`` file according to the following section. The oidc.yaml file ^^^^^^^^^^^^^^^^^^^ By default, the system will look for a file ``oidc.yaml`` in the same directory as the setup file. If desired, the name and location can be overridden in the setup file:: oidcConfigFile = ./my-idp-oidc.yaml Syntax """""" The file uses YAML syntax. It consists of an OIDC configuration record of the following form: .. code-block:: yaml configuration-name: authorizationServer: https://your.authorization.server clientId: auth-server-unique-client-id clientSecret: auth-server-client-secret redirectUri: https://your.edg.server/edg/login/oauth2/code/configuration-name attributeMappings: userNameAttribute: auth-server-loginname-attribute email: auth-server-email-attribute role: auth-server-group-attribute name: auth-server-displayname-attribute A record consits of these elements: ``configuration-name`` (required) A unique name of your choice for this OIDC configuration. This name must match the last path segment of the ``redirectUri`` (see below). ``authorizationServer`` (required) The base URL for the Authorization Server. This is the part that precedes ``/.well-known/openid-configuration`` in the Authorization Server's OpenID Provider Configuration. See below for examples. ``clientId`` (required) A unique identifier that identifies the EDG registration to the Authorization Server. It is obtained from the Authorization Server. ``clientSecret`` (required) A password issued by the Authorization Server used to authenticate the registered client (EDG). .. warning:: Storing secrets in plain text is a security risk and is strongly discouraged in production environments. Please use the syntax described in :ref:`setup_value_replacement` to store it in an environment variable or a file on an encrypted volume. EDG will log a warning if this value is stored in plain text. Example:: clientSecret: ${env:ENTRA_CLIENT_SECRET} ``redirectUri`` (required) The EDG URL to which the user should be forwarded after successful login. This is the URL where EDG is deployed, followed by ``login/oauth2/code/`` and the unique configuration name. Example:: https://your.edg.server/edg/login/oauth2/code/configuration-name This URL must be registered with the Authorization Server as one of the Redirection URI values for the client. ``attributeMappings`` (required) This maps the attributes returned by the Authorization Server in the ID token to attributes understood by EDG. The left-hand values are EDG attributes; the right-hand values are ID token attributes. The following EDG attributes are supported: ``userNameAttribute`` (required) The ID token attribute containing the user's unique username/login ID ``roles`` (required) The ID token attribute containing the user's group(s), to be used as EDG :ref:`security role(s) `. Only group/role names that match the :ref:`securityRoles field in the setup file ` are used. ``email`` (optional) The ID token attribute containing the user's email address, for notifications ``name`` (optional) The ID token attribute containing the user's full display name, if different from the ``userNameAttribute`` attribute Example `oidc.yaml` file for Okta """""""""""""""""""""""""""""""""" .. code-block:: yaml EDG-Okta: authorizationServer: https://your.okta.com/oauth2/default clientId: xxxxxxxxxxxxxxxxxxxx clientSecret: ${env:OKTA_CLIENT_SECRET} redirectUri: https://your.edg.server/edg/login/oauth2/code/EDG-Okta attributeMappings: userNameAttribute: email roles: groups email: email name: name Example `oidc.yaml` file for Microsoft Entra """"""""""""""""""""""""""""""""""""""""""""" .. code-block:: yaml EDG-Entra: authorizationServer: https://login.microsoftonline.com/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/v2.0 clientId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx clientSecret: ${file:/Volumes/encrypted/EntraClientSecret.txt} redirectUri: https://your.edg.server/edg/login/oauth2/code/EDG-Entra attributeMappings: userNameAttribute: email roles: groups email: email name: name Example `oidc.yaml` file for Google """""""""""""""""""""""""""""""""""" .. code-block:: yaml EDG-Google: authorizationServer: https://accounts.google.com clientId: xxxxxxxxxxx-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.apps.googleusercontent.com clientSecret: ${env:GOOGLE_CLIENT_SECRET} redirectUri: https://your.edg.server/edg/login/oauth2/code/EDG-Google attributeMappings: userNameAttribute: email roles: groups email: email name: name User management ^^^^^^^^^^^^^^^ With SSO, users are managed in the enterprise Authorization Server application. User accounts that exist in the Authorization Server but who have never logged in to EDG will not be known to EDG. They cannot be assigned permissions and will not receive notifications until they have accessed EDG for the first time. API client authentication ^^^^^^^^^^^^^^^^^^^^^^^^^ API client authentication with this authentication method is not possible. See :ref:`oidc_considerations` above.