As part of the UI rewrite, three new
acronyms features have landed in the CollectionSpace services layer. These will be available in the next release of CollectionSpace (tentatively numbered 4.5). You can try them today by building and deploying the master branch to your own server, or by hitting our nightly build server at .
The services layer treats XML as its first-class serialization format; it contains code that explicitly generates XML and expects to receive XML. For this reason, the JSON provided as output and expected as input is not a direct serialization of CollectionSpace resources. Instead, JSON is produced by converting XML output as it exits the services layer, and JSON is converted back into XML as it enters the services layer. This results in a couple of oddities, like using
@ to prefix fields that are translated from XML attributes, and using
@xmlns: to prefix fields that correspond to XML namespace declarations.
To request data in JSON format, send the HTTP
Accept header, with value
To send data in JSON format, send the HTTP
Content-Type header, with value
OAuth 2 Tokens
The REST API now grants and accepts authorization tokens. This is another step towards eliminating the application layer.
Tokens are granted following the OAuth 2 specification. Currently only the resource owner password credentials grant and refresh token grant are supported. Only one client identifier is currently allowed:
cspace-ui. In the terminology of the specification, the
cspace-ui client represents a public client and a user-agent-based application. Since this client is public (and therefore incapable of keeping a secret), the client secret (sent as the basic auth password in the following examples) is empty.
Tokens my be obtained by sending a POST request to the
This returns an access token and a refresh token.
The access token may be used to authorize requests against CollectionSpace resources. This is done by sending the HTTP
The refresh token may be used to obtain a new access token – typically, after the current access token has expired. This is done by sending a POST to the
- Access tokens are set to expire in one hour, and refresh tokens in 12 hours. Once the refresh token has expired, the user must re-authenticate with their username and password.
- The tokens are JWT, but this may change in the future. For now they should be considered opaque strings.
- The above examples are contrived to demonstrate how the API is used. For one-off curl requests, it's easier to use basic auth, which is still supported. Token auth is preferred when you're using a client that handles the token management for you.
- Tokens are signed with a random key generated when the services layer starts. Restarting the CollectionSpace server changes the signing key, invalidating all outstanding tokens. This means that all users must re-authenticate with their username and password. Restarting CollectionSpace is in fact the only way to revoke an outstanding token. There is no way to revoke an individual token; they will all be invalidated.
Future enhancements will include configurability – for example, of allowed client identifiers and associated secrets, token expiration times, and token signing keys – and support for additional OAuth 2 grant types. Additional design work around revoking individual tokens is also required.
Cross-origin requests are not allowed by default. Domains may be whitelisted for CORS on a single CollectionSpace server by adding a security.properties file to tomcat's lib directory. The
cors.allowed.origins property accepts a comma separated list of domains:
Alternatively, the default value of
cors.allowed.origins may be modified in the source tree by editing applicationContext-security.xml.