Documentation

OAuth2Provider extends OAuthProvider
in package
implements OAuth2Interface

AbstractYes

Implements an abstract OAuth2 provider with all methods required by the OAuth2Interface.

It also implements the ClientCredentials, CSRFToken, TokenRefresh and [...] interfaces in favor over traits.

Tags
link
https://oauth.net/2/
link
https://datatracker.ietf.org/doc/html/rfc6749
link
https://datatracker.ietf.org/doc/html/rfc7636
link
https://datatracker.ietf.org/doc/html/rfc9126

Table of Contents

Interfaces

OAuth2Interface
Specifies the basic methods for an OAuth2 provider.

Properties

$accessTokenURL  : string
The access token exchange URL
$apiDocs  : string|null
An optional link to the provider's API docs
$apiURL  : string
The API base URL
$applicationURL  : string|null
An optional URL to the provider's credential registration/application page
$authorizationURL  : string
The authorization URL
$clientCredentialsTokenURL  : string|null
An optional client credentials token endpoint in case the provider supports ClientCredentials.
$http  : ClientInterface
The PSR-18 HTTP client
$logger  : LoggerInterface
A PSR-3 logger
$name  : string
The name of the provider/class
$options  : OAuthOptions|SettingsContainerInterface
The options instance
$parAuthorizationURL  : string
An optional PAR (Pushed Authorization Request) endpoint URL
$refreshTokenURL  : string|null
An optional refresh token endpoint in case the provider supports TokenRefresh.
$requestFactory  : RequestFactoryInterface
A PSR-17 request factory
$revokeURL  : string
An optional URL for application side token revocation
$storage  : OAuthStorageInterface
A storage instance
$streamFactory  : StreamFactoryInterface
A PSR-17 stream factory
$uriFactory  : UriFactoryInterface
A PSR-17 URI factory
$userRevokeURL  : string|null
An optional link to the page where a user can revoke access tokens

Methods

__construct()  : mixed
OAuthProvider constructor.
checkState()  : void
implements CSRFToken::checkState()
getAccessToken()  : AccessToken
Obtains an OAuth2 access token with the given $code, verifies the $state if the provider implements the CSRFToken interface, and returns an AccessToken object
getAccessTokenFromStorage()  : AccessToken
Gets an access token from the current OAuthStorageInterface (shorthand/convenience)
getApiDocURL()  : string|null
Returns the link to the provider's API docs, or null if the value is not set
getApplicationURL()  : string|null
Returns the link to the provider's credential registration/application page, or null if the value is not set
getAuthorizationURL()  : UriInterface
Prepares the URL with optional $params which redirects to the provider's authorization prompt and returns a PSR-7 UriInterface with all necessary parameters set.
getName()  : string
Returns the name of the provider/class
getRequestAuthorization()  : RequestInterface
Authorizes the $request with the credentials from the given $token and returns a PSR-7 RequestInterface with all necessary headers and/or parameters set
getStorage()  : OAuthStorageInterface
Returns the current OAuthStorageInterface
getUserRevokeURL()  : string|null
Returns the link to the page where a user can revoke access tokens, or null if the value is not set
InvalidateAccessToken()  : bool
implements TokenInvalidate
refreshAccessToken()  : AccessToken
implements TokenRefresh::refreshAccessToken()
request()  : ResponseInterface
Prepares an API request to $path with the given parameters, gets authorization, fires the request and returns a PSR-7 ResponseInterface with the corresponding API response
sendRequest()  : ResponseInterface
setLogger()  : static
Sets an optional PSR-3 LoggerInterface
setRequestFactory()  : static
Sets an optional PSR-17 RequestFactoryInterface
setState()  : array<string, string>
implements CSRFToken::setState()
setStorage()  : static
Sets an optional OAuthStorageInterface
setStreamFactory()  : static
Sets an optional PSR-17 StreamFactoryInterface
setUriFactory()  : static
Sets an optional PSR-17 UriFactoryInterface
storeAccessToken()  : static
Sets an access token in the current OAuthStorageInterface (shorthand/convenience)
addBasicAuthHeader()  : RequestInterface
Adds an "Authorization: Basic <base64(key:secret)>" header to the given request
cleanBodyParams()  : array<string, string>
Cleans an array of body parameters
cleanQueryParams()  : array<string, string>
Cleans an array of query parameters
construct()  : void
A replacement constructor that you can call in extended classes, so that you don't have to implement the monstrous original `__construct()`
createAccessToken()  : AccessToken
Creates an access token with the provider set to $this->name
getAccessTokenRequestBodyParams()  : array<string, string>
prepares the request body parameters for the access token request
getAuthorizationURLRequestParams()  : array<string, string>
prepares the query parameters for the auth URL
getMeResponseData()  : array<int|string, mixed>
fetches the provider's "me" endpoint and returns the JSON data as an array
getRefreshAccessTokenRequestBodyParams()  : array<string, string|null>
prepares the request body parameters for the token refresh
getRequestHeaders()  : array<string, string>
Prepare request headers
getRequestTarget()  : string
Determine the request target from the given URI (path segment or URL) with respect to $apiURL, anything except host and path will be ignored, scheme will always be set to "https".
getRequestURL()  : string
Prepares the request URL
getTokenResponseData()  : array<string, string|mixed>
extracts the data from the access token response and returns an array with the key->value pairs contained
handleMeResponseError()  : void
handles errors for the `me()` endpoints - one horrible block of code to catch them all
nonce()  : string
returns a 32 byte random string (in hexadecimal representation) for use as a nonce
parseTokenResponse()  : AccessToken
Parses the response from a request to the token endpoint
sendAccessTokenRequest()  : ResponseInterface
sends a request to the access/refresh token endpoint $url with the given $body as form data
sendMeRequest()  : ResponseInterface
prepares and sends the request to the provider's "me" endpoint and returns a ResponseInterface
setRequestBody()  : RequestInterface
Prepares the request body and sets it in the given RequestInterface, along with a Content-Length header

