Download the PHP package zoreal/oauth2 without Composer

zoreal/oauth2

Login with ZOREAL for PHP backends: the relying-party half of the flow that @zoreal/oauth2-react starts in the browser.

The browser SDK runs the pairing (QR or app link), and hands your frontend an authorization code plus the code_verifier and nonce it generated. Your frontend posts all three to your backend, and this package does the rest: the code exchange with your client authentication, ES256 verification of the ID token against the provider's JWKS, and the /userinfo read for personal claims.

Install

PHP >= 8.1 with ext-curl, ext-json and ext-openssl. One dependency: firebase/php-jwt.

Getting your credentials

Everything the Client constructor needs comes from a ZOREAL asset.

1. Create an account at https://zoreal.com and open Assets.
2. Create an asset -- a website (a domain you own) or an app bundle (a reverse-DNS bundle id). An asset is the thing users log in to; its token is your client_id and it looks like ast_....
3. On the asset, open the OAuth2 tab and register:
   • the redirect URIs and JavaScript origins your app uses (requests from anything not registered are rejected -- this is the core control),
   • the scopes the client is allowed to request (see the catalogue below); a request for a scope you did not register is refused,
   • your client authentication: generate a client secret for client_secret_basic, or register a JWKS for private_key_jwt. A public client authenticates with PKCE alone and no secret.
4. A website asset must verify its domain (a DNS or meta-tag proof, shown in the dashboard) before it can request personal-data scopes or sign users in; the verified domain is what your users' pairwise sub is derived against.

The client_id is public -- it ships in your frontend. The client secret is a server-side secret: keep it in your secret store and never put it in the browser.

There is no test-identity sandbox -- and that is deliberate

ZOREAL never issues fake or sandbox humans: a pool of test identities would be a fraud vector against the exact thing the product proves. So you always authenticate real ZOREAL IDs.

To develop and test, create a free ZOREAL ID for yourself -- enrol in the ZOREAL ID app and sign in with it. While building, mark your asset's environment sandbox in the dashboard: a sandbox asset may register http://localhost origins and redirect URIs that a production asset may not. Flip it to production when you ship. The identities are real either way; only the allowed origins differ. There is no mock provider and no hosted test issuer to point at.

Quick start

Build one client at boot and share it; it is immutable.

The endpoint your frontend posts to:

Account matching, the shape that works:

Assurance levels -- acr, and requiring a liveness check

What acr is

acr is an OpenID Connect standard claim -- Authentication Context Class Reference. It is a single string in the ID token that says how strongly this particular login was authenticated. Every ZOREAL login carries one, and it is the difference between "someone who once enrolled this identity is behind this request" and "a live human, verified to be the right one, is behind this request right now".

It answers a question sub cannot. sub() tells you who -- a stable, pairwise identifier for this person at your site. acr() tells you how sure ZOREAL is that the person is really there for this login. A stolen, unlocked phone can still produce a sub; it cannot produce a fresh zoreal.live.

The three levels

Ordered weakest to strongest. Each is what actually happened, never what was requested -- a login that could only reach a weaker level says so honestly rather than claiming the level you asked for.

amr() (Authentication Methods References) is the companion claim listing the factors used: hwk a hardware key, user a user-presence/unlock gesture, face a face biometric. zoreal.live is exactly zoreal.device with face added, because a live login is a device approval with a capture on top.

