PHP OpenID Connect Basic Client

https://github.com/jumbojett/openid-connect-php
Admin
A simple PHP library that allows an application to authenticate a user through the basic OpenID...
Tokens:51,536
Snippets:357
Trust Score:8.7
License:Apache-2.0
Update:1 month ago
Show doc for...
Tokens:
Raw
### refreshToken() example

Source: https://github.com/jumbojett/openid-connect-php/blob/master/_autodocs/api-reference/OpenIDConnectClient-token-endpoints.md

Example of refreshing a token and outputting the new access token.

```php
$refresh = $oidc->getRefreshToken();
if ($refresh) {
    $json = $oidc->refreshToken($refresh);
    if (isset($json->access_token)) {
        echo 'New access token: ' . $oidc->getAccessToken();
    }
}
```

--------------------------------

### Usage example for verifyLogoutTokenClaims()

Source: https://github.com/jumbojett/openid-connect-php/blob/master/_autodocs/api-reference/OpenIDConnectClient-verification.md

Example showing how to verify decoded logout token claims and handle the result. Uses json_decode with false to get an object.

```php
// Used with a mocked/logged token: claims are an object
$claims = json_decode($logoutTokenPayload, false);
if ($oidc->verifyLogoutTokenClaims($claims)) {
    echo 'sid=' . $oidc->getSidFromBackChannel();
} else {
    echo 'Invalid logout claims';
}
```

--------------------------------

### Install library using composer

Source: https://github.com/jumbojett/openid-connect-php/blob/master/README.md

Run this command to install the openid-connect-php package via Composer. Requires PHP 7.2 or greater with CURL and JSON extensions.

```bash
composer require jumbojett/openid-connect-php
```

--------------------------------

### setClientName() usage example

Source: https://github.com/jumbojett/openid-connect-php/blob/master/_autodocs/api-reference/OpenIDConnectClient-configuration.md

Example of setting the client name to 'My Relying Party'.

```php
$oidc->setClientName('My Relying Party');
```

--------------------------------

### requestTokenExchange() example

Source: https://github.com/jumbojett/openid-connect-php/blob/master/_autodocs/api-reference/OpenIDConnectClient-token-endpoints.md

Example of calling requestTokenExchange() with a subject token, token type, and audience, then checking for an access token.

```php
$oidc = new OpenIDConnectClient('https://id.provider.com', 'id', 'secret');
$result = $oidc->requestTokenExchange(
    'at.jwt.for.another.api',
    'urn:ietf:params:oauth:token-type:jwt',
    'https://api.example.com'
);
if (isset($result->access_token)) {
    // use $result->access_token for the target API
}
```

--------------------------------

### getVerifiedClaims() example

Source: https://github.com/jumbojett/openid-connect-php/blob/master/_autodocs/api-reference/OpenIDConnectClient-userinfo.md

Shows how to retrieve a single claim or all verified claims after authentication. The 'sub' claim is used as an example, and calling without arguments returns an object of all claims.

```php
$oidc->authenticate();
$sub = $oidc->getVerifiedClaims('sub');   // implicit-flow example from README
$all = $oidc->getVerifiedClaims();        // (object) of claims
```

--------------------------------

### Subclass exposure and usage example for verifyJWTClaims()

Source: https://github.com/jumbojett/openid-connect-php/blob/master/_autodocs/api-reference/OpenIDConnectClient-verification.md

Example showing how to expose the protected method via a subclass and call it. Used in tests.

```php
class ProbeClient extends OpenIDConnectClient {
    public function checkClaims($claims): bool {
        return $this->verifyJWTClaims($claims);
    }
    public function getIdTokenPayload() {
        return (object)['sub' => 'sub'];
    }
}
$c = new ProbeClient();
$c->setClientID('client-id');
$c->setIssuer('issuer');
$c->setIdToken('');
$valid = $c->checkClaims((object)['aud' => 'client-id', 'iss' => 'issuer', 'sub' => 'sub']);
```

--------------------------------

### requestResourceOwnerToken() example

Source: https://github.com/jumbojett/openid-connect-php/blob/master/_autodocs/api-reference/OpenIDConnectClient-token-endpoints.md

Example of using requestResourceOwnerToken() to obtain a token via the password grant. Sets up the client, configures the token endpoint, adds scope and auth parameters, then calls the method with client authentication enabled. Checks for an access_token and logs an error if the grant fails.

```php
$oidc = new OpenIDConnectClient('https://id.provider.com', 'id', 'secret');
$oidc->providerConfigParam(['token_endpoint' => 'https://id.provider.com/connect/token']);
$oidc->addScope(['my_scope']);
$oidc->addAuthParam(['username' => 'user@example.com']);
$oidc->addAuthParam(['password' => 'hunter2']);

$token = $oidc->requestResourceOwnerToken(true);
if (!isset($token->access_token)) {
    error_log('Password grant failed: ' . $token->error);
}
```

--------------------------------

### setRedirectURL() usage example

Source: https://github.com/jumbojett/openid-connect-php/blob/master/_autodocs/api-reference/OpenIDConnectClient-configuration.md

Example call to setRedirectURL() with a valid URL. The URL is stored only if it has a valid host component.

```php
$oidc->setRedirectURL('https://app.example.com/callback');
```

--------------------------------

### Example: Use back-channel logout accessors

Source: https://github.com/jumbojett/openid-connect-php/blob/master/_autodocs/api-reference/OpenIDConnectClient-userinfo.md

Shows how to retrieve the sid and sub from a verified logout token and destroy the corresponding session.

```php
if ($oidc->verifyLogoutToken()) {
    $sid = $oidc->getSidFromBackChannel();
    $sub = $oidc->getSubjectFromBackChannel();
    if (isset($sid)) {
        destroySession(sidToSessionId($sid)); // RP-specific
    }
}
```

--------------------------------

### Dynamic Registration example

Source: https://github.com/jumbojett/openid-connect-php/blob/master/README.md

Registers a new client dynamically with the OpenID Connect provider. After registration, retrieve and store the client ID and secret for later use.

```php
use Jumbojett\OpenIDConnectClient;

$oidc = new OpenIDConnectClient("https://id.provider.com");

$oidc->register();
$client_id = $oidc->getClientID();
$client_secret = $oidc->getClientSecret();

// Be sure to add logic to store the client id and client secret
```

--------------------------------

