GoaOAuth2Provider

## GoaOAuth2Provider GoaOAuth2Provider — Abstract base class for OAuth 2.0 providers |

## Synopsis

    struct              GoaOAuth2Provider;
    struct              GoaOAuth2ProviderClass;
    const gchar *       goa_oauth2_provider_get_authentication_cookie
                                                            (GoaOAuth2Provider *provider);
    const gchar *       goa_oauth2_provider_get_authorization_uri
                                                            (GoaOAuth2Provider *provider);
    const gchar *       goa_oauth2_provider_get_token_uri   (GoaOAuth2Provider *provider);
    const gchar *       goa_oauth2_provider_get_redirect_uri
                                                            (GoaOAuth2Provider *provider);
    const gchar *       goa_oauth2_provider_get_scope       (GoaOAuth2Provider *provider);
    const gchar *       goa_oauth2_provider_get_client_id   (GoaOAuth2Provider *provider);
    const gchar *       goa_oauth2_provider_get_client_secret
                                                            (GoaOAuth2Provider *provider);
    gboolean            goa_oauth2_provider_get_use_mobile_browser
                                                            (GoaOAuth2Provider *provider);
    gboolean            goa_oauth2_provider_is_deny_node    (GoaOAuth2Provider *provider,
                                                             WebKitDOMNode *node);
    gboolean            goa_oauth2_provider_is_identity_node
                                                            (GoaOAuth2Provider *provider,
                                                             WebKitDOMHTMLInputElement *element);
    gboolean            goa_oauth2_provider_is_password_node
                                                            (GoaOAuth2Provider *provider,
                                                             WebKitDOMHTMLInputElement *element);
    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);
    gboolean            goa_oauth2_provider_get_use_external_browser
                                                            (GoaOAuth2Provider *provider);
    void                goa_oauth2_provider_add_account_key_values
                                                            (GoaOAuth2Provider *provider,
                                                             GVariantBuilder *builder);
    gchar *             goa_oauth2_provider_get_identity_sync
                                                            (GoaOAuth2Provider *provider,
                                                             const gchar *access_token,
                                                             gchar **out_presentation_identity,
                                                             GCancellable *cancellable,
                                                             GError **error);
    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);
    gboolean            goa_oauth2_provider_process_redirect_url
                                                            (GoaOAuth2Provider *provider,
                                                             const gchar *redirect_url,
                                                             gchar **authorization_code,
                                                             GError **error);

## Object Hierarchy

      GObject
       +----GoaProvider
             +----GoaOAuth2Provider
                   +----GoaGoogleProvider
                   +----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..

## Details

### struct GoaOAuth2Provider

    struct 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_redirect_uri)             (GoaOAuth2Provider            *provider);
      const gchar *(*get_client_id)                (GoaOAuth2Provider            *provider);
      const gchar *(*get_client_secret)            (GoaOAuth2Provider            *provider);
      const gchar *(*get_authentication_cookie)    (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);
      const gchar *(*get_token_uri)                (GoaOAuth2Provider            *provider);
      const gchar *(*get_scope)                    (GoaOAuth2Provider            *provider);
      gboolean     (*get_use_external_browser)     (GoaOAuth2Provider            *provider);
      gboolean     (*get_use_mobile_browser)       (GoaOAuth2Provider            *provider);
      void         (*add_account_key_values)       (GoaOAuth2Provider            *provider,
                                                    GVariantBuilder              *builder);

      /* pure virtual */
      gboolean     (*is_deny_node)                 (GoaOAuth2Provider            *provider,
                                                    WebKitDOMNode                *node);
      gboolean     (*is_identity_node)             (GoaOAuth2Provider            *provider,
                                                    WebKitDOMHTMLInputElement    *element);

      /* virtual but with default implementation */
      gboolean     (*is_password_node)             (GoaOAuth2Provider            *provider,
                                                    WebKitDOMHTMLInputElement    *element);

      gboolean     (*process_redirect_url)         (GoaOAuth2Provider            *provider,
                                                    const gchar                  *redirect_url,
                                                    gchar                       **access_token,
                                                    GError                      **error);
    };

Class structure for GoaOAuth2Provider.

