Installation of the EDG Server



This document covers installing the TopBraid Enterprise Data Governance (EDG) server into its platform environment and integrating it with systems services such as LDAP. To administer the EDG application user functions, see EDG Server Administration.

Installing the EDG application server may entail several Server Administration tasks including: license registration, application data storage, LDAP configuration, and access control. Initially, all users will have permissions to all EDG resources and functions via the default assignment of AdministratorGroup to ANY_ROLE.  An administrator’s initial task should be to use Access Control > Rights Management to transfer the AdministratorGroup to their organization’s defined administrative role(s) and then remove it from ANY_ROLE.

The EDG server uses Java servlets deployed to an Apache Tomcat web server and servlet container. Installation involves deploying the EDG WAR (Web Application Archive) file in the application server. Customers receive a link and login/password for the website to download the WAR file for installation. The installation files consist of the EDG server WAR file (edg.war) and this (current) documentation, EDG Installation and Administration.

Installation of the EDG server differs slightly for different operating systems. Detailed instructions for Tomcat, Linux and Windows are provided in the sections below. In general, installation consists of:

  1.  Deploying the EDG WAR file in the application server. For Tomcat, this involves copying the edg.war file to the Tomcat webapps directory, or using Tomcat Manager to deploy edg.war.
  2.  Setting the location of the EDG workspace. Upon deployment of the EDG application, library files will be written to this folder, including TopBraid (system library for TopBraid Suite features), (EDG server files for sessions, etc.), and other TopBraid Suite features. This folder will also contain all projects uploaded to the server. See EDG Methods to Deploy Projects to Servers.The location of the workspace can be changed by editing the -data value within the first init-param element in $APP_HOME/webapps/edg/WEB-INF/web.xml, where $APP_HOME is the home directory of the application server.

    If permissions for the user running the application server are insufficient to write to the workspace folder, full deployment of Enterprise Data Governance will not succeed. Edit the web.xml to point the workspace to a folder with write permissions and re-start the application server.

  3.  Setting authentication and role-based access control through Tomcat or a LDAP server. These are explained in more detail throughout this document.

EDG Server Platform Considerations

 These sections describe some aspects of the server platform to consider prior to installing the EDG server. 

Application Server and Supported Platforms

The EDG server uses Apache Tomcat running on Java. Some persistence options use relational databases. For the details of your EDG server version, see the  Supported Platforms page for compatible platform components (e.g., Java, database, etc.). This also includes sections with details and suggested configurations for installing on Linux or Windows Server. 

Suggested Java Configuration

If you are using both TopBraid EDG and another TopBraid server application on the same machine, we recommend that you run each in a separate JVM by running them with separate instances of Tomcat.

It is necessary to ensure that you have adequate physical memory to run EDG and that you have configured your Web Application Server to use it. During the purchasing process you should have received a guide to Server Sizing Specifications. Please set these appropriate to your data and users. If you did not receive this, please contact TopQuadrant support. 

See the installation instructions below for your operating system for more details concerning how to set the parameters.

Operating Systems

Installation on Linux

This section describes details and suggested configurations when using Linux as the base operating system and Tomcat as the Web Application Server.

A suggested configuration for Enterprise Data Governance is as follows:


Operating Systems: Current version of Linux with 2.6 or higher kernel 
Java Runtime Environment: Java 8, Java 11
Web Application Server


Must support 2.4 release of the Java Servlet specification.


Apache Tomcat 8.5.* (see supported-platforms for specific versions)


Permissions Full access to the Tomcat configuration area is required.


Enterprise Data Governance also requires that the nofile limit be increased as it opens a large number of JAR files, and each TDB database also has a large number of files. The default is 1024 open files and sockets. Reset this by adding the following two lines to the /etc/security/limits.conf configuration file:


tomcat8         soft    nofile          2048
tomcat8         hard    nofile          8192

Installation on Windows Server

This section describes details and suggested configurations when using Windows Server as the base operating system and Tomcat as the Web Application Server.

A suggested configuration for Enterprise Data Governance is as follows:


Operating Systems:


Windows Server, (e.g. 2008, 2012, 2016)


Administrator access is required for installation.


Java Runtime Environment: Java 8, 11
Web Application Server


Must support 2.4 release of the Java Servlet specification.


Apache Tomcat 8.5.* (see supported-platforms for specific versions)


Earlier versions of Java/Tomcat 8 are expected to work but are known to have memory leaks that may affect some Enterprise Data Governance functions.


Java configuration


The picture shows the use of the Tomcat properties window, which is reached by launching tomcat8w.exe. The permanent generation options should be added as shown, under Java options:. The memory options should be added under Maximum memory pool:. This step is performed before starting Tomcat.