Properties

$accessTokenURL

The access token exchange URL

protected string $accessTokenURL = ''

$apiDocs

An optional link to the provider's API docs

protected string|null $apiDocs = null

$applicationURL

An optional URL to the provider's credential registration/application page

protected string|null $applicationURL = null

$authorizationURL

The authorization URL

protected string $authorizationURL = ''

$clientCredentialsTokenURL

An optional client credentials token endpoint in case the provider supports ClientCredentials.

protected string|null $clientCredentialsTokenURL = null

If the provider supports client credentials and $clientCredentialsTokenURL is null, $accessTokenURL will be used instead.

Tags
see
ClientCredentials::getClientCredentialsToken()

$http

The PSR-18 HTTP client

protected ClientInterface $http

$name

The name of the provider/class

protected string $name = ''

$refreshTokenURL

An optional refresh token endpoint in case the provider supports TokenRefresh.

protected string|null $refreshTokenURL = null

If the provider supports token refresh and $refreshTokenURL is null, $accessTokenURL will be used instead.

Tags
see
TokenRefresh::refreshAccessToken()

$requestFactory

A PSR-17 request factory

protected RequestFactoryInterface $requestFactory

$streamFactory

A PSR-17 stream factory

protected StreamFactoryInterface $streamFactory

$uriFactory

A PSR-17 URI factory

protected UriFactoryInterface $uriFactory

$userRevokeURL

An optional link to the page where a user can revoke access tokens

protected string|null $userRevokeURL = null

Methods

__construct()

OAuthProvider constructor.

public final __construct(OAuthOptions|SettingsContainerInterface $options, ClientInterface $http, RequestFactoryInterface $requestFactory, StreamFactoryInterface $streamFactory, UriFactoryInterface $uriFactory[, OAuthStorageInterface $storage = new MemoryStorage() ][, LoggerInterface $logger = new NullLogger() ]) : mixed
Parameters
$options : OAuthOptions|SettingsContainerInterface
$http : ClientInterface
$requestFactory : RequestFactoryInterface
$streamFactory : StreamFactoryInterface
$uriFactory : UriFactoryInterface
$storage : OAuthStorageInterface = new MemoryStorage()
$logger : LoggerInterface = new NullLogger()

getAccessToken()

Obtains an OAuth2 access token with the given $code, verifies the $state if the provider implements the CSRFToken interface, and returns an AccessToken object

public getAccessToken(string $code[, string|null $state = null ]) : AccessToken
Parameters
$code : string
$state : string|null = null
Return values
AccessToken

getAccessTokenFromStorage()

Gets an access token from the current OAuthStorageInterface (shorthand/convenience)

public final getAccessTokenFromStorage() : AccessToken
Tags
codeCoverageIgnore
Return values
AccessToken

getApiDocURL()

Returns the link to the provider's API docs, or null if the value is not set

public final getApiDocURL() : string|null
Tags
codeCoverageIgnore
Return values
string|null

getApplicationURL()

Returns the link to the provider's credential registration/application page, or null if the value is not set

public final getApplicationURL() : string|null
Tags
codeCoverageIgnore
Return values
string|null

getAuthorizationURL()