The default is zoreal.device, never zoreal.session: a login that asks for nothing still requires the enrolled phone and a local unlock. Silence has to be explicitly asked for (the SDK's prompt: 'none' path), and it succeeds only for a returning holder at a site whose consent they have already given.

When to require which

• zoreal.session -- you never require this; it is what a returning holder gets for a low-stakes convenience re-auth when they ask for the silent path.
• zoreal.device (the default) -- a forum, a community, a normal account login. Possession of the enrolled phone plus a local unlock is a high bar already; most sites want exactly this and should pass no acr at all.
• zoreal.live -- a bank onboarding, a high-value transaction, an age-gated purchase, a first login, a "confirm it is really you" step before a sensitive action. Anywhere a fresh, unforgeable proof of the live, right human is worth the few seconds a face capture costs.

Requesting versus verifying -- the one rule that matters

Requesting a level and verifying it are two separate steps, and only the second is security:

1. Request it on the wire, in the frontend, with the SDK's acr_values: 'zoreal.live'. This is what makes the holder's ZOREAL ID app run the face capture before it will approve. It is advisory -- it shapes what the holder is asked to do, nothing more. A browser is attacker-controlled; a value that only travels through it proves nothing.
2. Verify it here, at token exchange, by passing acr. The signed acr claim in the ID token -- minted by ZOREAL, not by the browser -- is the proof.

An RP that requests zoreal.live on the wire but never passes acr here has checked nothing -- it has only asked the holder nicely and then trusted a value it never validated.

How the check behaves

Verification satisfies upward: zoreal.session < zoreal.device < zoreal.live, so a requirement of zoreal.device accepts a zoreal.live token (the holder gave you more assurance than you demanded). A token whose acr is below the requirement, missing entirely, or outside the vocabulary is refused with VerificationError. An unknown required value -- a typo like 'zoreal.liveness' -- throws ConfigurationError instead, because that is a bug in your code, not a bad token, and failing every login silently is worse than saying so.

If you prefer to branch rather than throw, omit acr and inspect the result:

satisfiesAcr() runs the same ordering as the enforcing check, so it agrees with what acr: 'zoreal.live' would have accepted; a value outside the vocabulary satisfies nothing.

acr versus the assurance block

Do not confuse acr with assurance(). acr grades this login event. The assurance block ($login->assurance()) describes the identity behind it -- how the person was verified at enrolment: the uniqueness basis, the verified_on month, whether chip liveness was proven, the trust_tier, and the device's key_protection. One is about now; the other is about who they are. A high-value flow usually wants both: acr: 'zoreal.live' for presence, and the assurance block for the strength of the underlying identity proofing.

What each call does

Login reads the ID token claims directly -- sub(), acr(), live(), satisfiesAcr('zoreal.device'), amr(), assurance(), ageOver(18), nationality() -- and the /userinfo claims lazily: email(), emailVerified(), name(), givenName(), familyName(), birthdate(), documentType(), documentNumber(), issuingCountry(), documentExpiresOn(), portrait().

Client authentication

Your client registers one token_endpoint_auth_method in the dashboard; build the matching ClientAuth here. The provider authenticates against what was registered, not against what arrives.

• none -- no secret, no key; the form carries client_id only. A public client can only ever have been granted Tier A scopes.
• client_secret_basic -- the secret rides as the HTTP Basic password, never as a form field; the form still carries client_id because the provider matches the code against it.
• private_key_jwt -- the library builds and signs a fresh assertion per exchange: iss = sub = your client id, aud = the token endpoint, exp = now + 60 seconds (the provider's maximum), a random single-use jti. Pass the key as PEM; a P-256 EC key signs ES256 (preferred -- the same key type the provider certifies), an RSA key signs RS256, anything else is refused at construction. The private key never leaves your process.
• tls_client_auth -- the certificate and key ride on the connection itself, through curl's client-certificate options. The method is registrable, and the provider currently answers the exchange with 501; that surfaces as an ExchangeError with status 501 and the provider's own words, because faking a not-yet-served method would be worse than saying so. If you inject your own transport, carrying the certificate is its job.

Scopes and claims

Scopes are requested in the frontend (the SDK's scope string, always starting with openid), consented to by the holder, and pre-authorized on your asset. What each grants and where it is delivered:

• Tier A rides in the ID token and is available to every client, so the no-backend browser button can use it. Tier B and C are personal data, served only from /userinfo to a confidential client on a domain you have verified, and never placed in a browser token.
• Age thresholds are a fixed set -- 13, 16, 18, 21, 65 -- that you register on the asset. $login->ageOver($n) returns null for a threshold you did not register (no claim was minted), which is different from false. The set is fixed on purpose: registering all five would let a site recover the age band.

Error reference

exchange() / authenticate() throw ExchangeError, which carries the provider's own $oauthError code, $description and HTTP $status verbatim. What you will actually see at /token:

A failure to reach the endpoint at all (DNS, TLS, timeout) surfaces the same way: an ExchangeError whose $oauthError is server_error. That one is transient -- a retry is reasonable where the three above are not.

Errors that surface in the frontend instead, before your backend is involved (from the SDK's onError / onNonOAuthError), so handle them there:

request_denied is a person choosing not to sign in, not a fault. Treat it like a cancelled dialog: clear any spinner and offer the button again, do not log it as a failure or show a red error.

This package's own exception classes, all extending OAuth2Error so one catch can take the whole family:

OAuth2Error is the shared base; a transport failure (TransportError, internal) is caught by the Client and rethrown as the domain error of the call in flight, so you only ever handle the four above. No error message in this package ever carries a token, a secret or a key.

The assurance block

$login->assurance() is the ID token's zoreal claim -- an array describing the strength of the identity behind this login (distinct from acr, which grades the login event), or null when the token carries none. Its keys and their value sets:

A high-value flow usually pairs acr: 'zoreal.live' (fresh presence) with a check on the assurance block (identity strength) -- e.g. requiring uniqueness === 'personal_number' and trust_tier === 'high':

A complete example

A plain PHP login handler, end to end -- the shape a real integration takes. Adapt the $users calls to your own persistence; the ZOREAL parts are exact.

Things worth knowing before you integrate

• The ID token never carries personal data. sub, timing, acr/amr, the assurance block, and -- if registered -- age_over_* booleans and nationality. Email, names, birthdate and document fields come only from /userinfo, which is why authenticate alone is not enough for a signup.
• The access token lives 10 minutes. Read /userinfo while handling the login; do not store the token for later.
• sub is pairwise per verified domain. It is the right account key and it is derived from your registered sector: changing your asset's domain rotates every sub you have stored. Plan domain changes as a migration.
• ES256 only. The provider signs with nothing else, and this package refuses other algorithms -- from the header, before any signature math -- rather than negotiating.
• Always pass the nonce through, and protect your own endpoint too. The SDK generates the nonce and gives it to your frontend in onSuccess; passing it here lets the package confirm the ID token was minted for this login rather than substituted. Two things it does not do: it is not your endpoint's CSRF token (protect your /auth/zoreal route with your framework's normal CSRF / same-origin defence), and PKCE -- not the nonce -- is what proves whoever exchanges the code is whoever started the flow.
• The issuer must match the token's iss exactly -- it is compared, not normalized. Production is https://id.zoreal.com; override issuer: only when you have been given a non-production provider to point at.
• Email is a deliberate choice. It is a Tier B scope precisely because a shared email defeats the unlinkability the pairwise sub provides. Request it because you need it, not because the checkbox is familiar.
• portrait is registrable and not served yet. The provider does not return the claim today; Login::portrait() exists so your code does not change when it starts to.
• The JWKS is cached for 10 minutes and refetched once on an unknown kid, which is how a provider key rotation is absorbed without a restart. The default cache is in-process; hand the Client anything implementing the two-method CacheInterface to share it across processes.

The ZOREAL OAuth2 library family

License

MIT.