### revokeToken() example

Source: https://github.com/jumbojett/openid-connect-php/blob/master/_autodocs/api-reference/OpenIDConnectClient-token-endpoints.md

Example of revoking a refresh token and checking the HTTP response code to confirm success.

```php
$oidc->revokeToken($oidc->getRefreshToken());
if ($oidc->getResponseCode() === 200) {
    echo 'Token revoked';
}
```

--------------------------------

### b64url2b64() usage example

Source: https://github.com/jumbojett/openid-connect-php/blob/master/_autodocs/api-reference/helpers.md

Example of converting a base64url-encoded JWT header to standard base64 with padding restored.

```php
use Jumbojett\b64url2b64;

// JWT header payload bytes, Base64URL-encoded without padding
$standard = b64url2b64('eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9');
// => 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9' with padding restored to a multiple of 4
```

--------------------------------

### requestClientCredentialsToken() example

Source: https://github.com/jumbojett/openid-connect-php/blob/master/_autodocs/api-reference/OpenIDConnectClient-token-endpoints.md

Shows how to request a client credentials token by setting the token endpoint, adding a scope, and calling the method. The response is checked for the access_token property.

```php
$oidc = new OpenIDConnectClient('https://id.provider.com', 'id', 'secret');
$oidc->providerConfigParam(['token_endpoint' => 'https://id.provider.com/connect/token']);
$oidc->addScope(['my_scope']);

$token = $oidc->requestClientCredentialsToken();
if (isset($token->access_token)) {
    // token is a JWT — validate before trusting (see verification page)
}
```

--------------------------------

### getJWTClientAssertion() example

Source: https://github.com/jumbojett/openid-connect-php/blob/master/_autodocs/api-reference/OpenIDConnectClient-verification.md

Generates a compact JWT signed with HS256 using the client secret. The audience should be the token endpoint URL.

```php
$assertion = $oidc->getJWTClientAssertion('https://id.provider.com/connect/token');
```

--------------------------------

### PHP: Typical RP controller using authenticate()

Source: https://github.com/jumbojett/openid-connect-php/blob/master/_autodocs/api-reference/OpenIDConnectClient.md

Example of a typical relying party controller. It creates an OpenIDConnectClient instance, calls authenticate(), and exits if the method returns false because the redirect has already been emitted. On success, it retrieves user info.

```php
$oidc = new OpenIDConnectClient('https://id.provider.com', 'id', 'secret');
if (!$oidc->authenticate()) {
    // redirect() already emitted the Location header and exited the script
    exit;
}
echo 'Logged in as: ' . $oidc->requestUserInfo('given_name');
```

--------------------------------

### urlEncode() example

Source: https://github.com/jumbojett/openid-connect-php/blob/master/_autodocs/api-reference/OpenIDConnectClient-verification.md

Encodes a binary string to Base64URL without padding. The method trims '=' and replaces '+' with '-' and '/' with '_'.

```php
$enc = $oidc->urlEncode('raw-signature-bytes');
```

--------------------------------

### introspectToken() example

Source: https://github.com/jumbojett/openid-connect-php/blob/master/_autodocs/api-reference/OpenIDConnectClient-token-endpoints.md

Example of introspecting a token. Checks the 'active' field to determine if the token is still usable.

```php
$oidc = new OpenIDConnectClient('https://id.provider.com', 'id', 'secret');
$data = $oidc->introspectToken('an.access-token.as.given');
if (!$data->active) {
    // the token is no longer usable
}
```

--------------------------------

### setUrlEncoding() usage example

Source: https://github.com/jumbojett/openid-connect-php/blob/master/_autodocs/api-reference/OpenIDConnectClient-configuration.md

Example call to setUrlEncoding() with PHP_QUERY_RFC3986 to change the URL encoding used in http_build_query calls.

```php
$oidc->setUrlEncoding(PHP_QUERY_RFC3986);
```

--------------------------------

### addAuthParam() usage examples

Source: https://github.com/jumbojett/openid-connect-php/blob/master/_autodocs/api-reference/OpenIDConnectClient-configuration.md

Adds 'prompt' and 'response_mode' parameters to the authorization request.

```php
$oidc->addAuthParam(['prompt' => 'login']);
$oidc->addAuthParam(['response_mode' => 'form_post']);
```

--------------------------------

### verifySignatures() usage example with try-catch

Source: https://github.com/jumbojett/openid-connect-php/blob/master/_autodocs/api-reference/OpenIDConnectClient-verification.md

Shows how to call verifySignatures() inside a try-catch block, printing 'Signature OK' on success or an error message on OpenIDConnectClientException.

```php
try {
    $oidc->verifySignatures($idToken);
    echo 'Signature OK';
} catch (OpenIDConnectClientException $e) {
    echo 'Signature check failed: ' . $e->getMessage();
}
```

--------------------------------

### Basic Client authentication example

Source: https://github.com/jumbojett/openid-connect-php/blob/master/README.md

Authenticates a user using the OpenID Connect flow. Requires the issuer URL, client ID, and client secret. Optionally sets a certificate path before authenticating, then retrieves user info such as 'given_name'.

```php
use Jumbojett\OpenIDConnectClient;

$oidc = new OpenIDConnectClient('https://id.provider.com',
                                'ClientIDHere',
                                'ClientSecretHere');
$oidc->setCertPath('/path/to/my.cert');
$oidc->authenticate();
$name = $oidc->requestUserInfo('given_name');
```

--------------------------------

### DiscoverClient subclass - Expose discovery method

Source: https://github.com/jumbojett/openid-connect-php/blob/master/_autodocs/api-reference/OpenIDConnectClient-network-session.md

Example subclass that exposes getWellKnownConfigValue() as discover(). The try/catch handles OpenIDConnectClientException when the provider authorization_endpoint could not be fetched.

```php
class DiscoverClient extends OpenIDConnectClient {
    public function discover(string $param, $default = null) {
        return $this->getWellKnownConfigValue($param, $default);
    }
}
try {
    $auth = $discoverClient->discover('authorization_endpoint');
} catch (OpenIDConnectClientException $e) {
    // "The provider authorization_endpoint could not be fetched. …"
}
```

--------------------------------

### Example: Extending handleJweResponse()

Source: https://github.com/jumbojett/openid-connect-php/blob/master/_autodocs/api-reference/OpenIDConnectClient-verification.md

