GDataOAuth1Authorizer

GDataOAuth1Authorizer — GData OAuth 1.0 authorization interface

Stability Level

Unstable, unless otherwise indicated

Synopsis

#include <gdata/gdata-oauth1-authorizer.h>

                    GDataOAuth1Authorizer;
                    GDataOAuth1AuthorizerClass;
GDataOAuth1Authorizer * gdata_oauth1_authorizer_new     (const gchar *application_name,
                                                         GType service_type);
GDataOAuth1Authorizer * gdata_oauth1_authorizer_new_for_authorization_domains
                                                        (const gchar *application_name,
                                                         GList *authorization_domains);
gchar *             gdata_oauth1_authorizer_request_authentication_uri
                                                        (GDataOAuth1Authorizer *self,
                                                         gchar **token,
                                                         gchar **token_secret,
                                                         GCancellable *cancellable,
                                                         GError **error);
void                gdata_oauth1_authorizer_request_authentication_uri_async
                                                        (GDataOAuth1Authorizer *self,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
gchar *             gdata_oauth1_authorizer_request_authentication_uri_finish
                                                        (GDataOAuth1Authorizer *self,
                                                         GAsyncResult *async_result,
                                                         gchar **token,
                                                         gchar **token_secret,
                                                         GError **error);
gboolean            gdata_oauth1_authorizer_request_authorization
                                                        (GDataOAuth1Authorizer *self,
                                                         const gchar *token,
                                                         const gchar *token_secret,
                                                         const gchar *verifier,
                                                         GCancellable *cancellable,
                                                         GError **error);
void                gdata_oauth1_authorizer_request_authorization_async
                                                        (GDataOAuth1Authorizer *self,
                                                         const gchar *token,
                                                         const gchar *token_secret,
                                                         const gchar *verifier,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
gboolean            gdata_oauth1_authorizer_request_authorization_finish
                                                        (GDataOAuth1Authorizer *self,
                                                         GAsyncResult *async_result,
                                                         GError **error);
const gchar *       gdata_oauth1_authorizer_get_application_name
                                                        (GDataOAuth1Authorizer *self);
const gchar *       gdata_oauth1_authorizer_get_locale  (GDataOAuth1Authorizer *self);
void                gdata_oauth1_authorizer_set_locale  (GDataOAuth1Authorizer *self,
                                                         const gchar *locale);
SoupURI *           gdata_oauth1_authorizer_get_proxy_uri
                                                        (GDataOAuth1Authorizer *self);
void                gdata_oauth1_authorizer_set_proxy_uri
                                                        (GDataOAuth1Authorizer *self,
                                                         SoupURI *proxy_uri);
guint               gdata_oauth1_authorizer_get_timeout (GDataOAuth1Authorizer *self);
void                gdata_oauth1_authorizer_set_timeout (GDataOAuth1Authorizer *self,
                                                         guint timeout);

Object Hierarchy

  GObject
   +----GDataOAuth1Authorizer

Implemented Interfaces

GDataOAuth1Authorizer implements GDataAuthorizer.

Properties

  "application-name"         gchar*                : Read / Write / Construct Only
  "locale"                   gchar*                : Read / Write
  "proxy-uri"                SoupURI*              : Read / Write
  "timeout"                  guint                 : Read / Write

Description

GDataOAuth1Authorizer provides an implementation of the GDataAuthorizer interface for authentication and authorization using the OAuth 1.0 process, which is Google's currently preferred authentication and authorization process, though OAuth 2.0 will be transitioned to in future.

OAuth 1.0 replaces the deprecated ClientLogin process. One of the main reasons for this is to allow two-factor authentication to be supported, by moving the authentication interface to a web page under Google's control.

The OAuth 1.0 process as implemented by Google follows the OAuth 1.0 protocol as specified by IETF in RFC 5849, with a few additions to support scopes (implemented in libgdata by GDataAuthorizationDomains), locales and custom domains. Briefly, the process is initiated by requesting an authenticated request token from the Google accounts service (using gdata_oauth1_authorizer_request_authentication_uri()), going to the authentication URI for the request token, authenticating and authorizing access to the desired scopes, then providing the verifier returned by Google to the Google accounts service again (using gdata_oauth1_authorizer_request_authorization()) to authorize the token. This results in an access token which is attached to all future requests to the online service.

While Google supports unregistered and registered modes for OAuth 1.0 authorization, it only supports unregistered mode for installed applications. Consequently, libgdata also only supports unregistered mode. For this purpose, the application name to be presented to the user on the authentication page at the URI returned by gdata_oauth1_authorizer_request_authentication_uri() can be specified when constructing the GDataOAuth1Authorizer.

As described, each authentication/authorization operation is in two parts: gdata_oauth1_authorizer_request_authentication_uri() and gdata_oauth1_authorizer_request_authorization(). GDataOAuth1Authorizer stores no state about ongoing authentication operations (i.e. ones which have successfully called gdata_oauth1_authorizer_request_authentication_uri(), but are yet to successfully call gdata_oauth1_authorizer_request_authorization()). Consequently, operations can be abandoned before calling gdata_oauth1_authorizer_request_authorization() without problems. The only state necessary between the calls is the request token and request token secret, as returned by gdata_oauth1_authorizer_request_authentication_uri() and taken as parameters to gdata_oauth1_authorizer_request_authorization().

GDataOAuth1Authorizer natively supports authorization against multiple services in a single authorization request (unlike GDataClientLoginAuthorizer).

Each access token is long lived, so reauthorization is rarely necessary with GDataOAuth1Authorizer. Consequently, refreshing authorization using gdata_authorizer_refresh_authorization() is not supported by GDataOAuth1Authorizer, and will immediately return FALSE with no error set.

Example 5. Authenticating Asynchronously Using OAuth 1.0

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
GDataSomeService *service;
GDataOAuth1Authorizer *authorizer;

/* Create an authorizer and authenticate and authorize the service we're using, asynchronously. */
authorizer = gdata_oauth1_authorizer_new (_("My libgdata application"), GDATA_TYPE_SOME_SERVICE);
gdata_oauth1_authorizer_request_authentication_uri_async (authorizer, cancellable,
                                                          (GAsyncReadyCallback) request_authentication_uri_cb, user_data);

/* Create a service object and link it with the authorizer */
service = gdata_some_service_new (GDATA_AUTHORIZER (authorizer));

static void
request_authentication_uri_cb (GDataOAuth1Authorizer *authorizer, GAsyncResult *async_result, gpointer user_data)
{
    gchar *authentication_uri, *token, *token_secret, *verifier;
    GError *error = NULL;

    authentication_uri = gdata_oauth1_authorizer_request_authentication_uri_finish (authorizer, async_result, &token, &token_secret,
                                                                                    &error);

    if (error != NULL) {
        /* Notify the user of all errors except cancellation errors */
        if (!g_error_matches (error, G_IO_ERROR, G_IO_ERROR_CANCELLED)) {
            g_error ("Requesting a token failed: %s", error->message);
        }

        g_error_free (error);
        goto finish;
    }

    /* (Present the page at the authentication URI to the user, either in an embedded or stand-alone web browser, and
     * ask them to grant access to the application and return the verifier Google gives them.) */
    verifier = ask_user_for_verifier (authentication_uri);

    gdata_oauth1_authorizer_request_authorization_async (authorizer, token, token_secret, verifier, cancellable,
                                                         (GAsyncReadyCallback) request_authorization_cb, user_data);

finish:
    g_free (verifier);
    g_free (authentication_uri);
    g_free (token);

    /* Zero out the secret before freeing. */
    if (token_secret != NULL) {
        memset (token_secret, 0, strlen (token_secret));
    }

    g_free (token_secret);
}

static void
request_authorization_cb (GDataOAuth1Authorizer *authorizer, GAsyncResult *async_result, gpointer user_data)
{
    GError *error = NULL;

    if (gdata_oauth1_authorizer_request_authorization_finish (authorizer, async_result, &error) == FALSE) {
        /* Notify the user of all errors except cancellation errors */
        if (!g_error_matches (error, G_IO_ERROR, G_IO_ERROR_CANCELLED)) {
            g_error ("Authorization failed: %s", error->message);
        }

        g_error_free (error);
        return;
    }

    /* (The client is now authenticated and authorized against the service.
     * It can now proceed to execute queries on the service object which require the user to be authenticated.) */
}

g_object_unref (service);
g_object_unref (authorizer);


Details

GDataOAuth1Authorizer

typedef struct _GDataOAuth1Authorizer GDataOAuth1Authorizer;

All the fields in the GDataOAuth1Authorizer structure are private and should never be accessed directly.

Since 0.9.0


GDataOAuth1AuthorizerClass

typedef struct {
} GDataOAuth1AuthorizerClass;

All the fields in the GDataOAuth1AuthorizerClass structure are private and should never be accessed directly.

Since 0.9.0


gdata_oauth1_authorizer_new ()

GDataOAuth1Authorizer * gdata_oauth1_authorizer_new     (const gchar *application_name,
                                                         GType service_type);

Creates a new GDataOAuth1Authorizer.

The GDataAuthorizationDomains for the given service_type (i.e. as returned by gdata_service_get_authorization_domains()) are the ones the user will be requested to authorize access to on the page at the URI returned by gdata_oauth1_authorizer_request_authentication_uri().

The given application_name will set the value of "application-name" and will be displayed to the user on authentication pages returned by Google. If NULL is provided, the value of g_get_application_name() will be used as a fallback.

application_name :

a human-readable, translated application name to use on authentication pages, or NULL. [allow-none]

service_type :

the GType of a GDataService subclass which the GDataOAuth1Authorizer will be used with

Returns :

a new GDataOAuth1Authorizer; unref with g_object_unref(). [transfer full]

Since 0.9.0


gdata_oauth1_authorizer_new_for_authorization_domains ()

GDataOAuth1Authorizer * gdata_oauth1_authorizer_new_for_authorization_domains
                                                        (const gchar *application_name,
                                                         GList *authorization_domains);

Creates a new GDataOAuth1Authorizer. This function is intended to be used only when the default authorization domain list for a single GDataService, as used by gdata_oauth1_authorizer_new(), isn't suitable. For example, this could be because the GDataOAuth1Authorizer will be used with multiple GDataService subclasses, or because the client requires a specific set of authorization domains.

The specified GDataAuthorizationDomains are the ones the user will be requested to authorize access to on the page at the URI returned by gdata_oauth1_authorizer_request_authentication_uri().

The given application_name will set the value of "application-name" and will be displayed to the user on authentication pages returned by Google. If NULL is provided, the value of g_get_application_name() will be used as a fallback.

application_name :

a human-readable, translated application name to use on authentication pages, or NULL. [allow-none]

authorization_domains :

a non-empty list of GDataAuthorizationDomains to be authorized against by the GDataOAuth1Authorizer. [element-type GDataAuthorizationDomain][transfer none]

Returns :

a new GDataOAuth1Authorizer; unref with g_object_unref(). [transfer full]

Since 0.9.0


gdata_oauth1_authorizer_request_authentication_uri ()

gchar *             gdata_oauth1_authorizer_request_authentication_uri
                                                        (GDataOAuth1Authorizer *self,
                                                         gchar **token,
                                                         gchar **token_secret,
                                                         GCancellable *cancellable,
                                                         GError **error);

Requests a fresh unauthenticated token from the Google accounts service and builds and returns the URI of an authentication page for that token. This should then be presented to the user (e.g. in an embedded or stand alone web browser). The authentication page will ask the user to log in using their Google account, then ask them to grant access to the GDataAuthorizationDomains passed to the constructor of the GDataOAuth1Authorizer. If the user grants access, they will be given a verifier, which can then be passed to gdata_oauth1_authorizer_request_authorization() (along with the token and token_secret values returned by this method) to authorize the token.

This method can fail if the server returns an error, but this is unlikely. If it does happen, a GDATA_SERVICE_ERROR_PROTOCOL_ERROR will be raised, token and token_secret will be set to NULL and NULL will be returned.

This method implements Section 2.1 and Section 2.2 of the OAuth 1.0 protocol.

When freeing token_secret, it's advisable to set it to all zeros first, to reduce the chance of the sensitive token being recoverable from the free memory pool and (accidentally) leaked by a different part of the process. This can be achieved with the following code:

1
2
3
4
if (token_secret != NULL) {
    memset (token_secret, 0, strlen (token_secret));
    g_free (token_secret);
}

self :

a GDataOAuth1Authorizer

token :

return location for the temporary credentials token returned by the authentication service; free with g_free(). [out callee-allocates]

token_secret :

return location for the temporary credentials token secret returned by the authentication service; free with g_free(). [out callee-allocates]

cancellable :

optional GCancellable object, or NULL. [allow-none]

error :

a GError, or NULL

Returns :

the URI of an authentication page for the user to use; free with g_free(). [transfer full]

Since 0.9.0


gdata_oauth1_authorizer_request_authentication_uri_async ()

void                gdata_oauth1_authorizer_request_authentication_uri_async
                                                        (GDataOAuth1Authorizer *self,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);

Requests a fresh unauthenticated token from the Google accounts service and builds and returns the URI of an authentication page for that token. self is reffed when this method is called, so can safely be unreffed after this method returns.

For more details, see gdata_oauth1_authorizer_request_authentication_uri(), which is the synchronous version of this method.

When the operation is finished, callback will be called. You can then call gdata_oauth1_authorizer_request_authentication_uri_finish() to get the results of the operation.

self :

a GDataOAuth1Authorizer

cancellable :

optional GCancellable object, or NULL. [allow-none]

callback :

a GAsyncReadyCallback to call when building the URI is finished

user_data :

data to pass to the callback function. [closure]

Since 0.9.0


gdata_oauth1_authorizer_request_authentication_uri_finish ()

gchar *             gdata_oauth1_authorizer_request_authentication_uri_finish
                                                        (GDataOAuth1Authorizer *self,
                                                         GAsyncResult *async_result,
                                                         gchar **token,
                                                         gchar **token_secret,
                                                         GError **error);

Finishes an asynchronous authentication URI building operation started with gdata_oauth1_authorizer_request_authentication_uri_async().

This method can fail if the server has returned an error, but this is unlikely. If it does happen, a GDATA_SERVICE_ERROR_PROTOCOL_ERROR will be raised, token and token_secret will be set to NULL and NULL will be returned.

When freeing token_secret, it's advisable to set it to all zeros first, to reduce the chance of the sensitive token being recoverable from the free memory pool and (accidentally) leaked by a different part of the process. This can be achieved with the following code:

1
2
3
4
if (token_secret != NULL) {
    memset (token_secret, 0, strlen (token_secret));
    g_free (token_secret);
}

self :

a GDataOAuth1Authorizer

async_result :

a GAsyncResult

token :

return location for the temporary credentials token returned by the authentication service; free with g_free(). [out callee-allocates]

token_secret :

return location for the temporary credentials token secret returned by the authentication service; free with g_free(). [out callee-allocates]

error :

a GError, or NULL

Returns :

the URI of an authentication page for the user to use; free with g_free(). [transfer full]

Since 0.9.0


gdata_oauth1_authorizer_request_authorization ()

gboolean            gdata_oauth1_authorizer_request_authorization
                                                        (GDataOAuth1Authorizer *self,
                                                         const gchar *token,
                                                         const gchar *token_secret,
                                                         const gchar *verifier,
                                                         GCancellable *cancellable,
                                                         GError **error);

Requests authorization of the given request token from the Google accounts service using the given verifier as entered by the user from the authentication page at the URI returned by gdata_oauth1_authorizer_request_authentication_uri(). token and token_secret must be the same values as were returned by gdata_oauth1_authorizer_request_authentication_uri() if it was successful.

If the verifier is valid (i.e. the user granted access to the application and the Google accounts service has no reason to distrust the client), TRUE will be returned and any operations performed from that point onwards on GDataServices using this GDataAuthorizer will be authorized.

If the user denies access to the application or the Google accounts service distrusts it, a bogus verifier could be returned. In this case, FALSE will be returned and a GDATA_SERVICE_ERROR_FORBIDDEN error will be raised.

Note that if the user denies access to the application, it may be the case that they have no verifier to enter. In this case, the client can simply not call this method. The GDataOAuth1Authorizer stores no state for authentication operations which have succeeded in calling gdata_oauth1_authorizer_request_authentication_uri() but not yet successfully called gdata_oauth1_authorizer_request_authorization().

This method implements Section 2.3 of the OAuth 1.0 protocol.

self :

a GDataOAuth1Authorizer

token :

the request token returned by gdata_oauth1_authorizer_request_authentication_uri()

token_secret :

the request token secret returned by gdata_oauth1_authorizer_request_authentication_uri()

verifier :

the verifier entered by the user from the authentication page

cancellable :

optional GCancellable object, or NULL. [allow-none]

error :

a GError, or NULL

Returns :

TRUE if authorization was successful, FALSE otherwise

Since 0.9.0


gdata_oauth1_authorizer_request_authorization_async ()

void                gdata_oauth1_authorizer_request_authorization_async
                                                        (GDataOAuth1Authorizer *self,
                                                         const gchar *token,
                                                         const gchar *token_secret,
                                                         const gchar *verifier,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);

Requests authorization of the given request token from the Google accounts service using the given verifier as entered by the user. self, token, token_secret and verifier are reffed/copied when this method is called, so can safely be freed after this method returns.

For more details, see gdata_oauth1_authorizer_request_authorization(), which is the synchronous version of this method.

When the operation is finished, callback will be called. You can then call gdata_oauth1_authorizer_request_authorization_finish() to get the results of the operation.

self :

a GDataOAuth1Authorizer

token :

the request token returned by gdata_oauth1_authorizer_request_authentication_uri()

token_secret :

the request token secret returned by gdata_oauth1_authorizer_request_authentication_uri()

verifier :

the verifier entered by the user from the authentication page

cancellable :

an optional GCancellable, or NULL. [allow-none]

callback :

a GAsyncReadyCallback to call when authorization is finished

user_data :

data to pass to the callback function. [closure]

Since 0.9.0


gdata_oauth1_authorizer_request_authorization_finish ()

gboolean            gdata_oauth1_authorizer_request_authorization_finish
                                                        (GDataOAuth1Authorizer *self,
                                                         GAsyncResult *async_result,
                                                         GError **error);

Finishes an asynchronous authorization operation started with gdata_oauth1_authorizer_request_authorization_async().

self :

a GDataOAuth1Authorizer

async_result :

a GAsyncResult

error :

a GError, or NULL

Returns :

TRUE if authorization was successful, FALSE otherwise

Since 0.9.0


gdata_oauth1_authorizer_get_application_name ()

const gchar *       gdata_oauth1_authorizer_get_application_name
                                                        (GDataOAuth1Authorizer *self);

Returns the application name being used on the authentication page at the URI returned by gdata_oauth1_authorizer_request_authentication_uri(); i.e. the value of "application-name".

self :

a GDataOAuth1Authorizer

Returns :

the application name, or NULL if one isn't set. [allow-none]

Since 0.9.0


gdata_oauth1_authorizer_get_locale ()

const gchar *       gdata_oauth1_authorizer_get_locale  (GDataOAuth1Authorizer *self);

Returns the locale currently being used for network requests, or NULL if the locale is the default.

self :

a GDataOAuth1Authorizer

Returns :

the current locale. [allow-none]

Since 0.9.0


gdata_oauth1_authorizer_set_locale ()

void                gdata_oauth1_authorizer_set_locale  (GDataOAuth1Authorizer *self,
                                                         const gchar *locale);

Set the locale used for network requests to locale, given in standard Unix locale format. See "locale" for more details.

Note that while it's possible to change the locale after sending network requests (i.e. calling gdata_oauth1_authorizer_request_authentication_uri() for the first time), it is unsupported, as the server-side software may behave unexpectedly. The only supported use of this method is after creation of the authorizer, but before any network requests are made.

self :

a GDataOAuth1Authorizer

locale :

the new locale in Unix locale format, or NULL for the default locale. [allow-none]

Since 0.9.0


gdata_oauth1_authorizer_get_proxy_uri ()

SoupURI *           gdata_oauth1_authorizer_get_proxy_uri
                                                        (GDataOAuth1Authorizer *self);

Gets the proxy URI on the GDataOAuth1Authorizer's SoupSession.

self :

a GDataOAuth1Authorizer

Returns :

the proxy URI, or NULL; free with soup_uri_free(). [transfer full][allow-none]

Since 0.9.0


gdata_oauth1_authorizer_set_proxy_uri ()

void                gdata_oauth1_authorizer_set_proxy_uri
                                                        (GDataOAuth1Authorizer *self,
                                                         SoupURI *proxy_uri);

Sets the proxy URI on the SoupSession used internally by the GDataOAuth1Authorizer. This forces all requests through the given proxy.

If proxy_uri is NULL, no proxy will be used.

self :

a GDataOAuth1Authorizer

proxy_uri :

the proxy URI, or NULL. [allow-none]

Since 0.9.0


gdata_oauth1_authorizer_get_timeout ()

guint               gdata_oauth1_authorizer_get_timeout (GDataOAuth1Authorizer *self);

Gets the "timeout" property; the network timeout, in seconds.

self :

a GDataOAuth1Authorizer

Returns :

the timeout, or 0

Since 0.9.0


gdata_oauth1_authorizer_set_timeout ()

void                gdata_oauth1_authorizer_set_timeout (GDataOAuth1Authorizer *self,
                                                         guint timeout);

Sets the "timeout" property; the network timeout, in seconds.

If timeout is 0, network operations will never time out.

self :

a GDataOAuth1Authorizer

timeout :

the timeout, or 0

Since 0.9.0

Property Details

The "application-name" property

  "application-name"         gchar*                : Read / Write / Construct Only

The human-readable, translated application name for the client, to be presented to the user on the authentication page at the URI returned by gdata_oauth1_authorizer_request_authentication_uri().

If NULL is provided in the constructor to GDataOAuth1Authorizer, the value returned by g_get_application_name() will be used as a fallback. Note that this may also be NULL: in this case, the authentication page will use the application name “anonymous”.

Default value: NULL

Since 0.9.0


The "locale" property

  "locale"                   gchar*                : Read / Write

The locale to use for network requests, in Unix locale format. (e.g. "en_GB", "cs", "de_DE".) Use NULL for the default "C" locale (typically "en_US").

This locale will be used by the server-side software to localise the authentication and authorization pages at the URI returned by gdata_oauth1_authorizer_request_authentication_uri().

The server-side behaviour is undefined if it doesn't support a given locale.

Default value: NULL

Since 0.9.0


The "proxy-uri" property

  "proxy-uri"                SoupURI*              : Read / Write

The proxy URI used internally for all network requests.

Since 0.9.0


The "timeout" property

  "timeout"                  guint                 : Read / Write

A timeout, in seconds, for network operations. If the timeout is exceeded, the operation will be cancelled and GDATA_SERVICE_ERROR_NETWORK_ERROR will be returned.

If the timeout is 0, operations will never time out.

Default value: 0

Since 0.9.0