OAuth 2.0 configuration. More...

#include <oauth2.h>

Public Member Functions
	oauth2_config (utility::string_t client_key, utility::string_t client_secret, utility::string_t auth_endpoint, utility::string_t token_endpoint, utility::string_t redirect_uri, utility::string_t scope=utility::string_t())

_ASYNCRTIMP utility::string_t	build_authorization_uri (bool generate_state)
	Builds an authorization URI to be loaded in the web browser/view. The URI is built with auth_endpoint() as basis. The implicit_grant() affects the built URI by selecting either authorization code or implicit grant flow. You can set generate_state to generate a new random state string. More...

_ASYNCRTIMP pplx::task< void >	token_from_redirected_uri (const web::http::uri &redirected_uri)
	Fetch an access token (and possibly a refresh token) based on redirected URI. Behavior depends on the implicit_grant() setting. If implicit_grant() is false, the URI is parsed for 'code' parameter, and then token_from_code() is called with this code. See: http://tools.ietf.org/html/rfc6749#section-4.1 Otherwise, redirect URI fragment part is parsed for 'access_token' parameter, which directly contains the token(s). See: http://tools.ietf.org/html/rfc6749#section-4.2 In both cases, the 'state' parameter is parsed and is verified to match state(). More...

pplx::task< void >	token_from_code (utility::string_t authorization_code)
	Fetches an access token (and possibly a refresh token) from the token endpoint. The task creates an HTTP request to the token_endpoint() which exchanges the authorization code for the token(s). This also sets the refresh token if one was returned. See: http://tools.ietf.org/html/rfc6749#section-4.1.3 More...

pplx::task< void >	token_from_refresh ()
	Fetches a new access token (and possibly a new refresh token) using the refresh token. The task creates a HTTP request to the token_endpoint(). If successful, resulting access token is set as active via set_token(). See: http://tools.ietf.org/html/rfc6749#section-6 This also sets a new refresh token if one was returned. More...

bool	is_enabled () const
	Returns enabled state of the configuration. The oauth2_handler will perform OAuth 2.0 authentication only if this method returns true. Return value is true if access token is valid (=fetched or manually set). More...

const utility::string_t &	client_key () const
	Get client key. More...

void	set_client_key (utility::string_t client_key)
	Set client key. More...

const utility::string_t &	client_secret () const
	Get client secret. More...

void	set_client_secret (utility::string_t client_secret)
	Set client secret. More...

const utility::string_t &	auth_endpoint () const
	Get authorization endpoint URI string. More...

void	set_auth_endpoint (utility::string_t auth_endpoint)
	Set authorization endpoint URI string. More...

const utility::string_t &	token_endpoint () const
	Get token endpoint URI string. More...

void	set_token_endpoint (utility::string_t token_endpoint)
	Set token endpoint URI string. More...

const utility::string_t &	redirect_uri () const
	Get redirect URI string. More...

void	set_redirect_uri (utility::string_t redirect_uri)
	Set redirect URI string. More...

const utility::string_t &	scope () const
	Get scope used in authorization for token. More...

void	set_scope (utility::string_t scope)
	Set scope for authorization for token. More...

const utility::string_t &	state ()
	Get client state string used in authorization. More...

void	set_state (utility::string_t state)
	Set client state string for authorization for token. The state string is used in authorization for security reasons (to uniquely identify authorization sessions). If desired, suitably secure state string can be automatically generated by build_authorization_uri(). A good state string consist of 30 or more random alphanumeric characters. More...

const oauth2_token &	token () const
	Get token. More...

void	set_token (oauth2_token token)
	Set token. More...

bool	implicit_grant () const
	Get implicit grant setting for authorization. More...

void	set_implicit_grant (bool implicit_grant)
	Set implicit grant setting for authorization. False means authorization code grant is used for authorization. True means implicit grant is used. Default: False. More...

bool	bearer_auth () const
	Get bearer token authentication setting. More...

