Overview

Purpose

The purpose of this document is to provide an overview of the Handle Service software developed by the Australian Research Data Commons.

The Handle service was not designed as a software package for end users. It does not come packaged with a friendly user interface, rather it is intended it be used for integration with other applications requiring a persistent identifier service.

At an implementation level, the Handle service is a Tomcat web application with each service point being implemented as a Java servlet. A PostgreSQL database provides the storage layer using the default CNRI Handle Server schema (as described in the Handle Technical Overview document). To simplify authentication of the Handle Service to the Local Handle Server (LHS) and keep these communications secure, the Handle Service must reside on the same machine as the LHS to take advantage of the default Public Key Infrastructure (PKI) authentication. Authentication of clients is required before access to administrative services is granted. This is currently implemented by registering trusted clients in the PostgreSQL database along with a unique key issued by the Handle Service. This key coupled with the client's identity (IP address) is used in determining whether a request to a service is granted.

Service calls are typically HTTP requests generated via a user interface or automated process containing an XML document. The XML document provides the identity of requestor, typically the owner of the target handle. This information is used to ensure the requestor has sufficient rights to undertake the administrative operation on the target handle. As an example, in the XML fragment below the appID is the Service-issued key identifying a the Handle Service trusted client, the identifier is the handle owner and authDomain specifies the authentication domain in which the user is operating (such as Shibboleth, LDAP, or some other trusted domain).

<request name="addValue">
    <properties>
        <property name="appId" value="5d9a4da3580c528ba98d8e6f088dab93f680dd6b " />
        <property name="identifier" value="scott" />
        <property name="authDomain" value="mycomputer.edu.au" />
    </properties>
</request>

The owner of the handle can only manage their handles from within the authDomain the handle was minted. The user and authDomain cannot be updated via service calls at this point in time. The implication of this is a user moving from one authentication domain to another (for example a different institution or application) will not be able to manage their handles without first organising an updating of their details with the the Handle Service service manager. The owner assigned when a handle is minted is the only user able to undertake further administrative operations on the handle.

Responses to service calls are also in an XML form and vary depending on the service called and whether the service call succeeded or failed. Requests based on a single handle will return the state of the handle after a successful request.

Each handle in the Identifier Service has two administrator records by default, namely the Handle Server admin (an HS_ADMIN entry) as well as the owner (a custom handle value type, AGENTID), i.e. the individual either directly creating the handle or the automated agent (application) on whose behalf the handle was created. An owner is assigned a handle and this value appears in the AGENTID value of an individual owner's handle records.