Eclipse User Storage Service SDK 2.0.0



[This release is a placeholder for a future API-breaking release, should a need arise.]

The USS SDK provides an idiomatic Java API to interface with the Foundation-hosted User Storage Service from an Eclipse workspace. The SDK handles login/authentication, session management and storage/retrieval of data.

The USS SDK was originally created by the Oomph project and released as USS SDK 1.0. The USS SDK was subsequently promoted as a full technology project. Version 2.0 will:

  • remove the deprecated login/password ('session') based authentication mechanism in favour of a new OAuth-based approach supported by the Foundation;
  • offer a failback mechanism for platforms where the SWT Browser cannot be used.

The USS SDK has documentation on the Eclipse Wiki.

Architectural Issues

Some contortions were required to support both the now-deprecated "session"-based authentication and the newer OAuth-based mechanism. The relevant code can be refactored and simplified once the session-based code is removed.

The USS SDK attempts to separate runtime and UI code. But OAuth authorization is a mix and the two cannot be untwined.

Security Issues

Our approach exposes the OAuth Client Secret: To simplify the user experience, the USS SDK uses the Authorization Code grant flow, where the OAuth client (the consumer of the USS SDK) provides a Client ID and Client Secret, rather than the Implicit flow which only requires the Client ID. The Authorization Code flow provides clients with a time-limited access token, a nonce that must be provided on each request, and a refresh token, which allows obtaining new access tokens. Clients using the Implicit flow only receive time-limited authorization tokens and do not receive a refresh token.

The Authorization code flow is normally intended for server-style applications where the Client Secret can be kept secret. Eclipse plugins are more akin to mobile apps, as their compiled bytecodes are open to introspection to a determined attacker. But ultimately the implicit flow results in a poorer user experience as the user must periodically re-affirm their authorization requests for the plugin to obtain a new access token (typically access tokens expire after an hour). For a mobile app, which is used periodically, but most Eclipse plugins will be long-lived.

As the USS is not suited to store private or confidential information, and user data is intended to be shared, the need for confidential client secrets is moot. And thanks to a contribution from Eike Stepper, and further improved by Carsten Reckord, we also provide a means to embed OAuth Client IDs and Secrets in a lightly-encrypted manner that can be committed to source repository. It adds a little bit of friction to an attempted crack.

Non-Code Aspects

User documentation, primarily an Eclipse Wiki page, is admittedly sparse. The REST protocol is documented, but has not been published by the Eclipse Foundation.

Conforms To UI/UX Guidelines
Not verified
Usability Details

OAuth authorization requires logging into the Eclipse Foundation web site, and is done through an internal web browser.

End of Life

Session-based authentication is removed. Plug-ins using session-based authentication provider should move to using the new OAuth-based provider.


The USS SDK does not really have a user community. The consuming projects are known to us and provide fixes and feedback on missing features.