Website integration

M7 Identity SDK currently supports two PHP website integration roles. Choose the smallest package that matches the application's responsibility.

Package Use it for Current version
web-php Browser authorization-code login, same-origin session and profile access, refresh, token acknowledgement, and logout through a PHP backend-for-frontend. 0.1.3 stable release
token-php Local validation of M7 access tokens received by a PHP application or API, plus optional online introspection and UserInfo calls. 0.1.2 stable release

An application may use both packages when it owns browser login and separately protects backend routes. Installing web-php does not automatically authorize the host application's own API routes; the host remains responsible for its route and resource policy.

web-php capabilities

The website package installs at the stable /m7_sso_session path and provides:

  • authorization-code login and signup with PKCE;
  • pushed authorization requests when configured by the M7 authority;
  • server-side code exchange and HttpOnly session cookies;
  • browser DPoP integration and request-bound ath support;
  • encrypted custody and acknowledgement of pending token packages;
  • same-origin session and profile operations;
  • registered refresh-mode handling; and
  • local session clearing plus the configured M7 logout flow.

The host website owns its pages, client registration, deployment secrets, backend authorization, and the decision to request the current session or profile.

token-php capabilities

The token package can protect PHP application and API code with:

  • compact JWT parsing;
  • RSA signature and claims validation;
  • exact issuer and audience policy;
  • scope matching;
  • optional request-bound DPoP proof validation;
  • trusted certificate resolution and consumer-owned caching;
  • separate OAuth token introspection; and
  • separate OpenID Connect UserInfo retrieval.

UserInfo response verification

UserInfo has separate ordinary JSON and signed-JWT response paths. The JSON path requires HTTP 200 with application/json, a JSON object, and a nonempty sub; an optional expected_sub must match exactly. It does not treat an ordinary JSON response as a signed identity assertion.

Signed UserInfo is included in the immutable token-php 0.1.2 artifact. The signed path accepts only application/jwt and keeps JWT verification in a dedicated verifier, segregated from ordinary JSON parsing and response handling.

JWT claims are not returned until all of these checks pass:

  1. the success response media type is exactly application/jwt;
  2. the compact JWT parses canonically and declares RS256 or RS512 with a usable key ID;
  3. the configured issuer's OpenID discovery document reports that exact issuer and supplies a safe HTTPS jwks_uri;
  4. the discovered JWKS contains exactly one applicable RSA signing key for the key ID, algorithm, use, and key operations, and the signature verifies;
  5. issuer, client-ID audience, and time claims pass with the configured leeway;
  6. sub is a nonempty string; and
  7. any configured expected_sub binding matches exactly.

The verifier may refresh the discovered JWKS once for signing-key rotation. Any media-type, discovery, key, algorithm, signature, claims, subject, or expected-sub failure returns a failed report without exposing decoded JWT claims.

Local validation, introspection, and UserInfo are distinct operations. An introspection or UserInfo response does not silently change a local validation result.

Requirements

The current website packages require PHP 8.1 or newer and OpenSSL. web-php also requires PHP cURL, HTTPS, normal PHP session support, and web-server routing for the stable package path. Use an M7 client registration whose redirect URI, authentication method, fingerprints, scopes, and lifecycle match the deployment.

Stable web-php 0.1.3 accepts each 32-byte fingerprint in the PHP environment as either 64 hexadecimal or 43 canonical unpadded base64url characters. This is input normalization only: the SDK continues to send the server's existing lowercase 64-character hexadecimal fingerprint format. The local-only pending-envelope key accepts the same two environment encodings, is decoded to raw key bytes, and is never sent to SSO. Separate random-generation commands produce different values; convert or print both encodings from the same bytes when an existing registration must be preserved.

Install

Follow the website installation guide to verify a release, install either package, and perform the first safe checks.

OIDC-Connect PHP example

Use the OIDC-Connect PHP purpose and integration guide when an independent website wants to add Sign in with M7 beside provider buttons it manages itself. The guide explains the website/M7 ownership boundary, the deliberate nested callback layout, release status, and links to the sanitized client-registration card and Apache deployment template.

Basic browser integration

After web-php is installed and configured, begin login through the local same-origin route:

window.location.assign("/m7_sso_session/");

Resolve the current session from host JavaScript with credentials included:

const response = await fetch("/m7_sso_session/me", {
  method: "POST",
  credentials: "include",
  headers: { "Content-Type": "application/json" },
  body: "{}",
});

const session = await response.json();
if (!response.ok || session.ok !== true) {
  throw new Error(session.error?.message || "M7 session request failed");
}

Treat any access token returned by /me as sensitive and keep it in memory only. The /profile operation uses the HttpOnly session cookie and does not return the token.

Web SSO setup diagnostics

M7_WEB_SDK_DEBUG is a Web SDK-only diagnostics switch included in the immutable web-php 0.1.3 artifact. It does not enable debug behavior in token-php.

The setting defaults to off. It accepts 1, true, yes, or on and 0, false, no, or off, ignoring case and surrounding whitespace. Any other value is a configuration error rather than a silent fallback. During a controlled initial setup, make the setting visible to the web PHP process, enable PHP log_errors, confirm that the worker can write its configured error log, and reload Apache or PHP-FPM after changing the environment:

M7_WEB_SDK_DEBUG=on

Web SDK configuration, session, upstream OAuth, endpoint-response, and fatal failures are written as structured [m7-identity-web-php] error-log records whether debug mode is on or off. With debug off, package-owned browser responses keep their normal production-safe shape. With debug on, failed JSON responses may add an opaque trace_id and a debug object containing a safe setup hint; package-owned text failures provide comparable safe guidance. Use the trace ID to locate the matching PHP error-log entry. It is a diagnostic reference only and must not drive authorization or application behavior.

Debug detail is sanitized. Logs and responses must not disclose client secrets, authorization headers, access or refresh tokens, cookies, authorization codes, PKCE or DPoP material, fingerprints, pending activation data, or raw upstream bodies. Do not enable PHP display_errors as a substitute for this facility. After login, callback, /me, /profile, refresh/ACK, and logout work through the deployed HTTPS path, set M7_WEB_SDK_DEBUG=off and reload the worker. Failures continue to reach the PHP error log with reduced production-safe context.

Security boundaries

Keep the installed m7_sso_session directory package-owned. Store OAuth client secrets and pending-envelope keys in the deployment secret manager, not in the public directory or application source. Never call the package's internal callback finalizer directly; the validated callback page owns that transition.

Use non-production registration values for the first deployment. Verify the complete login, callback, acknowledgement, session, profile, refresh, and logout sequence through the actual HTTPS proxy and PHP worker before production use.