GDataOAuth1Authorizer

GDataOAuth1Authorizer — GData OAuth 1.0 authorization interface

Stability Level

Stable, unless otherwise indicated

Functions

Properties

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

Types and Values

Object Hierarchy

    GObject
    ╰── GDataOAuth1Authorizer

Implemented Interfaces

GDataOAuth1Authorizer implements GDataAuthorizer.

Includes

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

Description

GDataOAuth1Authorizer provides an implementation of the GDataAuthorizer interface for authentication and authorization using the

OAuth 1.0 process,

which was preferred by Google until OAuth 2.0 was released — it is now preferred to use GDataOAuth2Authorizer.

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 8. 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);

Functions

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.

Parameters

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.

Parameters

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

Parameters

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.

Parameters

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

Parameters

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.

Parameters

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.

Parameters

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().

Parameters

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”.

Parameters

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.

Parameters

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.

Parameters

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);

gdata_oauth1_authorizer_get_proxy_uri has been deprecated since version 0.15.0 and should not be used in newly-written code.

Use gdata_oauth1_authorizer_get_proxy_resolver() instead, which gives more flexibility over the proxy used.

Gets the proxy URI on the GDataOAuth1Authorizer's SoupSession.

Parameters

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);

gdata_oauth1_authorizer_set_proxy_uri has been deprecated since version 0.15.0 and should not be used in newly-written code.

Use gdata_oauth1_authorizer_set_proxy_resolver() instead, which gives more flexibility over the proxy used.

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.

Parameters

self

a GDataOAuth1Authorizer

 

proxy_uri

the proxy URI, or NULL.

[allow-none]

Since: 0.9.0


gdata_oauth1_authorizer_get_proxy_resolver ()

GProxyResolver *
gdata_oauth1_authorizer_get_proxy_resolver
                               (GDataOAuth1Authorizer *self);

gdata_oauth1_authorizer_get_proxy_resolver is deprecated and should not be used in newly-written code.

Gets the GProxyResolver on the GDataOAuth1Authorizer's SoupSession.

Parameters

Returns

a GProxyResolver, or NULL.

[transfer none][allow-none]

Since: 0.15.0


gdata_oauth1_authorizer_set_proxy_resolver ()

void
gdata_oauth1_authorizer_set_proxy_resolver
                               (GDataOAuth1Authorizer *self,
                                GProxyResolver *proxy_resolver);

Sets the GProxyResolver on the SoupSession used internally by the given GDataOAuth1Authorizer.

Setting this will clear the “proxy-uri” property.

Parameters

self

a GDataOAuth1Authorizer

 

proxy_resolver

a GProxyResolver, or NULL.

[allow-none]

Since: 0.15.0


gdata_oauth1_authorizer_get_timeout ()

guint
gdata_oauth1_authorizer_get_timeout (GDataOAuth1Authorizer *self);

Gets the “timeout” property; the network timeout, in seconds.

Parameters

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.

Parameters

self

a GDataOAuth1Authorizer

 

timeout

the timeout, or 0

 

Since: 0.9.0

Types and Values

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

Property Details

The “application-name” property

  “application-name”         gchar *

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”.

Flags: Read / Write / Construct Only

Default value: NULL

Since: 0.9.0


The “locale” property

  “locale”                   gchar *

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.

Flags: Read / Write

Default value: NULL

Since: 0.9.0


The “proxy-resolver” property

  “proxy-resolver”           GProxyResolver *

The GProxyResolver used to determine a proxy URI. Setting this will clear the “proxy-uri” property.

Flags: Read / Write

Since: 0.15.0


The “proxy-uri” property

  “proxy-uri”                SoupURI *

The proxy URI used internally for all network requests.

GDataOAuth1Authorizer:proxy-uri has been deprecated since version 0.15.0 and should not be used in newly-written code.

Use “proxy-resolver” instead, which gives more flexibility over the proxy used.

Flags: Read / Write

Since: 0.9.0


The “timeout” property

  “timeout”                  guint

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.

Flags: Read / Write

Default value: 0

Since: 0.9.0