Prepares the URL with optional $params which redirects to the provider's authorization prompt and returns a PSR-7 UriInterface with all necessary parameters set.

public getAuthorizationURL([array<string, scalar>|null $params = null ][, array<string|int, string>|null $scopes = null ]) : UriInterface
Parameters
$params : array<string, scalar>|null = null
$scopes : array<string|int, string>|null = null
Return values
UriInterface

getName()

Returns the name of the provider/class

public final getName() : string
Tags
codeCoverageIgnore
Return values
string

getRequestAuthorization()

Authorizes the $request with the credentials from the given $token and returns a PSR-7 RequestInterface with all necessary headers and/or parameters set

public getRequestAuthorization(RequestInterface $request[, AccessToken|null $token = null ]) : RequestInterface
Parameters
$request : RequestInterface
$token : AccessToken|null = null
Return values
RequestInterface

getUserRevokeURL()

Returns the link to the page where a user can revoke access tokens, or null if the value is not set

public final getUserRevokeURL() : string|null
Tags
codeCoverageIgnore
Return values
string|null

request()

Prepares an API request to $path with the given parameters, gets authorization, fires the request and returns a PSR-7 ResponseInterface with the corresponding API response

public request(string $path[, array<string|int, mixed>|null $params = null ][, string|null $method = null ][, StreamInterface|array<string|int, mixed>|string|null $body = null ][, array<string|int, mixed>|null $headers = null ][, string|null $protocolVersion = null ]) : ResponseInterface
Parameters
$path : string
$params : array<string|int, mixed>|null = null
$method : string|null = null
$body : StreamInterface|array<string|int, mixed>|string|null = null
$headers : array<string|int, mixed>|null = null
$protocolVersion : string|null = null
Tags
throws
UnauthorizedAccessException
Return values
ResponseInterface

sendRequest()

public final sendRequest(RequestInterface $request) : ResponseInterface
Parameters
$request : RequestInterface
Tags
throws
InvalidAccessTokenException
Return values
ResponseInterface

setLogger()

Sets an optional PSR-3 LoggerInterface

public final setLogger(LoggerInterface $logger) : static
Parameters
$logger : LoggerInterface
Tags
codeCoverageIgnore
Return values
static

setRequestFactory()

Sets an optional PSR-17 RequestFactoryInterface

public final setRequestFactory(RequestFactoryInterface $requestFactory) : static
Parameters
$requestFactory : RequestFactoryInterface
Tags
codeCoverageIgnore
Return values
static

setStreamFactory()

Sets an optional PSR-17 StreamFactoryInterface

public final setStreamFactory(StreamFactoryInterface $streamFactory) : static
Parameters
$streamFactory : StreamFactoryInterface
Tags
codeCoverageIgnore
Return values
static

setUriFactory()

Sets an optional PSR-17 UriFactoryInterface

public final setUriFactory(UriFactoryInterface $uriFactory) : static
Parameters
$uriFactory : UriFactoryInterface
Tags
codeCoverageIgnore
Return values
static

storeAccessToken()

Sets an access token in the current OAuthStorageInterface (shorthand/convenience)

public final storeAccessToken(AccessToken $token) : static
Parameters
$token : AccessToken
Tags
codeCoverageIgnore
Return values
static

addBasicAuthHeader()

Adds an "Authorization: Basic <base64(key:secret)>" header to the given request

protected addBasicAuthHeader(RequestInterface $request) : RequestInterface
Parameters
$request : RequestInterface
Return values
RequestInterface

cleanBodyParams()

Cleans an array of body parameters

protected cleanBodyParams(array<string, scalar|bool|null> $params) : array<string, string>
Parameters
$params : array<string, scalar|bool|null>
Return values
array<string, string>

cleanQueryParams()

Cleans an array of query parameters

protected cleanQueryParams(array<string, scalar|bool|null> $params) : array<string, string>
Parameters
$params : array<string, scalar|bool|null>
Return values
array<string, string>

construct()

A replacement constructor that you can call in extended classes, so that you don't have to implement the monstrous original `__construct()`

protected construct() : void

createAccessToken()

Creates an access token with the provider set to $this->name

protected final createAccessToken() : AccessToken
Tags
codeCoverageIgnore
Return values
AccessToken

getAccessTokenRequestBodyParams()

prepares the request body parameters for the access token request

protected getAccessTokenRequestBodyParams(string $code) : array<string, string>
Parameters
$code : string
Tags
see
OAuth2Provider::getAccessToken()
Return values
array<string, string>

getAuthorizationURLRequestParams()

prepares the query parameters for the auth URL

