Download the PHP package binuka200/apple-sign-in without Composer

Safe Apple Sign In for PHP

A framework-neutral, defensive implementation of the complete Sign in with Apple server lifecycle for PHP 8.1+.

It replaces abandoned packages that vendor old JWT code or fetch Apple's keys on every login request. It does not create application sessions, users, routes, or database records; those decisions remain in your application.

This is an independent community project and is not affiliated with or endorsed by Apple Inc.

Included

• State- and nonce-protected authorization URLs and callback parsing.
• ES256 client-secret generation from Apple's .p8 key.
• Authorization-code exchange, refresh-token validation, and token revocation.
• RS256 identity-token verification with issuer, audience, time, subject, and optional nonce validation.
• First-authorization name and email parsing, explicitly treated as browser-posted profile data rather than identity proof.
• Side-effect-free typed server notification verification for account deletion, revoked consent, and private-email forwarding changes.
• PSR-16 JWKS caching, strict network bounds, one JWKS retry, stale-key fallback, forced-refresh rate limiting, and an optional cross-worker refresh lock.
• Observer hooks for metrics and structured logging without exposing secrets.

Install

Configuration

You need the following values from Apple Developer:

• Team ID
• App ID or Services ID, used as the client ID and token audience
• Sign in with Apple key ID
• Downloaded .p8 private-key file
• Registered HTTPS callback URI

Use a shared PSR-16 cache such as Redis in production. ArrayCache is only for tests and one-process examples.

The default client secret lasts five minutes and is generated for each API operation. Apple permits a maximum lifetime of 15,777,000 seconds.

Start authorization

Generate a challenge, store both values in the user's server-side session, then redirect to Apple:

Handle the callback

Consume the stored challenge once. Parsing the callback first validates state. Then verify that the callback ID token is bound to the single-use code, exchange the code, and verify the resulting identity token with the original nonce.

For native applications that send a SHA-256 nonce to Apple, verify against $challenge->hashedNonce() instead of the raw nonce.

Refresh and revoke

Authorization-code requests are not automatically retried because the code is single-use. A successful Apple response lost in transit cannot safely be replayed.

Server-to-server notifications

Configure the endpoint in Apple Developer. Verification deliberately has no side effects:

Apple describes each event as expected to be delivered once. Duplicate events may occur, but they are not a redelivery guarantee. Commit durable intake before returning a success status, retry account mutations from your own queue, and use monitoring plus reconciliation where possible. If verification or durable intake fails, return a non-success status and alert; do not rely on Apple to send the event again. See Apple's DTS guidance on notification delivery.

PSR-16 cannot express an atomic insert-if-absent operation. Use a database or durable queue with a unique key on jwtId for inbox idempotency.

Resilience and telemetry

JWKS responses are fresh for one hour and retained as a stale fallback for 24 hours. Successful and failed refresh attempts enter the forced-refresh cooldown, so repeated unknown key IDs cannot cause sequential network requests every time. Configure FlockRefreshLock to make this protection atomic between PHP-FPM workers on the same filesystem. Distributed deployments can implement RefreshLock using their existing Redis or database lock.

Implement Observer to forward safe events such as jwks.cache_hit, jwks.stale_fallback, oauth.token_succeeded, and oauth.token_rejected to your logger or metrics system. Context never includes codes, tokens, client secrets, or private keys.

Framework examples

• Expo and React Native mobile apps
• Plain PHP
• Laravel
• Symfony

Failure behavior

Failures while communicating with Apple or verifying Apple data extend AppleSignInException. Important subclasses are:

• InvalidIdentityToken, UnknownKeyId
• StateMismatch, InvalidAuthorizationResponse
• AppleApiException, AppleApiUnavailable
• InvalidNotification
• JwksUnavailable, InvalidConfiguration

Invalid credential and endpoint configuration uses InvalidConfiguration. Other invalid method or constructor arguments use PHP's InvalidArgumentException. Infrastructure failures from an injected cache or refresh-lock implementation may retain the exception type supplied by that implementation.

Map detailed failures to a generic login error at the public boundary. Never return raw Apple errors, tokens, codes, or claims to an unauthenticated client.

Development

CI covers PHP 8.1 through 8.5, including the lowest supported dependency set. The codebase is checked at PHPStan level 8 and dependencies are audited for published security advisories. Use a PHP branch that still receives upstream security fixes in production.

A separate job measures line coverage of src and fails when it drops below the committed floor:

Versioning and support

Releases follow Semantic Versioning. From 1.0 onward, breaking changes to the public API happen only in a major release. Only the latest release receives security fixes.

The public API is every type under the SafeApple\SignIn namespace except those marked @internal, which are implementation details shared between components and may change in any release. Because PHP supports named arguments, constructor and method parameter names are part of the public API as well as their order and types; new optional parameters are only ever appended.

Adding a property to a returned value object (AppleIdentity, AppleAccountEvent, TokenResponse) is treated as a compatible change, so match on the properties you use rather than destructuring every field.

Each GitHub release ships a source archive with a SHA-256 checksum and a Sigstore build-provenance attestation produced by the release workflow. To confirm an archive was built from this repository:

Release tags are protected against deletion and rewriting, so a published version always points at the same commit.

License

MIT