Example subclass overriding handleJweResponse() to provide custom JWE decryption. The method receives the JWE string and returns the decrypted payload. The comment 'RP-specific' indicates the decryption logic is specific to the relying party's implementation.

```php
class DecryptingClient extends OpenIDConnectClient {
    protected function handleJweResponse(string $jwe): string {
        return myJweDecrypt($jwe, $this->getClientSecret()); // RP-specific
    }
}
```

--------------------------------

### Structured error handling for monitoring

Source: https://github.com/jumbojett/openid-connect-php/blob/master/_autodocs/api-reference/OpenIDConnectClientException.md

Optional pattern for logging errors and handling registration failures. The example shows a recordError function and a try-catch block that calls it.

```php
function recordError(OpenIDConnectClientException $e) {
    error_log('OIDC error: ' . $e->getMessage());
}

try {
    $oidc->register();
} catch (OpenIDConnectClientException $e) {
    recordError($e);
    // e.g. 'Error registering: …' — provider requires manual registration
}
```

--------------------------------

### Back-channel logout handler using verifyLogoutToken()

Source: https://github.com/jumbojett/openid-connect-php/blob/master/_autodocs/api-reference/OpenIDConnectClient-verification.md

Example of calling verifyLogoutToken() from a back-channel logout route. On success, it retrieves the SID and destroys the session; on failure, it catches the exception and returns HTTP 400.

```php
function handleLogout() {
    if ($this->oidc->verifyLogoutToken()) {
        $sid = $this->oidc->getSidFromBackChannel();
        if (isset($sid)) {
            destroySessionForSid($sid); // RP-specific session lookup
        }
    }
}:

try {
    $ok = $oidc->verifyLogoutToken();
} catch (OpenIDConnectClientException $e) {
    http_response_code(400); // no logout_token supplied by OP
}
```

--------------------------------

### Example: Check response code and content type

Source: https://github.com/jumbojett/openid-connect-php/blob/master/_autodocs/api-reference/OpenIDConnectClient-userinfo.md

Shows how to check if the UserInfo response is a signed JWT by verifying the HTTP status code and content type.

```php
$oidc->requestUserInfo();
if ($oidc->getResponseCode() === 200 && $oidc->getResponseContentType() === 'application/jwt') {
    echo 'UserInfo was a signed JWT';
}
```

--------------------------------

### Subclass exposing requestTokens() for manual token exchange

Source: https://github.com/jumbojett/openid-connect-php/blob/master/_autodocs/api-reference/OpenIDConnectClient-token-endpoints.md

Example subclass that exposes the protected requestTokens() method as public exchangeCode(). It demonstrates catching OpenIDConnectClientException and logging the error. The example instantiates the subclass with provider URL, client ID, and secret, then calls exchangeCode() with an authorization code and custom header.

```php
// Subclass exposes the token exchange for manual client
class MyClient extends OpenIDConnectClient {
    public function exchangeCode(string $code, array $headers = []) {
        return $this->requestTokens($code, $headers);
    }
}

$c = new MyClient('https://id.provider.com', 'id', 'secret');
try {
    $response = $c->exchangeCode('auth-code-123', ['X-Custom: 1']);
} catch (OpenIDConnectClientException $e) {
    error_log($e->getMessage());
}
```

--------------------------------

### Development-mode example: disable TLS verification and upgrade

Source: https://github.com/jumbojett/openid-connect-php/blob/master/_autodocs/api-reference/OpenIDConnectClient-network-session.md

Disables host and peer verification and disables HTTP upgrade insecure requests for local development. Not recommended for production. Use only in development environments where HTTPS is not available.

```php
$oidc->setVerifyHost(false);
$oidc->setVerifyPeer(false);
$oidc->setHttpUpgradeInsecureRequests(false); // local http-only dev setup
```

--------------------------------

### addScope() usage example

Source: https://github.com/jumbojett/openid-connect-php/blob/master/_autodocs/api-reference/OpenIDConnectClient-configuration.md

Adds the 'email' and 'profile' scopes to the authorization request.

```php
$oidc->addScope(['email', 'profile']);
```

--------------------------------

### setIdToken() and getIdToken() methods

Source: https://github.com/jumbojett/openid-connect-php/blob/master/_autodocs/api-reference/OpenIDConnectClient-userinfo.md

Stores and retrieves the raw ID token string. The example shows using the ID token for a logout hand-off.

```php
public function setIdToken(string $idToken) {
    $this->idToken = $idToken;
}

public function getIdToken()
{
    return $this->idToken;
}
```

```php
$oidc->signOut($oidc->getIdToken(), 'https://app.example.com/bye');
```

--------------------------------

### Session helper methods

Source: https://github.com/jumbojett/openid-connect-php/blob/master/_autodocs/api-reference/OpenIDConnectClient-network-session.md

Provides the protected session helper methods used to start, commit, and manipulate session data. These are called internally by the state management methods.

```php
protected function startSession() {
    if (session_status() === PHP_SESSION_NONE) {
        @session_start();
    }
}

protected function commitSession() {
    $this->startSession();
    session_write_close();
}

protected function getSessionKey(string $key)      // value|false when key missing
protected function setSessionKey(string $key, $value)
protected function unsetSessionKey(string $key)
```

--------------------------------

### getAccessToken() and setAccessToken() methods

Source: https://github.com/jumbojett/openid-connect-php/blob/master/_autodocs/api-reference/OpenIDConnectClient-userinfo.md

Defines the getter and setter for the access token. The setter overwrites the stored token, and the getter returns it. The example shows setting a manual token and then using it to request user info.

```php
public function getAccessToken()
{
    return $this->accessToken;
}

public function setAccessToken(string $accessToken) {
    $this->accessToken = $accessToken;
}
```

```php
$oidc->setAccessToken('manual.access.token');
$user = $oidc->requestUserInfo('sub'); // uses the manually set token
```

--------------------------------

### introspectToken() with overridden credentials

Source: https://github.com/jumbojett/openid-connect-php/blob/master/_autodocs/api-reference/OpenIDConnectClient-token-endpoints.md

Example of calling introspectToken() with explicit client credentials, overriding the instance defaults.

```php
$data = $oidc->introspectToken($token, 'access_token', 'audit-user', 'audit-secret');
```

--------------------------------

### fetchURL()

