GDataOAuth2Authorizer

GDataOAuth2Authorizer — GData OAuth 2.0 authorization interface

Stability Level

Stable, unless otherwise indicated

Properties

gchar * client-id Read / Write / Construct Only
gchar * client-secret Read / Write / Construct Only
gchar * locale Read / Write
GProxyResolver * proxy-resolver Read / Write
gchar * redirect-uri Read / Write / Construct Only
gchar * refresh-token Read / Write
guint timeout Read / Write

Object Hierarchy

    GObject
    ╰── GDataOAuth2Authorizer

Implemented Interfaces

GDataOAuth2Authorizer implements GDataAuthorizer.

Includes

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

Description

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

OAuth 2.0

process, which is Google’s currently preferred authentication and authorization process.

OAuth 2.0 replaces the deprecated OAuth 1.0 and ClientLogin processes. 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 2.0 process as implemented by Google follows the

OAuth 2.0 protocol as specified by IETF in RFC 6749, with a few additions to

support scopes (implemented in libgdata by GDataAuthorizationDomains), locales and custom domains. Briefly, the process is initiated by building an authentication URI (using gdata_oauth2_authorizer_build_authentication_uri()) and opening it in the user’s web browser. The user authenticates and authorizes the requested scopes on Google’s website, then an authorization code is returned (via “redirect-uri”) to the application, which then converts the code into an access and refresh token (using gdata_oauth2_authorizer_request_authorization()). The access token is then attached to all future requests to the online service, and the refresh token can be used in future (with gdata_authorizer_refresh_authorization()) to refresh authorization after the access token expires.

The refresh token may also be accessed as “refresh-token” and saved by the application. It may later be set on a new instance of GDataOAuth2Authorizer, and gdata_authorizer_refresh_authorization_async() called to establish a new access token without requiring the user to re-authenticate unless they have explicitly revoked the refresh token.

For an overview of the standard OAuth 2.0 flow, see

RFC 6749.

Before an application can be authorized using OAuth 2.0, it must be registered with

Google’s Developer Console, and a client ID, client secret and redirect URI

retrieved. These must be built into your application, and knowledge of them will allow any application to impersonate yours, so it is recommended that they are kept secret (e.g. as a configure-time option).

libgdata supports

incremental authorization, where multiple GDataOAuth2Authorizers can be used to

incrementally build up authorizations against multiple scopes. Typically, you should use one GDataOAuth2Authorizer per GDataService your application uses, limit the scope of each authorizer, and enable incremental authorization when calling gdata_oauth2_authorizer_build_authentication_uri().

Each access token is long lived, so reauthorization is rarely necessary with GDataOAuth2Authorizer. It is supported using gdata_authorizer_refresh_authorization().

Example 9. Authenticating Asynchronously Using OAuth 2.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
GDataSomeService *service;
GDataOAuth2Authorizer *authorizer;
gchar *authentication_uri, *authorization_code;

/* Create an authorizer and authenticate and authorize the service we're using, asynchronously. */
authorizer = gdata_oauth2_authorizer_new ("some-client-id", "some-client-secret",
                                          GDATA_OAUTH2_REDIRECT_URI_OOB, GDATA_TYPE_SOME_SERVICE);
authentication_uri = gdata_oauth2_authorizer_build_authentication_uri (authorizer, NULL, FALSE);

/* (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 code Google gives them.) */
authorization_code = ask_user_for_code (authentication_uri);

gdata_oauth2_authorizer_request_authorization_async (authorizer, authorization_code, cancellable,
                                                     (GAsyncReadyCallback) request_authorization_cb, user_data);

g_free (authentication_uri);

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

