class OAuth2 implements FetchAuthTokenInterface (View source)

OAuth2 supports authentication by OAuth2 2-legged flows.

It primary supports

  • service account authorization
  • authorization where a user already has an access token

Constants

DEFAULT_EXPIRY_SECONDS

DEFAULT_SKEW_SECONDS

JWT_URN

STS_URN

private STS_REQUESTED_TOKEN_TYPE

Properties

static string[] $knownSigningAlgorithms

TODO: determine known methods from the keys of JWT::methods.

static string[] $knownGrantTypes

The well known grant types.

Methods

__construct(array $config)

Create a new OAuthCredentials.

null|object
verifyIdToken(string|Key|Key[] $publicKey = null, string|string[] $allowed_algs = [])

Verifies the idToken if present.

string
toJwt(array $config = [])

Obtains the encoded jwt from the instance data.

RequestInterface
generateCredentialsRequest(callable $httpHandler = null)

Generates a request for token credentials.

array
fetchAuthToken(callable $httpHandler = null)

Fetches the auth tokens based on the current state.

string
getCacheKey()

Obtains a key that can used to cache the results of #fetchAuthToken.

array
parseTokenResponse(ResponseInterface $resp)

Parses the fetched tokens.

void
updateToken(array $config)

Updates an OAuth 2.0 client.

UriInterface
buildFullAuthorizationUri(array $config = [])

Builds the authorization Uri that the user should be redirected to.

string|null
getCodeVerifier()

No description

void
setCodeVerifier(string|null $codeVerifier)

A cryptographically random string that is used to correlate the authorization request to the token request.

string
generateCodeVerifier()

Generates a random 128-character string for the "code_verifier" parameter in PKCE for OAuth 2.0. This is a cryptographically random string that is determined using random_int, hashed using "hash" and sha256, and base64 encoded.

void
setAuthorizationUri(string $uri)

Sets the authorization server's HTTP endpoint capable of authenticating the end-user and obtaining authorization.

UriInterface
getAuthorizationUri()

Gets the authorization server's HTTP endpoint capable of authenticating the end-user and obtaining authorization.

UriInterface
getTokenCredentialUri()

Gets the authorization server's HTTP endpoint capable of issuing tokens and refreshing expired tokens.

void
setTokenCredentialUri(string $uri)

Sets the authorization server's HTTP endpoint capable of issuing tokens and refreshing expired tokens.

?string
getRedirectUri()

Gets the redirection URI used in the initial request.

void
setRedirectUri(?string $uri)

Sets the redirection URI used in the initial request.

?string
getScope()

Gets the scope of the access requests as a space-delimited String.

void
setScope(string|string[]|null $scope)

Sets the scope of the access request, expressed either as an Array or as a space-delimited String.

?string
getGrantType()

Gets the current grant type.

void
setGrantType(string $grantType)

Sets the current grant type.

string
getState()

Gets an arbitrary string designed to allow the client to maintain state.

void
setState(string $state)

Sets an arbitrary string designed to allow the client to maintain state.

string
getCode()

Gets the authorization code issued to this client.

void
setCode(string $code)

Sets the authorization code issued to this client.

string
getUsername()

Gets the resource owner's username.

void
setUsername(string $username)

Sets the resource owner's username.

string
getPassword()

Gets the resource owner's password.

void
setPassword(string $password)

Sets the resource owner's password.

string
getClientId()

Sets a unique identifier issued to the client to identify itself to the authorization server.

void
setClientId(string $clientId)

Sets a unique identifier issued to the client to identify itself to the authorization server.

string
getClientSecret()

Gets a shared symmetric secret issued by the authorization server, which is used to authenticate the client.

void
setClientSecret(string $clientSecret)

Sets a shared symmetric secret issued by the authorization server, which is used to authenticate the client.

?string
getIssuer()

Gets the Issuer ID when using assertion profile.

void
setIssuer(string $issuer)

Sets the Issuer ID when using assertion profile.

?string
getSub()

Gets the target sub when issuing assertions.

void
setSub(string $sub)

Sets the target sub when issuing assertions.

?string
getAudience()

Gets the target audience when issuing assertions.

void
setAudience(string $audience)

Sets the target audience when issuing assertions.

?string
getSigningKey()

Gets the signing key when using an assertion profile.

void
setSigningKey(string $signingKey)

Sets the signing key when using an assertion profile.

?string
getSigningKeyId()

Gets the signing key id when using an assertion profile.

void
setSigningKeyId(string $signingKeyId)

Sets the signing key id when using an assertion profile.

?string
getSigningAlgorithm()

