Storing Delegated Assets

Once delegation is complete, clients will want to retrieve the private key, certificate chain and other items. The OA4MP client comes (as of 1.0.6) with a new storage system for these. Features are
  • Seamless integration. If an asset store is configured, assets are added automatically bythe system
  • Support for file-based as well as SQL-based storage
  • Simple API.
If you need to access the results elsewhere, such as in another servlet or even in another application then persistent storage of results is must. Note that if you do not configure storage, then a warning message will be entered in the log and any assets will be kept in an in-memory store. If you have no further need of assets, then you can safely ignore this feature.

How it works in a Nutshell

Each delegation request results in an Asset being created. There are various stores available. These are

New Store Creation

To create a new store has different requirements, depending on the store. For an memory only store, you need do nothing more that have an entry in the configuration file. Same for a file store. For an SQL-backed asset store, you should run either the install script for mysql, Maria DB or postgreSQL. These also presume database administration access to set them up.

The Asset object

Asset stores contain assets. An asset is a java bean populated by various bits of useful information.
Property name Mutator Comment
identifier getIdentifier, setIdentifier A client generated unique string (this is URI) which identifies this. It will be stored as a cookie in the user's browser and this cookie will later be used to find the correct asset. This is necessary to keep the private key, username and certificates associated with each other. You specify this at the time of the initial request to the OA4MPService.
username getUsername, setUsername The name the system used when contacting MyProxy. This usually be the name the user supplied at login, although some servers (such as CILogon) use another alias.
privateKey getPrivateKey, setPrivateKey The private key that the system generated when requesting this certificate. The certificate is useless without this generally.
certificates getCertificates, setCertificates An array of X509Certificate objects. This is the certificate chain returned from MyProxy. There is always at least one element after a sucessful delegation.
redirect getRedirect, setRedirect The URI that was returned by the OA4MP server and to which the user was redirected.
creationTime getCreationTime, setCreationTime The timestamp for when this asset was created. This is used by the automatic cleanup thread, if that facility is enabled or administrators may use this directly if they wish to implement their own aging/cleanup policies.
accessToken getAccessToken, setAccessToken Get the current access token. OAuth 2.0 assets only.
refreshToken getRefreshToken, setRefreshToken Get the current refresh token. OAuth 2.0 assets only.

Adding assets

Normally assets are created and managed automatically during delegation. Be sure to wait until delegation has completed before attempting to access properties or they may not exist yet.

Asset retrieval and use

The ClientEnvironment is created at server startup from the configuration file.

Creating your own ClientEnvironment

Another possible use of the OA4MP client api is as a library to allow other applications to get assets from a store. This can be done quite simply by populating a client environment from the configuration file and invoking its getAssetStore. Rather than hand-crafting an environment, it is best to use the right utility.
OAuth 1.0a
ClientEnvironmentUtil.load(String configFilePath, String configName)
OAuth 2.0
OA2ClientEnvironmentUtil.load(String configFilePath, String configName)
which returns a fully functional environment.

An example

You might specify the oa4mp-client-api as a dependency in another project. Then to get an asset there you would do something like this for OAuth 1.0a (again, OAuth 2.0 is identical aside from the first line): 
ClientEnvironment ce = ClientEnvironmentUtil.load("/path/to/config", "config-name");
Asset asset = ce.getAssetStore.get(identifier);
PrivateKey pKey = asset.getPrivateKey();
// etc., etc.
where identifier is the unique identifier that was used when the asset was created.

Removing old assets

There are two ways to do this. You may either simply remove them manually by invoking the remove method in the AssetStore or you can enable a worker thread to remove expired ones for you. The benefit of using the thread is that it will also garbage collect incomplete assets (such as when a user starts a delegation but does not complete it, for whatever reason) and generally keep the store cleaner.
OAuth 1.0a
This is configurable and is enabled by adding the following elements to your configuration:
    <enableAssetCleanup>true</enableAssetCleanup>
    <maxAssetLifetime>10000</maxAssetLifetime>
The first enables the cleanup facility (default is no cleanup) and the second specifies, in seconds, the maximum age of an asset. Typically this is at least as long as your site policy on the certificate lifetime itself.
OAuth 2.0
Only a single element is needed in the configuration file. 
    <enableAssetCleanup>true</enableAssetCleanup>
This enables automatic asset cleanup. The default is to have no cleanup. The lifetime of an asset is determined by the refresh token's stored lifetime, since it is impossible to get another access token one the refresh token expires without having the user authenticate. If you supply a 
maxAssetLifetime
in your configuration, it will be ignored.