Safer Sign in with Apple Library for PHP

Binuka Jayaweera — Fri, 28 Aug 2026 10:06:52 +0000

A defensive, framework-neutral implementation with bounded JWKS fetching, modern JWT verification, full OAuth lifecycle support, and Expo/React Native integration

Authentication code has an awkward property: when it works, nobody notices it. When it fails, it can block every login—or quietly accept something it should not.

I recently reviewed a PHP application whose Sign in with Apple flow depended on an old library. The package had helped many developers, but its implementation reflected a different time in the PHP ecosystem. It included a frozen copy of JWT code and downloaded Apple's public signing keys during every login using an unbounded network call.

That created three practical problems:

A slowdown at Apple could occupy every available PHP-FPM worker.
An unknown signing-key ID could fall through to the wrong array entry instead of producing a clear failure.
The bundled JWT implementation could not receive normal upstream security updates.

The application's audience validation was already correct, so this was not an authentication-bypass discovery. It was an availability, maintainability, and software-supply-chain problem.

I wanted a modern alternative that treated those concerns as part of authentication—not as optional infrastructure around it. That became Safe Apple Sign In for PHP, now available as the open-source Composer package binuka200/apple-sign-in and on GitHub.

The project is released under the permissive MIT license and is open to community contributions. PHP developers, security engineers, framework maintainers, and mobile developers are welcome to review the design, report bugs, propose improvements, add integrations, improve documentation, and submit pull requests.

composer require binuka200/apple-sign-in

The source is available on GitHub under the MIT license.

The hidden network call on the login path

Apple signs identity tokens with private keys and publishes the corresponding public keys as a JWKS document. A PHP backend needs those public keys to verify that a token really came from Apple.

The simplest implementation fetches Apple's JWKS endpoint whenever a user signs in. It is also a dangerous default.

Imagine a PHP-FPM replica with five workers. If five anonymous requests initiate Apple login while Apple's key endpoint is slow, and every request waits for the default socket timeout, the entire replica can become unavailable. The attacker does not need a valid Apple account because the expensive work happens before authentication succeeds.

The new library makes JWKS retrieval deliberately bounded:

Network timeout: two seconds
Maximum request duration: four seconds
One controlled retry
PSR-16 shared caching
One-hour fresh-key lifetime
A 24-hour stale-key fallback during an upstream outage
A refresh cooldown for unknown key IDs
An optional lock to prevent multiple PHP-FPM workers refreshing simultaneously

use SafeApple\SignIn\AppleJwksProvider;
use SafeApple\SignIn\Support\FlockRefreshLock;

$jwks = new AppleJwksProvider(
    cache: $sharedPsr16Cache,
    refreshLock: new FlockRefreshLock(
        '/run/lock/my-app-apple-jwks.lock'
    ),
);

In production, $sharedPsr16Cache should normally be backed by Redis or another cache shared by all application workers. The included in-memory cache is intended for tests and single-process examples.

This design does not pretend the network cannot fail. It limits the damage when it does.

Verification is more than checking a signature

A valid RSA signature only proves that Apple signed a token. It does not prove that the token was issued for your application or belongs to the authorization flow currently in progress.

The verifier therefore checks:

The RS256 algorithm and Apple signature
The exact Apple issuer
Issued-at and expiry claims, with a bounded clock leeway
A non-empty subject
The complete audience set
The authorized party (azp) when applicable
The expected nonce
The authorization-code hash (c_hash) for hybrid authorization responses
A strict token-size limit before decoding

use SafeApple\SignIn\AppleIdentityTokenVerifier;

$verifier = new AppleIdentityTokenVerifier(
    $jwks,
    ['com.example.ios', 'com.example.web'],
    leeway: 30,
);

$identity = $verifier->verifyAuthorizationResponse(
    $callback->identityToken,
    $callback->code,
    $challenge->nonce,
);

The audience rule is intentionally strict. If a token contains multiple audiences, every audience must be trusted and azp must identify an allowed member of that set. Weakening audience checks to make a configuration error disappear is exactly the wrong trade-off on a login endpoint.

The stable account key is Apple's sub claim—not the email address. A user can choose Apple's private email relay, and email-related data may change. The subject is the provider identity your user record should retain.

A complete server lifecycle, not only JWT decoding

Generating ES256 client secrets from Apple's .p8 private key
Building state- and nonce-protected authorization URLs
Parsing and validating authorization callbacks
Exchanging single-use authorization codes
Validating refreshed identity tokens
Revoking access and refresh tokens
Parsing the name and email supplied during first authorization
Verifying Apple's server-to-server account notifications

Here is the central callback flow:

use SafeApple\SignIn\AppleAuthorizationResponse;
use SafeApple\SignIn\LoginChallenge;

$stored = $_SESSION['apple_challenge'] ?? null;
unset($_SESSION['apple_challenge']); // Consume once.

if (!is_array($stored)) {
    throw new RuntimeException('Apple login session expired.');
}