Gets the signing algorithm when using an assertion profile.

void
setSigningAlgorithm(?string $signingAlgorithm)

Sets the signing algorithm when using an assertion profile.

array
getExtensionParams()

Gets the set of parameters used by extension when using an extension grant type.

void
setExtensionParams(array $extensionParams)

Sets the set of parameters used by extension when using an extension grant type.

int
getExpiry()

Gets the number of seconds assertions are valid for.

void
setExpiry(int $expiry)

Sets the number of seconds assertions are valid for.

int
getExpiresIn()

Gets the lifetime of the access token in seconds.

void
setExpiresIn(?int $expiresIn)

Sets the lifetime of the access token in seconds.

?int
getExpiresAt()

Gets the time the current access token expires at.

bool
isExpired()

Returns true if the acccess token has expired.

void
setExpiresAt(int $expiresAt)

Sets the time the current access token expires at.

?int
getIssuedAt()

Gets the time the current access token was issued at.

void
setIssuedAt(int $issuedAt)

Sets the time the current access token was issued at.

?string
getAccessToken()

Gets the current access token.

void
setAccessToken(string $accessToken)

Sets the current access token.

?string
getIdToken()

Gets the current ID token.

void
setIdToken(string $idToken)

Sets the current ID token.

string|null
getGrantedScope()

Get the granted space-separated scopes (if they exist) for the last fetched token.

void
setGrantedScope(string $grantedScope)

Sets the current ID token.

?string
getRefreshToken()

Gets the refresh token associated with the current access token.

void
setRefreshToken(string $refreshToken)

Sets the refresh token associated with the current access token.

void
setAdditionalClaims(array $additionalClaims)

Sets additional claims to be included in the JWT token

array
getAdditionalClaims()

Gets the additional claims to be included in the JWT token.

?string
getIssuedTokenType()

Gets the additional claims to be included in the JWT token.

null|array
getLastReceivedToken()

The expiration of the last received token.

Details

__construct(array $config)

Create a new OAuthCredentials.

The configuration array accepts various options

  • authorizationUri The authorization server's HTTP endpoint capable of authenticating the end-user and obtaining authorization.

  • tokenCredentialUri The authorization server's HTTP endpoint capable of issuing tokens and refreshing expired tokens.

  • clientId A unique identifier issued to the client to identify itself to the authorization server.

  • clientSecret A shared symmetric secret issued by the authorization server, which is used to authenticate the client.

  • scope The scope of the access request, expressed either as an Array or as a space-delimited String.

  • state An arbitrary string designed to allow the client to maintain state.

  • redirectUri The redirection URI used in the initial request.

  • username The resource owner's username.

  • password The resource owner's password.

  • issuer Issuer ID when using assertion profile

  • audience Target audience for assertions

  • expiry Number of seconds assertions are valid for

  • signingKey Signing key when using assertion profile

  • signingKeyId Signing key id when using assertion profile

  • refreshToken The refresh token associated with the access token to be refreshed.

  • accessToken The current access token for this client.

  • idToken The current ID token for this client.

  • extensionParams When using an extension grant type, this is the set of parameters used by that extension.

  • codeVerifier The code verifier for PKCE for OAuth 2.0.

  • resource The target service or resource where the client ntends to use the requested security token.

  • subjectTokenFetcher A fetcher for the "subject_token", which is a security token that represents the identity of the party on behalf of whom the request is being made.

  • subjectTokenType An identifier that indicates the type of the security token in the subjectToken parameter.

  • actorToken A security token that represents the identity of the acting party.

  • actorTokenType An identifier for the representation of the issued security token.

Parameters

array $config

Configuration array

null|object verifyIdToken(string|Key|Key[] $publicKey = null, string|string[] $allowed_algs = [])

Verifies the idToken if present.

  • if none is present, return null
  • if present, but invalid, raises DomainException.
  • otherwise returns the payload in the idtoken as a PHP object.

The behavior of this method varies depending on the version of firebase/php-jwt you are using. In versions 6.0 and above, you cannot provide multiple $allowed_algs, and instead must provide an array of Key objects as the $publicKey.

Parameters

string|Key|Key[] $publicKey

The public key to use to authenticate the token

string|string[] $allowed_algs

algorithm or array of supported verification algorithms. Providing more than one algorithm will throw an exception.

Return Value

null|object

Exceptions

DomainException
DomainException
UnexpectedValueException
InvalidArgumentException
SignatureInvalidException
BeforeValidException
ExpiredException

string toJwt(array $config = [])

Obtains the encoded jwt from the instance data.

Parameters

