SAML Authentication

This section describes how to use the EDG server with SAML authentication. When choosing this method of authentication, be sure that you have a technical resource familiar with your Identity Provider to assist with configuration. TopQuadrant is unable to assist with specific configuration options for each customers Identity Provider.

The TopBraid SAML valve supports SP-Initiated Browser based SAML 2.0 Single Sign On (SSO). HTTPS is required to be used by the Tomcat instance and the Tomcat will need to be supplied the certificates of the IDP to allow trusted HTTP communication. Likewise, the IDP will need to have the certificates of the Tomcat instance. 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. While the valve is also capable of detecting authorization headers – ie: basic auth included, those are routed to the authentication providers of the VM, eg: JNDI LDAP and/or local tomcat-users.xml.

If a BASIC authorization header is missing, then the valve will proceed to the IDP login process.

  • SAML will only work with secure connections (HTTPS).

  • API clients will need to use BASIC or OAuth if they want to use SAML for Browser SSO. You cannot authenticate using a SAML SSO user for APIs (including send projects to another server and publish to Explorer)

  • API clients will need to connect to EDG using HTTPS if EDG is using SAML.

  • Any SPARQLMotion modules that use URLs to connect to EDG will need to use HTTPS if EDG is using SAML.

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

  • SAML valve jar and dependencies

  • modified context.xml

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

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

Context.xml Changes

In the webapps/edg/META-INF directory, you can find an ADFS file that is a template to use for most SAML configurations (just change IDP, SP and attribute mappings.)

  1. Modify the context.xml to match the path to your IDP Federated Metadata URL.

  • The path to the metadata xml can be either file:/// or http:// paths.

  • file:/// paths should be absolute filesystem paths.

  • if there is latency to the http:// path, the xml can be downloaded to the local filesystem to improve performance.

  1. Modify the context.xml to match the attribute mappings sent by your IDP to the username and role fields used by EDG.

  • Map username/login ID URI =>name * required

  • Map group or role URI =>role * required for RBAC

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

  • Map email URI =>http://edg.topbraid.solutions/model/email

  • Map display name URI=>http://edg.topbraid.solutions/model/name

  1. Define the Service Provider

  1. Timeout

  • An appropriate SSO session timeout will be determined from the assertion sent from the IDP, if possible. Alternately, you can configure sessionTimeout (in minutes) in context.xml

    sessionTimeout=90

Debugging

If you need to debug the SAML Response or assertion attributes, you can place the following at the end of your logging.properties file in Tomcat and restart Tomcat. java.util.logging.ConsoleHandler.level = FINEST org.topbraidlive.auth.adapters.saml.tomcat.level = FINEST

This will give the entire SAML response and attributes in the catalina log file.

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