Accessing a Protected Resource

Enumerations
enum	OAUTH2_TOKEN_PARAM_NAME
Functions
	getAccessToken ($oauth_token)
	verifyAccessToken ($scope=NULL, $exit_not_present=TRUE, $exit_invalid=TRUE, $exit_expired=TRUE, $exit_scope=TRUE, $realm=NULL)
	checkScope ($required_scope, $available_scope)
	getAccessTokenParams ()
	getAuthorizationHeader ()

---

Detailed Description

Clients access protected resources by presenting an access token to the resource server. Access tokens act as bearer tokens, where the token string acts as a shared symmetric secret. This requires treating the access token with the same care as other secrets (e.g. end-user passwords). Access tokens SHOULD NOT be sent in the clear over an insecure channel.

See also:

http://tools.ietf.org/html/draft-ietf-oauth-v2-10#section-5

---

Enumeration Type Documentation

enum OAUTH2_TOKEN_PARAM_NAME

Used to define the name of the OAuth access token parameter (POST/GET/etc.).

IETF Draft sections 5.1.2 and 5.1.3 specify that it should be called "oauth_token" but other implementations use things like "access_token".

I won't be heartbroken if you change it, but it might be better to adhere to the spec.

See also:

http://tools.ietf.org/html/draft-ietf-oauth-v2-10#section-5.1.2

http://tools.ietf.org/html/draft-ietf-oauth-v2-10#section-5.1.3

Definition at line 186 of file OAuth2.inc.

---

Function Documentation

checkScope	(	$	required_scope,
		$	available_scope
	)			[private, inherited]

Check if everything in required scope is contained in available scope.

Parameters:

	$required_scope	Required scope to be check with.
	$available_scope	Available scope to be compare with.

Returns:

TRUE if everything in required scope is contained in available scope, and False if it isn't.

See also:

http://tools.ietf.org/html/draft-ietf-oauth-v2-10#section-5

Definition at line 915 of file OAuth2.inc.

Referenced by OAuth2::getAuthorizeParams(), OAuth2::grantAccessToken(), and OAuth2::verifyAccessToken().

getAccessToken

(

$

oauth_token

)

[abstract, protected, inherited]

Look up the supplied oauth_token from storage.

We need to retrieve access token data as we create and verify tokens.

Parameters:

$oauth_token

oauth_token to be check with.

Returns:

An associative array as below, and return NULL if the supplied oauth_token is invalid:

• client_id: Stored client identifier.
• expires: Stored expiration in unix timestamp.
• scope: (optional) Stored scope values in space-separated string.

Reimplemented in MongoOAuth2, and PDOOAuth2.

Referenced by OAuth2::verifyAccessToken().

getAccessTokenParams

(

)

[private, inherited]

Pulls the access token out of the HTTP request.

Either from the Authorization header or GET/POST/etc.

Returns:

Access token value if present, and FALSE if it isn't.

Todo:

Support PUT or DELETE.

See also:

http://tools.ietf.org/html/draft-ietf-oauth-v2-10#section-5.1

Definition at line 940 of file OAuth2.inc.

References OAuth2::errorJsonResponse(), and OAuth2::getAuthorizationHeader().

Referenced by OAuth2::verifyAccessToken().

getAuthorizationHeader

(

)

[private, inherited]

Pull out the Authorization HTTP header and return it.

Implementing classes may need to override this function for use on non-Apache web servers.

Returns:

The Authorization HTTP header, and FALSE if does not exist.

Todo:

Handle Authorization HTTP header for non-Apache web servers.

Definition at line 1406 of file OAuth2.inc.

Referenced by OAuth2::getAccessTokenParams().

verifyAccessToken	(	$	scope = NULL,
		$	exit_not_present = TRUE,
		$	exit_invalid = TRUE,
		$	exit_expired = TRUE,
		$	exit_scope = TRUE,
		$	realm = NULL
	)			[inherited]

Check that a valid access token has been provided.

The scope parameter defines any required scope that the token must have. If a scope param is provided and the token does not have the required scope, we bounce the request.

Some implementations may choose to return a subset of the protected resource (i.e. "public" data) if the user has not provided an access token or if the access token is invalid or expired.

The IETF spec says that we should send a 401 Unauthorized header and bail immediately so that's what the defaults are set to.

Parameters:

	$scope	A space-separated string of required scope(s), if you want to check for scope.
	$exit_not_present	If TRUE and no access token is provided, send a 401 header and exit, otherwise return FALSE.
	$exit_invalid	If TRUE and the implementation of getAccessToken() returns NULL, exit, otherwise return FALSE.
	$exit_expired	If TRUE and the access token has expired, exit, otherwise return FALSE.
	$exit_scope	If TRUE the access token does not have the required scope(s), exit, otherwise return FALSE.
	$realm	If you want to specify a particular realm for the WWW-Authenticate header, supply it here.

See also:

http://tools.ietf.org/html/draft-ietf-oauth-v2-10#section-5

Definition at line 878 of file OAuth2.inc.

References OAuth2::checkScope(), OAuth2::errorWWWAuthenticateResponseHeader(), OAuth2::getAccessToken(), and OAuth2::getAccessTokenParams().