Class SimpleID\Protocols\OAuth\Authorization

`implements`	`Storable`

An OAuth authorisation.

An OAuth authorisation permits an OAuth client to access resources with a specified scope owned by the resource owner. Authorisation codes, access and refresh tokens are issued based on this authorisation.

Within SimpleID, the owner (usually a user, but can sometimes be the client object itself) and the client must be Storable .

Each authorisation in SimpleID contains a randomly generated authorisation state. The authorisation state is stored permanently along with the authorisation. An authorisation state changes when:

a new authorisation is requested with a scope that is narrower (but not wider) than the scope stored with the authorisation
the user revokes the authorisation
a token grant (e.g. authorisation code or refresh token) is consumed
a security incident occurs

Authorisation codes, access and refresh tokens are issued based on a particular authorisation state. Therefore, if the authorisation state changes, all of these credentials are automatically revoked.

The authorisation ID is a hash of the client and owner IDs. The fully qualified authorisation ID is the authorisation ID along with the current authorisation state.

Located at core/Protocols/OAuth/Authorization.php

Methods


					
	public

__construct(
	Storable $owner,
	Storable $client,
	string|array<string> $scope = '',
	bool $issue_refresh_token = true,
	string|null $auth_state = null,
)

Creates an authorisation.

Once the authorisation is created, it needs to be stored using the \SimpleID\Store\StoreManager::save() method.

Parameters

`$owner`	the Storable object representing the resource owner
`$client`	the Storable object representing the client
`$scope`	a space-delimited string representing the scope of the authorization
`$issue_refresh_token`	whether to issue a refresh token if permitted
`$auth_state`	an existing authorisation state, or null to reset the authorisation state


					
	public

getOwner(): Storable

Returns the resource owner

Returns

the resource owner


					
	public

getClient(): Storable

Returns the client

Returns

the client


					
	protected

getStorable(string $ref, array<mixed> $args = []): Storable

Returns a Storable object based on a reference.

A reference of a Storable object is its store type (from SimpleID\Store\Storable::getStoreType()

) and its ID (from SimpleID\Store\Storable::getStoreID()

), separated by a colon.

Parameters

`$ref`	the reference to the storable object
`$args`	additional parameters

Returns

the storable object or null


					
	public

getScope(): array<string>

Returns the scope of the authorisation.

Returns

the scope of this authorisation


					
	public

setScope(string|array<string> $scope): void

Changes the scope of the authorisation.

If the new scope is narrower than the current scope (i.e contains fewer elements), then the authorisation state is reset. The new authorisation state can be obtained using the getAuthState() method.

Parameters

$scope

the new scope as a space-delimited string or an array


					
	public

hasScope(string|array<string> $scope): bool

Checks whether the authorisation covers a specified scope.

This method will return true if the authorisation covers all of the scope specified by $scope.

Parameters

$scope

the scope to test

Returns

true if the authorisation covers all of the specified scope


					
	public

filterScope(string|array<string> $scope): array<string>

Filter a scope parameter so that it is equal to or narrower than the scope authorised under this authorization.

Parameters

$scope

the scope to filter

Returns

the filtered scope


					
	public

getAuthState(): string

Returns the current authorisation state

Returns

the authorisation state


					
	public

resetAuthState(): string

Resets the current authorisation state

Returns

the new authorisation state


					
	public

getIssueRefreshToken(): bool

Returns whether a refresh token will be issued if permitted.

If this is true and the OAuth specification permits a refresh token to be issued, a refresh token ill be issued when issueCode() is called.

Returns

true a refresh token will be issued


					
	public

issueCode(string $redirect_uri, string|array<string> $scope = null, array<string, mixed> $additional = []): string

Creates an OAuth authorisation code.

Parameters

`$redirect_uri`	the redirect URI associated with the code
`$scope`	the allowed scope - this should be a subset of the scope provided by the authorisation, or null if all of the authorisation's scope is to be included
`$additional`	additional data to be stored in the code

Returns

the authorisation code


					
	public

