SAML Authentication

This section describes how to configure an EDG server to use Security Assertion Markup Language (SAML) authentication. 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.

The TopBraid SAML Tomcat valve supports Service Provider Initiated (SP-initiated) browser-based SAML 2.0 Single Sign On (SSO). The Tomcat instance running EDG must use HTTPS and be supplied with the appropriate IdP certificates to allow trusted communication. Likewise, the IdP will need to have the Tomcat instance’s certificates. The TopBraid SAML valve requires at least 2 attributes from the IdP, one to be mapped to the user object and one to be mapped to the role object. The TopBraid valve is also capable of detecting HTTP Authorization headers. For example, if an HTTP Basic authorization header is included with a request, authorization routed to the server’s authentication provider (e.g. JNDI LDAP) and/or the Tomcat authentication provider that uses the local tomcat-users.xml.

Note: the TopBraid-Auth.zip package does not support or replace the KeyCloak libraries, if they are present. If you use KeyCloak, continue to use those libraries. This section may be of reference for configuring attribute mappings for EDG from SAML assertions but these jars do not replace the KeyCloak libraries.

If an HTTP Basic authorization header is missing, the TopBraid valve will use the SAML IdP login process.

When EDG is configured to SAML SSO:

  • The Tomcat server running EDG must use secure connections (i.e. HTTPS).

  • API clients will need to use HTTP Basic authentication or OAuth authentication. API clients cannot use SAML SSO. Likewise, EDG cannot use SAML SSO when sending projects to another server or publishing to Explorer.

  • API clients must use HTTPS when connecting to EDG.

  • SPARQLMotion modules must use HTTPS when using URLs to connect to EDG.

The TopBraid valve consists of the following (provided in the zip file that also contains the edg.war file):

  • TopBraid SAML valve jar and dependencies

  • A modified context.xml

Place the jars from TopBraid-Auth.zip (available from the EDG download page) in the Tomcat lib directory.

Place the context.xml in the Tomcat webapps/edg/META-INF directory. It is a good idea to backup the original context.xml.

Context.xml Changes

The Tomcat webapps/edg/META-INF directory contains the default (i.e. non-SAML) EDG context.xml file. It also contains templates that can be modified and used to replace the default file:

  • context.xml.saml.adfs
    Microsoft Active Directory Federations Services (ADFS)
  • context.xml.saml.g-suite
    Google Workspace

Detailed instructions:

  1. Replace the default context.xml file with the appropriate template.

  2. Modify the value of the template’s federationMetadata XML attribute to be the URL of the appropriate IdP Federation Metadata resource.

    • 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.

  3. Modify the value of the template’s attributeMappings XML attribute to map the SAML attributes returned in the IdP response to the attributes required by EDG:

    • Map the IdP username/login ID attribute to the EDG name attribute

      • Required

    • Map the IdP group or role attribute to the EDG role attribute

  4. Additional optional attributes can be mapped for email address and display name. These will then be used in EDG’s user directory:

    • Map the IdP email attribute to the EDG http://edg.topbraid.solutions/model/email attribute

    • Map the IdP display name attribute to the EDG http://edg.topbraid.solutions/model/name attribute

  5. Modify the URL host of the template’s serviceProvider XML attribute to be the appropriate EDG host.

  6. Modify the value (in minutes) of the template’s sessionTimeout XML attribute as necessary.

    • If possible, an appropriate SAML SSO session timeout value will be determined from the assertion returned by the IdP. Alternatively, the session timeout can be configured here.

Troubleshooting

To debug the SAML response or assertion attributes, place the following at the end of the Tomcat conf/logging.properties file and restart Tomcat.

java.util.logging.ConsoleHandler.level = FINEST
org.topbraidlive.auth.adapters.saml.tomcat.level = FINEST

This will cause all the SAML responses and attributes to be logged to the Catalina log file.

Detailed instructions are provided upon request to support@topquadrant.com.