GoaOAuth2Provider

GoaOAuth2Provider — Abstract base class for OAuth 2.0 providers

Functions

Types and Values

Object Hierarchy

    GObject
    ╰── GoaProvider
        ╰── GoaOAuth2Provider
            ├── GoaFacebookProvider
            ╰── GoaWindowsLiveProvider

Description

GoaOAuth2Provider is an abstract base class for OAuth 2.0 based providers.

Subclasses must implement GoaOAuth2ProviderClass.get_authorization_uri, GoaOAuth2ProviderClass.get_token_uri, GoaOAuth2ProviderClass.get_redirect_uri, GoaOAuth2ProviderClass.get_scope, GoaOAuth2ProviderClass.get_client_id, GoaOAuth2ProviderClass.get_client_secret and GoaOAuth2ProviderClass.get_identity_sync methods.

Additionally, the GoaProviderClass.get_provider_type, GoaProviderClass.get_provider_name, GoaProviderClass.build_object (this should chain up to its parent class) methods must be implemented.

Note that the GoaProviderClass.add_account, GoaProviderClass.refresh_account and GoaProviderClass.ensure_credentials_sync methods do not need to be implemented - this type implements these methods..

Functions

goa_oauth2_provider_get_authorization_uri ()

const gchar *
goa_oauth2_provider_get_authorization_uri
                               (GoaOAuth2Provider *provider);

Gets the authorization endpoint used for authenticating the user and obtaining authorization.

You should not include any parameters in the returned URI. If you need to include additional parameters than the standard ones, override GoaOAuth2ProviderClass.build_authorization_uri - see goa_oauth2_provider_build_authorization_uri() for more details.

This is a pure virtual method - a subclass must provide an implementation.

Parameters

provider

A GoaOAuth2Provider.

 

Returns

A string owned by provider - do not free.

[transfer none]


goa_oauth2_provider_get_token_uri ()

const gchar *
goa_oauth2_provider_get_token_uri (GoaOAuth2Provider *provider);

Gets the token endpoint used for obtaining an access token.

You should not include any parameters in the returned URI.

This is a pure virtual method - a subclass must provide an implementation.

Parameters

provider

A GoaOAuth2Provider.

 

Returns

A string owned by provider - do not free.

[transfer none]


goa_oauth2_provider_get_redirect_uri ()

const gchar *
goa_oauth2_provider_get_redirect_uri (GoaOAuth2Provider *provider);

Gets the redirect_uri used when requesting authorization.

This is a pure virtual method - a subclass must provide an implementation.

Parameters

provider

A GoaOAuth2Provider.

 

Returns

A string owned by provider - do not free.

[transfer none]


goa_oauth2_provider_get_scope ()

const gchar *
goa_oauth2_provider_get_scope (GoaOAuth2Provider *provider);

Gets the scope used when requesting authorization.

This is a pure virtual method - a subclass must provide an implementation.

Parameters

provider

A GoaOAuth2Provider.

 

Returns

A string owned by provider - do not free.

[transfer none]


goa_oauth2_provider_get_client_id ()

const gchar *
goa_oauth2_provider_get_client_id (GoaOAuth2Provider *provider);

Gets the client_id identifying the client.

This is a pure virtual method - a subclass must provide an implementation.

Parameters

provider

A GoaOAuth2Provider.

 

Returns

A string owned by provider - do not free.

[transfer none]


goa_oauth2_provider_get_client_secret ()

const gchar *
goa_oauth2_provider_get_client_secret (GoaOAuth2Provider *provider);

Gets the client_secret associated with the client.

This is a pure virtual method - a subclass must provide an implementation.

Parameters

provider

A GoaOAuth2Provider.

 

Returns

A string owned by provider - do not free.

[transfer none]


goa_oauth2_provider_build_authorization_uri ()

gchar *
goa_oauth2_provider_build_authorization_uri
                               (GoaOAuth2Provider *provider,
                                const gchar *authorization_uri,
                                const gchar *escaped_redirect_uri,
                                const gchar *escaped_client_id,
                                const gchar *escaped_scope);

Builds the URI that can be opened in a web browser (or embedded web browser widget) to start authenticating an user.