issueTokens(
	array<string> $scope = [],
	int $expires_in = Token::TTL_PERPETUAL,
	TokenGrantType $grant = null,
	array<string, mixed> $additional = [],
): array<string, string>

Issues an access token and, if set, a refresh token.

This function calls issueAccessToken() to issue an access token. It will also call issueRefreshToken() if the authorisation was created with $issue_refresh_token set to true.

Parameters

`$scope`	the scope to be included in the tokens
`$expires_in`	the time over which the access token will be valid, in seconds, or SimpleID\Protocols\OAuth\Token::TTL_PERPETUAL if the token is not to expire
`$grant`	the grant, if any, from which the token is to be generated
`$additional`	additional data to be stored on the server for this token

Returns

an array of parameters that can be included in the OAuth token endpoint response


					
	public

issueAccessToken(
	array<string> $scope = [],
	int $expires_in = Token::TTL_PERPETUAL,
	TokenGrantType $grant = null,
	array<string, mixed> $additional = [],
): array<string, string>

Issues an access token.

Parameters

`$scope`	the scope to be included in the access token
`$expires_in`	the time over which the access token will be valid, in seconds, or SimpleID\Protocols\OAuth\Token::TTL_PERPETUAL if the token is not to expire
`$grant`	the grant, if any, from which the token is to be generated
`$additional`	additional data to be stored on the server for this token

Returns

an array of parameters that can be included in the OAuth token endpoint response


					
	protected

issueRefreshToken(
	array<string> $scope = [],
	TokenGrantType $grant = null,
	array<string, mixed> $additional = [],
): array<string, string>

Issues a refresh token.

Parameters

`$scope`	the scope to be included in the access token
`$grant`	the grant, if any, from which the token is to be generated
`$additional`	additional data to be stored on the server for this token

Returns

an array of parameters that can be included in the OAuth token endpoint response


					
	public

revokeTokensFromGrant(TokenGrantType $grant): void

Revokes all access and refresh tokens that were generated from a particular grant.

Parameters

$grant

the grant


					
	public

revokeAllTokens(): void

Revokes all access and refresh tokens for this authorisation.


					
	public

getFullyQualifiedID(): string

Returns the fully-qualified ID for this authorisation.

The fully-qualified ID for an authorisation is the authorisation state along with a hash of the owner and the client IDs.

Returns

the fully qualified ID


					
	public

getStoreType()

Returns the item type for this object

Returns

the item type

Implements

SimpleID\Store\Storable::getStoreType()


					
	public

getStoreID()

Returns the unique item ID for this object.

Returns

the ID for this object

Implements

SimpleID\Store\Storable::getStoreID()


					
	public

setStoreID($id)

Sets the unique item ID for this object

The ID should be:

unique for all items of this type; and
able to be used as a file name.

Parameters

$id

the ID for this object

Implements

SimpleID\Store\Storable::setStoreID()


					
	public
					static

buildID(Storable $owner, Storable $client): string

Builds a hash of the owner and client for identification purposes

Parameters

`$owner`	the Storable object representing the resource owner
`$client`	the Storable object representing the client

Returns

the hash

Constants
`public`		`AUTH_STATE_SEPARATOR = '.'` Separator for the authorisation ID and the authorisation state Separator for the authorisation ID and the authorisation state	#

Properties
`protected`	`string`	`$owner_ref` the type and ID of the resource owner the type and ID of the resource owner	#
`protected`	`string`	`$client_ref` the type and ID of the client the type and ID of the client	#
`protected`	`array<string>`	`$available_scope` the scope of the authorisation the scope of the authorisation	#
`protected`	`bool`	`$issue_refresh_token = true` whether refresh tokens are issued whether refresh tokens are issued	#
`public`	`array<string, mixed>`	`$additional = []` additional data to be stored with the authorization additional data to be stored with the authorization	#

Namespaces

Classes

Interfaces

Class SimpleID\Protocols\OAuth\Authorization

Parameters

Returns

Returns

Parameters

Returns

Returns

Parameters

Parameters

Returns

Parameters

Returns

Returns

Returns

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Returns

Implements

Returns

Implements

Parameters

Implements

Parameters

Returns