Other Issues to Consider Prior to Installation

The following issues may need configuration on your system.


Workspace location

The workspace location is defined in the Basic Configuration section of Tomcat Installation Instructions – the Workspace location field.

TopBraid Live requires a workspace compatible with the Eclipse Equinox implementation of the OSGi R4 framework. (This is similar to the TopBraid Composer workspace.) The default location, which may be modified in TopBraid Live’s web.xml file, is /var/lib/ontologies. This workspace location must be writable by the process running the Web Application Server.



The Apache Tomcat $TOMCAT_HOME/conf/tomcat-users.xml file stores contain user IDs and passwords. Unless you’ve configured Tomcat to use some other authentication method (JNDI LDAP), you can use a user ID and password from this file.

Tomcat installations (and most Java EE servers) generally assume that authentication occurs from an outside source. Out of the box, Tomcat is configured to use tomcat-users.xml to load authentication information into memory. If, for example, LDAP is used instead, then a user trying to log into a Tomcat application will send information from the sign-in (either Basic or Form authentication) to the authentication service, which responds with role/user id information.


Java EE memory management

TopBraid EDG is a Java EE application. To manage the memory, please set up monitoring software recommended by your organization.

Typical analysis for any memory issues are below:


  • Stop and restart from Tomcat’s admin module; after stopping EDG, wait five minutes and then select the find leaks option from Tomcat’s admin page.
  • The most severe leaks make it impossible to cleanly shutdown Tomcat and a “kill -KILL” command may be necessary.

To make a memory dump of your server, first find the process ID of your Tomcat process, and then issue the following command:


    jmap -dump:live,format=b,file=TB-dump.bin $PID


Then, compress the file TB-dump.bin.

Authentication for TopBraid EDG

All authentication issues for TopBraid Suite are handled by using standard Java EE web container methods. Once inside the container, users are free to design their own RBAC designs, such as TopBraid EDG’s User Roles management for vocabulary or asset models. Some of the details will depend on the authentication Realm set up for Tomcat – i.e. LDAP, AD, etc. However, authentication is always a handshake between the entity requiring access and the web container (e.g. Tomcat), not TopBraid Suite applications. Please see sections below for details on LDAP and SAML and OAuth authentication.

Authentication works the same across all HTTP methods.

The following outlines some basic concepts and suggestions for handling authentication from user and services. There are a number of ways to support authentication, and many organizations choose to build their own. Organization-specific IT policies will largely dictate interactions with the web container to authenticate users and services. Therefore, TopQuadrant can only play an advisory role for getting started with authentication issues.

Consult Java EE tutorials for a good starting point on authentication methods. The authentication method is chosen in the initial Deployment Descriptor Configuration wizard, which sets the login-config/auth-method element in the web.xml file. Only one authentication form can be used per server. TopBraid supports Form, Basic and no authentication: 

  1. No Authentication. No user id or password is required to invoke services. This is useful for Linked Open Data applications and applications are are used openly behind firewalls. This should only be used for read-only servers and the administrator should ensure that the Enable SPARQL Updates parameter in the Server Administration page is set to false, which is the default that blocks updates.
  2. Form-based authentication. This is the best choice for all UI-based applications, such as EDG and SWA/SWP-based applications. Form-based authentication will display a form for entering authentication, pass the challenge to the authentication agent, and respond with the challenge result. On logout, the user is logged out from the container.
  3. Basic authentication. This should be used for access via 3rd party entities, such as web services. It is not convenient for user-based authentication because the user cannot log out of the system without closing the browser. It is recommended to use Basic authentication when the server is used for web services and an administrator needs to occasionally log in to perform maintenance.* When using SAML, the IDP performs the authentication unless an API request with BASIC authorization header, which will need to use BASIC as the auth-method.

End User Authentication

If user logout is required, then it is best to use Form authentication. In this case the application (tbl/edg) controls the login and logout pages that are displayed to the user. When a user logs out, they are logged out from the web application container.

Some user information is cached in the graph <urn:x-evn-user-data> of the active TopBraid workspace. This information is passed to TopBraid from the web application container at login. Helper functions are available from any SPARQL context, including smf:currentUserName()smf:hasCurrentUser(), and smf:userWithName().


Web Service Authentication

Web services invocation on servers requiring authentication can use Basic or Form-based authentication. Basic authentication using HTTPS encryption is recommended.

Basic Authentication

Basic authentication should be used for access by web services. Basic authentication relies on a Base64 encoded ‘Authorization’ header whose value consists of the word ‘Basic’ followed by a space followed by the Base64 encoded name:password. This is better suited for service-only access because the only way a user can log out is to shut down their browser. The URL with header information can be submitted with authentication information. Here’s an example using cURL to access a SPARQLMotion service named ‘DisplaySimpleHtml’ in TopBraid:


