Mediates interaction with the user, client and an OAuth 2.0 server to obtain credentials for accessing protected resources. More...

#include "client/auth/oauth2_authorization.h"

Inheritance diagram for OAuth2AuthorizationFlow:

List of all members.

Public Types
typedef ResultCallback2 < util::Status, const OAuth2RequestOptions &, string * >	AuthorizationCodeCallback
	Responsible for getting an Authorization Code for the specified options.
Public Member Functions
	OAuth2AuthorizationFlow (HttpTransport *transport)
	Constructs the flow.
virtual	~OAuth2AuthorizationFlow ()
	Standard destructor.
util::Status	InitFromJson (const StringPiece &json)
	Initializes the flow attributes from the JSON string.
void	set_authorization_code_callback (AuthorizationCodeCallback *callback)
	Sets the callback used to obtain an Authorization Code.
AuthorizationCodeCallback *	authorization_code_callback () const
	Returns the callback for obtaining Authorization Codes, or NULL if it was not set.
void	ResetCredentialStore (CredentialStore *store)
	Sets the CredentialStore used by this flow.
CredentialStore *	credential_store () const
	Returne the bound credential store, if any.
const OAuth2ClientSpec &	client_spec () const
	Returns the client specification with the details needed for it to use the OAuth 2.0 server.
OAuth2ClientSpec *	mutable_client_spec ()
	Returns a modificable client specification.
const string &	default_scopes () const
	Returns the default scopes to request when asking for Access Tokens.
void	set_default_scopes (const StringPiece &scopes)
	Sets the default scopes to request when asking for Access Tokens.
virtual util::Status	RefreshCredentialWithOptions (const OAuth2RequestOptions &options, OAuth2Credential *credential)
	Refreshes the credential with a current access token.
string	GenerateAuthorizationCodeRequestUrl (const StringPiece &scopes) const
	Returns a URL to the OAuth 2.0 server requesting a new Authorization Code.
string	GenerateAuthorizationCodeRequestUrl (const vector< StringPiece > &scopes) const
	Variation of GenerateAuthorizationCodeRequestUrl that takes a vector of scopes rather than a ' '-delmited string.
virtual string	GenerateAuthorizationCodeRequestUrlWithOptions (const OAuth2RequestOptions &options) const
	Returns a URL to the OAuth 2.0 server requesting a new Authorization Code.
virtual util::Status	PerformRefreshToken (const OAuth2RequestOptions &options, OAuth2Credential *credential)
	Talk to the OAuth 2.0 server to refresh the access token.
virtual util::Status	PerformExchangeAuthorizationCode (const string &authorization_code, const OAuth2RequestOptions &options, OAuth2Credential *credential)
	Sends request to OAuth 2.0 server to obtain Access and Refresh tokens from an Authorization Code.
virtual util::Status	PerformRevokeToken (bool access_token_only, OAuth2Credential *credential)
	Sends a request to the OAuth 2.0 server to revoke the credentials.
OAuth2TokenRequest *	NewExchangeAuthorizationCodeRequest (const StringPiece &authorization_code, OAuth2Credential *credential)
	Creates a new request for obtaining Access and Refresh tokens from an Authorization Code.
OAuth2TokenRequest *	NewExchangeAuthorizationCodeRequestWithOptions (const StringPiece &authorization_code, const OAuth2RequestOptions &options, OAuth2Credential *credential)
	Creates a new request for obtaining Access and Refresh tokens from an Authorization Code.
OAuth2TokenRequest *	NewRefreshTokenRequest (OAuth2Credential *credential)
	Creates a new request for obtaining an Access Token from an existing Refresh Token.
OAuth2TokenRequest *	NewRevokeRefreshTokenRequest (OAuth2Credential *credential)
	Creates a new request for revoking a Refresh Token so that it is no longer valid.
OAuth2TokenRequest *	NewRevokeAccessTokenRequest (OAuth2Credential *credential)
	Creates a new request for revoking an Access Token so that it is no longer valid.
OAuth2Credential *	NewCredential ()
	Returns a new credential instance that will use this flow to refresh.
Static Public Member Functions
static OAuth2AuthorizationFlow *	MakeFlowFromClientSecretsPath (const StringPiece &path, HttpTransport transport, util::Status status)
	Creates a new flow from a client secrets file.
static OAuth2AuthorizationFlow *	MakeFlowFromClientSecretsJson (const StringPiece &json, HttpTransport transport, util::Status status)
	Creates a new flow from a client secrets JSON document.
static string	JoinScopes (const vector< StringPiece > &scopes)
	Helper function to produce a ' '-delimited scopes string from a vector of individual scopes.