g_free (authorization_code);

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

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

    if (gdata_oauth2_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_oauth2_authorizer_new ()

GDataOAuth2Authorizer *
gdata_oauth2_authorizer_new (const gchar *client_id,
                             const gchar *client_secret,
                             const gchar *redirect_uri,
                             GType service_type);

Creates a new GDataOAuth2Authorizer. The client_id must be unique for your application, and as registered with Google, and the client_secret must be paired with it.

Parameters

client_id

your application’s client ID

 

client_secret

your application’s client secret

 

redirect_uri

authorisation redirect URI

 

service_type

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

 

Returns

a new GDataOAuth2Authorizer; unref with g_object_unref().

[transfer full]

Since: 0.17.0


gdata_oauth2_authorizer_new_for_authorization_domains ()

GDataOAuth2Authorizer *
gdata_oauth2_authorizer_new_for_authorization_domains
                               (const gchar *client_id,
                                const gchar *client_secret,
                                const gchar *redirect_uri,
                                GList *authorization_domains);

Creates a new GDataOAuth2Authorizer. The client_id must be unique for your application, and as registered with Google, and the client_secret must be paired with it.

Parameters

client_id

your application’s client ID

 

client_secret

your application’s client secret

 

redirect_uri

authorisation redirect URI

 

authorization_domains

a non-empty list of GDataAuthorizationDomains to be authorized against by the GDataOAuth2Authorizer.

[element-type GDataAuthorizationDomain][transfer none]

Returns

a new GDataOAuth2Authorizer; unref with g_object_unref().

[transfer full]

Since: 0.17.0


gdata_oauth2_authorizer_build_authentication_uri ()

gchar *
gdata_oauth2_authorizer_build_authentication_uri
                               (GDataOAuth2Authorizer *self,
                                const gchar *login_hint,
                                gboolean include_granted_scopes);

Build an authentication URI to open in the user’s web browser (or an embedded browser widget). This will display an authentication page from Google, including an authentication form and confirmation of the authorisation domains being requested by this GDataAuthorizer. The user will authenticate in the browser, then an authorisation code will be returned via the “redirect-uri”, ready to be passed to gdata_oauth2_authorizer_request_authorization().

If login_hint is non-NULL, it will be passed to the server as a hint of which user is attempting to authenticate, which can be used to pre-fill the e-mail address box in the authentication form.

If include_granted_scopes is TRUE, the authentication request will automatically include all authorisation domains previously granted to this user/application pair, allowing for incremental authentication — asking for permissions as needed, rather than all in one large bundle at the first opportunity. If include_granted_scopes is FALSE, incremental authentication will not be enabled, and only the domains passed to the GDataOAuth2Authorizer constructor will eventually be authenticated. See the

reference documentation for more details.

Parameters

self

a GDataOAuth2Authorizer

 

login_hint

optional e-mail address or sub identifier for the user.

[nullable]

include_granted_scopes

TRUE to enable incremental authorisation

 

Returns

the authentication URI to open in a web browser; free with g_free().

[transfer full]

Since: 0.17.0


gdata_oauth2_authorizer_request_authorization ()

gboolean
gdata_oauth2_authorizer_request_authorization
                               (GDataOAuth2Authorizer *self,
                                const gchar *authorization_code,
                                GCancellable *cancellable,
                                GError **error);

Request an authorisation code from the user’s web browser is converted to authorisation (access and refresh) tokens. This is the final step in the authentication process; once complete, the GDataOAuth2Authorizer should be fully authorised for its domains.

On failure, GDATA_SERVICE_ERROR_FORBIDDEN will be returned if the user or server denied the authorisation request. GDATA_SERVICE_ERROR_PROTOCOL_ERROR will be returned if the server didn’t follow the expected protocol. G_IO_ERROR_CANCELLED will be returned if the operation was cancelled using cancellable .

Parameters

self

a GDataOAuth2Authorizer

 

authorization_code

code returned from the authentication page

 

cancellable

a GCancellable, or NULL.

[allow-none]

error

return location for a GError, or NULL

 

Returns

TRUE on success, FALSE otherwise

Since: 0.17.0


gdata_oauth2_authorizer_request_authorization_async ()

void
gdata_oauth2_authorizer_request_authorization_async
                               (GDataOAuth2Authorizer *self,
                                const gchar *authorization_code,
                                GCancellable *cancellable,
                                GAsyncReadyCallback callback,
                                gpointer user_data);

Asynchronous version of gdata_oauth2_authorizer_request_authorization().

Parameters

self

a GDataOAuth2Authorizer

 

authorization_code

code returned 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.17.0


gdata_oauth2_authorizer_request_authorization_finish ()

gboolean
gdata_oauth2_authorizer_request_authorization_finish
                               (GDataOAuth2Authorizer *self,
                                GAsyncResult *async_result,
                                GError **error);

Finishes an asynchronous authorization operation started with gdata_oauth2_authorizer_request_authorization_async().

Parameters

self

a GDataOAuth2Authorizer

 

async_result

a GAsyncResult

 

error

a GError, or NULL

 

Returns

TRUE if authorization was successful, FALSE otherwise

Since: 0.17.0


gdata_oauth2_authorizer_get_client_id ()

const gchar *
gdata_oauth2_authorizer_get_client_id (GDataOAuth2Authorizer *self);

Returns the authorizer's client ID, “client-id”, as specified on constructing the GDataOAuth2Authorizer.

Parameters

Returns

the authorizer's client ID

Since: 0.17.0


gdata_oauth2_authorizer_get_redirect_uri ()

const gchar *
gdata_oauth2_authorizer_get_redirect_uri
                               (GDataOAuth2Authorizer *self);

Returns the authorizer’s redirect URI, “redirect-uri”, as specified on constructing the GDataOAuth2Authorizer.

Parameters

Returns

the authorizer’s redirect URI

Since: 0.17.0


gdata_oauth2_authorizer_get_client_secret ()

const gchar *
gdata_oauth2_authorizer_get_client_secret
                               (GDataOAuth2Authorizer *self);

Returns the authorizer's client secret, “client-secret”, as specified on constructing the GDataOAuth2Authorizer.

Parameters

Returns

the authorizer's client secret

Since: 0.17.0


gdata_oauth2_authorizer_dup_refresh_token ()

gchar *
gdata_oauth2_authorizer_dup_refresh_token
                               (GDataOAuth2Authorizer *self);

Returns the authorizer's refresh token, “refresh-token”, as set by client code previously on the GDataOAuth2Authorizer, or as returned by the most recent authentication operation.

Parameters

Returns

the authorizer's refresh token.

[transfer full]

Since: 0.17.2


gdata_oauth2_authorizer_set_refresh_token ()

void
gdata_oauth2_authorizer_set_refresh_token
                               (GDataOAuth2Authorizer *self,
                                const gchar *refresh_token);

Sets the authorizer's refresh token, “refresh-token”. This is used to periodically refresh the access token. Set it to NULL to clear the current authentication from the authorizer.

Parameters

self

a GDataOAuth2Authorizer

 

refresh_token

the new refresh token, or NULL to clear authorization.

[nullable]

Since: 0.17.2


gdata_oauth2_authorizer_get_locale ()

const gchar *
gdata_oauth2_authorizer_get_locale (GDataOAuth2Authorizer *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.17.0


gdata_oauth2_authorizer_set_locale ()

void
gdata_oauth2_authorizer_set_locale (GDataOAuth2Authorizer *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_oauth2_authorizer_build_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 GDataOAuth2Authorizer

 

locale

the new locale in UNIX locale format, or NULL for the default locale.

[allow-none]

Since: 0.17.0


gdata_oauth2_authorizer_get_timeout ()

guint
gdata_oauth2_authorizer_get_timeout (GDataOAuth2Authorizer *self);

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

Parameters

Returns

the timeout, or 0

Since: 0.17.0


gdata_oauth2_authorizer_set_timeout ()

void
gdata_oauth2_authorizer_set_timeout (GDataOAuth2Authorizer *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 GDataOAuth2Authorizer

 

timeout

the timeout, or 0

 

Since: 0.17.0


gdata_oauth2_authorizer_get_proxy_resolver ()

GProxyResolver *
gdata_oauth2_authorizer_get_proxy_resolver
                               (GDataOAuth2Authorizer *self);

Gets the GProxyResolver on the GDataOAuth2Authorizer's SoupSession.

Parameters

Returns

a GProxyResolver, or NULL.

[transfer none][allow-none]

Since: 0.17.0


gdata_oauth2_authorizer_set_proxy_resolver ()

void
gdata_oauth2_authorizer_set_proxy_resolver
                               (GDataOAuth2Authorizer *self,
                                GProxyResolver *proxy_resolver);

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

Parameters

self

a GDataOAuth2Authorizer

 

proxy_resolver

a GProxyResolver, or NULL.

[allow-none]

Since: 0.17.0

Types and Values

GDATA_OAUTH2_REDIRECT_URI_OOB

#define GDATA_OAUTH2_REDIRECT_URI_OOB "urn:ietf:wg:oauth:2.0:oob"

OAuth 2 redirect URI for out-of-band authorisation code transfer, where the user is shown the authorisation code and asked to copy it.

See

reference documentation for details.

Since: 0.17.0


GDATA_OAUTH2_REDIRECT_URI_OOB_AUTO

#define GDATA_OAUTH2_REDIRECT_URI_OOB_AUTO "urn:ietf:wg:oauth:2.0:oob:auto"

OAuth 2 redirect URI for out-of-band authorisation code transfer, where the user is not shown the authorisation code or asked to copy it.

See

reference documentation for details.

Since: 0.17.0


GDataOAuth2Authorizer

typedef struct _GDataOAuth2Authorizer GDataOAuth2Authorizer;

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

Since: 0.17.0


GDataOAuth2AuthorizerClass

typedef struct {
} GDataOAuth2AuthorizerClass;

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

Since: 0.17.0

Property Details

The “client-id” property

  “client-id”                gchar *

A client ID for your application (see the

reference documentation).

It is recommended that the ID is of the form company name- application name- version ID.

Flags: Read / Write / Construct Only

Default value: NULL

Since: 0.17.0


The “client-secret” property

  “client-secret”            gchar *

Client secret provided by Google. This is unique for each application and is accessible from Google’s Developer Console when registering an application. It must be paired with the “client-id”.

See the

reference documentation for details.

Flags: Read / Write / Construct Only

Default value: NULL

Since: 0.17.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_oauth2_authorizer_build_authentication_uri().

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

Flags: Read / Write

Default value: NULL

Since: 0.17.0


The “proxy-resolver” property

  “proxy-resolver”           GProxyResolver *

The GProxyResolver used to determine a proxy URI.

Flags: Read / Write

Since: 0.17.0


The “redirect-uri” property

  “redirect-uri”             gchar *

Redirect URI to send the response from the authorisation request to. This must either be GDATA_OAUTH2_REDIRECT_URI_OOB, GDATA_OAUTH2_REDIRECT_URI_OOB_AUTO, or a

http://localhost URI with any port number (optionally)

specified.

This URI is where the authorisation server will redirect the user after they have completed interacting with the authentication page (gdata_oauth2_authorizer_build_authentication_uri()). If it is GDATA_OAUTH2_REDIRECT_URI_OOB, a page will be returned in the user’s browser with the authorisation code in its title and also embedded in the page for the user to copy if it is not possible to automatically extract the code from the page title. If it is GDATA_OAUTH2_REDIRECT_URI_OOB_AUTO, a similar page will be returned with the authorisation code in its title, but without displaying the code to the user — the user will simply be asked to close the page. If it is a localhost URI, the authentication page will redirect to that URI with the authorisation code appended as a code query parameter. If the user denies the authentication request, the authentication page will redirect to that URI with

error=access_denied appended as a query parameter.

Note that the redirect URI used must match that registered in Google’s Developer Console for your application.

See the reference documentation for details about choosing a redirect URI.

Flags: Read / Write / Construct Only

Default value: NULL

Since: 0.17.0


The “refresh-token” property

  “refresh-token”            gchar *

The server provided refresh token, which can be stored and passed in to new GDataOAuth2Authorizer instances before calling gdata_authorizer_refresh_authorization_async() to create a new short-lived access token.

The refresh token is opaque data and must not be parsed.

Flags: Read / Write

Default value: NULL

Since: 0.17.2


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