curl -H "Authorization: Basic c2NvdHQ6MTIzNDU=" -X POST "http://localhost:8080/edg/tbl/sparqlmotion?id=DisplaySimpleHtml"


GET works as well. The base 64 in the middle translates to the uid:pwd string “scott:12345”.


Some other examples of service calls with parameters (be sure to encode the URL before submitting as a web service call) :

curl -H “Authorization: Basic c2NvdHQ6MTIzNDU=” -X POST “http://localhost:8080/edg/tbl/sparql?default-graph-uri= ?s WHERE {?s a <>}”

curl -H “Authorization: Basic c2NvdHQ6MTIzNDU=” -X POST “http://localhost:8080/edg/tbl/sparql?query=SELECT ?s WHERE { GRAPH <> {?s a <>} }”

wget has a similar protocol:

wget –save-cookies=”/tmp/cookies” –header “Content-type: application/x-www-form-urlencoded” –post-data=”j_username=scott&j_password=tomcat” http://localhost:8080/edg/j_security_check

For secure access, web services should use HTTPS encryption.


Form-Based Authentication

Access using Form-based authentication, while not recommended, is possible using cookies generated by the server. One method is to respond to the challenge with a hardcoded URL with a valid user id and password. The general form of this response is:



Another method is to request an HTTP cookie that can be used in subsequent requests. The following is an example script for accessing a TopBraid form-based server. In summary, the script interaction has three parts:


  1. The client requests a cookie, e.g., loginRequestCookie, to use for logging in using GET or POST.
  2. The client logs in, and if successful, the client will receive another cookie, e.g., loginSuccessCookie, which is saved for subsequent requests.
  3. The client uses the loginSuccessCookie for subsequent TopBraid service requests, such as the SPARQL endpoint call in the example.

Assuming the following is defined in a file named


#The script needs the servername:portnumber, username and password respectively to work correctly.