protected getAuthorizationURLRequestParams(array<string, scalar> $params, array<string|int, string> $scopes) : array<string, string>
Parameters
$params : array<string, scalar>
$scopes : array<string|int, string>
Tags
see
OAuth2Provider::getAuthorizationURL()
Return values
array<string, string>

getMeResponseData()

fetches the provider's "me" endpoint and returns the JSON data as an array

protected final getMeResponseData(string $endpoint[, array<string, scalar|bool|null>|null $params = null ]) : array<int|string, mixed>
Parameters
$endpoint : string
$params : array<string, scalar|bool|null>|null = null
Tags
see
UserInfo::me()
see
OAuthProvider::sendMeRequest()
see
OAuthProvider::handleMeResponseError()
throws
ProviderException
Return values
array<int|string, mixed>

getRefreshAccessTokenRequestBodyParams()

prepares the request body parameters for the token refresh

protected getRefreshAccessTokenRequestBodyParams(string $refreshToken) : array<string, string|null>
Parameters
$refreshToken : string
Tags
see
OAuth2Provider::refreshAccessToken()
Return values
array<string, string|null>

getRequestHeaders()

Prepare request headers

protected final getRequestHeaders([array<string, string>|null $headers = null ]) : array<string, string>
Parameters
$headers : array<string, string>|null = null
Return values
array<string, string>

getRequestTarget()

Determine the request target from the given URI (path segment or URL) with respect to $apiURL, anything except host and path will be ignored, scheme will always be set to "https".

protected getRequestTarget(string $uri) : string

Throws if the host of a given URL does not match the host of $apiURL.

Parameters
$uri : string
Tags
see
OAuthInterface::request()
throws
ProviderException
Return values
string

getRequestURL()

Prepares the request URL

protected final getRequestURL(string $path[, array<string, scalar|bool|null>|null $params = null ]) : string
Parameters
$path : string
$params : array<string, scalar|bool|null>|null = null
Return values
string

getTokenResponseData()

extracts the data from the access token response and returns an array with the key->value pairs contained

protected getTokenResponseData(ResponseInterface $response) : array<string, string|mixed>

we don't bother checking the content type here as it's sometimes vendor specific, not set or plain wrong: the spec mandates a JSON body which is what almost all providers send - weird exceptions:

  • mixcloud sends JSON with a "text/javascript" header
  • deezer sends form-data with a "text/html" header (???)
  • silly amazon sends gzip compressed data... (handled by decodeJSON)
Parameters
$response : ResponseInterface
Tags
see
OAuth2Provider::parseTokenResponse()
throws
JsonException
Return values
array<string, string|mixed>

handleMeResponseError()

handles errors for the `me()` endpoints - one horrible block of code to catch them all

protected final handleMeResponseError(ResponseInterface $response) : void

we could simply throw a ProviderException and be done with it, but we're nice and try to provide a message too

Parameters
$response : ResponseInterface
Tags
throws
ProviderException|UnauthorizedAccessException

parseTokenResponse()

Parses the response from a request to the token endpoint

protected parseTokenResponse(ResponseInterface $response) : AccessToken
Parameters
$response : ResponseInterface
Tags
link
https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.4
link
https://datatracker.ietf.org/doc/html/rfc6749#section-5.1
see
OAuth2Provider::getAccessToken()
see
OAuth2Provider::refreshAccessToken()
see
OAuth2Provider::getClientCredentialsToken()
throws
ProviderException
Return values
AccessToken

sendAccessTokenRequest()

sends a request to the access/refresh token endpoint $url with the given $body as form data

protected sendAccessTokenRequest(string $url, array<string, scalar|bool|null> $body) : ResponseInterface
Parameters
$url : string
$body : array<string, scalar|bool|null>
Tags
see
OAuth2Provider::getAccessToken()
see
OAuth2Provider::refreshAccessToken()
see
OAuth2Provider::getParRequestUri()
Return values
ResponseInterface

sendMeRequest()

prepares and sends the request to the provider's "me" endpoint and returns a ResponseInterface

protected sendMeRequest(string $endpoint[, array<string, scalar|bool|null>|null $params = null ]) : ResponseInterface
Parameters
$endpoint : string
$params : array<string, scalar|bool|null>|null = null
Return values
ResponseInterface

setRequestBody()

Prepares the request body and sets it in the given RequestInterface, along with a Content-Length header

protected final setRequestBody(StreamInterface|array<string, scalar|bool|null>|string $body, RequestInterface $request) : RequestInterface
Parameters
$body : StreamInterface|array<string, scalar|bool|null>|string
$request : RequestInterface
Tags
throws
ProviderException
Return values
RequestInterface 

        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results