$challenge = new LoginChallenge(
    $stored['state'],
    $stored['nonce'],
);

$callback = AppleAuthorizationResponse::fromPost(
    $_POST,
    $challenge,
);

$callbackIdentity = $verifier->verifyAuthorizationResponse(
    $callback->identityToken,
    $callback->code,
    $challenge->nonce,
);

$tokens = $oauth->exchangeAuthorizationCode(
    $callback->code,
    'https://example.com/auth/apple/callback',
);

$exchangedIdentity = $verifier->verify(
    $tokens->identityToken,
    $challenge->nonce,
);

if (!hash_equals(
    $callbackIdentity->subject,
    $exchangedIdentity->subject,
)) {
    throw new RuntimeException('Apple identities do not match.');
}

The authorization-code exchange is not automatically retried. Codes are single-use, so blindly replaying one after an ambiguous network failure can create confusing behavior. Safe retry policy depends on the semantics of the operation, not merely on whether an HTTP request failed.

Server notifications without hidden side effects

Apple can send account events such as revoked consent, account deletion, or changes to private-email forwarding. The library verifies and returns a typed event, but it does not mark that event as processed.

That is intentional.

A cache interface cannot atomically combine “this notification has not been processed” with “apply this account change.” If a library records the event first and your database update then fails, Apple's retry may be discarded even though the account change never happened.

Instead, applications should store Apple's JWT ID under a database UNIQUE constraint and apply the account change in the same transaction:

$event = $notifications->verify($_POST['payload']);

processAppleEventOnce(
    $event->jwtId,
    function () use ($event): void {
        // Apply the corresponding account operation here.
    },
);

The library owns cryptographic verification. Your application owns durable idempotency and business behavior.

Using it with Expo and React Native

Yes, the PHP package can be the backend for a mobile app.

On iOS, Expo's expo-apple-authentication module obtains the Apple credential from the operating system. The app sends the identity token and authorization code to PHP, and PHP performs the trusted verification and code exchange. Private keys and client secrets must never be bundled into the mobile application.

The recommended shape is:

Expo / React Native       PHP backend                 Apple
        |                      |                         |
        |-- request challenge->|                         |
        |<- state + nonce -----|                         |
        |---------------- native Apple authorization -->|
        |<- credential ---------------------------------|
        |-- token, code, challenge ID ------------------>|
        |                      |-- verify/exchange ------>|
        |                      |<- tokens/identity -------|
        |<- application session|                         |

Generate the state and nonce on the server, associate them with a short-lived opaque challenge ID, and consume the challenge exactly once. The server should then verify the nonce, signature, issuer, audience, azp, time claims, and c_hash before creating its own application session.

Expo's native Apple Authentication module currently targets iOS and tvOS, not Android or web. Android and browser clients should use Apple's web authorization flow, while keeping token verification and secrets on PHP. The repository includes a complete Expo and React Native guide.

What the package deliberately does not do

Authentication libraries become risky when they quietly take ownership of application policy. This package does not create users, database records, framework routes, cookies, or sessions.

Your application is still responsible for:

Consuming login challenges once
Encrypting refresh tokens at rest
Creating secure application sessions
Applying rate limits at the public endpoint
Escaping first-login profile text before output
Mapping detailed internal exceptions to generic public errors
Processing notifications transactionally
Avoiding logs that contain tokens, authorization codes, nonces, or private keys

Framework examples are provided for plain PHP, Laravel, and Symfony, but the core remains framework-neutral.

Release confidence and honest boundaries

Version v0.1.0 supports PHP 8.1 through 8.5. Its CI pipeline runs linting, PHPStan level 8, PHPUnit tests, Composer advisory checks, and a lowest-supported-dependency build. GitHub Actions are pinned by commit SHA to reduce workflow supply-chain drift.

Those checks are valuable, but they are not the same as an independent professional security audit. This is a new open-source release, and careful review from PHP and identity specialists is welcome.

If you find a vulnerability, please use the repository's private vulnerability-reporting channel rather than opening a public issue with exploit details.

Open source and open for contributions

Safe Apple Sign In for PHP is not intended to be a closed, one-person implementation. Authentication benefits from review by people with different production environments, threat models, and framework experience.

Contributions are welcome, including:

Security and correctness reviews
Reproducible bug reports and regression tests
Laravel, Symfony, and other framework integrations
Expo and React Native examples
Cache and distributed-lock adapters
Documentation and accessibility improvements
Compatibility testing across supported PHP versions

You can start by reading the project's contribution guide, opening an issue, or submitting a pull request. For suspected vulnerabilities, please use GitHub's private vulnerability-reporting feature instead of publishing exploit details in a public issue.

Try it and help improve it

Install the package:

composer require binuka200/apple-sign-in

If this solves a problem in your project, a GitHub star, issue, test case, documentation improvement, or pull request would help the open-source library mature.

Authentication should fail closed, fail quickly, and remain maintainable. That is the standard this project is trying to meet.

DEV Community: Binuka Jayaweera