SAML Authentication

This section describes how to configure an EDG server to use Security Assertion Markup Language (SAML) authentication. EDG supports Service Provider Initiated (SP-initiated) browser-based SAML 2.0 Single Sign On (SSO).

With SSO, users attempting to log in to EDG are forwarded to an enterprise identity provider (IdP). The IdP is responsible for verifying the user’s identity, usually by asking the user to log in with a username and password. Some IdPs support two-factor authentication. On success, the IdP informs EDG of the user’s identity, and redirects them back to EDG. The IdP 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 SAML, EDG also supports SSO with OpenID Connect. 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 SAML SSO. Likewise, EDG cannot use SAML 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
Tomcat must be supplied with the appropriate IdP certificates to allow trusted communication
Likewise, the IdP will need to have the Tomcat instance’s certificates
The IdP must provide an attribute to be used as the user’s unique identifier
The IdP must provide an attribute to be used as the user’s role within EDG
The Assertion Consumer Service URL must be pre-registered in the EDG app registration at the IdP

Configuring

Note

When configuring this method of authentication, it is helpful to have a technical resource familiar with the SAML Identity Provider (IdP) to assist with the configuration. TopQuadrant is unable to assist with specific configuration options for each customer’s IdP.

Note

Versions of EDG prior to 8.0 required placement of additional jar files from TopBraid-Auth.zip into Tomcat’s lib directory, and modifications to context.xml. These steps are no longer necessary.

To enable SAML 2 authentication, add or uncomment in the setup file (edg-setup.properties):

endUserAuthMethod = saml2

Also, create a saml2.yaml file according to the following section.

The saml2.yaml file

By default, the system will look for a file saml2.yaml in the same directory as the setup file.

If desired, the name and location can be overridden in the setup file:

saml2ConfigFile = ./my-idp-saml2.yaml

Syntax

The file uses YAML syntax. It consists of a SAML configuration record of the following form:

configuration-name:
   assertionConsumerService: https://your.edg.server/edg/login/saml2/sso/configuration-name
   serviceProviderEntityID: https://your.edg.server/edg/login/saml2/sso/configuration-name
   federationMetadata: https://your.idp/saml/metadata.xml
   attributeMappings:
      name: idp-loginname-attribute
      email: idp-email-attribute
      role: ipd-group-attribute
      http://edg.topbraid.solutions/model/name: idp-displayname-attribute

A record consits of these elements:

configuration-name (required)

A unique name of your choice for this SAML configuration.

assertionConsumerService (required)

The URL of the EDG SAML assertion consumer endpoint. This is the URL where EDG is deployed, followed by login/saml2/sso/ and the unique configuration name. Example:

https://your.edg.server/edg/login/saml2/sso/configuration-name

serviceProviderEntityID (required)

A unique identifier that identifies the EDG SAML configuration within the IdP. This is sometimes referred to as entity ID or audience. In some cases, the value must be obtained from the IdP. In other cases, the value can be freely chosen and configured in the IdP. In that case, we recommend to use the value of assertionConsumerService.

federationMetadata (required)

The URL of the IdP’s Federation Metadata resource. This is an XML file provided by the IdP.

The URL can have either a file:/// or http:// scheme.
If using a file:/// scheme, the path should be an absolute file system path.
If performance is unacceptable when using an http:// scheme, the performance may be improved by downloading the target XML file to the local filesystem and using a file:/// scheme.
Some IdPs only offer the option to download the metadata, so in that case, you must use the file:/// scheme.

attributeMappings (required)

This maps the SAML attributes returned in the IdP response to attributes understood by EDG. The left-hand values are EDG attributes; the right-hand values are IdP attributes.

The following EDG attributes are supported:

name (required): The IdP attribute containing the user’s unique IdP username/login ID
role (required): The IdP attribute containing the user’s IdP 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 IdP attribute containing the user’s email address, for notifications
http://edg.topbraid.solutions/model/name (optional): The IdP attribute containing the user’s full display name, if different from the name attribute

Example `saml2.yaml` file for Okta IdP

EDG-Okta:
   assertionConsumerService: https://your.edg.server/edg/login/saml2/sso/EDG-Okta
   serviceProviderEntityID: https://your.edg.server/edg/login/saml2/sso/EDG-Okta
   federationMetadata: https://your.okta.com/app/xxxxxxxxxxxxxxxxxxxx/sso/saml/metadata
   attributeMappings:
      name: name
      email: name
      role: group
      "http://edg.topbraid.solutions/model/name": displayName

Example `saml2.yaml` file for Google IdP

EDG-Google:
   assertionConsumerService: https://your.edg.server/edg/login/saml2/sso/EDG-Google
   serviceProviderEntityID: https://your.edg.server/edg/login/saml2/sso/EDG-Google
   federationMetadata: file:///path/to/GoogleIDPMetadata-yourdomain.xml
   attributeMappings:
      name: name
      email: username
      role: MemberOf
      "http://edg.topbraid.solutions/model/name": username

Example `saml2.yaml` file for Microsoft Entra ID

EDG-Entra:
   assertionConsumerService: https://your.edg.server/edg/login/saml2/sso/EDG-Entra
   serviceProviderEntityID: spn:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
   federationMetadata: https://login.microsoftonline.com/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/federationmetadata/2007-06/federationmetadata.xml
   attributeMappings:
      name: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
      role: http://schemas.microsoft.com/ws/2008/06/identity/claims/role
      email: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
      "http://edg.topbraid.solutions/model/name": http://schemas.microsoft.com/identity/claims/displayname

User management

With SSO, users are managed in the enterprise identity provider (IdP) application.

User accounts that exist in the IdP 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.