5. Usage

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.

5.1. Using your Keytab

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

5.2. curl

The following is a simple example of using curl on a linux platform, authenticating with Kerberos to the CUD REST interface. Correct Kerberos configuration is assumed.

5.2.1. The Empty Query

$ KRB5CCNAME=krb5cc_test_cream ; kinit cud/example.unit.ox.ac.uk@OX.AC.UK -k -t example.keytab && \ curl --negotiate -u : https://ws.cud.ox.ac.uk/cudws/rest/search?q=

5.2.2. NegotiateRestClient.jar

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:

gssnegotiate-keytab-client { com.sun.security.auth.module.Krb5LoginModule required useKeyTab=true keyTab="example.keytab" principal="cud/example.unit.ox.ac.uk"; }; com.sun.security.jgss.login { com.sun.security.auth.module.Krb5LoginModule required useKeyTab=true keyTab="example.keytab" principal="cud/example.unit.ox.ac.uk"; }; com.sun.security.jgss.initiate { com.sun.security.auth.module.Krb5LoginModule required useKeyTab=true keyTab="example.keytab" principal="cud/example.unit.ox.ac.uk"; }; com.sun.security.jgss.accept { com.sun.security.auth.module.Krb5LoginModule required useKeyTab=true keyTab="example.keytab" principal="cud/example.unit.ox.ac.uk"; };

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.

With regard to the other configuration attributes, it is important that "useKeyTab" should be set to "true", to ensure that Java uses the keytab file to authenticate to the remote CUD REST interface.

To test the set-up it will help to have a basic kerberos configuration file in place so that the client has all its configuration information available locally. For our example this will be called

krb5.conf

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):

  1. %JAVA_HOME%/lib/security/krb5.conf
  2. %WINDOWS_ROOT%/krb5.ini

Alternatively you can specify the location of the Kerberos configuration file on the java command line, by setting the java.security.krb5.conf parameter, as in

% java -Djava.security.krb5.conf=/path/to/krb5.conf ...(etc)...

For use with the Oxford realm the contents of the krb5.conf kerberos configuration file should look

like the following:

[libdefaults] default_realm = OX.AC.UK [realms] OX.AC.UK = { kdc = kdc0.ox.ac.uk kdc = kdc1.ox.ac.uk kdc = kdc2.ox.ac.uk kdc = kdc3.ox.ac.uk default_domain = OX.AC.UK } [domain_realm] .OX.AC.UK = OX.AC.UK

The krb5.conf above can be re-used as-is.

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.

5.2.3. The Empty Query

The query is specified using the -d/--data flag, and the arguments following will be appended to the URL in a GET request. In this case, "q=" indicates that the query string is empty.

% java -Djava.security.krb5.conf=krb5.conf -jar NegotiateRestClient.jar -c login.conf \ -u https://ws.cud.ox.ac.uk/cudws/rest/search -d "q="

5.2.4. Some Example Queries

The following query retrieves all records that have a currently-active affiliation to OUCS, in XML format:

% java -Djava.security.krb5.conf=krb5.conf -jar NegotiateRestClient.jar -c login.conf \ -u https://ws.cud.ox.ac.uk/cudws/rest/search -d "q=cud\:cas\:current_affiliation:oucs&format=xml"

The next query retrieves a particular record for a person, with change history, in json format:

% java -Djava.security.krb5.conf=krb5.conf -jar NegotiateRestClient.jar -c login.conf \ -u https://ws.cud.ox.ac.uk/cudws/rest/search -d "q=cud\:cas\:sso_username:unit1234&format=json&history=y"

Up: Contents Previous: 4. Requesting Access