WorkOS PHP SDK

SessionManager
in package

Table of Contents

Constants

ALLOWED_JWS_ALGORITHMS  : mixed = ['RS256']
Algorithms permitted on the JWS header. WorkOS access tokens are signed with RS256; no other algorithm is accepted, in particular `none` is always rejected.
JWKS_CACHE_TTL_SECONDS  : mixed = 300
JWKS cache TTL in seconds. WorkOS rotates signing keys on the order of weeks, so a few minutes is plenty to absorb traffic spikes without making session checks dependent on a live JWKS round-trip.

Properties

$client  : HttpClient
$jwksCache  : array<string, array{keys: array, fetched_at: int}>
In-memory JWKS cache, keyed by client ID. Values are `['keys' => array, 'fetched_at' => int]`. Cache lives for the lifetime of the SessionManager instance and is bypassed when a token's `kid` isn't found, so key rotation still resolves quickly.

Methods

__construct()  : mixed
authenticate()  : array<string|int, mixed>
Authenticate a sealed session cookie by unsealing and validating the JWT.
fetchJwks()  : array<string|int, mixed>
Fetch the JWKS keys for the given client ID.
getJwksUrl()  : string
Build the JWKS URL for the given client ID.
getLogoutUrl()  : string
Get the logout URL for a session.
refresh()  : array<string|int, mixed>
Refresh a sealed session by exchanging the refresh token.
sealData()  : string
Encrypt a data array into a sealed string using symmetric encryption.
sealSessionFromAuthResponse()  : string
Seal session data from an authentication response into a cookie-safe string.
unsealData()  : array<string|int, mixed>
Decrypt a sealed string back to a data array.
base64UrlDecode()  : string|false
Decode a base64url-encoded segment, tolerating missing padding.
decodeAccessToken()  : array<string|int, mixed>
Decode and validate an access token JWT.
derEncodeBitString()  : string
derEncodeLength()  : string
derEncodeSequence()  : string
derEncodeUnsignedInteger()  : string
findJwkByKid()  : array<string, mixed>|null
Locate a JWK in the JWKS response by `kid`.
getCachedJwks()  : array<string, mixed>
Return the JWKS for `$clientId`, served from an in-memory cache with a {@see JWKS_CACHE_TTL_SECONDS}-second TTL. Set `$forceRefresh` to bypass the cache after a `kid` miss, which lets newly-rotated keys be discovered without waiting for TTL expiry.
jwkToRsaPublicKeyPem()  : string
Convert an RSA JWK (`kty=RSA`, base64url `n`/`e`) to a PEM-encoded public key suitable for {@see openssl_verify()}.

Constants

ALLOWED_JWS_ALGORITHMS

Algorithms permitted on the JWS header. WorkOS access tokens are signed with RS256; no other algorithm is accepted, in particular `none` is always rejected.

private mixed ALLOWED_JWS_ALGORITHMS = ['RS256']

JWKS_CACHE_TTL_SECONDS

JWKS cache TTL in seconds. WorkOS rotates signing keys on the order of weeks, so a few minutes is plenty to absorb traffic spikes without making session checks dependent on a live JWKS round-trip.

private mixed JWKS_CACHE_TTL_SECONDS = 300

Properties

$jwksCache

In-memory JWKS cache, keyed by client ID. Values are `['keys' => array, 'fetched_at' => int]`. Cache lives for the lifetime of the SessionManager instance and is bypassed when a token's `kid` isn't found, so key rotation still resolves quickly.

private array<string, array{keys: array, fetched_at: int}> $jwksCache = []

Methods

authenticate()

Authenticate a sealed session cookie by unsealing and validating the JWT.

public authenticate(string $sessionData, string $cookiePassword, string $clientId[, string $baseUrl = 'https://api.workos.com/' ]) : array<string|int, mixed>

Returns an associative array with 'authenticated' => true and session claims on success, or 'authenticated' => false and a 'reason' on failure.

Parameters
$sessionData : string

The sealed session cookie value.

$cookiePassword : string

The encryption key.

$clientId : string

The WorkOS client ID (for JWKS URL).

$baseUrl : string = 'https://api.workos.com/'

The WorkOS API base URL. Defaults to 'https://api.workos.com/'.

Return values
array<string|int, mixed> —

Authentication result.

fetchJwks()

Fetch the JWKS keys for the given client ID.

public fetchJwks(string $clientId) : array<string|int, mixed>
Parameters
$clientId : string

The WorkOS client ID.

Return values
array<string|int, mixed> —

The JWKS response.

getJwksUrl()

Build the JWKS URL for the given client ID.

public static getJwksUrl(string $clientId[, string $baseUrl = 'https://api.workos.com/' ]) : string
Parameters
$clientId : string

The WorkOS client ID.

$baseUrl : string = 'https://api.workos.com/'

The WorkOS API base URL.

Return values
string —

The JWKS URL.

getLogoutUrl()

Get the logout URL for a session.