array $config

array optional configuration parameters

Return Value

string

RequestInterface generateCredentialsRequest(callable $httpHandler = null)

Generates a request for token credentials.

Parameters

callable $httpHandler

callback which delivers psr7 request

Return Value

RequestInterface

the authorization Url.

array fetchAuthToken(callable $httpHandler = null)

Fetches the auth tokens based on the current state.

Parameters

callable $httpHandler

callback which delivers psr7 request

Return Value

array

a hash of auth tokens

string getCacheKey()

Obtains a key that can used to cache the results of #fetchAuthToken.

The key is derived from the scopes.

Return Value

string

a key that may be used to cache the auth token.

array parseTokenResponse(ResponseInterface $resp)

Parses the fetched tokens.

Parameters

ResponseInterface $resp

the response.

Return Value

array

the tokens parsed from the response body.

Exceptions

Exception

void updateToken(array $config)

Updates an OAuth 2.0 client.

Example:

$oauth->updateToken([
    'refresh_token' => 'n4E9O119d',
    'access_token' => 'FJQbwq9',
    'expires_in' => 3600
]);

Parameters

array $config

The configuration parameters related to the token.

  • refresh_token The refresh token associated with the access token to be refreshed.

  • access_token The current access token for this client.

  • id_token The current ID token for this client.

  • expires_in The time in seconds until access token expiration.

  • expires_at The time as an integer number of seconds since the Epoch

  • issued_at The timestamp that the token was issued at.

Return Value

void

UriInterface buildFullAuthorizationUri(array $config = [])

Builds the authorization Uri that the user should be redirected to.

Parameters

array $config

configuration options that customize the return url.

Return Value

UriInterface

the authorization Url.

Exceptions

InvalidArgumentException

string|null getCodeVerifier()

No description

Return Value

string|null

void setCodeVerifier(string|null $codeVerifier)

A cryptographically random string that is used to correlate the authorization request to the token request.

The code verifier for PKCE for OAuth 2.0. When set, the authorization URI will contain the Code Challenge and Code Challenge Method querystring parameters, and the token URI will contain the Code Verifier parameter.

Parameters

string|null $codeVerifier

Return Value

void

See also

https://datatracker.ietf.org/doc/html/rfc7636

string generateCodeVerifier()

Generates a random 128-character string for the "code_verifier" parameter in PKCE for OAuth 2.0. This is a cryptographically random string that is determined using random_int, hashed using "hash" and sha256, and base64 encoded.

When this method is called, the code verifier is set on the object.

Return Value

string

void setAuthorizationUri(string $uri)

Sets the authorization server's HTTP endpoint capable of authenticating the end-user and obtaining authorization.

Parameters

string $uri

Return Value

void

UriInterface getAuthorizationUri()

Gets the authorization server's HTTP endpoint capable of authenticating the end-user and obtaining authorization.

Return Value

UriInterface

UriInterface getTokenCredentialUri()

Gets the authorization server's HTTP endpoint capable of issuing tokens and refreshing expired tokens.

Return Value

UriInterface

void setTokenCredentialUri(string $uri)

Sets the authorization server's HTTP endpoint capable of issuing tokens and refreshing expired tokens.

Parameters

string $uri

Return Value

void

?string getRedirectUri()

Gets the redirection URI used in the initial request.

Return Value

?string

void setRedirectUri(?string $uri)

Sets the redirection URI used in the initial request.

Parameters

?string $uri

Return Value

void

?string getScope()

Gets the scope of the access requests as a space-delimited String.

Return Value

?string

void setScope(string|string[]|null $scope)

Sets the scope of the access request, expressed either as an Array or as a space-delimited String.

Parameters

string|string[]|null $scope

Return Value

void

Exceptions

InvalidArgumentException

?string getGrantType()

Gets the current grant type.

Return Value

?string

void setGrantType(string $grantType)

Sets the current grant type.

Parameters

string $grantType

Return Value

void

Exceptions

InvalidArgumentException

string getState()

Gets an arbitrary string designed to allow the client to maintain state.

Return Value

string

void setState(string $state)

Sets an arbitrary string designed to allow the client to maintain state.

Parameters

string $state

Return Value

void

string getCode()

Gets the authorization code issued to this client.

Return Value

string

void setCode(string $code)

Sets the authorization code issued to this client.

Parameters

string $code

Return Value

void

string getUsername()

Gets the resource owner's username.

Return Value

string

void setUsername(string $username)

Sets the resource owner's username.

Parameters

string $username

Return Value

void

string getPassword()

Gets the resource owner's password.

Return Value

string

