From 0ce5e2ab84baec752dc4b42629595bf1a0f326ec Mon Sep 17 00:00:00 2001 From: Alexander Kanavin Date: Wed, 28 Aug 2013 19:45:02 +0300 Subject: [PATCH] docs: add a gSSO examples chapter --- docs/reference/examples.xml | 162 ++++++++++++++++++++++++ docs/reference/libgsignon-glib-docs.xml | 1 + 2 files changed, 163 insertions(+) create mode 100644 docs/reference/examples.xml diff --git a/docs/reference/examples.xml b/docs/reference/examples.xml new file mode 100644 index 0000000..830d8f6 --- /dev/null +++ b/docs/reference/examples.xml @@ -0,0 +1,162 @@ + + + + + gSSO usage examples + + + + Introduction + + libgsignond-glib comes with an example application gsso-example + that demonstrates the most common use cases: listing available authentication methods and + their mechanisms, creating and removing identities and performing authentication + sessions. + + + Before running the example application, make sure that gSSO daemon and + gSSO UI (that is appropriate for your system) are installed and configured + correctly. + + + The source code for the example application is available at + + http://code.google.com/p/accounts-sso/source/browse/examples/gsso-example.c?repo=libgsignon-glib&name=master + + + The full list of available gsso-example options can be + obtained with gsso-example --help-all + + + + + Authentication methods and mechanisms + + The list of available authentication methods can be obtained with + --query-methods: + +> gsso-example --query-methods: +Available authentication methods: + password + oauth + digest + + + + For each of the available authentication methods it's possible to query + available authentication mechanisms with + gsso-example --query-mechanisms=method: + +> gsso-example --query-mechanisms=oauth +Available authentication mechanisms for method oauth: + oauth1 + oauth2 + + + + + + Identity management + + The list of stored identities that the gsso-example application is allowed + to use can be obtained with gsso-example --query-identities: + +> gsso-example --query-identities +Available identities: + id=27 caption='My test identity' + id=28 caption='Another test identity' + + + + To create an identity, use --create-identity option + with identity caption (user-readable name) and --identity-method + with the authentication method that the identity will be using. + +> gsso-example --create-identity="My test identity" --identity-method=password +Identity stored with id 28 + + + + To remove an identity, use --remove-identity option + with identity id: + +> gsso-example --remove-identity=28 +Identity removed + + + + + Using 'password' authentication method + + 'password' authentication simply returns to the application the username + and the password associated with an identity. If they haven't been stored + in gSSO secret database, they're asked from the user through gSSO UI. + + + To use the method, first create an identity with authentication method + set to 'password' (as shown above), note its identitiy id and then run: + +> gsso-example --get-password=27 +Geting password +Got response: {'UserName': <'megauser'>, 'Secret': <'megapassword'>} + + + + + Using 'oauth' authentication method + + 'oauth' authentication method is used to obtain an OAuth1 or OAuth2 + authentication token from a remote service over HTTP. An application + needs to supply a few service-specific parameters when initiating the + authentication. gSSO example application supports obtaining an oauth + token from Google service (google-specific parameters are hardcoded + into the app source code). + + + Obtaining an OAuth token may also include authorization of the application + by the user, which is done through user interaction with the service webpages + that are shown by gSSO UI. From the application point of view this authorization + happens completely transparently behind the scenes. + + + Before trying the example, if you're behind a proxy, and are using + the Gtk-based gSSO UI, make sure that your GNOME proxy settings are + correctly configured, either via GNOME UI, or via command line: + +> gsettings list-recursively org.gnome.system.proxy + + To set the proxy, use: + +> gsettings set org.gnome.system.proxy mode 'manual' +> gsettings set org.gnome.system.proxy.http port 8080 +> gsettings set org.gnome.system.proxy.http host 'myproxy.domain.lan' + + To disable the proxy, use + +> gsettings set org.gnome.system.proxy mode 'none' + + See all available configurations keys here: + + http://developer.gnome.org/ProxyConfiguration/ + + + You would also need a client identifier and key from Google. Instructions + about how to get them are available at + https://developers.google.com/console/help/#generatingoauth2 + + + Once the above are settled, create an identity with 'oauth' method + (as shown above) and issue: + +> gsso-example --get-google-token=12 --client-id=xxxxxxx.apps.googleusercontent.com --client-secret=yyyyyyyyyyyyy +Geting token +Got response: {'Scope': <'email'>, 'AccessToken': <'tokenvalue'>, + 'TokenParameters': <@a{sv} {}>, 'TokenType': <'Bearer'>, + 'RefreshToken': <'refreshtokenvalue'>, 'Duration': <int64 3600>, + 'Timestamp': <int64 1377707888>} + + + + \ No newline at end of file diff --git a/docs/reference/libgsignon-glib-docs.xml b/docs/reference/libgsignon-glib-docs.xml index 1685173..bdc2300 100644 --- a/docs/reference/libgsignon-glib-docs.xml +++ b/docs/reference/libgsignon-glib-docs.xml @@ -24,6 +24,7 @@ GLib applications. + -- 2.34.1