public getLogoutUrl(string $sessionData, string $cookiePassword, string $clientId[, string|null $returnTo = null ][, string $baseUrl = 'https://api.workos.com/' ]) : string
Parameters
$sessionData : string

The sealed session cookie value.

$cookiePassword : string

The encryption key.

$clientId : string

The WorkOS client ID.

$returnTo : string|null = null

Optional URL to redirect to after logout.

$baseUrl : string = 'https://api.workos.com/'

The WorkOS API base URL.

Tags
throws
InvalidArgumentException

If the session cannot be authenticated.

Return values
string —

The logout URL.

refresh()

Refresh a sealed session by exchanging the refresh token.

public refresh(string $sessionData, string $cookiePassword, string $clientId[, string|null $organizationId = null ]) : array<string|int, mixed>
Parameters
$sessionData : string

The sealed session cookie value.

$cookiePassword : string

The encryption key.

$clientId : string

The WorkOS client ID.

$organizationId : string|null = null

Optional organization to scope the refresh to.

Return values
array<string|int, mixed> —

Refresh result with 'authenticated', 'sealed_session', and claims.

sealData()

Encrypt a data array into a sealed string using symmetric encryption.

public static sealData(array<string|int, mixed> $data, string $key) : string
Parameters
$data : array<string|int, mixed>

The data to seal.

$key : string

The base64-encoded encryption key (must be 32 bytes decoded).

Return values
string —

The sealed (encrypted) string.

sealSessionFromAuthResponse()

Seal session data from an authentication response into a cookie-safe string.

public static sealSessionFromAuthResponse(string $accessToken, string $refreshToken, string $cookiePassword[, array<string|int, mixed>|null $user = null ][, array<string|int, mixed>|null $impersonator = null ]) : string
Parameters
$accessToken : string

The access token from the auth response.

$refreshToken : string

The refresh token from the auth response.

$cookiePassword : string

The encryption key (base64-encoded, 32 bytes decoded).

$user : array<string|int, mixed>|null = null

The user data from the auth response. (Optional)

$impersonator : array<string|int, mixed>|null = null

The impersonator data, if present. (Optional)

Return values
string —

A sealed session string suitable for storing in a cookie.

unsealData()

Decrypt a sealed string back to a data array.

public static unsealData(string $sealedData, string $key) : array<string|int, mixed>
Parameters
$sealedData : string

The sealed (encrypted) string.

$key : string

The base64-encoded encryption key.

Tags
throws
InvalidArgumentException

If decryption fails.

Return values
array<string|int, mixed> —

The decrypted data.

base64UrlDecode()

Decode a base64url-encoded segment, tolerating missing padding.

private static base64UrlDecode(string $segment) : string|false
Parameters
$segment : string
Return values
string|false —

The decoded bytes, or false on malformed input.

decodeAccessToken()

Decode and validate an access token JWT.

private decodeAccessToken(string $accessToken, string $clientId) : array<string|int, mixed>

Verifies the JWS signature against the JWKS published for $clientId, enforces an algorithm allow-list, and rejects expired tokens. This is the only path used by authenticate(); callers must not bypass it.

Parameters
$accessToken : string

The JWT access token.

$clientId : string

The WorkOS client ID (used to fetch JWKS).

Tags
throws
InvalidArgumentException

If the token cannot be decoded or fails verification.

Return values
array<string|int, mixed> —

The decoded JWT claims.

derEncodeBitString()

private static derEncodeBitString(string $bytes) : string
Parameters
$bytes : string
Return values
string

derEncodeLength()

private static derEncodeLength(int $length) : string
Parameters
$length : int
Return values
string

derEncodeSequence()

private static derEncodeSequence(string $contents) : string
Parameters
$contents : string
Return values
string

derEncodeUnsignedInteger()

private static derEncodeUnsignedInteger(string $bytes) : string
Parameters
$bytes : string
Return values
string

findJwkByKid()

Locate a JWK in the JWKS response by `kid`.

private static findJwkByKid(array<string, mixed> $jwks, string $kid) : array<string, mixed>|null
Parameters
$jwks : array<string, mixed>
$kid : string
Return values
array<string, mixed>|null

getCachedJwks()

Return the JWKS for `$clientId`, served from an in-memory cache with a {@see JWKS_CACHE_TTL_SECONDS}-second TTL. Set `$forceRefresh` to bypass the cache after a `kid` miss, which lets newly-rotated keys be discovered without waiting for TTL expiry.

private getCachedJwks(string $clientId[, bool $forceRefresh = false ]) : array<string, mixed>
Parameters
$clientId : string
$forceRefresh : bool = false
Return values
array<string, mixed>

jwkToRsaPublicKeyPem()

Convert an RSA JWK (`kty=RSA`, base64url `n`/`e`) to a PEM-encoded public key suitable for {@see openssl_verify()}.

private static jwkToRsaPublicKeyPem(array<string, mixed> $jwk) : string
Parameters
$jwk : array<string, mixed>
Return values
string
On this page

Search results