Source: https://github.com/jumbojett/openid-connect-php/blob/master/_autodocs/api-reference/OpenIDConnectClient-network-session.md

Performs an HTTP request using cURL. When post_body is provided, the request becomes a POST; otherwise it is a GET. Returns the raw response body or throws an exception on failure.

```APIDOC
## fetchURL()

### Description
Performs an HTTP request using cURL. When `post_body` is provided, the request becomes a POST; otherwise it is a GET. Returns the raw response body or throws an exception on failure.

### Method
Protected method

### Endpoint
`protected function fetchURL(string $url, ?string $post_body = null, array $headers = [])`

### Parameters
- **url** (string) - Required - Target URL
- **post_body** (?string) - Optional - When non-null, the request becomes a POST (`CURLOPT_CUSTOMREQUEST = 'POST'`, body via `CURLOPT_POSTFIELDS`).
- **headers** (array) - Optional - Extra headers as `'Name: Value'` strings

### Return Type
`bool|string` - Raw response body; `false` is never returned on failure (a failure throws instead).

### Throws
`OpenIDConnectClientException` - `'Curl error: (' . curl_errno($ch) . ') ' . curl_error($ch)` when cURL returns `false`.

### Behavior
cURL options set:
- `CURLOPT_URL` - `$url`
- `CURLOPT_CUSTOMREQUEST` / `CURLOPT_POSTFIELDS` - POST + body when `post_body !== null`
- `CURLOPT_USERAGENT` - `getUserAgent()` (always)
- `CURLOPT_HTTPHEADER` - `$headers` (+ `Content-Type: application/x-www-form-urlencoded` or `application/json` when the POST body decodes as a JSON object)
- `CURLOPT_PROXY` - `httpProxy` when set
- `CURLOPT_HEADER` - `0`, `CURLOPT_FOLLOWLOCATION` = `true`
- `CURLOPT_CAINFO` - `certPath` when set
- `CURLOPT_SSL_VERIFYHOST` - `2` / `0` from `verifyHost`
- `CURLOPT_SSL_VERIFYPEER` - `true` / `false` from `verifyPeer`
- `CURLOPT_RETURNTRANSFER` - `true`
- `CURLOPT_TIMEOUT` - `timeOut`

After the call, the instance's `responseCode` / `responseContentType` are recorded from `curl_getinfo()`. `curl_close()` is called only when `PHP_VERSION_ID < 80000`.
```

--------------------------------

### Subclass example accessing nonce

Source: https://github.com/jumbojett/openid-connect-php/blob/master/_autodocs/api-reference/OpenIDConnectClient-network-session.md

Shows a subclass of OpenIDConnectClient that exposes the protected getNonce() method. Use this pattern to read the nonce value between redirects.

```php
class SessionAwareClient extends OpenIDConnectClient {
    public function peekNonce() {
        return $this->getNonce();   // stored between redirects
    }
}
```

--------------------------------

### Basic Client for Implicit Flow with Azure AD B2C

Source: https://github.com/jumbojett/openid-connect-php/blob/master/README.md

Configures an OpenIDConnectClient for implicit flow, setting response type to 'id_token', enabling implicit flow, and using form_post response mode. Requires a certificate path and calls authenticate() to get verified claims.

```php
use Jumbojett\OpenIDConnectClient;

$oidc = new OpenIDConnectClient('https://id.provider.com',
                                'ClientIDHere',
                                'ClientSecretHere');
$oidc->setResponseTypes(['id_token']);
$oidc->setAllowImplicitFlow(true);
$oidc->addAuthParam(['response_mode' => 'form_post']);
$oidc->setCertPath('/path/to/my.cert');
$oidc->authenticate();
$sub = $oidc->getVerifiedClaims('sub');

```

--------------------------------

### Handle back-channel logout with verifyLogoutToken() and getSidFromBackChannel()

Source: https://github.com/jumbojett/openid-connect-php/blob/master/README.md

Use this snippet to validate a back-channel logout token from the OP and destroy the corresponding user session. It assumes $this->oidc is an OpenIDConnectClient instance. The example shows retrieving the sid, finding the session ID from Redis, and destroying that session. Adjust the session-finding logic to match your RP's design.

```php
function handleLogout() {
    // NOTE: assumes that $this->oidc is an instance of OpenIDConnectClient()
    if ($this->oidc->verifyLogoutToken()) {
        $sid = $this->oidc->getSidFromBackChannel();

        if (isset($sid)) {
            // Somehow find the session based on the $sid and
            // destroy it. This depends on your RP's design,
            // there is nothing in the OIDC spec to mandate how.
            //
            // In this example, we find a Redis key, which was
            // previously stored using the sid we obtained from
            // the access token after login.
            //
            // The value of the Redis key is that of the user's
            // session ID specific to this hypothetical RP app.
            //
            // We then switch to that session and destroy it.
            $this->redis->connect('127.0.0.1', 6379);
            $session_id_to_destroy = $this->redis->get($sid);
            if ($session_id_to_destroy) {
                session_commit();
                session_id($session_id_to_destroy); // switches to that session
                session_start();
                $_SESSION = []; // effectively ends the session
            }
        }
    }
}

```

--------------------------------

### Catching OpenIDConnectClientException in consumer code

Source: https://github.com/jumbojett/openid-connect-php/blob/master/_autodocs/api-reference/OpenIDConnectClientException.md

Wrap authentication calls in a try-catch block to handle failures. The example shows setting an HTTP 401 response and echoing the exception message.

```php
use Jumbojett\OpenIDConnectClient;
use Jumbojett\OpenIDConnectClientException;

$oidc = new OpenIDConnectClient('https://id.provider.com', 'ClientIDHere', 'ClientSecretHere');
try {
    $oidc->authenticate();
} catch (OpenIDConnectClientException $e) {
    // e.g. 'Unable to determine state' or 'Unable to verify JWT claims'
    http_response_code(401);
    echo 'Authentication failed: ' . $e->getMessage();
}
```

--------------------------------

### Using setProviderURL() and getProviderURL()

Source: https://github.com/jumbojett/openid-connect-php/blob/master/_autodocs/api-reference/OpenIDConnectClient-configuration.md

Shows how to set the provider URL and retrieve it, catching the exception when it is not set.

```php
$oidc->setProviderURL('https://id.provider.com');
try {
    echo $oidc->getProviderURL();
} catch (OpenIDConnectClientException $e) {
    // provider URL unset
}
```

