JWT

About 4 min

JWT

JWT-based auth session backend.

class JWT implements \Hazaar\Auth\Session\Backend\SessionBackend

Implements {@see SessionBackend} using signed JSON Web Tokens as the session transport format. Session state is encoded into token claims and validated on load with configurable signature algorithms and keys.

Supported capabilities:

HMAC (HS*) and OpenSSL-backed asymmetric algorithms (RS*, ES*, PS*)
Configurable issuer/expiry and optional key files
Optional device fingerprint claim binding (fp)
In-memory session data access through the SessionBackend API

Properties

config

public array $config

privateKey

public string $privateKey

publicKey

public string $publicKey

identity

public string $identity

data

public array $data

privateKeyCache

Cached list of private keys.

private array $privateKeyCache

publicKeyCache

Cached list of public keys.

private array $publicKeyCache

defaultPassphrase

Default passphrase for HMAC signing when not explicitly configured.

private string $defaultPassphrase = 'hazaar_default_jwt_passphrase_change_me'

Methods

__construct

Constructor for the JWT session backend.

public __construct(array $config): void

Initializes the configuration for JWT handling, including algorithm, issuer, expiration, refresh time, passphrase, and fingerprint keys. Loads cryptographic keys for signing and verification.

Configuration options:

'alg' (string): JWT signing algorithm. Default is 'HS256'.
'issuer' (string|null): Token issuer. If not set, generated at time of use. Default is null.
'expire' (int): Token expiration time in seconds. Default is 3600.
'refresh' (int): Token refresh time in seconds. Default is 86400.
'passphrase' (string): Passphrase for signing tokens. Default is 'hazaar_default_jwt_passphrase_change_me'.
'fingerprintKeys' (array): List of HTTP headers used for fingerprinting. Default is ['HTTP_USER_AGENT', 'HTTP_ACCEPT'].

Parameters

Parameter	Type	Description
`$config`	`array`	configuration options for JWT session backend

isEmpty

Indicates whether there is an active authenticated session identity.

public isEmpty(): bool

read

Reads and returns the session data.

public read(): void

has

Checks if a specific key exists in the session backend.

public has(string $key): bool

This method checks for the existence of a key within the JWT payload. If the key is 'identity', it checks the top-level 'identity' claim. For all other keys, it checks within the nested 'data' claim.

Parameters

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

get

Retrieves a value from the session backend.

public get(string $key): mixed

If the key is 'identity', the identity data is returned. Otherwise, the value associated with the key in the data array is returned.

Parameters

Parameter	Type	Description
`$key`	`string`	the key of the value to retrieve

set

Sets a value in the JWT payload.

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

This method stores a key-value pair in the 'data' section of the JWT payload. It specifically prevents overwriting the 'identity' key, which is reserved. If a value is successfully set, it flags the middleware to write the cookie.

Parameters

Parameter	Type	Description
`$key`	`string`	the key to set in the payload
`$value`	`mixed`	the value to store

Unsets a value from the session backend.

public (string $key): void

This method removes the value associated with the specified key from the session backend. Note that the 'identity' key is protected and cannot be unset.

Parameters

Parameter	Type	Description
`$key`	`string`	the key of the value to unset

clear

Clears the JWT session backend.

public clear(): void

This method checks if the session backend is not empty. If it contains data, it resets the internal data to null and sets a flag on the middleware to clear the associated cookie.

getToken

Generates a JWT token and optionally a refresh token.

public getToken(): ?ExpiringToken

This method constructs the JWT payload by merging existing data with standard claims such as issuer ('iss'), issued at ('iat'), expiration ('exp'), and subject ('sub'). It then builds the primary access token.

If a refresh timeout is configured, it also generates a refresh token with an extended expiration time, signed with a specific refresh token key.

Additionally, this method disables the middleware's cookie writing functionality to ensure the token is returned directly rather than set as a cookie.

getRefreshToken

public getRefreshToken(): ?ExpiringToken

create

Authorises the JWT token.

public create(string $identity, array $data): ExpiringToken

Parameters

Parameter	Type	Description
`$identity`	`string`
`$data`	`array`

load

Validates a JWT token.

public load(string $token, ?array $sessionData, string $tokenType = 'access', ?string $passphrase): bool

This method decodes the token, verifies its structure, and validates the signature using the configured public or private key. It supports RS, ES, and PS algorithms. It also checks standard claims like 'iss' (issuer) and 'exp' (expiration).

Parameters

Parameter	Type	Description
`$token`	`string`	the JWT token string to validate
`$sessionData`	`array`
`$tokenType`	`string`
`$passphrase`	`string`

refresh

Refreshes the session using the provided JWT token.

public refresh(string $token): bool

Attempts to reload the session data by calling the load method with the given token, session data, the 'refresh' context, and an optional refresh passphrase from the configuration.

Parameters

Parameter	Type	Description
`$token`	`string`	the JWT token to use for refreshing the session

getIdentity

Retrieves the identity associated with the current session.

public getIdentity(): ?string

loadCryptoKey

Loads a cryptographic key from configuration or file.

private loadCryptoKey(string $name, array $cacheList): ?string

Parameters

Parameter	Type	Description
`$name`	`string`	the name of the key in the configuration
`$cacheList`	`array`	reference to the cache list for loaded keys

buildToken

Builds a JWT token with the given JWT body and passphrase.

private buildToken(array $JWTBody, ?string $passphrase): string

Parameters

Parameter	Type	Description
`$JWTBody`	`array`	the body of the JWT token
`$passphrase`	`string`	The passphrase to sign the JWT token. Defaults to null.

generateDeviceFingerprint

Generates a device fingerprint based on specified HTTP headers.

private generateDeviceFingerprint(string $passphrase): string

This method constructs a unique fingerprint for the client device by concatenating the values of specified HTTP headers (defined in the configuration under 'fingerprintKeys') and encoding the result in base64.

Parameters

Parameter	Type	Description
`$passphrase`	`string`

getAlgoName

Parses the algorithm name and extracts the algorithm type and bit length.

private getAlgoName(string $alg, ?int $bits): ?string

This method validates the provided algorithm string against supported types (HS, RS, ES, PS) and bit lengths (256, 384, 512). If valid, it populates the reference variable $bits with the bit length and returns the algorithm prefix.

Parameters

Parameter	Type	Description
`$alg`	`string`	The algorithm string to parse (e.g., 'HS256', 'RS512').
`$bits`	`int`	[out] Reference variable to store the extracted bit length (256, 384, or 512)

getAlgoConst

Retrieves the OpenSSL algorithm constant based on the specified number of bits.

private getAlgoConst(int $bits): int

This method maps the bit length (256, 384, or 512) to the corresponding OpenSSL SHA algorithm constant.

Parameters

Parameter	Type	Description
`$bits`	`int`	The number of bits for the algorithm (e.g., 256, 384, 512).

sign

Signs the JWT token.

private sign(array $JWTHeader, array $JWTBody, ?string $passphrase): string

Parameters

Parameter	Type	Description
`$JWTHeader`	`array`	the header of the JWT token
`$JWTBody`	`array`	the body of the JWT token
`$passphrase`	`string`

Generated by Hazaar API Doc Generator on Tue, 21 Apr 2026 04:00:24 +0000