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>libgsignon-glib Reference Manual: gSSO usage examples</title>
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.78.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.20 (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="10"><tr valign="middle">
  16 <td width="100%" align="left" class="shortcuts"></td>
  17 <td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td>
  18 <td><a accesskey="u" href="libgsignon-glib-overview.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td>
  19 <td><a accesskey="p" href="gsso-intro.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
  20 <td><a accesskey="n" href="libgsignon-glib-objects.html"><img src="right.png" width="16" height="16" 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="id-1.2.3.3"></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="id-1.2.3.4"></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' ACL: (*:*)<br>
  86         id=28 caption='Another test identity' ACL: (/usr/bin/gsso-example:)<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         Depending on the identity method, you may also need to add a list of comma-separated
 103         realms that are allowed to be used with an identity. For example, the oauth method
 104         requires a list of domains that the OAuth authentication plugin is allowed to contact:
 105         </p>
 106 <div class="literallayout"><p><code class="computeroutput"><br>
 107 <strong class="userinput"><code>&gt; gsso-example --create-identity="Test Google identity" --identity-method=oauth --identity-realms=google.com</code></strong><br>
 108 Identity stored with id 29            <br>
 109         </code></p></div>
 110 <p>
 111     </p>
 112 <p>
 113         To remove an identity, use <strong class="userinput"><code>--remove-identity</code></strong> option
 114         with identity id:
 115         </p>
 116 <div class="literallayout"><p><code class="computeroutput"><br>
 117 <strong class="userinput"><code>&gt; gsso-example --remove-identity=28</code></strong><br>
 118 Identity removed<br>
 119         </code></p></div>
 120 <p>
 121     </p>
 122 <p>
 123         To add security context to identity's Access Control List, use <strong class="userinput"><code>--add-context</code></strong> option
 124         with identity id:
 125         </p>
 126 <div class="literallayout"><p><code class="computeroutput"><br>
 127 <strong class="userinput"><code>&gt; gsso-example --add-context=28 --system-context=* --application-context=*</code></strong><br>
 128 Identity stored with id 28<br>
 129         </code></p></div>
 130 <p>
 131     </p>
 132 <p>
 133         To remove security context from identity's Access Control List, use <strong class="userinput"><code>--remove-context=</code></strong> option
 134         with identity id:
 135         </p>
 136 <div class="literallayout"><p><code class="computeroutput"><br>
 137 <strong class="userinput"><code>&gt; gsso-example --remove-context=28 --system-context=* --application-context=*</code></strong><br>
 138 Identity stored with id 28<br>
 139         </code></p></div>
 140 <p>
 141     </p>
 142 </div>
 143 <div class="refsect1">
 144 <a name="id-1.2.3.5"></a><h2>Using 'password' authentication method</h2>
 145 <p>
 146         'password' authentication simply returns to the application the username
 147         and the password associated with an identity. If they haven't been stored
 148         in gSSO secret database, they're asked from the user through gSSO UI.
 149     </p>
 150 <p>
 151         To use the method, first create an identity with authentication method
 152         set to 'password' (as shown above), note its identitiy id and then run:
 153         </p>
 154 <div class="literallayout"><p><code class="computeroutput"><br>
 155 <strong class="userinput"><code>&gt; gsso-example --get-password=27</code></strong><br>
 156 Geting password<br>
 157 Got response: {'UserName': &lt;'megauser'&gt;, 'Secret': &lt;'megapassword'&gt;}<br>
 158         </code></p></div>
 159 <p>
 160     </p>
 161 </div>
 162 <div class="refsect1">
 163 <a name="id-1.2.3.6"></a><h2>Using 'oauth' authentication method</h2>
 164 <p>
 165         'oauth' authentication method is used to obtain an OAuth1 or OAuth2
 166         authentication token from a remote service over HTTP. An application
 167         needs to supply a few service-specific parameters when initiating the
 168         authentication. gSSO example application supports obtaining an oauth
 169         token from Google service (google-specific parameters are hardcoded
 170         into the app source code).
 171     </p>
 172 <p>
 173         Obtaining an OAuth token may also include authorization of the application
 174         by the user, which is done through user interaction with the service webpages
 175         that are shown by gSSO UI. From the application point of view this authorization
 176         happens completely transparently behind the scenes.
 177     </p>
 178 <p>
 179         Before trying the example, if you're behind a proxy, and are using
 180         the Gtk-based gSSO UI, make sure that your GNOME proxy settings are
 181         correctly configured, either via GNOME UI, or via command line:
 182         </p>
 183 <div class="literallayout"><p><code class="computeroutput"><br>
 184 <strong class="userinput"><code>&gt; gsettings list-recursively org.gnome.system.proxy</code></strong><br>
 185         </code></p></div>
 186 <p>
 187         To set the proxy, use:
 188         </p>
 189 <div class="literallayout"><p><code class="computeroutput"><br>
 190 <strong class="userinput"><code>&gt; gsettings set org.gnome.system.proxy mode 'manual'<br>
 191 &gt; gsettings set org.gnome.system.proxy.http port 8080<br>
 192 &gt; gsettings set org.gnome.system.proxy.http host 'myproxy.domain.lan'</code></strong><br>
 193         </code></p></div>
 194 <p>
 195         To disable the proxy, use
 196         </p>
 197 <div class="literallayout"><p><code class="computeroutput"><br>
 198 <strong class="userinput"><code>&gt; gsettings set org.gnome.system.proxy mode 'none'</code></strong><br>
 199         </code></p></div>
 200 <p>
 201         See all available configurations keys here:
 202         <a class="ulink" href="http://developer.gnome.org/ProxyConfiguration/" target="_top">
 203         http://developer.gnome.org/ProxyConfiguration/</a>
 204     </p>
 205 <p>
 206         You would also need a client identifier and key from Google. Instructions
 207         about how to get them are available at
 208         <a class="ulink" href="https://developers.google.com/console/help/#generatingoauth2" target="_top">https://developers.google.com/console/help/#generatingoauth2</a>
 209     </p>
 210 <p>
 211         Once the above are settled, create an identity with 'oauth' method
 212         (as shown above) and issue:
 213         </p>
 214 <div class="literallayout"><p><code class="computeroutput"><br>
 215 <strong class="userinput"><code>&gt; gsso-example --get-google-token=12 --client-id=xxxxxxx.apps.googleusercontent.com --client-secret=yyyyyyyyyyyyy</code></strong><br>
 216 Geting token<br>
 217 Got response: {'Scope': &lt;'email'&gt;, 'AccessToken': &lt;'tokenvalue'&gt;, <br>
 218                'TokenParameters': &lt;@a{sv} {}&gt;, 'TokenType': &lt;'Bearer'&gt;, <br>
 219                'RefreshToken': &lt;'refreshtokenvalue'&gt;, 'Duration': &lt;int64 3600&gt;, <br>
 220                'Timestamp': &lt;int64 1377707888&gt;}                <br>
 221         </code></p></div>
 222 <p>
 223     </p>
 224 </div>
 225 </div>
 226 <div class="footer">
 227 <hr>
 228           Generated by GTK-Doc V1.20</div>
 229 </body>
 230 </html>