OAuth2Proxy

## OAuth2Proxy OAuth2Proxy |

## Synopsis

                        OAuth2Proxy;
    RestProxy *         oauth2_proxy_new                    (const char *client_id,
                                                             const char *auth_endpoint,
                                                             const gchar *url_format,
                                                             gboolean binding_required);
    RestProxy *         oauth2_proxy_new_with_token         (const char *client_id,
                                                             const char *access_token,
                                                             const char *auth_endpoint,
                                                             const gchar *url_format,
                                                             gboolean binding_required);
    char *              oauth2_proxy_build_login_url_full   (OAuth2Proxy *proxy,
                                                             const char *redirect_uri,
                                                             GHashTable *extra_params);
    char *              oauth2_proxy_build_login_url        (OAuth2Proxy *proxy,
                                                             const char *redirect_uri);
    const char *        oauth2_proxy_get_access_token       (OAuth2Proxy *proxy);
    void                oauth2_proxy_set_access_token       (OAuth2Proxy *proxy,
                                                             const char *access_token);
    char *              oauth2_proxy_extract_access_token   (const char *url);

## Object Hierarchy

      GObject
       +----RestProxy
             +----OAuth2Proxy

## Properties

      "access-token"             gchar*                : Read / Write
      "auth-endpoint"            gchar*                : Read / Write / Construct Only
      "client-id"                gchar*                : Read / Write / Construct Only

## Description

## Details

### OAuth2Proxy

    typedef struct _OAuth2Proxy OAuth2Proxy;

OAuth2Proxy has no publicly available members.

### oauth2_proxy_new ()

    RestProxy *         oauth2_proxy_new                    (const char *client_id,
                                                             const char *auth_endpoint,
                                                             const gchar *url_format,
                                                             gboolean binding_required);

Create a new OAuth2Proxy for the specified endpoint `url_format`, using the specified API key and secret.

This proxy won't have the Token set so will be unauthorised. If the token is unknown then the following steps should be taken to acquire an access token: - Get the authentication url with `oauth2_proxy_build_login_url()` - Display this url in an embedded browser widget - wait for the browser widget to be redirected to the specified redirect_uri - extract the token from the fragment of the redirected uri (using convenience function `oauth2_proxy_extract_access_token()`) - set the token with `oauth2_proxy_set_access_token()`

Set `binding_required` to `TRUE` if the URL contains string formatting operations (for example "http://foo.com/%s". These must be expanded using `rest_proxy_bind()` before invoking the proxy.

`client_id` : | the client (application) id
`auth_endpoint` : | the authentication endpoint URL
`url_format` : | the endpoint URL
`binding_required` : | whether the URL needs to be bound before calling
Returns : | A new OAuth2Proxy.

### oauth2_proxy_new_with_token ()

    RestProxy *         oauth2_proxy_new_with_token         (const char *client_id,
                                                             const char *access_token,
                                                             const char *auth_endpoint,
                                                             const gchar *url_format,
                                                             gboolean binding_required);

Create a new OAuth2Proxy for the specified endpoint `url_format`, using the specified client id

`access_token` is used for the Access Token, so if they are still valid then this proxy is authorised.

Set `binding_required` to `TRUE` if the URL contains string formatting operations (for example "http://foo.com/%s". These must be expanded using `rest_proxy_bind()` before invoking the proxy.

`client_id` : | the client (application) id
`access_token` : | the Access Token
`auth_endpoint` : | the authentication endpoint URL
`url_format` : | the endpoint URL
`binding_required` : | whether the URL needs to be bound before calling
Returns : | A new OAuth2Proxy.

### oauth2_proxy_build_login_url_full ()

    char *              oauth2_proxy_build_login_url_full   (OAuth2Proxy *proxy,
                                                             const char *redirect_uri,
                                                             GHashTable *extra_params);

Builds a url at which the user can log in to the specified OAuth2-based web service. In general, this url should be displayed in an embedded browser widget, and you should then intercept the browser's redirect to `redirect_uri` and extract the access token from the url fragment. After the access token has been retrieved, call `oauth2_proxy_set_access_token()`. This must be done before making any API calls to the service.

See the oauth2 spec for more details about the "user-agent" authentication flow.

The `extra_params` and `redirect_uri` should not be uri-encoded, that will be done automatically

`proxy` : | a OAuth2Proxy object
`redirect_uri` : | the uri to redirect to after the user authenticates
`extra_params` : | any extra parameters to add to the login url (e.g. facebook uses 'scope=foo,bar' to request extended permissions).
Returns : | a newly allocated uri string

### oauth2_proxy_build_login_url ()

    char *              oauth2_proxy_build_login_url        (OAuth2Proxy *proxy,
                                                             const char *redirect_uri);

Builds a url at which the user can log in to the specified OAuth2-based web service. See the documentation for `oauth2_proxy_build_login_url_full()` for detailed information.

`proxy` : | an OAuth2Proxy object
`redirect_uri` : | the uri to redirect to after the user authenticates
Returns : | a newly allocated uri string

### oauth2_proxy_get_access_token ()

    const char *        oauth2_proxy_get_access_token       (OAuth2Proxy *proxy);

Get the current request or access token.

`proxy` : | an OAuth2Proxy
Returns : | the token, or `NULL` if there is no token yet. This string is owned by OAuth2Proxy and should not be freed.

### oauth2_proxy_set_access_token ()

    void                oauth2_proxy_set_access_token       (OAuth2Proxy *proxy,
                                                             const char *access_token);

Set the access token.

`proxy` : | an OAuth2Proxy
`access_token` : | the access token

### oauth2_proxy_extract_access_token ()

    char *              oauth2_proxy_extract_access_token   (const char *url);

A utility function to extract the access token from the url that results from the redirection after the user authenticates

`url` : | the url which contains an access token in its fragment

## Property Details

### The `"access-token"` property

      "access-token"             gchar*                : Read / Write

The request or access token.

Default value: NULL

### The `"auth-endpoint"` property

      "auth-endpoint"            gchar*                : Read / Write / Construct Only

The authentication endpoint url.

Default value: NULL

### The `"client-id"` property

      "client-id"                gchar*                : Read / Write / Construct Only

The client (application) id.

Default value: NULL