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.

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 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 HTTP Basic Authentication or Authentication with OAuth 2.0 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 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:

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). To avoid storing the secret in plain text, you can use the syntax described in Reading values from files or environment variables to store it in an environment variable or a file on an encrypted volume. 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 security role(s). Only group/role names that match the 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

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

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

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