--------------------------------

### getAccessTokenHeader() and getAccessTokenPayload() methods

Source: https://github.com/jumbojett/openid-connect-php/blob/master/_autodocs/api-reference/OpenIDConnectClient-userinfo.md

Returns the decoded header and payload of the access token. The header is at section 0 and the payload at section 1. The example shows retrieving the payload and checking for the 'sub' claim.

```php
public function getAccessTokenHeader() {
    return $this->decodeJWT($this->accessToken);
}

public function getAccessTokenPayload() {
    return $this->decodeJWT($this->accessToken, 1);
}
```

```php
$payload = $oidc->getAccessTokenPayload();
echo isset($payload->sub) ? $payload->sub : '(no sub claim)';
```

--------------------------------

### Register client with OpenIDConnectClient::register()

Source: https://github.com/jumbojett/openid-connect-php/blob/master/_autodocs/api-reference/OpenIDConnectClient-token-endpoints.md

Creates an OpenIDConnectClient instance, adds a registration parameter for post-logout redirect URIs, and calls register(). After successful registration, retrieves and persists the client ID and secret. The provider must support dynamic registration; otherwise, an exception is thrown.

```php
$oidc = new OpenIDConnectClient('https://id.provider.com');
$oidc->addRegistrationParam(['post_logout_redirect_uris' => ['https://app.example.com/bye']]);
$oidc->register();

$client_id     = $oidc->getClientID();
$client_secret = $oidc->getClientSecret();
// Persist $client_id / $client_secret before proceeding
```

--------------------------------

### getIdToken() / setIdToken()

Source: https://github.com/jumbojett/openid-connect-php/blob/master/_autodocs/api-reference/OpenIDConnectClient-userinfo.md

Gets or sets the raw ID token string.

```APIDOC
## getIdToken() / setIdToken()

### Description
Stores or retrieves the raw ID-token string.

### Methods

#### setIdToken(string $idToken)
```php
public function setIdToken(string $idToken) {
    $this->idToken = $idToken;
}
```

**Parameters:**
- `idToken` (string) - Required - The raw ID token string.

**Return Type:** void

#### getIdToken()
```php
public function getIdToken()
{
    return $this->idToken;
}
```

**Return Type:** `string|null` - The stored ID token string.

### Example (logout hand-off)
```php
$oidc->signOut($oidc->getIdToken(), 'https://app.example.com/bye');
```
```

--------------------------------

### setProviderURL() and getProviderURL() implementation

Source: https://github.com/jumbojett/openid-connect-php/blob/master/_autodocs/api-reference/OpenIDConnectClient-configuration.md

Defines the methods to set and retrieve the provider URL. getProviderURL() throws an exception if the URL is not set.

```php
public function setProviderURL($provider_url) {
    $this->providerConfig['providerUrl'] = $provider_url;
}

public function getProviderURL() {
    if (!isset($this->providerConfig['providerUrl'])) {
        throw new OpenIDConnectClientException('The provider URL has not been set');
    }
    return $this->providerConfig['providerUrl'];
}
```

--------------------------------

### setResponseTypes() usage example

Source: https://github.com/jumbojett/openid-connect-php/blob/master/_autodocs/api-reference/OpenIDConnectClient-configuration.md

Sets the response type to 'id_token' for implicit flow.

```php
$oidc->setResponseTypes(['id_token']);
```

--------------------------------

### setVerifyHost() and getVerifyHost() methods

Source: https://github.com/jumbojett/openid-connect-php/blob/master/_autodocs/api-reference/OpenIDConnectClient-network-session.md

Controls SSL host verification. Default is true, setting CURLOPT_SSL_VERIFYHOST to 2; when disabled, it becomes 0. Use to validate or ignore the hostname in the SSL certificate.

```php
public function setVerifyHost(bool $verifyHost) {
    $this->verifyHost = $verifyHost;
}
public function getVerifyHost(): bool
{
    return $this->verifyHost;
}
```

--------------------------------

### setClientName() and getClientName() methods

Source: https://github.com/jumbojett/openid-connect-php/blob/master/_autodocs/api-reference/OpenIDConnectClient-configuration.md

Sets and retrieves the client name. Returns string|null. Sent as client_name during dynamic registration.

```php
public function setClientName(string $clientName) {
    $this->clientName = $clientName;
}
public function getClientName()
{
    return $this->clientName;
}
```

--------------------------------

### getAccessToken() / setAccessToken()

Source: https://github.com/jumbojett/openid-connect-php/blob/master/_autodocs/api-reference/OpenIDConnectClient-userinfo.md

Gets or sets the access token used for authenticated requests.

```APIDOC
## getAccessToken() / setAccessToken()

### Description
Gets or sets the access token. The token is received during `authenticate()` / `refreshToken()`, or can be set explicitly.

### Methods

#### getAccessToken()
```php
public function getAccessToken()
{
    return $this->accessToken;
}
```

**Return Type:** `string|null` - Token received during `authenticate()` / `refreshToken()`, or set explicitly.

#### setAccessToken(string $accessToken)
```php
public function setAccessToken(string $accessToken) {
    $this->accessToken = $accessToken;
}
```

**Parameters:**
- `accessToken` (string) - Required - The access token to store.

**Return Type:** void

### Example
```php
$oidc->setAccessToken('manual.access.token');
$user = $oidc->requestUserInfo('sub'); // uses the manually set token
```
```

--------------------------------

### decodeJWT() example

Source: https://github.com/jumbojett/openid-connect-php/blob/master/_autodocs/api-reference/OpenIDConnectClient-verification.md

Decodes the payload section of an ID token using decodeJWT() with section index 1.

```php
$payload = $oidc->decodeJWT($idToken, 1);
```

--------------------------------

### validateIssuer() example

Source: https://github.com/jumbojett/openid-connect-php/blob/master/_autodocs/api-reference/OpenIDConnectClient-verification.md

Calls validateIssuer() with an issuer URL and catches OpenIDConnectClientException thrown by getIssuer()/getWellKnownIssuer() when unset.

```php
try {
    $ok = $oidc->validateIssuer('https://id.provider.com/');
} catch (OpenIDConnectClientException $e) {
    // thrown by getIssuer()/getWellKnownIssuer() when unset
}
```

--------------------------------

