docs/reference/html/gsso-examples.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html>
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
   5 <title>gSSO usage examples</title>
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
   7 <link rel="home" href="index.html" title="libgsignon-glib Reference Manual">
   8 <link rel="up" href="libgsignon-glib-overview.html" title="Part I. gSSO Overview">
   9 <link rel="prev" href="gsso-intro.html" title="gSSO introduction">
  10 <link rel="next" href="libgsignon-glib-objects.html" title="Part II. libgsignon-glib Objects">
  11 <meta name="generator" content="GTK-Doc V1.18 (XML mode)">
  12 <link rel="stylesheet" href="style.css" type="text/css">
  13 </head>
  14 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  15 <table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2"><tr valign="middle">
  16 <td><a accesskey="p" href="gsso-intro.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
  17 <td><a accesskey="u" href="libgsignon-glib-overview.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
  18 <td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
  19 <th width="100%" align="center">libgsignon-glib Reference Manual</th>
  20 <td><a accesskey="n" href="libgsignon-glib-objects.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
  21 </tr></table>
  22 <div class="refentry">
  23 <a name="gsso-examples"></a><div class="titlepage"></div>
  24 <div class="refsect1">
  25 <a name="intro"></a><h2>Introduction</h2>
  26 <p>
  27         libgsignond-glib comes with an example application <span class="application">gsso-example</span>
  28         that demonstrates the most common use cases: listing available authentication methods and
  29         their mechanisms, creating and removing identities and performing authentication
  30         sessions.
  31     </p>
  32 <p>
  33         Before running the example application, make sure that gSSO daemon and
  34         gSSO UI (that is appropriate for your system) are installed and configured
  35         correctly.
  36     </p>
  37 <p>
  38         The source code for the example application is available at
  39         <a class="ulink" href="http://code.google.com/p/accounts-sso/source/browse/examples/gsso-example.c?repo=libgsignon-glib&amp;name=master" target="_top">
  40             http://code.google.com/p/accounts-sso/source/browse/examples/gsso-example.c?repo=libgsignon-glib&amp;name=master</a>
  41      </p>
  42 <p>
  43          The full list of available <span class="application">gsso-example</span> options can be
  44          obtained with <strong class="userinput"><code>gsso-example --help-all</code></strong>
  45      </p>
  46 </div>
  47 <div class="refsect1">
  48 <a name="idp36034400"></a><h2>Authentication methods and mechanisms</h2>
  49 <p>
  50         The list of available authentication methods can be obtained with
  51         <strong class="userinput"><code>--query-methods</code></strong>:
  52         </p>
  53 <div class="literallayout"><p><code class="computeroutput"><br>
  54 <strong class="userinput"><code>&gt; gsso-example --query-methods</code></strong>:<br>
  55 Available authentication methods:<br>
  56         password<br>
  57         oauth<br>
  58         digest<br>
  59         </code></p></div>
  60 <p>
  61      </p>
  62 <p>
  63          For each of the available authentication methods it's possible to query
  64          available authentication mechanisms with
  65          <strong class="userinput"><code>gsso-example --query-mechanisms=method</code></strong>:
  66         </p>
  67 <div class="literallayout"><p><code class="computeroutput"><br>
  68 <strong class="userinput"><code>&gt; gsso-example --query-mechanisms=oauth</code></strong><br>
  69 Available authentication mechanisms for method oauth:<br>
  70         oauth1<br>
  71         oauth2<br>
  72         </code></p></div>
  73 <p>
  74      </p>
  75 </div>
  76 <div class="refsect1">
  77 <a name="idp35463792"></a><h2>Identity management</h2>
  78 <p>
  79         The list of stored identities that the gsso-example application is allowed
  80         to use can be obtained with <strong class="userinput"><code>gsso-example --query-identities</code></strong>:
  81         </p>
  82 <div class="literallayout"><p><code class="computeroutput"><br>
  83 <strong class="userinput"><code>&gt; gsso-example --query-identities</code></strong><br>
  84 Available identities:<br>
  85         id=27 caption='My test identity'<br>
  86         id=28 caption='Another test identity'<br>
  87         </code></p></div>
  88 <p>
  89     </p>
  90 <p>
  91         To create an identity, use <strong class="userinput"><code>--create-identity</code></strong> option
  92         with identity caption (user-readable name) and <strong class="userinput"><code>--identity-method</code></strong>
  93         with the authentication method that the identity will be using.
  94         </p>
  95 <div class="literallayout"><p><code class="computeroutput"><br>
  96 <strong class="userinput"><code>&gt; gsso-example --create-identity="My test identity" --identity-method=password</code></strong><br>
  97 Identity stored with id 28            <br>
  98         </code></p></div>
  99 <p>
 100     </p>
 101 <p>
 102         To remove an identity, use <strong class="userinput"><code>--remove-identity</code></strong> option
 103         with identity id:
 104         </p>
 105 <div class="literallayout"><p><code class="computeroutput"><br>
 106 <strong class="userinput"><code>&gt; gsso-example --remove-identity=28</code></strong><br>
 107 Identity removed<br>
 108         </code></p></div>
 109 <p>
 110     </p>
 111 </div>
 112 <div class="refsect1">
 113 <a name="idp34225360"></a><h2>Using 'password' authentication method</h2>
 114 <p>
 115         'password' authentication simply returns to the application the username
 116         and the password associated with an identity. If they haven't been stored
 117         in gSSO secret database, they're asked from the user through gSSO UI.
 118     </p>
 119 <p>
 120         To use the method, first create an identity with authentication method
 121         set to 'password' (as shown above), note its identitiy id and then run:
 122         </p>
 123 <div class="literallayout"><p><code class="computeroutput"><br>
 124 <strong class="userinput"><code>&gt; gsso-example --get-password=27</code></strong><br>
 125 Geting password<br>
 126 Got response: {'UserName': &lt;'megauser'&gt;, 'Secret': &lt;'megapassword'&gt;}<br>
 127         </code></p></div>
 128 <p>
 129     </p>
 130 </div>
 131 <div class="refsect1">
 132 <a name="idp34229760"></a><h2>Using 'oauth' authentication method</h2>
 133 <p>
 134         'oauth' authentication method is used to obtain an OAuth1 or OAuth2
 135         authentication token from a remote service over HTTP. An application
 136         needs to supply a few service-specific parameters when initiating the
 137         authentication. gSSO example application supports obtaining an oauth
 138         token from Google service (google-specific parameters are hardcoded
 139         into the app source code).
 140     </p>
 141 <p>
 142         Obtaining an OAuth token may also include authorization of the application
 143         by the user, which is done through user interaction with the service webpages
 144         that are shown by gSSO UI. From the application point of view this authorization
 145         happens completely transparently behind the scenes.
 146     </p>
 147 <p>
 148         Before trying the example, if you're behind a proxy, and are using
 149         the Gtk-based gSSO UI, make sure that your GNOME proxy settings are
 150         correctly configured, either via GNOME UI, or via command line:
 151         </p>
 152 <div class="literallayout"><p><code class="computeroutput"><br>
 153 <strong class="userinput"><code>&gt; gsettings list-recursively org.gnome.system.proxy</code></strong><br>
 154         </code></p></div>
 155 <p>
 156         To set the proxy, use:
 157         </p>
 158 <div class="literallayout"><p><code class="computeroutput"><br>
 159 <strong class="userinput"><code>&gt; gsettings set org.gnome.system.proxy mode 'manual'<br>
 160 &gt; gsettings set org.gnome.system.proxy.http port 8080<br>
 161 &gt; gsettings set org.gnome.system.proxy.http host 'myproxy.domain.lan'</code></strong><br>
 162         </code></p></div>
 163 <p>
 164         To disable the proxy, use
 165         </p>
 166 <div class="literallayout"><p><code class="computeroutput"><br>
 167 <strong class="userinput"><code>&gt; gsettings set org.gnome.system.proxy mode 'none'</code></strong><br>
 168         </code></p></div>
 169 <p>
 170         See all available configurations keys here:
 171         <a class="ulink" href="http://developer.gnome.org/ProxyConfiguration/" target="_top">
 172         http://developer.gnome.org/ProxyConfiguration/</a>
 173     </p>
 174 <p>
 175         You would also need a client identifier and key from Google. Instructions
 176         about how to get them are available at
 177         <a class="ulink" href="https://developers.google.com/console/help/#generatingoauth2" target="_top">https://developers.google.com/console/help/#generatingoauth2</a>
 178     </p>
 179 <p>
 180         Once the above are settled, create an identity with 'oauth' method
 181         (as shown above) and issue:
 182         </p>
 183 <div class="literallayout"><p><code class="computeroutput"><br>
 184 <strong class="userinput"><code>&gt; gsso-example --get-google-token=12 --client-id=xxxxxxx.apps.googleusercontent.com --client-secret=yyyyyyyyyyyyy</code></strong><br>
 185 Geting token<br>
 186 Got response: {'Scope': &lt;'email'&gt;, 'AccessToken': &lt;'tokenvalue'&gt;, <br>
 187                'TokenParameters': &lt;@a{sv} {}&gt;, 'TokenType': &lt;'Bearer'&gt;, <br>
 188                'RefreshToken': &lt;'refreshtokenvalue'&gt;, 'Duration': &lt;int64 3600&gt;, <br>
 189                'Timestamp': &lt;int64 1377707888&gt;}                <br>
 190         </code></p></div>
 191 <p>
 192     </p>
 193 </div>
 194 </div>
 195 <div class="footer">
 196 <hr>
 197           Generated by GTK-Doc V1.18</div>
 198 </body>
 199 </html>