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.
