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

char * | client-id | Read / Write / Construct Only
char * | client-secret | Read / Write / Construct Only
char * | locale | Read / Write
GProxyResolver * | proxy-resolver | Read / Write
char * | redirect-uri | Read / Write / Construct Only
char * | 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

    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

self | a GDataOAuth2Authorizer |

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

self | a GDataOAuth2Authorizer |

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

self | a GDataOAuth2Authorizer |

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

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”                char *

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

Owner: GDataOAuth2Authorizer

Flags: Read / Write / Construct Only

Default value: NULL

Since: 0.17.0

### The `“client-secret”` property

      “client-secret”            char *

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.

Owner: GDataOAuth2Authorizer

Flags: Read / Write / Construct Only

Default value: NULL

Since: 0.17.0

### The `“locale”` property

      “locale”                   char *

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.

Owner: GDataOAuth2Authorizer

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.

Owner: GDataOAuth2Authorizer

Flags: Read / Write

Since: 0.17.0

### The `“redirect-uri”` property

      “redirect-uri”             char *

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.

Owner: GDataOAuth2Authorizer

Flags: Read / Write / Construct Only

Default value: NULL

Since: 0.17.0

### The `“refresh-token”` property

      “refresh-token”            char *

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.

Owner: GDataOAuth2Authorizer

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.

Owner: GDataOAuth2Authorizer

Flags: Read / Write

Default value: 0

Since: 0.17.0