Apple

​

At a glance

npx @deploybaseline/cli start --service apple

import { createEmulator } from "@deploybaseline/cli";

const apple = await createEmulator({ service: "apple" });
// apple.url is http://localhost:4000

{
  "apple": {
    "users": [
      {
        "email": "[email protected]",
        "name": "Test User"
      }
    ],
    "oauth_clients": [
      {
        "client_id": "com.example.app",
        "team_id": "TEAM001",
        "name": "My Apple App",
        "redirect_uris": ["http://localhost:3000/api/auth/callback/apple"]
      }
    ]
  }
}

​

Start

npx @deploybaseline/cli start --service apple

​

Authorization flow

• GET /auth/authorize — Authorize: shows the user picker
• POST /auth/token — Exchange token: authorization code, refresh token, and client credentials with scope user.migration
• POST /auth/revoke — Revoke token

1. Redirect the user to /auth/authorize with client_id, redirect_uri, scope, state, response_mode=form_post (required for name or email), and optionally nonce and code_challenge
2. The emulator renders a user picker page where the user selects a seeded account
3. On selection, the emulator auto-submits a form to redirect_uri with code and state (or redirects, for query and fragment)
4. On the first authorization per user and client, the form also carries the user JSON, as Apple’s does
5. Exchange the code for tokens via POST /auth/token with client_id, client_secret, redirect_uri, and code_verifier when a challenge was sent

• name and email can only come back through response_mode=form_post. A query or fragment request for either scope gets Apple’s error, response_mode must be form_post when name or email scope is requested. With scope=openid (or no scope), query puts code and state in the query string and fragment puts them after #.
• The user JSON (name and email, only the parts that were requested) is posted with the code on the first authorization per user and client only.
• A code works once, only for the client_id it was issued to, and only with the redirect_uri of the authorization request. Codes expire after 5 minutes.
• PKCE: Apple does not document it and discovery does not list it, but when the authorization request carries a code_challenge (S256 or plain), the token request must send the matching code_verifier. Another code_challenge_method is refused.
• Refresh tokens and revocation are tied to the client that received the token; another client’s refresh is invalid_grant and its revocation is a quiet no-op.

​

Parameters

​

Client secret

import { SignJWT, importPKCS8 } from 'jose'

const clientSecret = await new SignJWT({})
  .setProtectedHeader({ alg: 'ES256', kid: process.env.APPLE_KEY_ID })
  .setIssuer(process.env.APPLE_TEAM_ID)
  .setSubject(process.env.APPLE_CLIENT_ID)
  .setAudience('https://appleid.apple.com')
  .setIssuedAt()
  .setExpirationTime('180d')
  .sign(await importPKCS8(process.env.APPLE_PRIVATE_KEY, 'ES256'))

​

ID tokens

• GET /.well-known/openid-configuration — OIDC discovery document
• GET /auth/keys — JSON Web Key Set (JWKS)

​

Signing key

​

Team transfers

• POST /auth/usermigrationinfo — Transfer user: team transfers (transfer_sub)

1. The sending team posts sub, target (the recipient team ID), client_id, and client_secret, and gets {"transfer_sub": "..."}.
2. The recipient team posts transfer_sub, client_id, and client_secret, and gets {"sub": "..."} with the user’s new sub at that team, plus a new private relay email and is_private_email for users who hide their email.

​

Server-to-server notifications

• POST /_apple/simulate/notification — Simulate notification: send a server-to-server notification and apply its change

{ "type": "email-disabled", "sub": "001234.abc...", "email": "[email protected]", "is_private_email": "true", "event_time": 1760870000000 }

​

Seed config

{
  "apple": {
    "users": [
      {
        "email": "[email protected]",
        "name": "Test User",
        "given_name": "Test",
        "family_name": "User"
      },
      {
        "email": "[email protected]",
        "name": "Private User",
        "is_private_email": true
      }
    ],
    "oauth_clients": [
      {
        "client_id": "com.example.app",
        "team_id": "TEAM001",
        "key_id": "KEY0000001",
        "public_key": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----",
        "name": "My Apple App",
        "redirect_uris": ["http://localhost:3000/api/auth/callback/apple"]
      }
    ]
  }
}

​

Conformance