### setWellKnownConfigParameters() implementation

Source: https://github.com/jumbojett/openid-connect-php/blob/master/_autodocs/api-reference/OpenIDConnectClient-configuration.md

Sets optional query parameters for the well-known discovery URL.

```php
public function setWellKnownConfigParameters(array $params = []){
    $this->wellKnownConfigParameters=$params;
}
```

--------------------------------

### getWellKnownConfigValue() - Fetch and cache well-known config

Source: https://github.com/jumbojett/openid-connect-php/blob/master/_autodocs/api-reference/OpenIDConnectClient-network-session.md

Fetches and caches {providerURL}/.well-known/openid-configuration (plus wellKnownConfigParameters query string) on first use, then reads $param from the cached document. Falsy well-known values fall back to $default, and a missing value with no default throws OpenIDConnectClientException.

```php
protected function getWellKnownConfigValue(string $param, $default = null)
{
    if(!$this->wellKnown) {
        $well_known_config_url = rtrim($this->getProviderURL(), '/') . '/.well-known/openid-configuration';
        if (count($this->wellKnownConfigParameters) > 0){
            $well_known_config_url .= '?' .  http_build_query($this->wellKnownConfigParameters) ;
        }
        $this->wellKnown = json_decode($this->fetchURL($well_known_config_url), false);
    }

    $value = $this->wellKnown->{$param} ?? false;

    if ($value) {
        return $value;
    }
    if (isset($default)) {
        return $default;
    }
    throw new OpenIDConnectClientException("The provider $param could not be fetched. Make sure your provider has a well known configuration available.");
}
```

--------------------------------

### Basic OpenIDConnectClient construction

Source: https://github.com/jumbojett/openid-connect-php/blob/master/_autodocs/api-reference/OpenIDConnectClient.md

Basic client construction for authorization-code flow. Creates an OpenIDConnectClient with provider URL, client ID, and client secret, then sets a certificate path and calls authenticate().

```php
use Jumbojett\OpenIDConnectClient;

$oidc = new OpenIDConnectClient(
    'https://id.provider.com',
    'ClientIDHere',
    'ClientSecretHere'
);
$oidc->setCertPath('/path/to/my.cert');
$oidc->authenticate();
```

--------------------------------

### base64url_decode() usage example

Source: https://github.com/jumbojett/openid-connect-php/blob/master/_autodocs/api-reference/helpers.md

Decodes a base64url-encoded JWT header and prints the JSON payload. Checks for false return value.

```php
use Jumbojett\base64url_decode;

// A JWT header ('{"alg":"HS256","typ":"JWT"}') in Base64URL form
$decoded = base64url_decode('eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9');
if ($decoded !== false) {
    echo $decoded; // {"alg":"HS256","typ":"JWT"}
}
```

--------------------------------

### PHP: signOut() with redirect target

Source: https://github.com/jumbojett/openid-connect-php/blob/master/_autodocs/api-reference/OpenIDConnectClient.md

Logs out by passing the ID token and a post-logout redirect URI. The end_session_endpoint must be discoverable via provider config or an injected override; otherwise an OpenIDConnectClientException is thrown.

```php
$idToken = $oidc->getIdToken();
$oidc->signOut($idToken, 'https://myapp.example.com/bye');
```

--------------------------------

### PHP: signOut() without redirect target

Source: https://github.com/jumbojett/openid-connect-php/blob/master/_autodocs/api-reference/OpenIDConnectClient.md

Logs out without a post_logout_redirect_uri, omitting that parameter. The example shows handling an OpenIDConnectClientException when end_session_endpoint cannot be discovered.

```php
try {
    $oidc->signOut($oidc->getIdToken(), null);
} catch (OpenIDConnectClientException $e) {
    // end_session_endpoint could not be discovered
}
```

--------------------------------

### verifyJWKHeader() override example

Source: https://github.com/jumbojett/openid-connect-php/blob/master/_autodocs/api-reference/OpenIDConnectClient-verification.md

Override this protected hook to support self-signed JWTs that embed their own 'jwk' in the header. The default implementation always throws an exception.

```php
class TrustingClient extends OpenIDConnectClient {
    protected function verifyJWKHeader($jwk) {
        // assert pin / trusted fingerprint of $jwk->n here
    }
}
```

--------------------------------

### setCodeChallengeMethod() / getCodeChallengeMethod()

Source: https://github.com/jumbojett/openid-connect-php/blob/master/_autodocs/api-reference/OpenIDConnectClient-configuration.md

Configures PKCE (Proof Key for Code Exchange) by setting the code challenge method. Supported methods are 'S256' and 'plain'.

```APIDOC
## setCodeChallengeMethod() / getCodeChallengeMethod()

### Description
Configures PKCE (Proof Key for Code Exchange) by setting the code challenge method. Supported methods are `'S256'` and `'plain'`. PKCE parameters are added during authorization and token exchange only when the provider advertises the method.

### Method
PHP method

### Endpoint
N/A

### Parameters
#### Parameters
- **codeChallengeMethod** (string) - Required - The PKCE code challenge method (e.g., `'S256'`).

### Request Example
```php
$oidc->setCodeChallengeMethod('S256');
$oidc->authenticate();
```

### Response
#### Success Response
- **getCodeChallengeMethod()** (string) - Returns the current code challenge method.

#### Response Example
```php
$method = $oidc->getCodeChallengeMethod();
```
```

--------------------------------

### new OpenIDConnectClient()

Source: https://github.com/jumbojett/openid-connect-php/blob/master/_autodocs/api-reference/OpenIDConnectClient.md

Constructs a new OpenIDConnectClient instance with the given provider URL, client ID, client secret, and optional issuer. The constructor stores the provider URL and issuer, and assigns client credentials.

