Child pages
  • _Authenticating Service Calls
Skip to end of metadata
Go to start of metadata

Authenticating Service Calls

When accessing TopBraid services via RESTful web service calls, authentication of the invoking entity needs to be considered. There are a few options and tradeoffs when using the application server underlying TopBraid. The following sections provide an overview of Java EE and choices available for authentication of services.

Authentication for TopBraid Suite Server

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 $ProductAbbrevName'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.

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 (see Tomcat Installation Instructions), 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 Server Administration > Setup - Server Configuration Parameters > Advanced Parameters 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 $ProductAbbrevName 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.

End User Authentication

If user log-in is required, then it is best to use Form authentication. In this case the application (tbl/$ProductAbbrevLowercase) 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 /server.topbraidlive.org/dynamic/users.ttl 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/$ProductAbbrevLowercase/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/$ProductAbbrevLowercase/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/$ProductAbbrevLowercase/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/$ProductAbbrevLowercase/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]/$ProductAbbrevLowercase/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:

  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 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/$ProductAbbrevLowercase/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/$ProductAbbrevLowercase/tbl/j_security_check" -H "Context-Type: application/x-www-form-urlencoded" --data "j_username=$2&j_password=$3"  -L "http://$1/$ProductAbbrevLowercase/tbl" -c ~/loginSuccessCookie -D ~/secReqHeaders 

curl -b ~/loginSuccessCookie -X POST "http://$1/$ProductAbbrevLowercase/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/$ProductAbbrevLowercase/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/$ProductAbbrevLowercase/tbl/sparql : password

For a query like the following, TopBraid $ProductAbbrevName 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
WHERE {
	SERVICE <https://localhost:8080/$ProductAbbrevLowercase/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.

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 /server.topbridlive.org/dynamic/users.ttl 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.

  • No labels