void	set_bearer_auth (bool bearer_auth)
	Set bearer token authentication setting. This must be selected based on what the service accepts. True means access token is passed in the request header. (http://tools.ietf.org/html/rfc6750#section-2.1) False means access token in passed in the query parameters. (http://tools.ietf.org/html/rfc6750#section-2.3) Default: True. More...

bool	http_basic_auth () const
	Get HTTP Basic authentication setting for token endpoint. More...

void	set_http_basic_auth (bool http_basic_auth)
	Set HTTP Basic authentication setting for token endpoint. This setting must be selected based on what the service accepts. True means HTTP Basic authentication is used for the token endpoint. False means client key & secret are passed in the HTTP request body. Default: True. More...

const utility::string_t &	access_token_key () const
	Get access token key. More...

void	set_access_token_key (utility::string_t access_token_key)
	Set access token key. If the service requires a "non-standard" key you must set it here. Default: "access_token". More...

const web_proxy &	proxy () const
	Get the web proxy object More...

void	set_proxy (const web_proxy &proxy)
	Set the web proxy object that will be used by token_from_code and token_from_refresh More...

Friends
class	web::http::client::http_client_config

class	web::http::oauth2::details::oauth2_handler

Detailed Description

OAuth 2.0 configuration.

Encapsulates functionality for:

Authenticating requests with an access token.
Performing the OAuth 2.0 authorization code grant authorization flow. See: http://tools.ietf.org/html/rfc6749#section-4.1
Performing the OAuth 2.0 implicit grant authorization flow. See: http://tools.ietf.org/html/rfc6749#section-4.2

Performing OAuth 2.0 authorization:

Set service and client/app parameters:

Client/app key & secret (as provided by the service).
The service authorization endpoint and token endpoint.
Your client/app redirect URI.
Use set_state() to assign a unique state string for the authorization session (default: "").
If needed, use set_bearer_auth() to control bearer token passing in either query or header (default: header). See: http://tools.ietf.org/html/rfc6750#section-2
If needed, use set_access_token_key() to set "non-standard" access token key (default: "access_token").
If needed, use set_implicit_grant() to enable implicit grant flow.

Build authorization URI with build_authorization_uri() and open this in web browser/control.
The resource owner should then clicks "Yes" to authorize your client/app, and as a result the web browser/control is redirected to redirect_uri().
Capture the redirected URI either in web control or by HTTP listener.
Pass the redirected URI to token_from_redirected_uri() to obtain access token.

The method ensures redirected URI contains same state() as set in step 1.
In implicit_grant() is false, this will create HTTP request to fetch access token from the service. Otherwise access token is already included in the redirected URI.

Usage for issuing authenticated requests:

Perform authorization as above to obtain the access token or use an existing token.

Some services provide option to generate access tokens for testing purposes.

Pass the resulting oauth2_config with the access token to http_client_config::set_oauth2().
Construct http_client with this http_client_config. As a result, all HTTP requests by that client will be OAuth 2.0 authenticated.

Member Function Documentation

const utility::string_t& web::http::oauth2::experimental::oauth2_config::access_token_key ( ) const

inline

Get access token key.

Returns: Access token key string.

const utility::string_t& web::http::oauth2::experimental::oauth2_config::auth_endpoint ( ) const

inline

Get authorization endpoint URI string.

Returns: Authorization endpoint URI string.

bool web::http::oauth2::experimental::oauth2_config::bearer_auth ( ) const

inline

Get bearer token authentication setting.

Returns: Bearer token authentication setting.

_ASYNCRTIMP utility::string_t web::http::oauth2::experimental::oauth2_config::build_authorization_uri ( bool generate_state )

Builds an authorization URI to be loaded in the web browser/view. The URI is built with auth_endpoint() as basis. The implicit_grant() affects the built URI by selecting either authorization code or implicit grant flow. You can set generate_state to generate a new random state string.

Parameters

generate_state If true, a new random state() string is generated which replaces the current state(). If false, state() is unchanged and used as-is.

Returns: Authorization URI string.

const utility::string_t& web::http::oauth2::experimental::oauth2_config::client_key ( ) const

inline

Get client key.

Returns: Client key string.

const utility::string_t& web::http::oauth2::experimental::oauth2_config::client_secret ( ) const

inline

Get client secret.

Returns: Client secret string.

bool web::http::oauth2::experimental::oauth2_config::http_basic_auth ( ) const

inline

Get HTTP Basic authentication setting for token endpoint.

Returns: HTTP Basic authentication setting for token endpoint.

bool web::http::oauth2::experimental::oauth2_config::implicit_grant ( ) const

inline

Get implicit grant setting for authorization.

Returns: Implicit grant setting for authorization.

bool web::http::oauth2::experimental::oauth2_config::is_enabled ( ) const

inline

Returns enabled state of the configuration. The oauth2_handler will perform OAuth 2.0 authentication only if this method returns true. Return value is true if access token is valid (=fetched or manually set).

Returns: The configuration enabled state.

const web_proxy& web::http::oauth2::experimental::oauth2_config::proxy ( ) const

inline

Get the web proxy object

Returns: A reference to the web proxy object.

const utility::string_t& web::http::oauth2::experimental::oauth2_config::redirect_uri ( ) const

inline

Get redirect URI string.

Returns: Redirect URI string.

const utility::string_t& web::http::oauth2::experimental::oauth2_config::scope ( ) const

inline

Get scope used in authorization for token.

Returns: Scope string used in authorization.

void web::http::oauth2::experimental::oauth2_config::set_access_token_key ( utility::string_t access_token_key )

inline

Set access token key. If the service requires a "non-standard" key you must set it here. Default: "access_token".

void web::http::oauth2::experimental::oauth2_config::set_auth_endpoint ( utility::string_t auth_endpoint )

inline

Set authorization endpoint URI string.

Parameters

auth_endpoint Authorization endpoint URI string to set.

void web::http::oauth2::experimental::oauth2_config::set_bearer_auth ( bool bearer_auth )

inline

Set bearer token authentication setting. This must be selected based on what the service accepts. True means access token is passed in the request header. (http://tools.ietf.org/html/rfc6750#section-2.1) False means access token in passed in the query parameters. (http://tools.ietf.org/html/rfc6750#section-2.3) Default: True.

Parameters

bearer_auth The bearer token authentication setting to set.

void web::http::oauth2::experimental::oauth2_config::set_client_key ( utility::string_t client_key )

inline

Set client key.

Parameters

client_key Client key string to set.

void web::http::oauth2::experimental::oauth2_config::set_client_secret ( utility::string_t client_secret )

inline

Set client secret.

Parameters

client_secret Client secret string to set.

void web::http::oauth2::experimental::oauth2_config::set_http_basic_auth ( bool http_basic_auth )

inline

Set HTTP Basic authentication setting for token endpoint. This setting must be selected based on what the service accepts. True means HTTP Basic authentication is used for the token endpoint. False means client key & secret are passed in the HTTP request body. Default: True.

Parameters

http_basic_auth The HTTP Basic authentication setting to set.

void web::http::oauth2::experimental::oauth2_config::set_implicit_grant ( bool implicit_grant )

inline

Set implicit grant setting for authorization. False means authorization code grant is used for authorization. True means implicit grant is used. Default: False.

Parameters

implicit_grant The implicit grant setting to set.

void web::http::oauth2::experimental::oauth2_config::set_proxy ( const web_proxy & proxy )

inline

Set the web proxy object that will be used by token_from_code and token_from_refresh

Parameters

proxy A reference to the web proxy object.

void web::http::oauth2::experimental::oauth2_config::set_redirect_uri ( utility::string_t redirect_uri )

inline

Set redirect URI string.

Parameters

redirect_uri Redirect URI string to set.

void web::http::oauth2::experimental::oauth2_config::set_scope ( utility::string_t scope )

inline

Set scope for authorization for token.

Parameters

scope Scope string for authorization for token.

void web::http::oauth2::experimental::oauth2_config::set_state ( utility::string_t state )

inline

Set client state string for authorization for token. The state string is used in authorization for security reasons (to uniquely identify authorization sessions). If desired, suitably secure state string can be automatically generated by build_authorization_uri(). A good state string consist of 30 or more random alphanumeric characters.

Parameters

state Client authorization state string to set.

void web::http::oauth2::experimental::oauth2_config::set_token ( oauth2_token token )

inline

Set token.

Parameters

token Token to set.

void web::http::oauth2::experimental::oauth2_config::set_token_endpoint ( utility::string_t token_endpoint )

inline

Set token endpoint URI string.

Parameters

token_endpoint Token endpoint URI string to set.

const utility::string_t& web::http::oauth2::experimental::oauth2_config::state ( )

inline

Get client state string used in authorization.

Returns: Client state string used in authorization.

const oauth2_token& web::http::oauth2::experimental::oauth2_config::token ( ) const

inline

Get token.

Returns: Token.

const utility::string_t& web::http::oauth2::experimental::oauth2_config::token_endpoint ( ) const

inline

Get token endpoint URI string.

Returns: Token endpoint URI string.

pplx::task<void> web::http::oauth2::experimental::oauth2_config::token_from_code ( utility::string_t authorization_code )

inline

Fetches an access token (and possibly a refresh token) from the token endpoint. The task creates an HTTP request to the token_endpoint() which exchanges the authorization code for the token(s). This also sets the refresh token if one was returned. See: http://tools.ietf.org/html/rfc6749#section-4.1.3

Parameters

authorization_code Code received via redirect upon successful authorization.

Returns: Task that fetches token(s) based on the authorization code.

_ASYNCRTIMP pplx::task<void> web::http::oauth2::experimental::oauth2_config::token_from_redirected_uri ( const web::http::uri & redirected_uri )

Fetch an access token (and possibly a refresh token) based on redirected URI. Behavior depends on the implicit_grant() setting. If implicit_grant() is false, the URI is parsed for 'code' parameter, and then token_from_code() is called with this code. See: http://tools.ietf.org/html/rfc6749#section-4.1 Otherwise, redirect URI fragment part is parsed for 'access_token' parameter, which directly contains the token(s). See: http://tools.ietf.org/html/rfc6749#section-4.2 In both cases, the 'state' parameter is parsed and is verified to match state().

Parameters

redirected_uri The URI where web browser/view was redirected after resource owner's authorization.

Returns: Task that fetches the token(s) based on redirected URI.

pplx::task<void> web::http::oauth2::experimental::oauth2_config::token_from_refresh ( )

inline

Fetches a new access token (and possibly a new refresh token) using the refresh token. The task creates a HTTP request to the token_endpoint(). If successful, resulting access token is set as active via set_token(). See: http://tools.ietf.org/html/rfc6749#section-6 This also sets a new refresh token if one was returned.

Returns: Task that fetches the token(s) using the refresh token.

The documentation for this class was generated from the following file:

include/cpprest/oauth2.h

Public Member Functions

Friends

Detailed Description

Member Function Documentation