The default implementation just returns the expected URI (e.g. http://example.com/dialog/oauth2?response_type=code&redirect_uri=https3A2F2Fclient2Eexample2Ecom2Fcb&client_id=foo&scope=email20stuff)

  • override (and chain up) if you e.g. need to to pass additional parameters.

The authorization_uri , escaped_redirect_uri , escaped_client_id and escaped_scope parameters originate from the result of the the goa_oauth2_provider_get_authorization_uri(), goa_oauth2_provider_get_redirect_uri(), goa_oauth2_provider_get_client_id() and goa_oauth2_provider_get_scope() methods with the latter three escaped using g_uri_escape_string().

Parameters

provider

A GoaOAuth2Provider.

 

authorization_uri

An authorization URI.

 

escaped_redirect_uri

An escaped redirect URI

 

escaped_client_id

An escaped client id

 

escaped_scope

The escaped scope.

 

Returns

An authorization URI that must be freed with g_free().

[transfer full]


goa_oauth2_provider_get_use_external_browser ()

gboolean
goa_oauth2_provider_get_use_external_browser
                               (GoaOAuth2Provider *provider);

Returns whether an external browser (the users default browser) should be used for user interaction.

If an external browser is used, then the dialogs presented in goa_provider_add_account() and goa_provider_refresh_account() will show a simple "Paste authorization code here" instructions along with an entry and button.

This is a virtual method where the default implementation returns FALSE.

Parameters

provider

A GoaOAuth2Provider.

 

Returns

TRUE if the user interaction should happen in an external browser, FALSE to use an embedded browser widget.


goa_oauth2_provider_add_account_key_values ()

void
goa_oauth2_provider_add_account_key_values
                               (GoaOAuth2Provider *provider,
                                GVariantBuilder *builder);

Hook for implementations to add key/value pairs to the key-file when creating an account.

This is a virtual method where the default implementation does nothing.

Parameters

provider

A GoaProvider.

 

builder

A GVariantBuilder for a a{ss} variant.

 

goa_oauth2_provider_get_identity_sync ()

gchar *
goa_oauth2_provider_get_identity_sync (GoaOAuth2Provider *provider,
                                       const gchar *access_token,
                                       gchar **out_presentation_identity,
                                       GCancellable *cancellable,
                                       GError **error);

Method that returns the identity corresponding to access_token .

The identity is needed because all authentication happens out of band. In addition to the identity, an implementation also returns a presentation identity that is more suitable for presentation (the identity could be a GUID for example).

The calling thread is blocked while the identity is obtained.

Parameters

provider

A GoaOAuth2Provider.

 

access_token

A valid OAuth 2.0 access token.

 

out_presentation_identity

Return location for presentation identity or NULL.

[out]

cancellable

A GCancellable or NULL.

[allow-none]

error

Return location for error or NULL.

 

Returns

The identity or NULL if error is set. The returned string must be freed with g_free().


goa_oauth2_provider_get_access_token_sync ()

gchar *
goa_oauth2_provider_get_access_token_sync
                               (GoaOAuth2Provider *provider,
                                GoaObject *object,
                                gboolean force_refresh,
                                gint *out_access_token_expires_in,
                                GCancellable *cancellable,
                                GError **error);

Synchronously gets an access token for object . The calling thread is blocked while the operation is pending.

The resulting token is typically read from the local cache so most of the time only a local roundtrip to the storage for the token cache (e.g. gnome-keyring-daemon) is needed. However, the operation may involve refreshing the token with the service provider so a full network round-trip may be needed.

Note that multiple calls are serialized to avoid multiple outstanding requests to the service provider.

This operation may fail if e.g. unable to refresh the credentials or if network connectivity is not available. Note that even if a token is returned, the returned token isn't guaranteed to work - use goa_provider_ensure_credentials_sync() if you need stronger guarantees.

Parameters

provider

A GoaOAuth2Provider.

 

object

A GoaObject.

 

force_refresh

If set to TRUE, forces a refresh of the access token, if possible.

 

out_access_token_expires_in

Return location for how many seconds the returned token is valid for (0 if unknown) or NULL.

[out]

cancellable

A GCancellable or NULL.

[allow-none]

error

Return location for error or NULL.

 

Returns

The access token or NULL if error is set. The returned string must be freed with g_free().

Types and Values

GoaOAuth2Provider

typedef struct _GoaOAuth2Provider GoaOAuth2Provider;

The GoaOAuth2Provider structure contains only private data and should only be accessed using the provided API.


struct GoaOAuth2ProviderClass

struct GoaOAuth2ProviderClass {
  GoaProviderClass parent_class;

  /* pure virtual */
  const gchar *(*get_authorization_uri)    (GoaOAuth2Provider  *provider);
  const gchar *(*get_token_uri)            (GoaOAuth2Provider  *provider);
  const gchar *(*get_redirect_uri)         (GoaOAuth2Provider  *provider);
  const gchar *(*get_scope)                (GoaOAuth2Provider  *provider);
  const gchar *(*get_client_id)            (GoaOAuth2Provider  *provider);
  const gchar *(*get_client_secret)        (GoaOAuth2Provider  *provider);
  gchar       *(*get_identity_sync)        (GoaOAuth2Provider  *provider,
                                            const gchar        *access_token,
                                            gchar             **out_presentation_identity,
                                            GCancellable       *cancellable,
                                            GError            **error);

  /* virtual but with default implementation */
  gchar       *(*build_authorization_uri)  (GoaOAuth2Provider  *provider,
                                            const gchar        *authorization_uri,
                                            const gchar        *escaped_redirect_uri,
                                            const gchar        *escaped_client_id,
                                            const gchar        *escaped_scope);
  gboolean     (*get_use_external_browser) (GoaOAuth2Provider  *provider);
  void         (*add_account_key_values)   (GoaOAuth2Provider  *provider,
                                            GVariantBuilder    *builder);
};

Class structure for GoaOAuth2Provider.

Members

GoaProviderClass parent_class;

The parent class.

 

get_authorization_uri ()

Virtual function for goa_oauth2_provider_get_authorization_uri().

 

get_token_uri ()

Virtual function for goa_oauth2_provider_get_token_uri().

 

get_redirect_uri ()

Virtual function for goa_oauth2_provider_get_redirect_uri().

 

get_scope ()

Virtual function for goa_oauth2_provider_get_scope().

 

get_client_id ()

Virtual function for goa_oauth2_provider_get_client_id().

 

get_client_secret ()

Virtual function for goa_oauth2_provider_get_client_secret().

 

get_identity_sync ()

Virtual function for goa_oauth2_provider_get_identity_sync().

 

build_authorization_uri ()

Virtual function for goa_oauth2_provider_build_authorization_uri().

 

get_use_external_browser ()

Virtual function for goa_oauth2_provider_get_use_external_browser().

 

add_account_key_values ()

Virtual function for goa_oauth2_provider_add_account_key_values().