void setPassword(string $password)

Sets the resource owner's password.

Parameters

string $password

Return Value

void

string getClientId()

Sets a unique identifier issued to the client to identify itself to the authorization server.

Return Value

string

void setClientId(string $clientId)

Sets a unique identifier issued to the client to identify itself to the authorization server.

Parameters

string $clientId

Return Value

void

string getClientSecret()

Gets a shared symmetric secret issued by the authorization server, which is used to authenticate the client.

Return Value

string

void setClientSecret(string $clientSecret)

Sets a shared symmetric secret issued by the authorization server, which is used to authenticate the client.

Parameters

string $clientSecret

Return Value

void

?string getIssuer()

Gets the Issuer ID when using assertion profile.

Return Value

?string

void setIssuer(string $issuer)

Sets the Issuer ID when using assertion profile.

Parameters

string $issuer

Return Value

void

?string getSub()

Gets the target sub when issuing assertions.

Return Value

?string

void setSub(string $sub)

Sets the target sub when issuing assertions.

Parameters

string $sub

Return Value

void

?string getAudience()

Gets the target audience when issuing assertions.

Return Value

?string

void setAudience(string $audience)

Sets the target audience when issuing assertions.

Parameters

string $audience

Return Value

void

?string getSigningKey()

Gets the signing key when using an assertion profile.

Return Value

?string

void setSigningKey(string $signingKey)

Sets the signing key when using an assertion profile.

Parameters

string $signingKey

Return Value

void

?string getSigningKeyId()

Gets the signing key id when using an assertion profile.

Return Value

?string

void setSigningKeyId(string $signingKeyId)

Sets the signing key id when using an assertion profile.

Parameters

string $signingKeyId

Return Value

void

?string getSigningAlgorithm()

Gets the signing algorithm when using an assertion profile.

Return Value

?string

void setSigningAlgorithm(?string $signingAlgorithm)

Sets the signing algorithm when using an assertion profile.

Parameters

?string $signingAlgorithm

Return Value

void

array getExtensionParams()

Gets the set of parameters used by extension when using an extension grant type.

Return Value

array

void setExtensionParams(array $extensionParams)

Sets the set of parameters used by extension when using an extension grant type.

Parameters

array $extensionParams

Return Value

void

int getExpiry()

Gets the number of seconds assertions are valid for.

Return Value

int

void setExpiry(int $expiry)

Sets the number of seconds assertions are valid for.

Parameters

int $expiry

Return Value

void

int getExpiresIn()

Gets the lifetime of the access token in seconds.

Return Value

int

void setExpiresIn(?int $expiresIn)

Sets the lifetime of the access token in seconds.

Parameters

?int $expiresIn

Return Value

void

?int getExpiresAt()

Gets the time the current access token expires at.

Return Value

?int

bool isExpired()

Returns true if the acccess token has expired.

Return Value

bool

void setExpiresAt(int $expiresAt)

Sets the time the current access token expires at.

Parameters

int $expiresAt

Return Value

void

?int getIssuedAt()

Gets the time the current access token was issued at.

Return Value

?int

void setIssuedAt(int $issuedAt)

Sets the time the current access token was issued at.

Parameters

int $issuedAt

Return Value

void

?string getAccessToken()

Gets the current access token.

Return Value

?string

void setAccessToken(string $accessToken)

Sets the current access token.

Parameters

string $accessToken

Return Value

void

?string getIdToken()

Gets the current ID token.

Return Value

?string

void setIdToken(string $idToken)

Sets the current ID token.

Parameters

string $idToken

Return Value

void

string|null getGrantedScope()

Get the granted space-separated scopes (if they exist) for the last fetched token.

Return Value

string|null

void setGrantedScope(string $grantedScope)

Sets the current ID token.

Parameters

string $grantedScope

Return Value

void

?string getRefreshToken()

Gets the refresh token associated with the current access token.

Return Value

?string

void setRefreshToken(string $refreshToken)

Sets the refresh token associated with the current access token.

Parameters

string $refreshToken

Return Value

void

void setAdditionalClaims(array $additionalClaims)

Sets additional claims to be included in the JWT token

Parameters

array $additionalClaims

Return Value

void

array getAdditionalClaims()

Gets the additional claims to be included in the JWT token.

Return Value

array

?string getIssuedTokenType()

Gets the additional claims to be included in the JWT token.

Return Value

?string

null|array getLastReceivedToken()

The expiration of the last received token.

Return Value

null|array

{ The last received access token.

@type string $access_token The access token string.
@type int $expires_at The time the token expires as a UNIX timestamp.

}