DO NOT REMOVE, this is updated!

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