GoaProviderClass `parent_class`; | The parent class.
`get_authorization_uri` () | Virtual function for `goa_oauth2_provider_get_authorization_uri()`.
`get_redirect_uri` () | Virtual function for `goa_oauth2_provider_get_redirect_uri()`.
`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_authentication_cookie` () | Virtual function for `goa_oauth2_provider_get_authentication_cookie()`.
`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_token_uri` () | Virtual function for `goa_oauth2_provider_get_token_uri()`.
`get_scope` () | Virtual function for `goa_oauth2_provider_get_scope()`.
`get_use_external_browser` () | Virtual function for `goa_oauth2_provider_get_use_external_browser()`.
`get_use_mobile_browser` () | Virtual function for `goa_oauth2_provider_get_use_mobile_browser()`.
`add_account_key_values` () | Virtual function for `goa_oauth2_provider_add_account_key_values()`.
`is_deny_node` () | Virtual function for `goa_oauth2_provider_is_deny_node()`.
`is_identity_node` () | Virtual function for `goa_oauth2_provider_is_identity_node()`.
`is_password_node` () | Virtual function for `goa_oauth2_provider_is_password_node()`.
`process_redirect_url` () | Virtual function for `goa_oauth2_provider_process_redirect_url()`.

### goa_oauth2_provider_get_authentication_cookie ()

    const gchar *       goa_oauth2_provider_get_authentication_cookie
                                                            (GoaOAuth2Provider *provider);

Gets the name of a cookie whose presence indicates that the user has been able to log in during the authorization step. This is used to modify the embedded web browser UI that is presented to the user.

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

`provider` : | A GoaOAuth2Provider.
Returns : | A string owned by `provider` - do not free. [transfer none]

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

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

A token URI is only needed when the OAuth2 provider does not support a separate client-side flow. In such cases, override GoaOAuth2ProviderClass.get_token_uri. You should not include any parameters in the returned URI.

This is a virtual method where the default implementation returns `NULL`.

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

`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 virtual method where the default implementation returns `NULL`.

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

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

`provider` : | A GoaOAuth2Provider.
Returns : | A string owned by `provider` - do not free. [transfer none]

### goa_oauth2_provider_get_use_mobile_browser ()

    gboolean            goa_oauth2_provider_get_use_mobile_browser
                                                            (GoaOAuth2Provider *provider);

Returns whether there is a need for the embedded browser to identify itself as running on a mobile phone in order to get a more compact version of the approval page.

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

`provider` : | A GoaOAuth2Provider.
Returns : | `TRUE` if the embedded browser should identify itself as running on a mobile platform, `FALSE` otherwise.

### goa_oauth2_provider_is_deny_node ()

    gboolean            goa_oauth2_provider_is_deny_node    (GoaOAuth2Provider *provider,
                                                             WebKitDOMNode *node);

Checks whether `node` is the HTML UI element that the user can use to deny permission to access his account. Usually they are either a WebKitDOMHTMLButtonElement or a WebKitDOMHTMLInputElement.

Please note that providers may have multiple such elements in their UI and this method should catch all of them.

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

`provider` : | A GoaOAuth2Provider.
`node` : | A WebKitDOMNode.
Returns : | `TRUE` if the `node` can be used to deny permission.

### goa_oauth2_provider_is_identity_node ()

    gboolean            goa_oauth2_provider_is_identity_node
                                                            (GoaOAuth2Provider *provider,
                                                             WebKitDOMHTMLInputElement *element);

Checks whether `element` is the HTML UI element that the user can use to identify herself at the provider.

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

`provider` : | A GoaOAuth2Provider.
`element` : | A WebKitDOMHTMLInputElement.
Returns : | `TRUE` if the `element` can be used to deny permission.

### goa_oauth2_provider_is_password_node ()

    gboolean            goa_oauth2_provider_is_password_node
                                                            (GoaOAuth2Provider *provider,
                                                             WebKitDOMHTMLInputElement *element);

Checks whether `element` is the HTML UI element that the user can use to enter her password. This can be used to offer a GoaPasswordBased interface by saving the user's password. Providers usually frown upon doing this, so this is not recommended.

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

`provider` : | A GoaOAuth2Provider.
`element` : | A WebKitDOMHTMLInputElement
Returns : | `TRUE` if `element` can be used to enter the password.

### 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=https`3A`%2F`2Fclient`%2Eexample`2Ecom`%2Fcb&client_id=foo&scope=email`20stuff``)

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

`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 or `NULL`. [allow-none]
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`.

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

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

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

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

### goa_oauth2_provider_process_redirect_url ()

    gboolean            goa_oauth2_provider_process_redirect_url
                                                            (GoaOAuth2Provider *provider,
                                                             const gchar *redirect_url,
                                                             gchar **authorization_code,
                                                             GError **error);

Certain OAuth2-like, but not exactly OAuth2, providers do not follow the standard mechanisms for extracting the access token or auth code from the redirect URI. They use some non-standard technique to do so. This is a provider specific hook to accommodate them and will only be used if implemented.

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

`provider` : | A GoaOAuth2Provider.
`redirect_url` : | A redirect URI from the web browser
`authorization_code` : | Return location for access token. [out]
`error` : | Return location for error or `NULL`
Returns : | `TRUE` if `provider` could process `redirect_url`, `FALSE` otherwise.