Authentication for TopBraid EDG

All authentication for TopBraid is 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 or Governance Roles 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, SAML and OAuth authentication.

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. TopBraid supports Form, Basic and no authentication:

No Authentication. No user id or password is required to invoke services. This is useful for Linked Open Data applications and applications that 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 EDG Administration and Configuration is set to false, which is the default, that blocks updates.
Form-based authentication. This is the best choice for all UI-based applications, such as EDG and 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.
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 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().

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, that 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.

Web Service Authentication

Web services invocation on servers requiring authentication can use Basic or Form-based authentication. Basic authentication using HTTPS encryption is recommended. SAML SSO cannot be used for web services. Please see SAML below for more information.

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=http://topbraid.org/examples/kennedys&format=application/sparql-results+json
&query=SELECT ?s WHERE {?s a <http://www.w3.org/2002/07/owl#Class>}”

curl -H “Authorization: Basic c2NvdHQ6MTIzNDU=” -X POST “http://localhost:8080/edg/tbl/sparql
?query=SELECT ?s WHERE { GRAPH <http://topbraid.org/examples/kennedys> {?s a <http://www.w3.org/2002/07/owl#Class>} }”

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:

http://[host]:[port]/edg/j_security_check?j_username=[username]&j_password=[password]

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:

The client requests a cookie, e.g., loginRequestCookie, to use for logging in using GET or POST.
The client logs in, and if successful, the client will receive another cookie, e.g., loginSuccessCookie, which is saved for subsequent requests.
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 authenticateCallService.sh:

#!/bin/bash

#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
fi

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 -i -b ~/loginRequestCookie -d "j_username=$2" -d "j_password=$3" -L http://$1/edg/tbl/swp?_viewName=home http://$1/edg/tbl/j_security_check -c ~/loginSuccessCookie

curl -b ~/loginSuccessCookie -X POST "http://$1/edg/tbl/sparql" -G --data-urlencode "query=SELECT * WHERE{?s a <http://www.w3.org/2002/07/owl#Class>} "
--data-urlencode "default-graph-uri=http://topbraid.org/examples/kennedys" --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 Password Management in Server Administration 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 storage that ends with the given URI, and returns the first one.

SELECT ?fname
WHERE {
       SERVICE <https://localhost:8080/edg/tbl/sparql> {
               GRAPH <http://topbraid.org/examples/kennedys> {
                       ?subject <http://topbraid.org/examples/kennedys#firstName> ?fname
               }
       }
}

This is used to generate the credentials for basic authentication.