OpenID

About 9 min

OpenID

OAuth short summary.

OAuth description.

Full name: \Hazaar\Auth\Adapter\OpenID
Parent class: \Hazaar\Auth\Adapter\OAuth2

Methods

__construct

Construct the adapter.

public __construct(string $clientID, string $clientSecret, string $grantType = &#039;code&#039;, ?\Hazaar\Map $config = null): mixed

Parameters:

Parameter	Type	Description
`$clientID`	string
`$clientSecret`	string
`$grantType`	string
`$config`	?\Hazaar\Map	The configuration options

setLogoutURI

Sets the URI for the logout endpoint.

public setLogoutURI(string $uri): void

This method updates the metadata to include the specified URI as the endpoint for ending a session.

Parameters:

Parameter	Type	Description
`$uri`	string	the URI to be set as the logout endpoint

getProfile

Retrieves the user profile from the OAuth2 data stored in the session.

public getProfile(): null|\stdClass

This method checks if the 'oauth2_data' is present in the storage and if it is an instance of \stdClass with a property 'id_token'. If these conditions are met, it decodes the 'id_token' and returns the decoded JSON object representing the user profile.

Return Value:

the user profile as a \stdClass object, or null if the profile cannot be retrieved

logout

Logs out the user by clearing the session and redirecting to the OpenID end session endpoint.

public logout(null|string $redirect_url = null): bool|\Hazaar\HTTP\URL

Parameters:

Parameter	Type	Description
`$redirect_url`	null\|string	optional URL to redirect to after logout

Return Value:

returns the URL object for the end session endpoint if successful, or false on failure

Inherited methods

__construct

Construct the adapter.

public __construct(string $clientID, string $clientSecret, string $grantType = &#039;code&#039;, array|\Hazaar\Map $config = []): mixed

Parameters:

Parameter	Type	Description
`$clientID`	string
`$clientSecret`	string
`$grantType`	string
`$config`	array\|\Hazaar\Map	The configuration options

setIdentity

Sets the identity for the authentication adapter.

public setIdentity(string $identity): void

Parameters:

Parameter	Type	Description
`$identity`	string	the identity to be set

setCredential

Sets the credential for authentication.

public setCredential(string $credential): void

Parameters:

Parameter	Type	Description
`$credential`	string	the credential to be set

getIdentity

Retrieves the identity of the current user.

public getIdentity(): null|string

Return Value:

the identity of the user, or null if not set

getCredentialHash

Get the encrypted hash of a credential/password.

public getCredentialHash(?string $credential = null): ?string

This method uses the "encryption" options from the application configuration to generate a password hash based on the supplied password. If no password is supplied then the currently set credential is used.

NOTE: Keep in mind that if no credential is set, or it's null, or an empty string, this will still return a valid hash of that empty value using the defined encryption hash chain.

Parameters:

Parameter	Type	Description
`$credential`	?string

authenticate

Authenticate the user credentials using the OAuth2 "password" grant type.

public authenticate(string $identity = null, string $credential = null, bool $autologin = false, bool $skip_auth_check = false): bool

Parameters:

Parameter	Type	Description
`$identity`	string	the user identity (username)
`$credential`	string	the user credential (password)
`$autologin`	bool	The autologin flag. If checked the session will be remembered and the refresh token used to obtain a new access token when it expires.
`$skip_auth_check`	bool

Return Value:

True if the authentication was successful. False otherwise.

authenticateRequest

Authenticates an HTTP request using Basic Authentication.

public authenticateRequest(\Hazaar\Application\Request $request): bool

This method checks if the request contains a valid 'Authorization' header with Basic Authentication credentials. It decodes the credentials and verifies them using the authenticate method.

Parameters:

Parameter	Type	Description
`$request`	\Hazaar\Application\Request	the HTTP request to authenticate

Return Value:

returns true if the request is authenticated successfully, false otherwise

Throws:

if the authentication fails

Unauthorised

authenticated

Check if there is a current user authentication in the session namespace.

public authenticated(): bool

Returns true if we have an access token. False otherwise.

Return Value:

true if the user is authenticated, false otherwise

check

Check that the supplied password is correct for the current identity.

public check(string $credential): bool

This is useful for checking an account password before allowing something important to be updated. This does the same steps as authenticate() but doesn't actually do the authentication.

Parameters:

Parameter	Type	Description
`$credential`	string

clear

Clears the authentication storage.

public clear(): bool

This method checks if the storage is empty. If it is not empty, it clears the storage and returns true. If the storage is already empty, it returns false.

Return Value:

returns true if the storage was cleared, false if the storage was already empty

unauthorised

Helper method that sets the basic auth header and throws an unauthorised exception.

public unauthorised(): void

disableCredentialHashing

Toggles on/off the internal credential hashing algorithm.

public disableCredentialHashing(bool $value = true): void

This is useful is you want to authenticate with an already hashed credential.

WARNING: This should NOT normally be used. And if it IS used, it should only be used to authenticate credentials supplied internally by the application itself, and not provided by a user/client/etc. Disabling password hash essentially turns this all into clear text credentials.

Parameters:

Parameter	Type	Description
`$value`	bool

get

Retrieves a value from the storage based on the provided key.

public get(string $key): mixed

Parameters:

Parameter	Type	Description
`$key`	string	the key used to retrieve the value from the storage

Return Value:

the value associated with the provided key

set

Sets a value in the storage with the specified key.

public set(string $key, mixed $value): void

Parameters:

Parameter	Type	Description
`$key`	string	the key under which the value will be stored
`$value`	mixed	the value to be stored

has

Checks if a given key exists in the storage.

public has(string $key): bool

Parameters:

Parameter	Type	Description
`$key`	string	the key to check for existence in the storage

Return Value:

returns true if the key exists, false otherwise

unset

public unset(string $key): void

Parameters:

Parameter	Type	Description
`$key`	string

offsetExists

public offsetExists(mixed $offset): bool

Parameters:

Parameter	Type	Description
`$offset`	mixed

offsetGet

public offsetGet(mixed $offset): mixed

Parameters:

Parameter	Type	Description
`$offset`	mixed

offsetSet

public offsetSet(mixed $offset, mixed $value): void

Parameters:

Parameter	Type	Description
`$offset`	mixed
`$value`	mixed

offsetUnset

public offsetUnset(mixed $offset): void

Parameters:

Parameter	Type	Description
`$offset`	mixed

getAuthData

Retrieves authentication data from the storage.

public getAuthData(): array&lt;string,mixed&gt;

Return Value:

the authentication data

getToken

Retrieves the OAuth2 token from the storage.

public getToken(): null|array{token: string}

This method returns an associative array containing the 'access_token' from the 'oauth2_data' stored in the class. If the 'access_token' is not present, it returns null.

Return Value:

an associative array with the 'access_token' or null if not found

setStorageAdapter

Sets the storage adapter for authentication.

public setStorageAdapter(string $storage, array&lt;string,mixed&gt;|\Hazaar\Map $options = []): bool

Parameters:

Parameter	Type	Description
`$storage`	string	the name of the storage adapter to use
`$options`	array<string,mixed>\|\Hazaar\Map	optional configuration options for the storage adapter

Return Value:

returns true if the storage adapter was successfully set

Throws:

if the specified storage adapter class does not exist

UnknownStorageAdapter

getIdentifier

Generates a hashed identifier for the given identity string.

protected getIdentifier(string $identity): null|string

This method takes an identity string and returns its SHA-1 hash. If the identity string is empty or null, the method returns null.

Parameters:

Parameter	Type	Description
`$identity`	string	the identity string to be hashed

Return Value:

the SHA-1 hash of the identity string, or null if the identity is empty

setDataFields

Set the extra data fields.

protected setDataFields(string[] $fields): void

Parameters:

Parameter	Type	Description
`$fields`	string[]	The extra data fields

authenticationSuccess

Overload function called when a user is successfully authenticated.

protected authenticationSuccess(string $identity, array $data): void

This can occur when calling authenticate() or authenticated() where a session has been saved. This default method does nothing but can be overridden.

Parameters:

Parameter	Type	Description
`$identity`	string	The identity that was successfully authenticated
`$data`	array	The data returned from the authentication query

authenticationFailure

Overload function called when a user fails authentication.

protected authenticationFailure(string $identity, array $data): void

This can occur when calling authenticate() or authenticated() where a session has been saved. This default method does nothing but can be overridden.

Parameters:

Parameter	Type	Description
`$identity`	string	the identity that failed authentication
`$data`	array	the data returned from the authentication query

setAuthURI

Sets the authorization endpoint URI for OAuth2 authentication.

public setAuthURI(string $uri): void

Parameters:

Parameter	Type	Description
`$uri`	string	the URI of the authorization endpoint

setTokenURI

Sets the URI for the token endpoint.

public setTokenURI(string $uri): void

Parameters:

Parameter	Type	Description
`$uri`	string	the URI to be set for the token endpoint

setRegistrationURI

Sets the registration URI for the OAuth2 metadata.

public setRegistrationURI(string $uri): void

This method updates the 'registration_endpoint' key in the metadata array with the provided URI.

Parameters:

Parameter	Type	Description
`$uri`	string	the registration URI to be set

setIntrospectURI

Sets the URI for the introspection endpoint.

public setIntrospectURI(string $uri): void

This method updates the metadata to include the provided URI for the introspection endpoint, which is used to validate access tokens.

Parameters:

Parameter	Type	Description
`$uri`	string	the URI of the introspection endpoint

setRevokeURI

Sets the URI for the revocation endpoint.

public setRevokeURI(string $uri): void

This method allows you to specify the URI that will be used to revoke OAuth2 tokens.

Parameters:

Parameter	Type	Description
`$uri`	string	the URI of the revocation endpoint

setUserinfoURI

Sets the URI for the user info endpoint in the OAuth2 metadata.

public setUserinfoURI(string $uri): void

Parameters:

Parameter	Type	Description
`$uri`	string	the URI of the user info endpoint

setAuthenticateCallback

Sets the callback function to be used for authentication.

public setAuthenticateCallback(\Closure $cb): void

Parameters:

Parameter	Type	Description
`$cb`	\Closure	the callback function to be used for authentication

discover

Discover OAuth2 metadata from a given URI.

public discover(string $uri): bool

This method attempts to retrieve and cache OAuth2 metadata from the specified URI. If the metadata is not already cached, it fetches the metadata from the URI and stores it. If the URI cannot be accessed, an exception is thrown.

Parameters:

Parameter	Type	Description
`$uri`	string	the URI to discover OAuth2 metadata from

Return Value:

returns true on successful discovery

Throws:

if the authentication platform is offline or service discovery fails

Exception

addScope

Adds one or more scopes to the OAuth2 authorization.

public addScope(): void

This method accepts a variable number of arguments. Each argument can be a string representing a single scope or an array of scopes. If an array is provided, the method will recursively add each scope in the array.

hasScope

Checks if the authenticated user has a specific scope.

public hasScope(string $key): bool

This method verifies if the user is authenticated and if the specified scope key exists within the user's scopes.

Parameters:

Parameter	Type	Description
`$key`	string	the scope key to check

Return Value:

returns true if the user is authenticated and has the specified scope, false otherwise

scopes

Get the current scopes for this OAuth2 adapter.

public scopes(): string[]

refresh

Refreshes the OAuth2 token.

public refresh(null|string $token = null, null|string $identity = null, null|string $credential = null): bool

This method attempts to refresh the OAuth2 token using the provided refresh token, identity, and credential. If no token is provided, it will attempt to retrieve a refresh token using the getRefreshToken method. The method sends a POST request to the token endpoint with the necessary parameters to obtain a new access token.

Parameters:

Parameter	Type	Description
`$token`	null\|string	the refresh token to use for refreshing the access token
`$identity`	null\|string	the identity (username) to use for authentication
`$credential`	null\|string	the credential (password) to use for authentication

Return Value:

returns true if the token was successfully refreshed and authorized, false otherwise

Throws:

if there is no token endpoint set for this auth adapter

Exception

getAccessToken

Retrieves the OAuth2 access token.

public getAccessToken(): bool|string

This method checks if the 'oauth2_data' key exists in the storage. If it exists, it returns the 'access_token' from the 'oauth2_data'. Otherwise, it returns false.

Return Value:

the access token if available, otherwise false

getRefreshToken

Retrieves the refresh token from the OAuth2 data storage.

public getRefreshToken(): bool|string

This method checks if the 'oauth2_data' key exists in the storage. If it does, it attempts to retrieve the 'refresh_token' from the 'oauth2_data' array. If the 'refresh_token' is not found, it returns false.

Return Value:

returns the refresh token if available, otherwise false

queryAuth

Query the authentication adapter.

public queryAuth(string $identity, array $extra = []): array|bool

Parameters:

Parameter	Type	Description
`$identity`	string	The identity
`$extra`	array

getTokenType

Retrieves the token type from the OAuth2 data storage.

public getTokenType(): string

This method accesses the 'oauth2_data' array within the storage and returns the value associated with the 'token_type' key. If the 'token_type' key does not exist, it defaults to returning 'Bearer'.

Return Value:

the token type, defaulting to 'Bearer' if not specified

introspect

Introspects the given token using the OAuth2 introspection endpoint.

public introspect(null|string $token = null, string $token_type = &#039;access_token&#039;): bool|string

Parameters:

Parameter	Type	Description
`$token`	null\|string	The token to introspect. If null, the access token from storage will be used.
`$token_type`	string	the type of the token, default is 'access_token'

Return Value:

the response body from the introspection endpoint, or false if the endpoint is not available

revoke

Revokes the OAuth2 access token.

public revoke(): bool|string

This method sends a revocation request to the OAuth2 server's revocation endpoint. It constructs a POST request with the client ID and access token, and sends it using the HTTP client. The response from the server is then checked for a result.

Return Value:

Returns false if the revocation endpoint is not found or if the revocation fails. Returns the result from the server's response body if the revocation is successful.

userinfo

Retrieves user information from the OAuth2 user info endpoint.

public userinfo(): bool|string

This method sends a GET request to the user info endpoint specified in the metadata. If the endpoint is not available or the request fails, it returns false. Otherwise, it returns the response body containing the user information.

Return Value:

returns the user information as a string on success, or false on failure

authorize

Authorizes the OAuth2 data by validating the required properties and storing the data.

private authorize(\stdClass $data): bool

Parameters:

Parameter	Type	Description
`$data`	\stdClass	the OAuth2 data object containing token information

Return Value:

returns true if the data contains valid OAuth2 token information, otherwise false

authenticateCredentials

Authenticates user credentials against an OAuth2 token endpoint.

private authenticateCredentials(string $identity, string $credential, string $grantType = &#039;password&#039;, null|string $scope = null): bool|\stdClass

Parameters:

Parameter	Type	Description
`$identity`	string	The user's identity (e.g., username or email).
`$credential`	string	The user's credential (e.g., password).
`$grantType`	string	The type of grant being requested. Defaults to 'password'.
`$scope`	null\|string	optional scope of the access request

Return Value:

returns a stdClass object containing the token information if authentication is successful, or false otherwise

authenticateCode

Authenticates the user using the OAuth2 authorization code flow.

private authenticateCode(): bool|\stdClass

This method handles the OAuth2 authorization code flow by performing the following steps:

Checks if an authorization code is present in the request.
Validates the state parameter to prevent CSRF attacks.
Sends a request to the token endpoint to exchange the authorization code for an access token.
Handles the implicit grant type by converting the hash response to a query response.
Redirects the user to the authorization endpoint if no authorization code or access token is present.

Return Value:

returns the response body as an object if the authentication is successful, or false if the authentication fails

Throws:

if the state code is invalid or if there is no authorization endpoint set

Exception

getRedirectUri

Generates the redirect URI based on the current request URI.

private getRedirectUri(): string

Return Value:

the generated redirect URI

Throws:

if the current APPLICATION_BASE does not match the REQUEST_URI

Exception

Automatically generated on 2024-11-14