Eclipse USS

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.

Getting Started

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:

1. Provide the client ID to application name mapping
2. 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");

See the org.eclipse.userstorage.sdk's 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.