Authentication with OpenID Connect (OIDC)

This section describes how to configure a TQ Data Foundation server to use OpenID Connect (OIDC) authentication. Data Foundation supports authentication with OIDC using OAuth 2.0 Authorization Code flow.

With SSO, users attempting to log in to Data Foundation 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 Data Foundation of the user’s identity, and redirects them back to Data Foundation. The Authorization Server may provide Data Foundation 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 Data Foundation.

Aside from OIDC, Data Foundation 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, Data Foundation cannot use OIDC SSO when sending projects to another Data Foundation 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 Data Foundation 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 Data Foundation

  • The Data Foundation 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.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 Data Foundation 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 (Data Foundation).

Warning

Storing secrets in plain text is a security risk and is strongly discouraged in production environments. Please 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. Data Foundation will log a warning if this value is stored in plain text.

Example:

clientSecret: ${env:ENTRA_CLIENT_SECRET}
redirectUri (required)

The Data Foundation URL to which the user should be forwarded after successful login. This is the URL where Data Foundation is deployed, followed by login/oauth2/code/ and the unique configuration name. Example:

https://your.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 Data Foundation. The left-hand values are Data Foundation attributes; the right-hand values are ID token attributes.

The following Data Foundation 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 Data Foundation 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.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.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.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 Data Foundation will not be known to the application. They cannot be assigned permissions and will not receive notifications until they have accessed Data Foundation for the first time.

API client authentication

API client authentication with this authentication method is not possible. See Considerations above.