Merge lp:~nataliabidart/ubuntu/natty/ubuntu-sso-client/ubuntu-sso-client-1.1.7 into lp:ubuntu/natty/ubuntu-sso-client

[Natalia Bidart]

  * New upstream release.
    [ Natalia B. Bidart <email address hidden> ]
       * Avoid generating an extra token when attempting to validate a user
         account (LP: #687523).
       * Documented CredentialsManagement interface (LP: #673054).

=== modified file 'PKG-INFO'
--- PKG-INFO	2010-11-30 13:21:17 +0000
+++ PKG-INFO	2010-12-16 17:45:45 +0000
@@ -1,6 +1,6 @@
 Metadata-Version: 1.1
 Name: ubuntu-sso-client
-Version: 1.1.5
+Version: 1.1.7
 Summary: Ubuntu Single Sign-On client
 Home-page: https://launchpad.net/ubuntu-sso-client
 Author: Natalia Bidart

=== modified file 'README'
--- README	2010-06-16 15:11:04 +0000
+++ README	2010-12-16 17:45:45 +0000
@@ -1,1 +1,213 @@
-This is the Ubuntu Single Sign-On client.
+= 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 ==

=== modified file 'debian/changelog'
--- debian/changelog	2010-12-09 11:53:18 +0000
+++ debian/changelog	2010-12-16 17:45:45 +0000
@@ -1,3 +1,14 @@
+ubuntu-sso-client (1.1.7-0ubuntu1) UNRELEASED; urgency=low
+
+  * New upstream release.
+
+    [ Natalia B. Bidart <[e-mail]> ]
+       * Avoid generating an extra token when attempting to validate a user
+         account (LP: #687523).
+       * Documented CredentialsManagement interface (LP: #673054).
+
+ -- Natalia Bidart (nessita) <[e-mail]>  Thu, 16 Dec 2010 13:32:36 -0300
+
 ubuntu-sso-client (1.1.5-0ubuntu2) natty; urgency=low
 
   * No change rebuild with the new python

=== modified file 'setup.py'
--- setup.py	2010-11-30 13:21:17 +0000
+++ setup.py	2010-12-16 17:45:45 +0000
@@ -87,7 +87,7 @@
 
 DistUtilsExtra.auto.setup(
     name='ubuntu-sso-client',
-    version='1.1.5',
+    version='1.1.7',
     license='GPL v3',
     author='Natalia Bidart',
     author_email='[e-mail]',

=== modified file 'ubuntu_sso/account.py'
--- ubuntu_sso/account.py	2010-11-30 13:21:17 +0000
+++ ubuntu_sso/account.py	2010-12-16 17:45:45 +0000
@@ -172,12 +172,10 @@
                      'token_name: %r', credentials['consumer_key'], token_name)
         return credentials
 
-    def is_validated(self, email, password, token_name, sso_service=None):
+    def is_validated(self, token, sso_service=None):
         """Return if user with 'email' and 'password' is validated."""
+        logger.debug('is_validated: requesting accounts.me() info.')
         if sso_service is None:
-            token = self.login(email=email, password=password,
-                               token_name=token_name)
-
             oauth_token = oauth.OAuthToken(token['token'],
                                            token['token_secret'])
             authorizer = OAuthAuthorizer(token['consumer_key'],
@@ -189,8 +187,8 @@
         key = 'preferred_email'
         result = key in me_info and me_info[key] != None
 
-        logger.debug('is_validated: email: %r token_name: %r, result: %r.',
-                     email, token_name, result)
+        logger.info('is_validated: consumer_key: %r, result: %r.',
+                    token['consumer_key'], result)
         return result
 
     def validate_email(self, email, password, email_token, token_name):

=== modified file 'ubuntu_sso/main.py'
--- ubuntu_sso/main.py	2010-11-30 13:21:17 +0000
+++ ubuntu_sso/main.py	2010-12-16 17:45:45 +0000
@@ -192,9 +192,7 @@
 
         def success_cb(app_name, credentials):
             """Login finished successfull."""
-            token_name = get_token_name(app_name)
-            is_validated = self.processor.is_validated(email, password,
-                                                       token_name)
+            is_validated = self.processor.is_validated(credentials)
             logger.debug('user is validated? %r.', is_validated)
             if is_validated:
                 # pylint: disable=E1101

=== modified file 'ubuntu_sso/tests/test_account.py'
--- ubuntu_sso/tests/test_account.py	2010-11-30 13:21:17 +0000
+++ ubuntu_sso/tests/test_account.py	2010-12-16 17:45:45 +0000
@@ -249,7 +249,7 @@
 
     def test_is_validated(self):
         """If preferred email is not None, user is validated."""
-        result = self.processor.is_validated(**self.login_kwargs)
+        result = self.processor.is_validated(token=TOKEN)
         self.assertTrue(result, 'user must be validated.')
 
     def test_is_not_validated(self):
@@ -257,7 +257,7 @@
         service = FakedSSOServer(None, None)
         service.accounts.preferred_email = None
         result = self.processor.is_validated(sso_service=service,
-                                             **self.login_kwargs)
+                                             token=TOKEN)
         self.assertFalse(result, 'user must not be validated.')
 
     def test_is_not_validated_empty_result(self):
@@ -265,7 +265,7 @@
         service = FakedSSOServer(None, None)
         service.accounts.me = lambda: {}
         result = self.processor.is_validated(sso_service=service,
-                                             **self.login_kwargs)
+                                             token=TOKEN)
         self.assertFalse(result, 'user must not be validated.')
 
     # validate_email

=== modified file 'ubuntu_sso/tests/test_main.py'
--- ubuntu_sso/tests/test_main.py	2010-11-30 13:21:17 +0000
+++ ubuntu_sso/tests/test_main.py	2010-12-16 17:45:45 +0000
@@ -210,7 +210,7 @@
         processor = self.create_mock_processor()
         processor.login(EMAIL, PASSWORD, TOKEN_NAME)
         self.mocker.result(TOKEN)
-        processor.is_validated(EMAIL, PASSWORD, TOKEN_NAME)
+        processor.is_validated(TOKEN)
         self.mocker.result(True)
         self.patch(ubuntu_sso.main, "blocking", fake_ok_blocking)
         self.mocker.replay()
@@ -236,7 +236,7 @@
         processor = self.create_mock_processor()
         processor.login(EMAIL, PASSWORD, TOKEN_NAME)
         self.mocker.result(TOKEN)
-        processor.is_validated(EMAIL, PASSWORD, TOKEN_NAME)
+        processor.is_validated(TOKEN)
         self.mocker.result(False)
         self.patch(ubuntu_sso.main, "blocking", fake_ok_blocking)
         self.mocker.replay()