```APIDOC
## Constructor

### Description
Initializes an OpenIDConnectClient instance with provider URL, client ID, client secret, and optional issuer. The constructor stores the provider URL and issuer, and assigns client credentials.

### Method
Constructor

### Signature
```php
public function __construct(?string $provider_url = null, ?string $client_id = null, ?string $client_secret = null, ?string $issuer = null)
```

### Parameters
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `provider_url` | `?string` | no | `null` | Base URL of the OpenID Connect provider. Stored via `setProviderURL()` and used as the issuer when `issuer` is omitted. |
| `client_id` | `?string` | no | `null` | OAuth client identifier. |
| `client_secret` | `?string` | no | `null` | OAuth client secret. Pass `null` for public clients / PKCE flows. |
| `issuer` | `?string` | no | `null` | Expected issuer value for JWT `iss` validation. Defaults to `provider_url`. |

### Return / Throws
- Returns nothing (void). Note: it does **not** throw on missing arguments; calls that need a provider URL or issuer throw later at use site (e.g. `getProviderURL()` throws `OpenIDConnectClientException` when `providerUrl` is unset).

### Behavior
1. `setProviderURL($provider_url)` stores `providerConfig['providerUrl']`.
2. `setIssuer()` stores `providerConfig['issuer']` — either the `$issuer` argument or, when `null`, the `$provider_url`.
3. `clientID` and `clientSecret` are assigned.

### Examples
Basic client construction (authorization-code flow):

```php
use Jumbojett\OpenIDConnectClient;

$oidc = new OpenIDConnectClient(
    'https://id.provider.com',
    'ClientIDHere',
    'ClientSecretHere'
);
$oidc->setCertPath('/path/to/my.cert');
$oidc->authenticate();
```

Public-client construction where the issuer differs from the provider URL (e.g. Azure AD B2C user flows):

```php
$oidc = new OpenIDConnectClient(
    'https://login.microsoftonline.com/tenant/oauth2/authorize',
    'public-client-id',
    null,                                    // no client secret
    'https://login.microsoftonline.com/tenant/'
);
$oidc->setCodeChallengeMethod('S256');       // PKCE, see configuration page
$oidc->setAllowImplicitFlow(true);
$oidc->addAuthParam(['response_mode' => 'form_post']);
```
```

--------------------------------

### register()

Source: https://github.com/jumbojett/openid-connect-php/blob/master/_autodocs/api-reference/OpenIDConnectClient-token-endpoints.md

Registers the client dynamically with the OpenID Connect provider using the registration endpoint. On success, sets the client ID and secret from the response.

```APIDOC
## register()

### Description
Registers the client dynamically with the OpenID Connect provider using the registration endpoint. On success, sets the client ID and secret from the response.

### Method
POST

### Endpoint
registration_endpoint (as configured in the provider's discovery document)

### Parameters
None (input from `registrationParams`, `clientName`, and `getRedirectURL()`)

### Request Example
```json
{
  "redirect_uris": ["https://app.example.com/callback"],
  "client_name": "My App",
  "post_logout_redirect_uris": ["https://app.example.com/bye"]
}
```

### Response
#### Success Response (200)
- **client_id** (string) - The client identifier assigned by the provider
- **client_secret** (string) - The client secret assigned by the provider

#### Response Example
```json
{
  "client_id": "abc123",
  "client_secret": "xyz789"
}
```

### Throws
- **OpenIDConnectClientException** - If registration fails due to invalid JSON response, error_description in response, or missing client_secret.
```

--------------------------------

### setVerifyHost() / getVerifyHost()

Source: https://github.com/jumbojett/openid-connect-php/blob/master/_autodocs/api-reference/OpenIDConnectClient-network-session.md

Controls whether SSL host verification is enabled. Default is true; when enabled, CURLOPT_SSL_VERIFYHOST is set to 2, otherwise 0.

```APIDOC
## setVerifyHost() / getVerifyHost()

### Description
Controls whether SSL host verification is enabled. Default is true; when enabled, CURLOPT_SSL_VERIFYHOST is set to 2, otherwise 0.

### Methods
- setVerifyHost(bool $verifyHost)
- getVerifyHost(): bool

### Parameters
- **$verifyHost** (bool) - Required - Whether to verify the SSL host.

### Return Value
- getVerifyHost() returns bool.

### Behavior
setVerifyHost() sets CURLOPT_SSL_VERIFYHOST to 2 when true, 0 when false.

### Example
```php
$oidc->setVerifyHost(false);
$verify = $oidc->getVerifyHost();
```
```

--------------------------------

### getSidFromBackChannel() and getSubjectFromBackChannel() methods

Source: https://github.com/jumbojett/openid-connect-php/blob/master/_autodocs/api-reference/OpenIDConnectClient-userinfo.md

Return the sid and sub claims from the back-channel logout token. Populated during verifyLogoutTokenClaims() when the token carries these claims.

```php
public function getSidFromBackChannel(): string
{
    return $this->backChannelSid;
}

public function getSubjectFromBackChannel(): string
{
    return $this->backChannelSubject;
}
```

--------------------------------

### PHP: redirect() direct call

Source: https://github.com/jumbojett/openid-connect-php/blob/master/_autodocs/api-reference/OpenIDConnectClient.md

Sets a Location header and exits. The example notes it is used internally by signOut()/requestAuthorization() and can also be called directly with a destination URL.

```php
// Used internally by signOut()/requestAuthorization(); also callable directly
$oidc->redirect('https://id.provider.com/authorize?client_id=abc');
```

--------------------------------

### setIssuer() and getIssuer() implementation

Source: https://github.com/jumbojett/openid-connect-php/blob/master/_autodocs/api-reference/OpenIDConnectClient-configuration.md

Defines methods to set and retrieve the expected issuer. getIssuer() throws an exception if not set.

```php
public function setIssuer($issuer) {
    $this->providerConfig['issuer'] = $issuer;
}

public function getIssuer(): string
{
    if (!isset($this->providerConfig['issuer'])) {
        throw new OpenIDConnectClientException('The issuer has not been set');
    }
    return $this->providerConfig['issuer'];
}
```

--------------------------------

### setIssuerValidator() / getIssuerValidator()

Source: https://github.com/jumbojett/openid-connect-php/blob/master/_autodocs/api-reference/OpenIDConnectClient-configuration.md

Installs a custom issuer validator callable invoked during issuer validation. The callable receives the JWT 'iss' claim and must return true for a valid issuer.

```APIDOC
## setIssuerValidator() / getIssuerValidator()

### Description
Installs a custom issuer validator callable invoked from `validateIssuer()` with the JWT `iss` claim; must return `true` for a valid issuer. `getIssuerValidator()` returns `callable|null`.

### Method
PHP method

### Endpoint
N/A

### Parameters
#### Parameters
- **issuerValidator** (callable) - Required - The custom validator function.

### Request Example
```php
$oidc->setIssuerValidator(function(string $iss) {
    return $iss === 'https://trusted.example.com/';
});
```

### Response
#### Success Response
- **getIssuerValidator()** (callable|null) - Returns the current validator or null.

#### Response Example
```php
$validator = $oidc->getIssuerValidator();
```
```

