Client API Reference

Clients wishing to access an OA4MP server directly can do so using the supplied programming API. This document outlines the steps needed and discusses how to accomplish this.

Accessing the Client API via Maven

The only supported method for including the client API in your project is via maven. This is supported by most every IDE and works well from the command line too. Simply include the following dependency in your project pom:

OAuth 1.0a
<dependency>
   <groupId>edu.uiuc.ncsa.myproxy</groupId>
   <artifactId>oa4mp-client-oauth1</artifactId>
   <version>5.5</version>
</dependency>
OAuth 2.0
<dependency>
   <groupId>edu.uiuc.ncsa.myproxy</groupId>
   <artifactId>oa4mp-client-oauth2</artifactId>
   <version>5.5</version>
</dependency>
OA4MP is hosted in the Sonatype repository, so specifying the dependency should be sufficient.

All references should be resolved at build time.

The Basic Client API

The major class that you will need is an instance of edu.uiuc.ncsa.myproxy.oa4mp.client.OA4MPService.java This has precisely two basic calls:

public OA4MPResponse requestCert();
public AssetResponse getCert(String tempToken, String verifier)

The first generates a public/private keypair and certificate request. The OA4MPResponse object contains the URI to which to redirect the user and the generated private key. You must redirect the user to the given URI since this is where s/he will authenticate with the MyProxy server.

Once the user has finished, the server does a callback to the uri you specify. It will contain parameters in the request for the temp token and verifier. You must pass these to the method. The OA4MPService instance will then complete the rest of the OAuth protocol and get the certificate. The AssetResponse contains the username, i.e. the name the user used to authenticate and the X509 certificate itself.

A Basic Example

To use the service, you must create a ClientEnvironment object. This is certainly do-able manually, but it is much better to use one of the ClientEnvironmentUtil's load methods. Here is an example. 
ClientEnvironment ce = ClientEnvironmentUtil.load("/path/to/file", "my-cfg");
OA4MPService service = new OA4MPService(ce);
OA4MPResponse response = service.requestCert();

Later, once the user has authenticated and the callback has been invoked, the identifier, access token and verifier need to be used:

ClientEnvironment ce = ClientEnvironmentUtil.load("/path/to/file", "my-cfg");
OA4MPService service = new OA4MPService(ce);
String accessToken; // from  the callback URL
String verifier;   // from  the callback URL
AssetResponse assetResponse = service.getCert(accessToken, verifier);

"OAuth 2 extensions

For OAuth 2 support, there are two more API calls possible to support the specification. This being Java you need to instantiate the class edu.uiuc.ncsa.oa4mp.oauth2.client.OA2MPService which extends the above OA4MPService class above. There are two additional calls
  • refresh(String identifier)
  • getUserInfo(String identifier)
You can read up detailed examples of how to use these in the user info and refresh token document.

The Asset Store API

There are two other calls in the API that will tell the service to use the asset store. Note that these will fail if there is no such store enabled. You must supply a unique identifier which is a URI. The associated asset may then be recovered with this key. Typically this identifier is stored in the user's browser as a cookie and retrieved on during the callback.

A simple example

ClientEnvironment ce; // as per above.
OA4MPService service = new OA4MPService(ce);
Identifier id = BasicIdentifier.newID("my:test:uri/1");
OA4MPResponse response = service.requestCert(id);

At this point, the first exchange with the server is done and an asset with the given id has been created in the store. After callback when you have the accessToken and the verifier you can finish the exchange and get the asset:

String accessToken;
String verifier;
// other values as per the previous example
AssetResponse response = service.getCert(accessToken, verifier, id);
Asset asset = ce.getAssetStore().get(id);