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 https://gitlab.com/accounts-sso/libgsignon-glib/blob/master/examples/gsso-example.c

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' ACL: (*:*)
        id=28 caption='Another test identity' ACL: (/usr/bin/gsso-example:)
        

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            
        

Depending on the identity method, you may also need to add a list of comma-separated realms that are allowed to be used with an identity. For example, the oauth method requires a list of domains that the OAuth authentication plugin is allowed to contact:


> gsso-example --create-identity="Test Google identity" --identity-method=oauth --identity-realms=google.com
Identity stored with id 29            
        

To remove an identity, use --remove-identity option with identity id:


> gsso-example --remove-identity=28
Identity removed
        

To add a security context to identity's Access Control List, use --add-context option with an identity id:


> gsso-example --add-context=28 --system-context=/path/to/executable --application-context=
Identity stored with id 28
        

/path/to/executable should be used if gsso is configured to use the default ACL extension, otherwise the system context value is defined by the extension that is in use.

To remove a security context from identity's Access Control List, use --remove-context= option with identity id:


> gsso-example --remove-context=28 --system-context=/path/to/executable --application-context=
Identity stored with id 28
        

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>}