~alecu/ubuntu-sso-client/changed-secrets-spec

= Ubuntu Single Sign-On Client =

ubuntu-sso-client is a desktop application that provides a D-Bus interface to
let other applications store and manage credentials in the local keyring.

When requesting a set of credentials for a given application, if those
credentials are not yet present on the user's keyring, the user is presented
with a GUI to either register a new account, or log in using an existing
account by means of the Ubuntu SSO web service.

Since version 1.1.5, this service does not depend on the gnome-keyring
service, but on any keyring service that implements the freedesktop secrets
specification (see
http://freedesktop.org/wiki/Specifications/secret-storage-spec for reference).

== ubuntu-sso-client D-Bus API ==

This section details the API that ubuntu-sso-client exposes through D-Bus. It
is available under the:

 * {{{com.ubuntu.sso}}} bus name, on the
 * {{{/com/ubuntu/sso/credentials}}} object path.

That object implements the {{{com.ubuntu.sso.CredentialsManagement}}}
interface, that has the methods and signals listed below. All of these  methods
are asynchronous, and return immediately with no value. Signal handlers are
required to handle results specially, where necessary.

They all return information to the caller through signals, since all the
operations (either against the keyring, or against the SSO web service) are
blocking, and so the Ubuntu SSO API is entirely asynchronous.

NOTE: formerly, the {{{ApplicationCredentials}}} interface was implemented
under the {{{/credentials}}} object path. That interface is deprecated and
should not be used. However, current applications using this interface will be
able to do so until the Ubuntu 11.04 release inclusive, since it won't be
removed it until 11.10.

=== com.ubuntu.sso.CredentialsManagement Methods ===

Any of these methods may emit the {{{CredentialsError}}} signal, with the
caller's "app_name" as the first parameter, and a dictionary with key and value
both as strings describing the error. See below for details about this signal.

==== find_credentials(String app_name, Dict of {String, String} extra_params) ====

Look for credentials on the user's keyring for "app_name". Currently, the
parameter "extra_params" is not used and an empty dict must be passed.

If credentials were found for "app_name", the signal {{{CredentialsFound}}} is
emitted with "app_name" and the corresponding credentials dict as the result.

If credentials were not found, the signal {{{CredentialsNotFound}}} is emitted
with "app_name" as the only parameter.

==== clear_credentials(String app_name, Dict of {String, String} extra_params) ====

Clear the credentials on the user's keyring for "app_name". Currently, the
parameter "extra_params" is not used and an empty dict should be passed.

This method always emits the signal {{{CredentialsCleared}}} with "app_name" as
only parameter (except on error when {{{CredentialsError}}} is emitted).

==== store_credentials(String app_name, Dict of {String, String} credentials) ====

Store the given set of 'credentials' on the user's keyring, for "app_name".
Second parameter 'credentials' must provide at least these 4 keys with valid
values:

 * 'token'
 * 'token_secret'
 * 'consumer_key'
 * 'consumer_secret'

If the credentials were successfully set for "app_name", the signal
{{{CredentialsStored}}} is emitted with "app_name" as the only parameter.

==== register(String app_name, Dict of {String, String} ui_settings) ====

This method will try to fetch the credentials from the user's keyring for
"app_name", and will emit the {{{CredentialsFound}}} signal if they are found.

If existing credentials are not found, it will open a graphical dialog to let
the user create a new account for "app_name", or login to an existing SSO
account. Once the user is successfully registered or logged in, the newly
acquired credentials for "app_name" will be stored in the keyring and will be
returned to the caller through the {{{CredentialsFound}}} signal.

 * 'app_name': will be displayed in the GUI header (so it should be human
 readable), plus it will be used to find/build/clear tokens. Special attention
 must be paid to this value since if it collides with some other app name,
 return signals may be misleading because the identifier is the application
 name.

The second parameter 'ui_settings' can contain any of the following (none is
required):

 * 'help_text': an explanatory text for the end-users, will be shown below the
 header in most of the registration process.

 * 'ping_url': an url to open after successful token retrieval. If defined, the
 email will be attached to the url and will be pinged with a OAuth-signed
 request (this is usually useful for server application to keep track of new
 tokens).

 * 'tc_url': the link to a Terms and Conditions web page. If defined, a
 checkbox to agree to the terms will be presented to the user, and will be
 required to be checked to continue the registration. Also, a link to the terms
 will be offered for browsing. If not defined, nothing will be shown.

 * 'window_id': an X11 window identifier to be used for
 gtk.gdk.set_transient_for, so the dialog is always shown above the specified
 parent window. Usually it is str(!GtkWidget.window.xid) for GTK callers. If
 not defined, no parent will be set.

Additionally, this 'ui_settings' can provide 2 extra keys to define which UI
module and UI class should be used in case the service needs to open a
graphical interface to the end user. These keys are:

 * 'ui_class': the name of a class that lives within 'ui_module' and that
 accepts proper parameters (TODO: document parameters). An example of this
 class can be seen at ubuntu_sso.gtk.gui.UbuntuSSOClientGUI.

 * 'ui_module': a string pointing to a python module that holds 'ui_class' in
 it, and is importable from the system PYTHONPATH.

==== login(String app_name, Dict of {String, String} ui_settings) ====

This method behaves like 'register' except that the graphical interface, if
shown to the user, will offer login only functionality.

So, it will try to fetch the credentials from the user's keyring for
"app_name", and will emit the {{{CredentialsFound}}} signal if found. If
existing credentials are not found, it will open a graphical dialog to let the
user log in into an existing SSO account. Once the user is successfully logged
in, the newly acquired credentials for "app_name" will be stored in the keyring
and will be returned to the caller through the {{{CredentialsFound}}} signal.

Options for parameters on 'ui_settings' match the one listed above for
'register', except that the 'tc_url' will not be used even if defined.

=== com.ubuntu.sso.CredentialsManagement Signals ===

The applications listening for this signals should make sure the app_name sent
as parameter for each signal matches the one they used for calling the methods
defined in the previous section. If the app_name does not match, then the
calling applications can safely assume those credentials or error messages are
meant for another application and just discard them.

==== CredentialsFound(String app_name, Dict of {String, String} credentials) ====

The credentials are returned when this signal is emitted. It means that the
credentials were either on the keyring, or that the login and/or register
process was successful and a set of credentials has been stored on the keyring. 

 * "app_name" is the application name as passed to the called method.

 * "credentials" is a dictionary that contains at least four keys with the
 token and consumer keys and secrets. The dictionary keys are named:

  * 'token'
  * 'token_secret'
  * 'consumer_key'
  * 'consumer_secret'

==== CredentialsNotFound(String app_name) ====

Emitted after 'find_credentials' was called and the credentials for "app_name"
were not found in the user's keyring.

 * "app_name" is the application name as passed to the called method.

==== AuthorizationDenied(String app_name) ====

Emitted when the user was presented with a graphical interface and s/he
canceled the request for login and/or register by clicking on a 'Cancel'
button before the process was completed.

 * "app_name" is the application name as passed to the called method.

==== CredentialsError(String app_name, Dict of {String, String} error_dict) ====

This signal is raised when there is any problem getting, setting or clearing
the credentials.

 * "app_name" is the application name as passed to the called method.

 * "error_dict" is a dictionary containing at least 2 fields:

  * "error_message" a simple message that can be shown to the user explaining
  the error (is not translated to any language).

  * "detailed_error" is a string containing a Python stacktrace or something
  similar to help the developers debug the problem. The application calling
  ubuntu-sso-client may choose to show it to the user using a !GtkExpander, or
  write it to a log file, etc.

==== CredentialsCleared(String app_name) ====

Emitted when the credentials for "app_name" were successfully removed from the
user's keyring. Note that if an application requested the removal of
non-existent credentials, this signals will be emitted if no error occurred.

 * "app_name" is the application name as passed to the called method.

==== CredentialsStored(String app_name) ====

Emitted when the credentials passed as the parameter to 'store_credentials'
were successfully stored.

 * "app_name" is the application name as passed to the called method.

== To be done: add API docs for accounts service ==