--------------------------------

### getProviderConfigValue() - Get provider config with fallback

Source: https://github.com/jumbojett/openid-connect-php/blob/master/_autodocs/api-reference/OpenIDConnectClient-network-session.md

Returns an injected/merged config value or, failing that, performs discovery and caches the discovered value. Uses $default when the well-known document lacks the key.

```php
protected function getProviderConfigValue(string $param, $default = null)
{
    // If the configuration value is not available, attempt to fetch it from a well known config endpoint
    if (!isset($this->providerConfig[$param])) {
        $this->providerConfig[$param] = $this->getWellKnownConfigValue($param, $default);
    }
    return $this->providerConfig[$param];
}
```

--------------------------------

### Network and Security configuration

Source: https://github.com/jumbojett/openid-connect-php/blob/master/README.md

Configures a proxy and certificate path for the OpenID Connect client. Use these methods to route requests through a proxy and to specify a custom CA certificate.

```php
// Configure a proxy
$oidc->setHttpProxy("http://my.proxy.com:80/");

// Configure a cert
$oidc->setCertPath("/path/to/my.cert");
```

--------------------------------

### setCertPath() / getCertPath()

Source: https://github.com/jumbojett/openid-connect-php/blob/master/_autodocs/api-reference/OpenIDConnectClient-network-session.md

Sets and retrieves the full system path to the CA certificate bundle used for SSL verification.

```APIDOC
## setCertPath() / getCertPath()

### Description
Sets and retrieves the full system path to the CA certificate bundle used for SSL verification.

### Methods
- setCertPath(string $certPath)
- getCertPath()

### Parameters
- **$certPath** (string) - Required - Full system path to the CA certificate bundle.

### Return Value
- getCertPath() returns string|null (default unset).

### Behavior
setCertPath() sets CURLOPT_CAINFO to the provided path.

### Example
```php
$oidc->setCertPath('/path/to/cacert.pem');
$path = $oidc->getCertPath();
```
```

--------------------------------

### Distinguishing transport failures from protocol failures

Source: https://github.com/jumbojett/openid-connect-php/blob/master/_autodocs/api-reference/OpenIDConnectClientException.md

Use the exception message to differentiate network-level errors (starting with 'Curl error') from HTTP status errors (containing 'status code') and other failures.

```php
try {
    $oidc->requestUserInfo();
} catch (OpenIDConnectClientException $e) {
    if (strpos($e->getMessage(), 'Curl error') === 0) {
        // network-level problem — retry may help
    } elseif (strpos($e->getMessage(), 'status code') !== false) {
        // provider returned a non-200 HTTP status
    } else {
        // claim/signature/endpoint failure
    }
}
```

--------------------------------

### Protected methods for nonce, state, and PKCE verifier

Source: https://github.com/jumbojett/openid-connect-php/blob/master/_autodocs/api-reference/OpenIDConnectClient-network-session.md

Declares the protected methods for storing and retrieving the nonce, CSRF state, and PKCE verifier in the session. Use these in subclasses to manage the flow state between redirects.

```php
protected function setNonce(string $nonce): string  // stores & returns $nonce
protected function getNonce()                        // string|false
protected function unsetNonce()
protected function setState(string $state): string
protected function getState()
protected function unsetState()
protected function setCodeVerifier(string $codeVerifier): string
protected function getCodeVerifier()
protected function unsetCodeVerifier()
```

--------------------------------

### PKCE setCodeChallengeMethod and getCodeChallengeMethod

Source: https://github.com/jumbojett/openid-connect-php/blob/master/_autodocs/api-reference/OpenIDConnectClient-configuration.md

Method definitions for PKCE configuration. Default is false (disabled). Supported algorithms are 'S256' (sha256) and 'plain'. PKCE params are added only when provider advertises the method.

```php
public function setCodeChallengeMethod(string $codeChallengeMethod) {
    $this->codeChallengeMethod = $codeChallengeMethod;
}
public function getCodeChallengeMethod() {
    return $this->codeChallengeMethod;
}
```

```php
$oidc->setCodeChallengeMethod('S256');
$oidc->authenticate();
```

--------------------------------

### setHttpUpgradeInsecureRequests() and getHttpUpgradeInsecureRequests() methods

Source: https://github.com/jumbojett/openid-connect-php/blob/master/_autodocs/api-reference/OpenIDConnectClient-network-session.md

Controls whether the HTTP_UPGRADE_INSECURE_REQUESTS header triggers HTTPS in the redirect URL. Default is true. Set to false to ignore the header, useful in local HTTP-only development setups.

```php
public function setHttpUpgradeInsecureRequests(bool $httpUpgradeInsecureRequests) {
    $this->httpUpgradeInsecureRequests = $httpUpgradeInsecureRequests;
}
public function getHttpUpgradeInsecureRequests(): bool
{
    return $this->httpUpgradeInsecureRequests;
}
```

--------------------------------

### setAllowImplicitFlow and getAllowImplicitFlow

Source: https://github.com/jumbojett/openid-connect-php/blob/master/_autodocs/api-reference/OpenIDConnectClient-configuration.md

Method definitions for enabling and checking the implicit flow setting. Default is false; when true, authenticate() accepts id_token without an authorization code.

```php
public function setAllowImplicitFlow(bool $allowImplicitFlow) {
    $this->allowImplicitFlow = $allowImplicitFlow;
}
public function getAllowImplicitFlow(): bool
{
    return $this->allowImplicitFlow;
}
```

```php
$oidc->setAllowImplicitFlow(true);
$oidc->addAuthParam(['response_mode' => 'form_post']);
```

--------------------------------

### OpenIDConnectClient constructor signature

Source: https://github.com/jumbojett/openid-connect-php/blob/master/_autodocs/configuration.md

Constructor signature for OpenIDConnectClient. All parameters are optional and default to null. provider_url is the base for OIDC discovery, client_secret is null for public clients (PKCE), and issuer defaults to provider_url when omitted.

```php
new OpenIDConnectClient(?string $provider_url = null, ?string $client_id = null,
                        ?string $client_secret = null, ?string $issuer = null)
```
Tokens:
Raw