Get started

PHP SDK

identvia/identvia-php 1.0.0 signs users in with OpenID Connect. Plain PHP 8.1+, no framework, works on shared hosting.

Download zip (includes vendor/) Example app

Requirements

PHP 8.1 or newer with openssl and json (standard everywhere).
Optional: curl (otherwise PHP streams are used) and apcu (otherwise the key cache uses files).
One dependency: firebase/php-jwt for signature checks. The SDK never implements cryptography itself.

Install

Terminal

composer require identvia/identvia-php

Or upload the zip with cPanel’s File Manager and include vendor/autoload.php.

Configuration

PHP

$identvia = new Identvia\Sdk\Identvia([
    'issuer'        => 'https://id.identvia.com',          // required
    'client_id'     => 'oid_…',             // required
    'client_secret' => 'ivs_…',             // confidential apps only
    'redirect_uri'  => 'https://example.com/callback.php', // must match exactly
    'scopes'        => ['email', 'profile'], // openid is always added
    'cache_dir'     => __DIR__ . '/../storage/identvia', // optional; default: system temp dir
    'leeway'        => 60,                  // clock skew allowed, seconds
    'timeout'       => 10,                  // HTTP timeout, seconds
]);

Option	Notes
token_auth	client_secret_basic (default) or client_secret_post
ca_bundle	Path to a CA file if your host’s certificate store is outdated. TLS verification can’t be turned off.
cache, http, state_store	Bring your own cache, HTTP client or state storage (interfaces in src/).

Keep the secret out of your code repository: use environment variables, or a config.php outside the web root.

Sign in

PHP

// login.php: sends the user to Identvia (state, nonce and PKCE are handled for you)
$identvia->redirectToSignIn([
    'return_to' => '/account',   // optional; only same-site paths are accepted
    // 'prompt'  => 'login',      // force a fresh sign-in
    // 'max_age' => 300,          // require a sign-in in the last 5 minutes
]);

// callback.php: completes it
$signIn = $identvia->handleCallback($_GET);
$signIn->sub();           // the user's ID for your app
$signIn->email();         // null if not shared
$signIn->emailVerified();
$signIn->name();
$signIn->amr();           // e.g. ['hwk', 'user'] for a passkey
$signIn->tokens;          // TokenSet: accessToken, refreshToken, idToken, expiresAt
$signIn->returnTo;

Errors

Exception	When	What to do
AuthorizationException	The user pressed Cancel (userCancelled()) or Identvia returned an error	Show a friendly message
InvalidStateException	Expired, reused or forged callback; wrong issuer	Start sign-in again
TokenException	Code exchange failed (invalid_grant, invalid_client)	Check your secret; start again
ValidationException	The ID token failed a check	Never sign the user in; log it
HttpException	Network or TLS failure	Retry later

All of them extend Identvia\Sdk\Exception\IdentviaException.

Userinfo, refresh, revoke, logout

PHP

$claims = $identvia->userinfo($tokens->accessToken, $signIn->sub());

// Needs the offline_access scope. Identvia rotates refresh tokens: always store the new one.
$tokens = $identvia->refresh($tokens->refreshToken, $signIn->sub());

$identvia->revoke($tokens->refreshToken);   // on sign-out

// Optional: also end the Identvia session
header('Location: ' . $identvia->logoutUrl($tokens->idToken, 'https://example.com/'));

What the SDK checks

state: random, single use, expires after 10 minutes, several tabs can sign in at once.
PKCE (S256) on every request, also for confidential apps.
iss on the callback (RFC 9207), which defends against identity-provider mix-up.
ID token signature with Identvia’s published keys (RS256/ES256 only, never none or HMAC); keys are cached for an hour and re-fetched once when Identvia rotates them.
iss, aud, azp, exp, iat, nonce, auth_time against max_age, and at_hash.
HTTPS with certificate verification for every call; http:// is accepted only for localhost.

Sessions

The SDK keeps pending sign-ins in the PHP session and starts one if needed. The session cookie must be sent when Identvia redirects back, so use SameSite=Lax (not Strict). Call session_regenerate_id(true) after a successful sign-in.

Example app: Identvia Notes

A complete app with a strict CSP, the button, sign-in, sign-out and per-user notes. It’s in the zip under examples/notes-app.

Terminal

cd identvia-php/examples/notes-app
cp config.example.php config.php    # paste your client ID and secret
php -S localhost:9999 -t public     # then open http://localhost:9999