Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
The Eclipse User Storage Service (USS) allows Eclipse projects to store user-specific project information on the Eclipse Foundation servers. The goal is to make it easy for our projects to offer a better user experience by storing relevant information in a central location.
The git project is moved to http://git.eclipse.org/c/usssdk/org.eclipse.usssdk.git/
IMPORTANT: the USS is intended to be used for data that may be exposed publicly. Application developers must not use this service to store personal data, such as name, email address, host/server information or anything else that is best suited for local storage or the Eclipse Secure Storage.
The USS has two components:
- REST API server. The actual storage service.
- USS SDK: a java API to interface with the REST server from an Eclipse workspace. The SDK handles login/authentication, session management and storage/retrieval of data.
To store data in the USS, an Eclipse project must first apply for an Application Token by sending a request to the Eclipse Webmaster. The Application Token is a string that allows projects to differentiate their user data from that of other projects. Since the Application Token is used in the context of Open Source projects, it is not private, it is not hidden, and may even be used in source code. It is not meant to be an authorization or authentication mechanism; however, there are plans to increase the security of this mechanism, as any Eclipse project could use any authorized token. An Application Token may be shared with other Eclipse projects.
The USS uses OAuth to allow the user to grant fine-grained authorization for a specific Eclipse project to access their user data. Each Eclipse project is considered as a separate OAuth Client. Each Eclipse project must apply to the Eclipse Webmaster for a unique ID and secret. The OAuth specification describes a work flow to to prompt the user to authorize an OAuth Client (the Eclipse project) to access the user's data. If the user approves, the OAuth Client is provided an access code. This access code must be provided on each call when accessing the USS.
Using the USS SDK
The USS SDK is a library that simplifies accessing the USS.
Configuring the USS SDK
There are two steps for configuring the USS SDK:
- Provide the client ID to application name mapping
- Configure the USS OAuth Credentials Provider
Configuring the Client ID to Application Name Mapping
The USS SDK provides a *Linked Accounts* preference page that lists current credentials with the client (application) and user account. To have your application name listed, add an extension to the
org.eclipse.userstorage.oauth.clients extension point to describe the MPC app:
<extension point="org.eclipse.userstorage.oauth.clients"> <client id="eclipse_uss_sdk" name="USS SDK Examples" icon="icons/eclipse.png" authURI="https://accounts.eclipse.org/"> </client> </extension>
Configuring the OAuth Credentials Provider
The USS SDK's
EclipseOAuthCredentialsProvider class is used to obtain authorization from the user for your application to work with their user data managed by the Eclipse Foundation.
It's easiest to use the
OAuthParameters class to configure your OAuth parameters. See the class comment for details on configuring your own instance.
final IStorage storage = StorageFactory.DEFAULT.create(appToken); OAuthParameters oauthParameters = new MyOAuthParameters(); EclipseOAuthCredentialsProvider credentialsProvider = new EclipseOAuthCredentialsProvider(oauthParameters); credentialsProvider.setShell(getViewSite()); storage.setCredentialsProvider(credentialsProvider); // and now start fetching content IBlob b = storage.getBlob("xxx");
USSBrowsingView for a running example of configuring and fetching content from the USS.
Storing and Fetching Data using the USS SDK
The USS SDK Storage Tests class provides a good sample implementation. Please see: http://git.eclipse.org/c/oomph/uss.git/tree/org.eclipse.userstorage.tests/src/org/eclipse/userstorage/tests/StorageTests.java
Additional UI Extension Points for the USS SDK
The USS provides a tool item and menu (Help > Eclipse User Storage) that opens an extensible cascaded menu with ID org.eclipse.userstorage.accounts. This menu has the following format:
<Account widget> menuId: org.eclipse.userstorage.accounts +- Open My Account opens accounts.eclipse.org +----------------- separator tagged `actions` +----------------- separator tagged `accounts` +- Authorized Applications opens USS OAuth pref page +- USS Example Browser list of authorized applications +- Sign Out discards all data +----------------- separator tagged `additions`
For example, the Marketplace Client adds an item to open the MPC on the user's favourites:
<extension point="org.eclipse.ui.menus"> <menuContribution allPopups="false" locationURI="menu:org.eclipse.userstorage.accounts?after=actions"> <command commandId="org.eclipse.epp.mpc.ui.command.showFavorites" icon="icons/marketplace16.png" label="%command.account.favorites.label" style="push" tooltip="%command.account.favorites.tooltip"> </command> </menuContribution> </extension>
Projects Using USS
- Oomph: allowing users to save their preferences to the USS for persistence across workspaces on different computers and/or virtual boxes.
- Marketplace Client (MPC): (planned) to store user favorites to the USS.