if [[ $# -ne 3 ]] ; then
echo ‘Invalid command. Please run authenticate script in following format ./authenticateCallService <servername:port> <username> <password>’
exit 1

curl -c ~/loginRequestCookie -X POST “http://$1/edg/tbl” -D ~/firstReqHeaders > /dev/null

#The server sends a new cookie as a response to this request. Use that cookie for subsequent requests.
curl -b ~/loginRequestCookie -X POST “http://$1/edg/tbl/j_security_check” -H “Context-Type: application/x-www-form-urlencoded” –data “j_username=$2&j_password=$3” -L “http://$1/edg/tbl” -c ~/loginSuccessCookie -D ~/secReqHeaders

curl -b ~/loginSuccessCookie -X POST “http://$1/edg/tbl/sparql” -G –data-urlencode “query=SELECT * WHERE{?s a <>} ” –data-urlencode “default-graph-uri=” –data “format=json” -D ~/thirdReqHeaders

#Logout when done so as not to exhaust the user limit on the license
curl -b ~/loginSuccessCookie -X POST “http://$1/edg/tbl/purgeuser” -D ~/logoutReqHeaders

The script can be invoked by the command:


./authenticateCallService <servername:port> <username> <password>


For secure access, web services should use HTTPS encryption.


Authenticating calls that use SPARQL’s SERVICE keyword

To enable the use of the SPARQL SERVICE keyword to retrieve data from SPARQL endpoints that require authentication, add an entry to secure storage of the following form:


username@localhost:8080/edg/tbl/sparql : password


For a query like the following, TopBraid EDG will check whether there is a user@uri key in secure storage that ends with the given URI, and returns the first one. 


SELECT ?fname
	SERVICE <https://localhost:8080/edg/tbl/sparql> {
		GRAPH <> {
			?subject <> ?fname


This is used to generate the credentials for basic authentication.

See Password Management for more information about managing passwords in secure storage.


Role-Based Access Control (RBAC) in TopBraid

TopBraid does not directly handle user authentication, which is performed by an authentication layer, such as LDAP or Active Directory, the interacts with the web application container (Tomcat). Once a user has passed the authentication challenge from the web application, the user id and roles are cached in TopBraid. An important implication is that the TopBraid infrastructure cannot know about the existence of a user until they have successfully logged in to the web container.

Once a user has successfully passed authentication by the web container,user information is cached in the urn:x-evn-user-data graph in the TopBraid workspace. Useful SPARQL functions for access to user information accessible by TopBraid include the following:

  • smf:currentUserName: Gets the name of the user that is currently logged into TopBraid. Should be preceded by smf:hasCurrentUser to avoid exceptions.
  • smf:userWithName: Converts a user name into a URI resource, following the default settings in TopBraid. Often used in conjunction with smf:currentUserName().
  • teamwork:currentUserHasPrivilege: Checks whether the currently logged in user has a given privilege, specified by a role property. The current user must have that role or a sub-property thereof, for the given governed resource. The query will be executed on the given team graph.

Please see Help > TopBraid Composer > SPARQL Function Reference in TopBraid Composer for more information on these and other functions.

Note that there is no connection between TopBraid and LDAP/AD/other authentication systems. TopBraid caches some user information when an entity is authenticated that can be accessed by TopBraid solutions.

EDG Server Installation

Enterprise Data Governance runs on Web Application servers that support the 2.4 release of the Java Servlet specification. The following sections detail specific instructions for running TopBraid servers on Tomcat.


Tomcat Installation Instructions

The instructions give details for Tomcat, and may need variation depending on local setup. The details vary with other Web Application Servers and between different versions of Tomcat. As of TopBraid EDG 6.4, creation and deployment of the web.xml on a new workspace is done automatically using a wizard.


    1. Copy the downloaded zip archive file named TopBraidEDG-[NNN].zip to any location.The WAR file edg.war included in the zip is to be deployed on the Web Application Server. These instructions assume you do not rename this file.
    2. Undeploy any current edg.war instance.
      • If hot deploy is enabled, delete edg.war from the deployment directory and Tomcat will do the rest. The file to delete will be:$TOMCAT_HOME/webapps/edg.war. These paths may be different if your Tomcat installation is configured with a different deployment directory.
      • Without hot deploy, or if hot deploy fails, you may need to stop the server and then manually undeploy: For Tomcat, remove the following:
        • $TOMCAT_HOME/webapps/edg.war
        • the directory $TOMCAT_HOME/webapps/edg
        • the directory $TOMCAT_HOME/work/Catalina/[server_name]/edg
    3. In a separate terminal or window, open the log file for Tomcat in $TOMCAT_HOME/logs/catalina.out. This is the log file that prints startup messages for Tomcat.
    4. Copy edg.war to the deployment directory: $TOMCAT_HOME/webapps.
    5. Check the log file. At this stage, relevant messages will include:Deploying web application archive edg.war
    6. Open the edg console by directing a browser to the Enterprise Data Governance server being installed: http://[Web-application-server-host]:[Web-application-server-port]/edg. A window similar to the following will appear:

This page will guide you through setup of the web.xml used for EDG. After filling out all the fields, the web.xml file will be deployed to the webapps/edg/WEB-INF directory and the page refreshed. A copy of web.xml is also automatically saved to your local file system.  Configuration information will be saved to Tomcat webapps/edg/config folder. If you create a new workspace using this same Tomcat instance, the license and configuration choices will be used. If this isn’t desired, please clear that folder. See below for details on setting up Application Data Storage and Secure Storage.

When the application refreshes, you will need to log in if you have set up authentication, see Configuring authentication below.

  • EDG uses Secure Storage to save passwords that it uses (e.g., for databases). If you provide a Master password (recommended), EDG will use it to encrypt its stored passwords. Otherwise, EDG only uses Base64 encoding (i.e., unencrypted). Saving the Master password in the EDG web.xml simply uses plain text, so you must ensure that access to the web.xml is restricted. Alternatively, instead of using the web.xml to save the Master password, it can be manually entered by an administrator each time the server is started: see EDG AdministrationAccess Control: Provide secure storage password.
  • Application data storage parameter offers three types of persistence technology: (1) relational database, (2) Jena TDB files, or (3) Data Platform.
    App data storage type Description File Extension
    In-memory + RDBMS persistence Choice of relational DB: Oracle, Microsoft SQL Server, or MySQL, which requires further RDMS Configuration. .sdb
    TDB (One database per graph) Apache Jena TDB, configured for each graph to use its own TDB database.  For EDG instances with application storage type of TDB (Each graph stored in its own, separate database), setting ulimit to unlimited is recommended. This will prevent EDG from reaching too many open files on your instance. .tdb
    TDB (Shared graph database) Apache Jena TDB, configured for all graphs to share a single TDB database, data will be stored in the _Data folder at the root of the workspace.



    Data Platform Data Platform as a data store. This will enable all EDG collections to be synced between EDG nodes. See Data Platform documentation for specific instructions on setting up Data Platform. Requires further configuration. .dpc

    Because EDG’s own system graphs also depend on the data storage type, changing the Application data storage should be considered as tantamount to a new installation, especially if the original installation used a non-TDB, remote data-store. Although existing graph data is not directly affected, changing the data storage type’s remote store could entail the need to migrate data from the old source.

    The TDB options require no additional setup or parameters. RDBMS and Data Platform each have additional required configuration, as described in  Server Administration page.  If you choose either of these options you will see the screen below after logging into the application. 

    NOTE: The choice of back-end storage is mainly a customer preference until you are getting into large scale data of over 30 million triples. With the TDB options, the database lives in the workspace file system on the server. With TDB – one database per graph (gTDB), each graph will have it’s own database. With TDB – shared graph database (xTDB), one database contains all the graphs. You will see the extensions in the connector files in your Base URI Management page as “graph name”.tdb and .xdb. Either TDB does not use as much memory as a RDBMS option. It also does not load all the data into cache at server startup. You will notice significantly quicker startup times with TDB. With RDBMS you will have the data residing in a database on another server and the connector files in the workspace. This extension will be .sdb. The difference between Oracle, MySQL and SQL Server is minimal as far as EDG is concerned. They have different ways of processing the reads/writes so performance may differ slightly with large amounts of data. If choosing RDBMS, you should choose what your DBA’s are most comfortable maintaining and tuning.

    Even organizations that are expecting to have a relatively small number of triples will often choose a TDB option over RDBMS in order to get up and running quicker and have less moving parts.

    With any option you choose, it’s important to keep your workspace regularly backed up or use server snapshots.


Configuring authentication

The web.xml file created in the Tomcat Installation Instructions contains configuration settings based on how you filled out the form at installation. Use either the tomcat-users configuration, here, or the LDAP configuration, below. If using In Memory / User Database, please ensure that your <TOMCAT_ROOT>/conf/tomcat-users.xml is setup and users belong to appropriate roles.  An example is below:

 <role rolename=”Admin”/>
<role rolename=”Manager”/>
<role rolename=”Editor”/>
<role rolename=”Viewer”/>
<user username=”Admin_user” password=”password32″ roles=”Admin,Manager”/>
<user username=”Editor_user” password=”password54″ roles=”Editor”/>
<user username=”Guest” password=”password76″ roles=”Viewer”/>


It is imperative that your web.xml security roles match the roles defined in this tomcat-users.xml file.


The LDAP Configuration section of this installation guide has information on using TopBraid EDG with LDAP.


The SAML Configuration section of this installation guide has information on using TopBraid EDG with SAML.


    Configure Logging

    If you encounter server startup problems, the following settings in Apache Tomcat’s conf/ file can give you a better picture of what’s going on:


    handlers =,,,,, java.util.logging.ConsoleHandler = FINE = ${catalina.base}/logs =edg.  
    org.apache.catalina.core.ContainerBase.[Catalina].[localhost].[/edg].level = INFO 
    org.apache.catalina.core.ContainerBase.[Catalina].[localhost].[/edg].handlers =


    Keep in mind that:

    • The handlers setting would replace the existing one. It is shown as three lines above, but should be one line in your file.
    • TopBraid Suite messages, including those related to startup issues, are sent to their own log file in the workspace under the logs folder.

    Tomcat settings – other

    A tomcat SSL connector, without an exclusion rule will require some characters be encoded where a flat http connector will not. This can cause problems with embedded links.

    The relaxedQueryChars exclusion rule can be set to relaxedQueryChars=“[]|{}^&#x5c;&#x60;&quot;&lt;&gt;”


    LDAP Configuration

    This section describes how to use the EDG server with LDAP authentication.


    Integration Instructions

    Authentication is the process by which users log on to EDG. It is possible, but not advised, to run EDG without authentication. In this case, all users get full administrative privileges.

    EDG uses the Tomcat web-app server for authentication. This is intended to help implementation of policies such as single sign-on. EDG provides no further features for single sign-on. If this is a policy mandated for your environment, first find some other Java EE based service and understand which Web Application Server they are using, and how they authenticate users in accordance with the single sign-on policy. Then contact TopQuadrant with this information for advice as to how to configure EDG in a similar way.

    This section provides instructions for integrating EDG with LDAP in Linux and Active Directory in Windows Server.


    LDAP Configuration within Tomcat

    These instructions cover the configuration of LDAP within Tomcat. For any other web application server, there could be some differences. Note that the exact formats used will depend on your LDAP configuration. Also, although the description below has a step to initiate an LDAP service, normally this is not required because you will be using a pre-existing LDAP service for configuring Tomcat and EDG.


    Identifying/Creating a Group and at Least One User in That Group

    In the sample configuration routine shown below, we will set the security to permit a specific group to access EDG. This group needs a name, which is configured within LDAP. You may already have an appropriate group.


    Configuring Tomcat to Use LDAP

    Next, we need to configure tomcat to connect to LDAP. This is specified in this document :

    This is the difficult step. It requires adding an entry to server.xml, found in the conf folder for Tomcat. For our example, the entry is as follows:


    <Realm   className="org.apache.catalina.realm.JNDIRealm" debug="99"


    inside of the Engine element. Note that in this expression, {0} and {1} both stand in for the username (they are written literally as {0} {1} in the web.xml file), but the actual expressions such as uid={0},ou=people,dc=tqinc,dc=info will be different depending on your LDAP service.

    For reference, this is for group configuration that looks like this in LDAP:


    keefe@keefetq:~$ ldapsearch -xLLL -b "dc=tqinc,dc=info" -s sub "(memberUid=keefe)"
    dn: cn=acme,ou=groups,dc=tqinc,dc=info
    objectClass: posixGroup
    cn: acme
    gidNumber: 10001
    description: Group account
    memberUid: keefe


    If your LDAP directory is setup in a straightforward way, it should be easy to modify the search expression appropriately. However, you may need assistance from someone who knows your LDAP system.

    Three pieces of information are needed:

    1. A base pattern to identify groups in LDAP, (in this case: ou=groups,dc=tqinc,dc=info).
    2. A property at which the rolename we will use in securing EDG may be found, in this case:cn
    3. A search filter that indicates role membership, in this case : (memberUid={1}) where {1} is the username.

    Active Directory Integration within Tomcat

    These instructions concern integrating Active Directory within Tomcat using the LDAP protocol. Note that the exact format depends on your LDAP configuration.


    Populate LDAP

    The security to permit a specific group of users to must be set to access EDG. This group needs a name, which is configured within LDAP. You may already have an appropriate group.

    1. Create users in Active Directory for EDG use. If existing users need to use the EDG, then ignore this step.
    2. Create a TopBraid EDG group named acme and associate users with this group in Active Directory using the wizard.

    Configuring Tomcat to Use LDAP

    Next, configure tomcat to connect to LDAP. This is specified in this document :

    This is the difficult step. It requires adding an entry to server.xml, found in the conf folder for Tomcat. For our example, the entry is as follows:


    <Realm className="org.apache.catalina.realm.JNDIRealm"
    		connectionPassword="enter password here"


    inside of the Engine element.

    In the userSearch expression, {0} stands for the username as typed by the end-user, whereas in the roleSearch expression, {0} stands for the distinguished name found from the user look up. (These are written literally as {0} in the server.xml file), but the actual expressions such as (sAMAccountName={0}) and CN=Users,DC=tblive,DC=tqinc,DC=info will be different depending on your LDAP service. With Active Directory, (sAMAccountName={0}) and roleSearch="(member={0})" should generally be correct.

    If your LDAP directory is setup in a straightforward way, it should be easy to modify the search expression appropriately. However, you may need assistance from someone who knows your LDAP system.

    Three pieces of information are needed:

    1. A base pattern to identify groups in ldap, (in this case: CN=Users,DC=tblive,DC=tqinc,DC=info).
    2. A property at which the rolename we will use in securing EDG may be found, in this case:cn
    3. A search filter that indicates role membership, in this case : (member={0}) where {0}is the distinguishedName (and {1} is the username).

    This can also be seen using an LDAP explorer tool something similar to JXplorer

    For reference, the screen-shot below shows how the Active Directory group configuration looks like in JXplorer:

    Connecting to LDAP:



    User record for user Scott:



    Group record belonging to user Scott:



    Configuring EDG to Use LDAP

    Finally, add a security constraint to EDG in the web.xml file:


      <display-name>Example Security Constraint</display-name>
      <web-resource-name>Protected Area</web-resource-name>
    <!-- Define the context-relative URL(s) to be protected --> 
    <!-- If you list http methods, only those methods are protected -->
    <!-- Anyone with one of the listed roles may access this area -->
    <!-- Default login configuration uses basic authentication -->
    <!-- Security roles referenced by this web application -->

    Starting an LDAP Service in Linux

     This is intended as a quick guide. More detailed instructions can be found elsewhere: 

    1. Install LDAP. For an example of installation documentation, see the documentation for the Ubuntu OpenLDAP Server.
    2. Configure LDAP by running through the setup wizard and setting up a domain name and related information. For example:
      domain =
      organization name = tq
    3. Populate LDAPThe example below, which uses the ldapadd utility, is based Ubuntu’s OpenLDAP configuration guide, replacing all references with the domain specified above:
      keefe@keefetq:~$ ldapadd -x -D cn=admin,dc=tqinc,dc=info -W -f test.ldif 
      Enter LDAP Password:
      adding new entry "ou=people,dc=tqinc,dc=info"
      adding new entry "ou=groups,dc=tqinc,dc=info"
      adding new entry "uid=john,ou=people,dc=tqinc,dc=info"
      adding new entry "cn=example,ou=groups,dc=tqinc,dc=info"

    Identifying/Creating a Group and at Least One User in that Group

     In this stage, we’ll set the security to permit one or more specific groups to access EDG. This group needs a name, which is configured within LDAP.

    First we install the LDAP scripts and add a group and a user,remembering to configure the LDAP scripts first. With a different LDAP server, this step will be different.

    keefe@keefetq:~$ sudo ldapaddgroup acme
    Error adding group acme to LDAP


    The error message shows that the LDAP scripts must be configured first:

    keefe@keefetq:~$ sudo gedit /etc/ldapscripts/ldapscripts.conf 
    keefe@keefetq:~$ sudo sh -c "echo -n 'monkey' > /etc/ldapscripts/ldapscripts.passwd"
    keefe@keefetq:~$ sudo chmod 400 /etc/ldapscripts/ldapscripts.passwd
    keefe@keefetq:~$ sudo ldapaddgroup acme
    Successfully added group acme to LDAP
    keefe@keefetq:~$ sudo ldapadduser keefe acme 
    Successfully added user keefe to LDAP 
    keefe@keefetq:~$ sudo ldapsetpasswd keefe 
    Changing password for user uid=keefe,ou=people,dc=tqinc,dc=info
    New Password:
    Retype New Password:
    Successfully set password for user uid=keefe,ou=people,dc=tqinc,dc=info

    LDAP Servers (Service Providers)

    The preceding LDAP sections configure EDG to use of LDAP for authentication: user login identity and roles. To further configure EDG for using additional LDAP information, e.g., email, see Server Administration – Server Configuration – LDAP Parameters

    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 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 or invalid, 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.
    – 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.
    – Direct links to sub-pages of EDG will redirect to the home page with SAML if the user is not already logged in. This is being worked on for an upcoming release.

    The valve consists of the following (located in the zip file provided by TopQuadrant which also includes the edg.war):
    -SAML valve jar and dependencies
    -modified context.xml

    Place the TopBraid-SAML jars 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

    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.

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

    When defining the Service Provider in the IDP, the assertion consumer URL will be http://yourserver/edg/saml

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

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

    OAuth Authentication

    Integrating APIs with EDG using OAuth

    TopBraid EDG version 6.4.2 introduces OAuth for APIs. Users will need to use another authentication method. 

    Unzip into /lib directory of your Tomcat installation.  Eg. /var/lib/tomcat8/lib

    • unzip -d lib
    • If you previously had TopBraid SAML from a version of EDG prior to 6.4.2, then you need to move those old jars out.


    Add Oauth config to EDG context.xml

    • Edit webapps/edg/META-INF/context.xml
    • If you previously had TopBraid SAML from a version of EDG prior to 6.4.2, then you need to adjust the className for SAML to  org.topbraidlive.auth.adapters.saml.tomcat.SamlValve
    • Make sure the OAuth valve comes before the SAML valve


    <?xml version=’1.0′ encoding=’utf-8′?>

    <!– Copyright (c) 2016 TopQuadrant, Inc. All rights reserved. –>

    <Context path=”/edg”>


          By default, Tomcat 8 tries to scan our jars for tag library

          definitions.  We don’t have any, so skipping these jars will

          improve startup and JSP compile times.



            <JarScanFilter defaultTldScan=”false”/>



        <Resources cacheMaxSize=”40960″/>

            <!–  Disable session persistence per PLAT-769 because Java8/Mars seems to have broken it.  –>

            <Manager pathname=”” />



       TopBraid adapter for OAuth


      <Valve className=”org.topbraidlive.auth.adapters.oauth.tomcat.OAuthValve”








       TopBraid adapter for SAML


      <Valve className=”org.topbraidlive.auth.adapters.saml.tomcat.SamlValve”

               assertionConsumerService=”/saml”           attributeMappings=”>name;>role”           federationMetadata=””




    Browse to your EDG webapp UI.  Navigate to Server Administration -> Server Configuration


    Under the OAuth Parameters, fill in the following:

      • Authorization server URL  (eg, ADFS https://server/adfs/oauth2/token)
      • Client ID obtained by your SSO administrator for this Application
      • Client secret obtained by your SSO administrator for this Application

     OAuth workflows

    The authorization code workflow involves the following steps: 

    The OAuth client initiates the flow when it directs the user agent of the resource owner to the authorization endpoint. … The OAuth client requests an access token from the authorization server through the token endpoint.  This is likely where you will utilize internal scripts/apis to access EDG.


    The client credentials workflow involves EDG-to-EDG applications, such as Publishing to Explorer, Send Projects or Federated Sparql queries.  The system authenticates and authorizes the app (EDG) rather than a user. For this scenario, typical authentication schemes like username + password or social logins don’t make sense. Instead, uses the Client Credentials Flow in which they pass along their Client ID and Client Secret to authenticate themselves and get a token.

    1. Your app authenticates with the Authorization Server using its Client ID and Client Secret (/https://server/adfs/oauth2/token endpoint).
    2. Your Authorization Server validates the Client ID and Client Secret.
    3. Your Authorization Server responds with an Access Token.
    4. Your application can use the Access Token to call an API on behalf of itself.
    5. The API responds with requested data.


    The Password grant workflow is a way to exchange a user’s credentials for an access token. Because the client application has to collect the user’s password and send it to the authorization server, it is not recommended that this grant be used at all anymore.


    This flow provides no mechanism for things like multifactor authentication or delegated accounts, so is quite limiting in practice.


    The latest OAuth 2.0 Security Best Current Practice disallows the password grant entirely.


    These 4 attributes are needed to fulfil OAuth authorization requirements in EDG.

    •         appid
    •         sub
    •         role
    •         apptype

     * a role of Confidential must be placed in web.xml for ADFS OAuth.

    If you need to test programs against EDG, you can do so with the tool included at https://yourserver/edg/oauth/getTokens



    Accessing the EDG application

    For access to the EDG Console, send your browser to the URL http://[Web-application-server-host]:[Web-application-server-port]/edg/tbl/


    (This corresponds to TopBraid Composer ME’s http://localhost:8083/edg/ .)


    NOTE: Until EDG completes the license registration step, only one administrator may log in.


    On the first visit, TopBraid Live itself is initialized, and you should see entries like the following added to the log:


      09-Sep-2016 13:06:36.478 INFO [main] org.apache.catalina.startup.VersionLoggerListener.log Server version: Apache Tomcat/8.0.33
      09-Sep-2016 13:06:36.479 INFO [main] org.apache.catalina.startup.VersionLoggerListener.log Server built: Mar 18 2016 20:31:49 UTC
      09-Sep-2016 13:06:36.480 INFO [main] org.apache.catalina.startup.VersionLoggerListener.log Server number:
      <etc., etc.>
      09-Sep-2016 13:07:13.371 INFO [main] org.apache.coyote.AbstractProtocol.start Starting ProtocolHandler ["http-apr-8080"]
      09-Sep-2016 13:07:13.384 INFO [main] org.apache.coyote.AbstractProtocol.start Starting ProtocolHandler ["ajp-apr-8009"]
      09-Sep-2016 13:07:13.395 INFO [main] org.apache.catalina.startup.Catalina.start Server startup in 36001 ms


    If there are permission problems with the workspace, this step will not work. If the workspace does not exist, or is an empty directory, it will be created and populated.


    The project and several others will be created in the workspace. If not, there were initialization problems and the TopBraid server will not work properly. In a Linux installation, the most common source of problems are folder permissions for the process running the Web Application Server. Try removing the workspace folder and reloading web.xml, making sure that the process has write access to the parent folder of the workspace folder.


    License registration

     As part of the deployment/setup wizard, the license file will be added to EDG. If this is incorrect, expired or missing, a message will appear that points to the registration page, as shown in the following screen shot:



    1. Click on the link. A page will appear stating that there are “No currently registered products!”
    2. Click on the Change or Update Registration Information link. Use the Choose File button to choose the license file (.lic file) sent by TopBraid support when the license was issued.

    A dialog will appear, verifying that the license was updated. The licenses and their expiration date will be displayed. This page is always available through the Server Administration tab and choosing the Server Administration then the Product Registration links.

    The TopBraid EDG license will control the number of concurrent users, human and API, that can be using EDG at any one time. For form based authentication, a license seat is used by each unique session. This means that many tabs in one browser are all counted in the same user session/license seat but unique browsers by the same user are counted as different sessions using their own license seat. API calls authenticate into EDG as well using a license seat during processing. For APIs if using form authentication, be sure to log out after completion. Sessions expire upon timeout (set in web.xml in Tomcat), thus releasing the license seat held by the session. 

    With EDG 6.4, you have the ability to track user licenses with form authentication. To enable follow the steps below. This will add details to the log files for user log in, log out, and expired sessions. 

    1. Navigate to your workspace. 

    2. Edit the file log4j2.xml.

    3.  Add the following to the Loggers section:

    <Logger name="org.topbraid.core.license.FormsAuthConcurrentUsers" level="trace" />


     Sample Data

     The EDG server-based application does not include the sample data that is included in TopBraid Composer-Maestro Edition (TBC-ME). If desired, the examples can be deployed from TBC-ME to the server by clicking on the sample project in TBC-ME’s Navigator window and choosing Export… > TopBraid Composer > Deploy Project to TopBraid Live Server. Permission will default to “Administrator” for the sample project. Please update this in the role management page if needed.