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


For the JVM 8, the recommended JAVA_OPTS (environment variable) parameter setting for heap space is:




The 4g value for Java heap space (-Xmx) represents a maximum allocation for Tomcat servers. If this figure is too low, then you might likely see a HTTP 500 server error on the first page accessed.


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 such as Red Hat 7 or Ubuntu 14.04 LTS
Java Runtime Environment: Java 8
Web Application Server


Must support 2.4 release of the Java Servlet specification.


Apache Tomcat 8 (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
Web Application Server


Must support 2.4 release of the Java Servlet specification.


Apache Tomcat 8 (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 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.



Internet Explorer and SSL


For your users using TopBraid applications from Internet Explorer over SSL, certain settings in your httpd.conf file will ensure that the application’s behavior will be consistent with its use from other browsers. The following shows the end of a VirtualHost element in an httpd.conf file, with the IE-related lines in bold.


   SSLEngine On

   SSLProtocol all -SSLv2

   SSLCertificateFile    /etc/ssl/certs/server.crt
   SSLCertificateKeyFile /etc/ssl/private/server.key

   SSLCertificateChainFile /etc/ssl/ca/
   SSLCACertificateFile    /etc/ssl/ca/ca.pem
    SetEnvIf User-Agent ".*MSIE.*" is_ie nokeepalive ssl-unclean-shutdown downgrade-1.0 force-response-1.0 #Needed for IE Flash image loading bug Header set Cache-Control no-store env=is_ie Header unset Pragma env=is_ie 


The SetEnvIf line sets a series of environment variables to true for user agents with MSIE in their name, and the two Header lines adjust the HTTP header that will be sent to the browsers.


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 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 log-in 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 / file 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 a file named / 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. Manual editing of the web.xml file is no longer supported. The following steps will create a correct web.xml file. Manual edits made for other applications are outside of the scope of this document, and not supported by TopQuadrant.


    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.warThese 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:
      1. 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.
      2. Fill in the details on this page and “Submit”.
      3. A web.xml file will be generated and either displayed by your browser or saved to your local file system.
    7. Stop Tomcat. Replace the $TOMCAT_HOME/webapps/edg/WEB-INF/web.xml with the web.xml generated in the previous step.

Start Tomcat.


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.

Redeploying Web.xml

With Hot Deploy

If hot deploy is enabled, then this step is already done. A Tomcat log file will show something like the following:


May 23, 2009 2:13:23 PM org.apache.catalina.startup.HostConfig checkResources
INFO: Undeploying context [/tbl]
May 23, 2009 2:16:28 PM org.apache.catalina.startup.HostConfig deployWAR
INFO: Deploying web application archive edg.war
osgi> May 23, 2009 2:18:26 PM org.apache.catalina.startup.HostConfig checkResources
INFO: Reloading context [/tbl]
May 23, 2009 2:18:26 PM org.apache.catalina.core.StandardContext stop
INFO: Container org.apache.catalina.core.ContainerBase.
   [Catalina].[localhost].[/tbl] has not been started
osgi> May 23, 2009 2:18:29 PM org.apache.catalina.core.StandardContext start
INFO: Container org.apache.catalina.core.ContainerBase.
   [Catalina].[localhost].[/tbl] has already been started


This may take a couple of minutes.


Other Web Application Servers will report the same behavior in different ways.


Without Hot Deploy


Go to the console for Tomcat or the equivalent if using another WebApplication Server. Find the edg application and either Reload or Stop and then start the application.

    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 tomcat log file in $TOMCAT_HOME/logs/edg.log.

    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.


    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 switch to BASIC if they want to use SAML for Browser SSO (non-API logins).
    – 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:
    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 SP 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.

    Detailed instructions are provided upon request to

    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


    After these steps, log into the EDG server. A message will appear that point 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.


    TopBraid GUI apps require persistence configuration: Application data storage


    For GUI applications (excluding TopBraid Live), an administrator must configure the persistence installation for graph data, following these steps: Teamwork Platform Parameters: Application data storage.


    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.