Skip to main content

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.

Jump to: navigation, search

Difference between revisions of "Eclipse USS"

(Add more detail about the USS SDK)
Line 10: Line 10:
  
 
== Getting Started ==
 
== Getting Started ==
To store data in the USS, Eclipse projects 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.
+
 
 +
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.  An Eclipse project must apply to the Eclipse Webmaster for their unique ''ID'' and ''secret''.  The OAuth specification describes a work flow to prompt the user to authorize the Eclipse project, to obtain an  ''access code''. This access code must be provided when accessing the USS.
 +
 
 +
== Using the USS SDK ==
 +
 
 +
The USS SDK is a library that simplifies accessing the USS.  An Eclipse project must configure the
 +
 
 +
=== Configuring the USS SDK ===
 +
 
 +
There are steps for configuring the USS SDK:
 +
 
 +
  1. Provide the client ID to application name mapping
 +
  2. Configure the USS OAuth Credentials Provider
 +
 
 +
==== Map Client ID to Application Name ====
 +
 
 +
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 <code>org.eclipse.userstorage.oauth.clients</code> extension point to describe the MPC app:
 +
<source lang="xml">
 +
  <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>
 +
</source>
 +
 
 +
==== Configure the OAuth Credentials Provider ====
 +
 
 +
The USS SDK's <code>EclipseOAuthCredentialsProvider</code> class is used to obtain authorization from the user for your application to work with their user data managed by the Eclipse Foundation.
 +
 
 +
=== Storing and Fetching Data with 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
 
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 <tt>org.eclipse.userstorage.accounts</tt>.  This menu has the following format:
 +
<pre>
 +
<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`
 +
</pre>
 +
For example, the Marketplace Client adds an item to open the MPC on the user's favourites:
 +
<source lang="xml">
 +
  <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>
 +
</source>
  
 
== Projects Using USS ==
 
== Projects Using USS ==
 
* Oomph: allowing users to save their preferences to the USS for persistence across workspaces on different computers and/or virtual boxes.  
 
* 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.
 
* Marketplace Client (MPC): (planned) to store user favorites to the USS.

Revision as of 13:30, 29 May 2017

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.

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. An Eclipse project must apply to the Eclipse Webmaster for their unique ID and secret. The OAuth specification describes a work flow to prompt the user to authorize the Eclipse project, to obtain an access code. This access code must be provided when accessing the USS.

Using the USS SDK

The USS SDK is a library that simplifies accessing the USS. An Eclipse project must configure the

Configuring the USS SDK

There are steps for configuring the USS SDK:

 1. Provide the client ID to application name mapping
 2. Configure the USS OAuth Credentials Provider

Map Client ID to Application Name

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>

Configure 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.

Storing and Fetching Data with 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.

Back to the top