Static Public Attributes
static const char	kOutOfBandUrl []
	The standard URL used for clients that do not have an HTTP server.
static const char	kGoogleAccountsOauth2Url []
	The root URL for the standard OAuth 2.0 server used by the Google Cloud Platform.
Protected Member Functions
virtual util::Status	InitFromJsonData (const SimpleJsonData *data)
	Called by InitFromJson.
Friends
class	OAuth2Credential
	The parser is currently private to the implementation because I do not want to couple JsonCpp in the public API at this time.

Detailed Description

Mediates interaction with the user, client and an OAuth 2.0 server to obtain credentials for accessing protected resources.

This classs is based on a Mediator Pattern with the goal of obtaining credentials to access resources protected by OAuth 2.0.

This class is concrete, however is often subclassed for different OAuth 2.0 flow patterns that may add additional specialized parameters to their token requests. These are determined by the Client Type selection in the Google APIs console when the client was registered.

To use this class you must first configure the client secrets needed to issue requests to the OAuth 2.0 server on behalf of the client. The easiest way to do this is to use the MakeFlowFromClientSecretsPath() factory method to construct the flow or the InitFromJson() method if you want to instantiate the flow yourself. Otherwise get the client spec using mutable_client_spec().

If a CredentialStore is bound to the flow then it will be used as a cache. This is particularly useful for persisting refresh tokens across multiple program executions. Without an existing refresh token the user will have to re-authorize access all over again. With the store, the user will only have to authorize access the first time the program is run.

See also:: OAuth2Credential; OAuth2ClientSpec; MakeFlowFromClientSecretsPath; ResetCredentialStore

Member Typedef Documentation

typedef ResultCallback2< util::Status, const OAuth2RequestOptions&, string*> AuthorizationCodeCallback

Responsible for getting an Authorization Code for the specified options.

Note the Authorization Code is not an access token.

Returns:: util::Status is a failure if the authorization code could not be obtained, including if the user denies access.

Parameters:

[in]	OAuth2RequestOptions	Specifies the scope and redirect_uri.
[out]	string	The authorization code if the call is successful.

Constructor & Destructor Documentation

OAuth2AuthorizationFlow ( HttpTransport * transport ) [explicit]

Constructs the flow.

Parameters:

[in] transport Transport to use when talking to the OAuth 2.0 server. Ownership is passed to the flow.

virtual ~OAuth2AuthorizationFlow ( ) [virtual]

Standard destructor.

Member Function Documentation

AuthorizationCodeCallback* authorization_code_callback ( ) const [inline]

Returns the callback for obtaining Authorization Codes, or NULL if it was not set.

const OAuth2ClientSpec& client_spec ( ) const [inline]

Returns the client specification with the details needed for it to use the OAuth 2.0 server.

CredentialStore* credential_store ( ) const [inline]

Returne the bound credential store, if any.

const string& default_scopes ( ) const [inline]

Returns the default scopes to request when asking for Access Tokens.

string GenerateAuthorizationCodeRequestUrl ( const StringPiece & scopes ) const [inline]

Returns a URL to the OAuth 2.0 server requesting a new Authorization Code.

This method is only intended when manually implementing flows.

Parameters:

[in] scopes The desired scopes. If more than one scope is desired then this should be a ' '-delimited string. The scope values are specified by the specific service you wish to get authorization to access.

Returns:: The appropriate URL to HTTP GET.

See also:: RefreshCredentialWithOptions.; GeenrateAuthorizationCodeRequestUrlWithOptions

Reimplemented in OAuth2WebApplicationFlow, and OAuth2InstalledApplicationFlow.

string GenerateAuthorizationCodeRequestUrl ( const vector< StringPiece > & scopes ) const

Variation of GenerateAuthorizationCodeRequestUrl that takes a vector of scopes rather than a ' '-delmited string.

Parameters:

[in] scopes The individual scope strings.

See also:: GenerateAuthorizationCodeRequestUrl

virtual string GenerateAuthorizationCodeRequestUrlWithOptions ( const OAuth2RequestOptions & options ) const [virtual]

Returns a URL to the OAuth 2.0 server requesting a new Authorization Code.

This method is only intended when manually implementing flows.

Parameters:

[in] options Used to refine what is being requested.

Returns:: The appropriate URL to HTTP GET.

See also:: RefreshCredentialWithOptions.

util::Status InitFromJson ( const StringPiece & json )

Initializes the flow attributes from the JSON string.

This includes the standard attributes for the client spec, and any additional attributes for the specialization within the flow. This method calls the protected InitFromJsonData() method so that derived classes can initialize their specialized attributes as well.

Parameters:

[in] json JSON-encoded object with the configuraton attributes.

