Constants

STATE

STATE

API_TOKEN

API_TOKEN

DEFAULT_SCOPE

DEFAULT_SCOPE

IDENTITY_TOKEN

IDENTITY_TOKEN

CODE_REQUESTED

CODE_REQUESTED

CODE_PROVIDED

CODE_PROVIDED

TOKEN_REQUESTED

TOKEN_REQUESTED

TOKEN_PROVIDED

TOKEN_PROVIDED

NEGOTIATION_COMPLETE

NEGOTIATION_COMPLETE

NEGOTIATION_FAILED

NEGOTIATION_FAILED

SESSION

SESSION

OAUTH_ENDPOINT

OAUTH_ENDPOINT

API_URL

API_URL

CLIENT_ID

CLIENT_ID

CLIENT_SECRET

CLIENT_SECRET

CODE

CODE

ERROR

ERROR

RESPONSE_TYPE

RESPONSE_TYPE

REDIRECT_URI

REDIRECT_URI

SCOPES

SCOPES

LANDING_PAGE

LANDING_PAGE

PURPOSE

PURPOSE

SCOPE

SCOPE

IDENTITY

IDENTITY

API

API

TOKEN

TOKEN

USER

USER

IS_API_TOKEN

IS_API_TOKEN

Properties

$SCOPES

$SCOPES : 

Type

$ready

$ready : boolean

Type

boolean — Is the token ready yet?

$apiUrl

$apiUrl : string

Type

string — The URL of the API

$token

$token : string

Type

string — The token provided via OAuth

$isApiToken

$isApiToken : boolean

Type

boolean — The token provides authenticated access to the API

$error

$error : string|null

Type

string|null — Any errors returned explaining why we might be "ready" but not have a token

Methods

__construct()

__construct(string  $OAuthEndpoint = null, string  $clientId = null, string  $clientSecret = null, string  $landingPage = false, string  $purpose = null, string  $APIEndpoint = false, string  $scopes = self::DEFAULT_SCOPE, string  $responseType = 'code',   $redirectURI = null) : void

Construct OAuthNegotiator to start (or continue) OAuth authentication negotiations

Parameters

string $OAuthEndpoint

(Optional) URI of the OAuth authentication endpoint (e.g. 'https:///login/oauth2') -- required on first instantiation

string $clientId

(Optional) A unique client ID for the application requesting authentication (usually some terrible hash or serial number) -- required on first instantiation

string $clientSecret

(Optional) A shared secret key between this application and the OAuth server -- required on first instantiation

string $landingPage

(Optional) URI to land at after OAuth is negotiated (defaults to $_SERVER[PHP_SELF])

string $purpose

(Optional) How this authentication token will be used (defaults to $_SERVER[PHP_SELF])

string $APIEndpoint

(Optional) URI of the API endpoint (e.g. 'https:///api/vi', defaults to str_replace('/login/oauth2', '/api/v1', $OAuthEndpoint))

string $scopes

(Optional) The scope of this authentication (defaults to API token request)

string $responseType

(Optional) Type of response expected from OAuth server (defaults to 'code')

$redirectURI

Throws

\OAuthNegotiator_Exception

OAUTH_ENDPOINT if $OAuthEndpoint is empty or not provided

\OAuthNegotiator_Exception

CLIENT_ID if $clientId is empty or not provided

\OAuthNegotiator_Exception

CLIENT_SECRET if $clientSecret is empty or not provided

\OAuthNegotiator_Exception

STATE_MISMATCH if $_REQUEST[state] does not align with $_SESSION[SESSION][STATE]

isReady()

isReady() : boolean

Is the OAuth negotiation complete?

Returns

boolean —

TRUE if negotiations have finished, FALSE if they are ongoing

isIdentityToken()

isIdentityToken() : boolean

Returns

boolean —

TRUE if OAuth negoation is complete and resulted in an identy token (FALSE if negotiations are onging or the token is an API access token)

isAPIToken()

isAPIToken() : boolean

Returns

boolean —

TRUE if OAuth negotation is complete and resulted in an API access token (FALSE if negotations are ongoing or the token is an identity token)

getApiUrl()

getApiUrl() : string|boolean|null

Returns

string|boolean|null —

URL of the API (if any) if OAuth negotiation is complete (FALSE if ongoing)

getToken()

getToken() : string|boolean|null

Returns

string|boolean|null —

OAuth token (if any) if OAuth negotiation is complete (FALSE if ongoing)

getError()

getError() : string|boolean|null

Returns

string|boolean|null —

Error (if any) that ended the OAuth negotiation (FALSE if negotiation is ongoing)

constructStateless()

constructStateless(string  $OAuthEndpoint, string  $clientId, string  $clientSecret, string  $landingPage = false, string  $purpose = null, string  $APIEndpoint = false, string  $scopes = self::DEFAULT_SCOPE, string  $responseType = 'code',   $redirectURI = null) 

Construct a "stateless" (i.e. unstarted) OAuthNegotiator

Parameters

string $OAuthEndpoint

URI of the OAuth authentication endpoint (e.g. 'https:///login/oauth2')

string $clientId

A unique client ID for the application requesting authentication (usually some terrible hash or serial number)

string $clientSecret

A shared secret key between this application and the OAuth server

string $landingPage

optional URI to land at after OAuth is negotiated (defaults to $_SERVER[PHP_SELF])

string $purpose

optional How this authentication token will be used (defaults to $_SERVER[PHP_SELF])

string $APIEndpoint

optional URI of the API endpoint (e.g. 'https:///api/vi', defaults to str_replace('/login/oauth2', '/api/v1', $OAuthEndpoint))

string $scopes

optional The scope of this authentication (defaults to API token request)

string $responseType

optional Type of response expected from OAuth server (defaults to 'code')

$redirectURI

Throws

\OAuthNegotiator_Exception

OAUTH_ENDPOINT if $OAuthEndpoint is empty or not provided

\OAuthNegotiator_Exception

CLIENT_ID if $clientId is empty or not provided

\OAuthNegotiator_Exception

CLIENT_SECRET if $clientSecret is empty or not provided

constructIdentityToken()

constructIdentityToken() : void

Construct an OAuthNegotiator to use an access code to request an identity token

Throws

\OAuthNegotiator_Exception

CODE_RESPONSE if the prior request for an authorization token resulted in neither an authorization code or an erro (weird!)

constructAPIToken()

constructAPIToken() : void

Construct an OAuthNegotiator to use an access code to request an API Token with matching user profile

Throws

\OAuthNegotiator_Exception

CODE_RESPONSE if the prior request for an authorization token resulted in neither an authorization code or an error (weird!)

\OAuthNegotatior_Exception

USER_RESPONSE if a user profile cannot be acquired to match the API access token (i.e. the OAuth server is probably not a Canvas instance)

constructNegotiationReporter()

constructNegotiationReporter() : void

Prepare to report on the results of the OAuth negotiation

requestAuthorizationCode()

requestAuthorizationCode(string  $responseType, string  $scopes, string  $purpose) : void

Request an authorization code from the OAuth server

Parameters

string $responseType

Always 'code'

string $scopes

The type of token for which we need an authorization code (IDENTITY_TOKEN|API_TOKEN)

string $purpose

User-readable description of the purpose for which this token will be used

requestToken()

requestToken(string  $code, string  $tokenType) : void

Request a token from the OAuth server

Parameters

string $code

An authorization code provided by the OAuth server

string $tokenType

Type of token being requested (IDENTITY_TOKEN|API_TOKEN)

Throws

\OAuthNegotiator_Exception

TOKEN_RESPONSE if a token no token is received or on any other uanticipated response from the OAuth server