OAuth2Proxy: librest Reference Manual

## OAuth2Proxy OAuth2Proxy |

## Functions

RestProxy * | oauth2_proxy_new ()
RestProxy * | oauth2_proxy_new_with_token ()
char * | oauth2_proxy_build_login_url_full ()
char * | oauth2_proxy_build_login_url ()
const char * | oauth2_proxy_get_access_token ()
void | oauth2_proxy_set_access_token ()
char * | oauth2_proxy_extract_access_token ()

## Properties

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

## Types and Values

| OAuth2Proxy

## Object Hierarchy

        GObject
        ╰── RestProxy
            ╰── OAuth2Proxy

## Description

## Functions

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

#### Parameters

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.

#### Parameters

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

#### Parameters

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

## Types and Values

### OAuth2Proxy

    typedef struct _OAuth2Proxy OAuth2Proxy;

OAuth2Proxy has no publicly available members.

## Property Details

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

      “access-token”             gchar *

The request or access token.

Flags: Read / Write

Default value: NULL

### The `“auth-endpoint”` property

      “auth-endpoint”            gchar *

The authentication endpoint url.

Flags: Read / Write / Construct Only

Default value: NULL

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

      “client-id”                gchar *

The client (application) id.

Flags: Read / Write / Construct Only

Default value: NULL