virtual util::Status InitFromJsonData ( const SimpleJsonData * data ) [protected, virtual]

Called by InitFromJson.

Parameters:

[out] data The data to initialized.

Reimplemented in OAuth2WebApplicationFlow, and OAuth2InstalledApplicationFlow.

static string JoinScopes ( const vector< StringPiece > & scopes ) [static]

Helper function to produce a ' '-delimited scopes string from a vector of individual scopes.

Parameters:

[in] scopes

Returns:: scopes string for OAuth2RequestOptions

static OAuth2AuthorizationFlow* MakeFlowFromClientSecretsJson	(	const StringPiece &	json,
		HttpTransport *	transport,
		util::Status *	status
	)		`[static]`

Creates a new flow from a client secrets JSON document.

The JSON document is a composite object whose name specifies the type of flow to be created. For example

{
    "installed": {
       "client_id": "<deleted>.apps.googleusercontent.com",
       "client_secret": "<deleted>"
    }
 }

where <deleted> were values created when the program was registered.

Parameters:

[in]	json	The JSON encoded client secrets to configure the flow from. This can come from the Google APIs Console.
[in]	transport	The transport to use with the flow will be owned by the flow. If the flow could not be created then this transport will be destroyed.
[out]	status	Will explain the cause for failure.

Returns:: Ownership of a new authorization flow or NULL on failure.

static OAuth2AuthorizationFlow* MakeFlowFromClientSecretsPath	(	const StringPiece &	path,
		HttpTransport *	transport,
		util::Status *	status
	)		`[static]`

Creates a new flow from a client secrets file.

This method is a wrapper around MakeFlowFromClientSecretsJson that reads the contents of a file and uess that as the JSON paraemter to MakeFlowFromClientSecretsJson.

As a security safeguard, the file must be read-only and not a symbolic link.

Parameters:

[in]	path	The path to a file containing the JSON-encoded secrets.
[in]	transport	The transport to use with the flow will be owned by the flow. If the flow could not be created then this transport will be destroyed.
[out]	status	Will explain the cause for failure.

Returns:: Ownership of a new authorization flow or NULL on failure.

See also:: MakeFlowFromClientSecretsJson

OAuth2ClientSpec* mutable_client_spec ( ) [inline]

Returns a modificable client specification.

OAuth2Credential* NewCredential ( )

Returns a new credential instance that will use this flow to refresh.

Returns:: Ownership of the credential is passed to the caller. The instance will be constructed with this flow bound to it to implement its refresh method. Therefore this flow must remain valid over the lifetime of the result or until you unbind the flow using OAuth2Credential::set_flow(NULL).

OAuth2TokenRequest* NewExchangeAuthorizationCodeRequest	(	const StringPiece &	authorization_code,
		OAuth2Credential *	credential
	)		`[inline]`

Creates a new request for obtaining Access and Refresh tokens from an Authorization Code.

This method is only intended when manually implementing flows.

Parameters:

[in]	authorization_code	The Authorization Code.
[out]	credential	The credential to update with the tokens.

See also:: RefreshCredentialWithOptions.; PerformExchangeAuthorizationCode

Deprecated:

OAuth2TokenRequest* NewExchangeAuthorizationCodeRequestWithOptions	(	const StringPiece &	authorization_code,
		const OAuth2RequestOptions &	options,
		OAuth2Credential *	credential
	)

Creates a new request for obtaining Access and Refresh tokens from an Authorization Code.

This method is only intended when manually implementing flows.

Parameters:

[in]	authorization_code	The Authorization Code.
[in]	options	Used to refine what is being requested.
[out]	credential	The credential to update with the tokens.

See also:: RefreshCredentialWithOptions.; PerformExchangeAuthorizationCode

Deprecated:

OAuth2TokenRequest* NewRefreshTokenRequest ( OAuth2Credential * credential )

Creates a new request for obtaining an Access Token from an existing Refresh Token.

Parameters:

[in] credential The credential to update should already contain an existing refresh token. The credential will be updated with a new Access Token if the request is executed successfully.

See also:: RefreshCredentialWithOptions; PerformRefreshToken

Deprecated:

OAuth2TokenRequest* NewRevokeAccessTokenRequest ( OAuth2Credential * credential )

Creates a new request for revoking an Access Token so that it is no longer valid.

Parameters:

[in] credential The credential to update should already contain an existing access token. The token will be cleared after the revoke request executes successfully.

See also:: PerformRevokeToken

Deprecated:

OAuth2TokenRequest* NewRevokeRefreshTokenRequest ( OAuth2Credential * credential )

Creates a new request for revoking a Refresh Token so that it is no longer valid.

