This document aims to describe how to use command-line client tools to interact with the Core User Directory (CUD) REST interface, for the extraction of data according to specific queries. These tools are intended to help with the automation of a batch-processing strategy.
Requests to the CUD REST interface are made using the HTTP GET method, with parameters included in the query string. Results are streamed in the HTTP response in a choice of formats: XML; JSON; CSV; Delimited Text with named delimiter and text qualifier.
A self service interface is also available to enable users to pre-build queries which can then be referenced by name in the query string. Access to the REST end points are over SSL/TLS, with the Kerberos GSS-Negotiate mechanism used for authentication.
Queries to the CUD REST interface use the Solr/Lucene query syntax. More information about Solr query syntax may be found at http://wiki.apache.org/solr/SolrQuerySyntax.
The delimiter parameter in CUD is optional, and only relevant when the 'text' format is used. For other formats this parameter will be ignored. The first character of the value set for this parameter will be used as the field delimiter. If the text format is set, and this parameter is omitted, a comma will be used as the delimiter.
The qualifier parameter in CUD is optional, and only relevant when the 'text' format is used. For other formats this parameter will be ignored. The first character of the value set for this parameter will be used. The purpose of this parameter is generally to escape the field. If the text format is set, and this parameter is omitted, no additional qualifier will be used.
The history parameter in CUD queries is optional, and indicates whether you wish the response to contain historical values for attributes and affiliations. You should only request this if it is required, and the default is not to include history. Include history if you wish are requesting data in XML or JSON format and wish it to be richly structured (see the CUD UI User Guide for further details).
To automate access to the CUD REST interface a tool is required that will allow authentication using the GSS Negotiate protocol with a Kerberos service principal keytab. The following tools offer this functionality and have been successfully tested to work with the CUD REST interface.
The curl tool may be used as long as it has been compiled with GSS-Negotiate and SSL support. Compiling with GSS-Negotiate support is dependent upon the availability of particular Kerberos libraries. The MacOS and linux operating systems are examples for which curl has been packaged with built-in GSS-Negotiate support, while curl built for the Windows OS may not have been.
To use this tool you must have installed the prerequisite Java SE (Standard Edition) Runtim Environment (JRE). This is available as a free download from http://java.oracle.com . Alternatively an equivalent OpenJDK edition can be installed if it is available for your OS platform. The minimum required Java Runtime Environment (JRE) version is Java 7.
Email email@example.com to request a service principal for access to CUD, specifying the /itss principal that should have administrative rights over that principal, and that the principal is intended to be used to access CUD data.
Once you have the service principal you can generate a keytab using the kadmin utility on a workstation that has been secured for this purpose (since linux.ox.ac.uk is a shared service it is not recommended for this). Since the keytab contains password-equivalent keys for system-to-system authentication it should be kept in a secure location.
The following examples are based on a fictitious server called example.unit.ox.ac.uk, which is using a service principal, cud/example.unit.ox.ac.uk@OX.AC.UK for which a keytab has been created in the current directory with the name of example.keytab
In contrast to curl, the java client uses a configuration file in which the principal and the keytab location are specified. Given the example principal and keytab described above we will place our authentication configuration file in the current directory, and call it login.conf. Its contents will look like the following:
NOTE that the values assigned to the attributes "keyTab" and "principal" above will need to be changed for your own set-up, i.e. you should substitute the correct values for the location and name of your own keytab file, and the name of your cud service principal.
By default the program will look in the current directory for the krb5.conf file. If the file is not found there Java will try to locate this file in these locations on a Windows platform (trying each in turn):
So to summarise, for this example we should have three files available: the keytab file (example.keytab), the authentication configuration file (login.conf), and the kerberos configuration file (krb5.conf). With that in mind the following are examples of using NegotiateRestClient.jar, and authenticating transparently with Kerberos to the CUD REST interface.