GDataOAuth2Authorizer: GData Reference Manual

GDataOAuth2Authorizer

GDataOAuth2Authorizer — GData OAuth 2.0 authorization interface

Stability Level

Stable, unless otherwise indicated

Functions

GDataOAuth2Authorizer *	gdata_oauth2_authorizer_new ()
GDataOAuth2Authorizer *	gdata_oauth2_authorizer_new_for_authorization_domains ()
gchar *	gdata_oauth2_authorizer_build_authentication_uri ()
gboolean	gdata_oauth2_authorizer_request_authorization ()
void	gdata_oauth2_authorizer_request_authorization_async ()
gboolean	gdata_oauth2_authorizer_request_authorization_finish ()
const gchar *	gdata_oauth2_authorizer_get_client_id ()
const gchar *	gdata_oauth2_authorizer_get_redirect_uri ()
const gchar *	gdata_oauth2_authorizer_get_client_secret ()
gchar *	gdata_oauth2_authorizer_dup_refresh_token ()
void	gdata_oauth2_authorizer_set_refresh_token ()
const gchar *	gdata_oauth2_authorizer_get_locale ()
void	gdata_oauth2_authorizer_set_locale ()
guint	gdata_oauth2_authorizer_get_timeout ()
void	gdata_oauth2_authorizer_set_timeout ()
GProxyResolver *	gdata_oauth2_authorizer_get_proxy_resolver ()
void	gdata_oauth2_authorizer_set_proxy_resolver ()

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

Types and Values

#define	GDATA_OAUTH2_REDIRECT_URI_OOB
#define	GDATA_OAUTH2_REDIRECT_URI_OOB_AUTO
	GDataOAuth2Authorizer
	GDataOAuth2AuthorizerClass

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

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

a GDataOAuth2Authorizer

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

self

a GDataOAuth2Authorizer

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

self

a GDataOAuth2Authorizer

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

self

a GDataOAuth2Authorizer

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

GDataOAuth2Authorizer

Stability Level

Functions

Properties

Types and Values

Object Hierarchy

Implemented Interfaces

Includes

Description

Functions

gdata_oauth2_authorizer_new ()

Parameters

Returns

gdata_oauth2_authorizer_new_for_authorization_domains ()

Parameters

Returns

gdata_oauth2_authorizer_build_authentication_uri ()

Parameters

Returns

gdata_oauth2_authorizer_request_authorization ()

Parameters

Returns

gdata_oauth2_authorizer_request_authorization_async ()

Parameters

gdata_oauth2_authorizer_request_authorization_finish ()

Parameters

Returns

gdata_oauth2_authorizer_get_client_id ()

Parameters

Returns

gdata_oauth2_authorizer_get_redirect_uri ()

Parameters

Returns

gdata_oauth2_authorizer_get_client_secret ()

Parameters

Returns

gdata_oauth2_authorizer_dup_refresh_token ()

Parameters

Returns

gdata_oauth2_authorizer_set_refresh_token ()

Parameters

gdata_oauth2_authorizer_get_locale ()

Parameters

Returns

gdata_oauth2_authorizer_set_locale ()

Parameters

gdata_oauth2_authorizer_get_timeout ()

Parameters

Returns

gdata_oauth2_authorizer_set_timeout ()

Parameters

gdata_oauth2_authorizer_get_proxy_resolver ()

Parameters

Returns

gdata_oauth2_authorizer_set_proxy_resolver ()

Parameters

Types and Values

GDATA_OAUTH2_REDIRECT_URI_OOB

GDATA_OAUTH2_REDIRECT_URI_OOB_AUTO

GDataOAuth2Authorizer

GDataOAuth2AuthorizerClass

Property Details

The “client-id” property

The “client-secret” property

The “locale” property

The “proxy-resolver” property

The “redirect-uri” property

The “refresh-token” property

The “timeout” property

The `“client-id”` property

The `“client-secret”` property

The `“locale”` property

The `“proxy-resolver”` property

The `“redirect-uri”` property

The `“refresh-token”` property

The `“timeout”` property