The user will have to go through the entire flow to obtain a new Authorization Code if they want to use the credential again.

Parameters:

[in] credential The credential to update should already contain an existing refresh token. The token will be cleared after the revoke request executes successfully.

See also:: PerformRevokeToken

Deprecated:

virtual util::Status PerformExchangeAuthorizationCode	(	const string &	authorization_code,
		const OAuth2RequestOptions &	options,
		OAuth2Credential *	credential
	)		`[virtual]`

Sends request to OAuth 2.0 server to obtain Access and Refresh tokens from an Authorization Code.

Parameters:

[in]	authorization_code	The Authorization Code.
[in]	options	Used to refine what is being requested.
[out]	credential	The credential to update with the tokens.

Returns:: ok or reason for error.

See also:: RefreshCredentialWithOptions.

virtual util::Status PerformRefreshToken	(	const OAuth2RequestOptions &	options,
		OAuth2Credential *	credential
	)		`[virtual]`

Talk to the OAuth 2.0 server to refresh the access token.

Parameters:

[in]	options	Overriden options, like the redirect_uri.
[in,out]	credential	Uses the refresh_token to update access_token.

Returns:: ok on success or reason for failure.

virtual util::Status PerformRevokeToken	(	bool	access_token_only,
		OAuth2Credential *	credential
	)		`[virtual]`

Sends a request to the OAuth 2.0 server to revoke the credentials.

Parameters:

[in]	access_token_only	If true then only revoke the access token leaving the refresh token intact.
[in]	credential	The credential to update should contain the refresh and/or access tokens. The tokens will be cleared after the revoke request executes successfully.

virtual util::Status RefreshCredentialWithOptions	(	const OAuth2RequestOptions &	options,
		OAuth2Credential *	credential
	)		`[virtual]`

Refreshes the credential with a current access token.

Parameters:

options

Clarifies details about the desired credentials.

Option	Purpose
user_id	Only used as a key for the CredentialStore. If there is no store for the flow or this is empty then the call will proceed without using a CredentialStore. Some flows, such as the web flow, may also use this as a login_hint.
scopes	Used to override the flow's default scope. This option is only required if the flow was not given a default.
redirect_uri	Used to override the flow's default redirect_uri. This option is only required if the flow was not given a default.

[in] credential The credential to refresh can be empty. If it has already been initialized then the user_id, if any, must match that in the options.

The a CredentialStore is to be used, then the flow will attempt to read an existing credential from the store. Also, the flow will store newly obtained or updated credentials into the store.

When existing credentials are found in the store, it may already have a valid access token. Otherwise it should have a refresh token from which a new access token can be obtained. The flow will attempt to obtain a valid access token and update the credential as needed.

If there is no credential in the store, or the credential failed to update then the flow will attempt to obtain a new Authorization Code, which will require user interaction to approve. To obtain the Authorization Code, the flow will call the AuthorizationCodeCallback, if one was bound. If this code is obtained, the flow will use it to update the credential with a valid Access Token and store the updated credential if a store was configured. TODO(ewiseblatt): This currently only considers the scopes when the credential has no refresh_token. If there is a refresh token, then the updated credentials will still only be for the old scopes. To get around this bug, you need to clear the credential and start all over.

void ResetCredentialStore ( CredentialStore * store )

Sets the CredentialStore used by this flow.

Parameters:

[in] store Ownership of the credential store is passed to the flow. A NULL valid indicates that credentials should neither be stored nor restored.

void set_authorization_code_callback ( AuthorizationCodeCallback * callback )

Sets the callback used to obtain an Authorization Code.

Parameters:

[in] callback Must be repeatable if not NULL. Ownership is passed to the flow.

See also:: NewPermanentCallback()

void set_default_scopes ( const StringPiece & scopes ) [inline]

Sets the default scopes to request when asking for Access Tokens.

The OAuth2RequestOptions passed to various methods can be used to override these on a per-request basis if needed. It is not required to set this, but it is simpler if requests tend to use the same scopes.

Parameters:

[in] scopes The specific values are specified by the individual services that you wish to talk to.

Friends And Related Function Documentation

friend class OAuth2Credential [friend]

The parser is currently private to the implementation because I do not want to couple JsonCpp in the public API at this time.

Member Data Documentation

const char kGoogleAccountsOauth2Url[] [static]

The root URL for the standard OAuth 2.0 server used by the Google Cloud Platform.

const char kOutOfBandUrl[] [static]

The standard URL used for clients that do not have an HTTP server.

/ TODO(ewiseblatt): Better description.

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

googleapis/client/auth/oauth2_authorization.h

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Protected Member Functions

Friends

Detailed Description

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

Member Data Documentation