Sign in with Apple hands your service a team-scoped user identifier and, often, an email address that is not the person's real inbox, and most account linking and recovery designs quietly assume the opposite. Teams that treat the relay address as a normal email, key accounts on it, or skip server-side token checks end up with duplicate accounts, broken password resets and orphaned data when a user hides their email, revokes consent or deletes their Apple Account. This guide is for developers, identity architects and customer identity (CIAM) owners who run Sign in with Apple on iOS, macOS or the web. It covers token validation, the relay service, linking and recovery, notifications, revocation, client secrets and app transfers. General social login linking rules are in the Social Login and Account Linking Security Guide; this page goes deeper on the Apple-specific behaviour.
This is an independent guide from NHI Mgmt Group, based on Apple's public documentation as of November 2026. It is not sponsored or reviewed by Apple. Product features change, so confirm settings against Apple's current documentation.
Key takeaways
- Key every account on
sub, never on email. Apple's documentation describessubas the stable, primary identifier for the user, shared across all apps in your development team and unchanged if the user stops and later resumes using Sign in with Apple. - Validate the identity token on your server every time. Check the signature against Apple's published keys (matching
kid),issequal tohttps://appleid.apple.com,audequal to yourclient_id,exp, and thenonceyou issued. - Treat the relay address as a delivery channel, not an identity. It routes to one of the user's verified addresses, is unique per development team, carries a daily limit of 100 emails, and stops delivering the moment the user turns forwarding off.
- Subscribe to server-to-server notifications.
email-disabled,email-enabled,consent-revokedandaccount-deletedevents tell you when to stop emailing, end sessions or start deletion. - Revoke tokens when an account closes. Apple asks apps that support Sign in with Apple to call the REST revoke endpoint during account deletion, so store a refresh token at first sign-in to make that possible.
How Sign in with Apple differs from other social login
Sign in with Apple follows the familiar OAuth 2.0 and OpenID Connect pattern: your app receives an identity token (a signed JWT), a single-use authorisation code, the state from your request and a user identifier. Several behaviours are specific to Apple and drive most of the security design.
| Behaviour | What Apple documents | Design consequence |
|---|---|---|
| Team-scoped identifier | sub is the same across all apps of one development team and different for the same person across teams | Store sub as the federated key; plan for app transfers, because a new team sees a new sub |
| Name and email on first authorisation | The API shares name and email the first time the user signs in; later sign-ins do not ask again, though the email remains in the identity token | Persist the name immediately and idempotently; a failed first request loses it until the user disconnects and reconnects |
| Private email relay | Users can share an anonymous address ending in @privaterelay.appleid.com or, for new addresses from late 2026, @private.icloud.com (Apple developer news, 24 August 2026) | Email matching to existing accounts fails by design; build an explicit linking step |
| Two-factor Apple Account | Sign-in uses the user's two-factor Apple Account, with Face ID, Touch ID or passcode on Apple devices | A strong first factor, but your own session, step-up and recovery controls still apply |
| Real user indicator | real_user_status returns 0 Unsupported, 1 Unknown or 2 LikelyReal, on first sign-in only and only on native platforms from iOS 14 and macOS 11 | Use it as one fraud signal at account creation, never as a gate |
| Web versus native | Native apps allow only the signed-in iCloud user; web interactions allow any Apple Account | Web flows need state, nonce and redirect URI discipline that native flows partly get from the platform |
Whether to offer social sign-in at all is covered in Social Login vs Native Accounts.
Identity token validation on the server
Apple's "Verifying a user" article lists the server checks. Do them in your backend, never only in the client, and reject the sign-in if any fails.
- Signature: fetch Apple's JSON Web Key Set from
https://appleid.apple.com/auth/keys. Apple notes the endpoint can return several keys and the count varies over time, so select the key whosekidmatches the token header. Cache the set and pin the accepted algorithm in your JWT library rather than trusting the header. See the JWT Security Guide. - Issuer:
issmust be exactlyhttps://appleid.apple.com. - Audience:
audmust be yourclient_id: the bundle ID for a native app or the Services ID for the web. If you run both, keep an explicit allow-list of your own IDs, not a prefix match. - Expiry: the current time must be earlier than
exp. - Nonce: generate a random nonce per sign-in, bind it to the client session, and compare it to the
nonceclaim. Apple'snonce_supportedclaim tells you whether the platform supports anti-replay values: if you sent a nonce, the claim is missing andnonce_supportedis true, fail the transaction. - Authorisation code exchange: for web apps, Apple says the identity token is obtained by validating the authorisation code at
POST https://appleid.apple.com/auth/tokenwithgrant_type=authorization_code. The response carries anid_token, a one-hour access token and a refresh token. Includeredirect_urionly if your original request did. - Bind state: on the web, compare the returned
statewith the value stored in the user's pre-authentication session to stop cross-site request forgery on the callback.
Claims to read, and how to read them
| Claim | Meaning (per Apple) | Safe use |
|---|---|---|
sub | Unique, stable user identifier for your team | Primary key of the federated identity record |
email | Real address or relay address; Apple says not to use it as an identifier | Contact channel only |
email_verified | String or Boolean; may be false for Sign in with Apple at Work and School users | Parse both forms; never assume true |
is_private_email | String or Boolean showing whether the address is the relay proxy | Drives your linking and messaging logic |
real_user_status | 0, 1 or 2; native platforms only | Risk score input at sign-up |
transfer_sub | Transfer identifier, present only during the 60-day transfer period | Map migrated users to new sub values |
org_id | Organisation of a Managed Apple Account in Apple School Manager or Apple Business Manager | Tenant routing for business and education apps |
A common parsing defect is comparing email_verified or is_private_email with a Boolean when the token carries the string "true", or the reverse. Normalise both forms in one function and unit-test it.
The private email relay service
When a user chooses Hide My Email, Apple's relay routes all mail between you and the user through an automatically generated address. Apple documents three properties that matter for security design:
- Delivery: mail to the relay reaches one of the Apple Account's verified addresses, and replies return through the relay, so the user's real address is never revealed to you.
- Scope: the address is the same for a user across all apps of one development team and different across teams. Two of your apps see one relay address; a partner company sees another.
- Limit: each relay address has a daily limit of 100 emails, counting your messages to the address and the user's replies.
Sender registration
To send to relay addresses you must register your outbound email addresses or domains in your Apple developer account and authenticate the mail with SPF. Apple states this ensures only you can reach your users through the channel. In practice:
- Register every sending path: transactional mail, marketing platforms and support desks often send from different domains or third-party infrastructure. An unregistered sender's mail is not delivered, which surfaces as "password reset never arrived" tickets.
- Keep SPF, DKIM and DMARC aligned: Apple names SPF; DKIM and DMARC remain good practice for every recipient. See the DMARC, SPF and DKIM Guide.
- Treat the registration list as a controlled asset: anyone who can add a sender can reach your entire Apple user base through the relay. Restrict who can change it.
- Budget for the daily limit: notification-heavy products should collapse alerts into digests for relay users rather than risk hitting 100 messages a day and losing a security notice.
When a user stops receiving email from your app, the relay rejects all future messages to that address. Because the address is shared by your team's apps, Apple informs the user of all other affected apps. Your platform learns of it through the email-disabled notification described below.
Account linking when the email is a proxy
Email-based auto-linking, already risky for any provider, simply does not work for relay users: the relay address will never match the address on an existing native account. Apple's own guidance on preventing duplicate accounts suggests two approaches: offer existing keychain credentials through ASAuthorizationPasswordProvider so the user signs in to the account they already have, and, for new Sign in with Apple accounts, tell the user they are creating a new account and ask whether they have an existing one to link.
- Link only after proving control of both sides: the user signs in with Apple, then authenticates to the existing account with its own credential (password plus MFA, or a passkey). Only then write the
subto the existing account record. Never link on a matching real email shown in the token without that second proof; the general pre-hijacking classes are in the Social Login and Account Linking Security Guide. - Store one federated record per provider: a table of (provider, subject, user ID, linked_at, link_method) keeps Apple identities separate from email, so a later change of relay state does not break the link.
- Record the relay flag: keep
is_private_emailbeside the stored email so support staff and automated jobs know the address is a proxy. - Offer a verified contact address: if your service needs a real address (receipts to an accounts team, regulatory notices), ask for it separately and verify it with a one-time link. Keep it distinct from the Apple-supplied address and let the user choose which to use.
- Unlinking: before letting a user remove Sign in with Apple, require another working sign-in method, or the account becomes unreachable.
Recovery and support when Apple is the only credential
Most recovery flows send a reset link to the account email. For a relay user that link travels through Apple, works only while forwarding is enabled, and lands in an inbox you cannot see. Design for these cases:
| Situation | What happens | Recovery design |
|---|---|---|
| Forwarding disabled | Relay rejects mail; your reset emails and security alerts fail | On email-disabled, flag the account and prompt in-app for a verified contact address |
| Consent revoked | Credentials become invalid for your app | End sessions; on next Apple sign-in the same sub returns, so reattach the existing account |
| Apple Account deleted | Apple invalidates all user tokens and disables relay forwarding for all associated apps | Start your deletion or dormancy process; there is no Apple path back to this identity |
| Help desk caller claims to own an account | The agent sees only a relay address and a sub | Verify through an in-app or signed-in channel, never by "confirming" a relay address read out on the phone |
Help desk social engineering targets exactly these gaps. See the Account Recovery and Help Desk Security Guide for verification scripts.
Server-to-server notifications and session control
Register an endpoint in your developer account to receive Apple's notifications. Apple requires TLS 1.2 or later on the endpoint and allows one URL for several teams and apps. Each notification is a JWS signed by Apple; validate its signature with the same key set as identity tokens, using the algorithm from the header, then act on the type in the events claim.
| Event type | Meaning | Action |
|---|---|---|
email-disabled | User turned off forwarding to their personal address | Suppress mail to the relay address; request another contact channel in-app |
email-enabled | User turned forwarding back on | Re-enable mail; keep suppression history for audit |
consent-revoked | User stopped using their Apple Account with your app; credentials are invalid | Revoke your sessions and refresh tokens for that sub; keep the account for a defined period |
account-deleted | User asked Apple to delete their Apple Account | Run your account deletion or retention process for that sub |
- Validate before acting: check signature,
iss,audandiat; deduplicate onjtiso a replayed notification cannot repeat a deletion. - Native apps: Apple notes that on account deletion the system does not send
credentialRevokedNotificationto native apps; callgetCredentialState(forUserID:completion:), which Apple describes as a local, inexpensive call, and sign the user out when the state changes. - Refresh token checks: on other platforms, Apple suggests using periodic refresh token validation to set session lifetime, no more than once a day, as calls may be throttled above that rate.
Token revocation and account deletion
Apple's account deletion guidance says apps that support Sign in with Apple should use the REST API to revoke user tokens. The revoke endpoint is POST https://appleid.apple.com/auth/revoke with your client_id, client_secret, the token, and token_type_hint set to refresh_token or access_token. It returns HTTP 200 with no body when the token is invalidated or was already invalid.
- Store the refresh token at first sign-in: revocation needs a valid refresh or access token. Encrypt it at rest with a key held in a secrets manager or KMS, scoped to the deletion service.
- Order the deletion steps: revoke with Apple, end your own sessions, then delete or anonymise data, logging each step against the
sub. - Handle failure safely: if revocation errors, retry with backoff and alert; do not report deletion complete to the user until it succeeds or a documented manual path is followed.
Where identity fits: the client secret and signing key
Every call to /auth/token and /auth/revoke authenticates your service with a client_secret: a JWT you sign with a private key downloaded from your developer account. Apple's specification is alg ES256, a 10-character kid, iss set to your Team ID, aud set to https://appleid.apple.com, sub set to the App ID or Services ID, and an exp no more than 15777000 seconds (six months) ahead. That private key is a non-human credential with power over your whole Apple user base.
- Keep the key in a vault or HSM-backed KMS, never in source, mobile binaries or CI variables visible to every job. See the Secrets Management Guide.
- Mint short-lived client secrets (minutes to hours) on demand, rather than one six-month secret pasted into configuration.
- Rotate the key when staff with developer account access leave, and revoke unused keys in the developer account.
- Limit developer account roles, since the same account controls keys, Services IDs, return URLs, notification endpoints and relay sender registration.
App transfers between developer teams
Because sub and relay addresses are team-scoped, moving an app to another team (an acquisition or a reorganisation) changes both. Apple's migration process protects user privacy with a transfer identifier:
- Ungroup apps that are grouped for Sign in with Apple; App Store Connect will not transfer an app that is part of a group.
- Obtain access tokens: the transferring team can request one with
grant_type=client_credentialsandscope=user.migration. - Generate transfer identifiers: call
POST /auth/usermigrationinfowith each user'ssuband the recipient Team ID to receive atransfer_sub. - Export only the transfer identifier: Apple requires the export to exclude the team-scoped identifier and private email address.
- Recipient exchanges within 60 days: the recipient must exchange transfer identifiers for its own team-scoped identifiers within 60 days of accepting the transfer; the
transfer_subclaim appears in identity tokens only during that period. - Plan email continuity: Apple warns that if a user uses no other app from the transferring team, the transferring team can no longer reach them by relay address after the transfer. Send any required notices before completion.
Track the 60-day deadline as a project milestone and encrypt the export in transit.
Implementation and rollout
- Model the data first: federated identity table keyed on (provider,
sub), relay flag, verified contact email, encrypted refresh token. - Build server validation with the seven checks above and unit tests for expired tokens, wrong
aud, missing nonce and string versus Boolean claims. - Register sender domains and send test mail to a relay address from every system that emails customers.
- Stand up the notification endpoint and replay sample payloads in staging to prove each event drives the right action.
- Wire revocation into account deletion and test it end to end with a test Apple Account.
- Pilot linking and recovery with internal users who choose Hide My Email, then release behind a feature flag. Roll back by disabling new Apple sign-ups while keeping sign-in for existing linked accounts, so no user is locked out.
Detection and measurement
- Token validation failure rate by reason (signature,
aud,exp, nonce). A spike in nonce oraudfailures points to replay attempts or a misconfigured client. - Relay bounce and rejection rate per sending system; unregistered senders show up here first.
- Notification processing lag from
event_timeto completed action; target minutes, not days, forconsent-revoked. - Duplicate account rate among new Apple sign-ups, measured by later support merges.
- Revocation success rate on account deletion.
- Link events logged with method and source IP, alerting on links to high-value accounts shortly after a password reset. Map these to ATT&CK T1078 Valid Accounts and T1550.001 Application Access Token when building detections.
Framework mapping
| Control area | NIST SP 800-53 Rev. 5 | NIST CSF 2.0 | OWASP ASVS 5.0 |
|---|---|---|---|
| Authenticating external users through a federated provider | IA-8 | PR.AA-03 | OAuth and OIDC chapter |
| Account lifecycle on revoke and delete events | AC-2 | PR.AA-01 | Authentication chapter |
| Client secret and signing key management | IA-5, SC-12 | PR.AA-01 | Self-contained tokens chapter |
| Session binding, nonce and state | SC-23, AC-12 | PR.AA-03 | Session management chapter |
| Monitoring link and token events | AU-6 | DE.CM-03 | Logging chapter |
Common failure patterns
- Accounts keyed on email: the user hides their email on a second device or after reconnecting, and a duplicate account appears with no history.
- Name lost on first sign-in: the backend call fails, the app retries later, and Apple no longer returns the name.
- Client-only validation: the mobile app decodes the token and posts
subto the API, which trusts it; anyone can then post anysub. - Unregistered marketing or support sender: security notices and resets to relay users silently fail.
- No notification endpoint: consent revocations and account deletions are never processed, leaving live sessions and retained data for people who have left.
- Six-month client secret in a repository: one leaked file grants token exchange and revocation for every user.
Practitioner checklist
- Key federated identities on (Apple,
sub) and treat email as a contact attribute only. - Validate signature by
kid,iss,aud,exp,nonceand webstateon the server for every sign-in. - Persist name, email and relay flag on first authorisation, idempotently.
- Register every outbound sender for the relay and authenticate with SPF, DKIM and DMARC.
- Require proof of the existing credential before linking an Apple identity to an account.
- Run a validated, deduplicated server-to-server notification endpoint for all four event types.
- Store refresh tokens encrypted and call the revoke endpoint in account deletion.
- Hold the client secret signing key in a vault or KMS, mint short-lived secrets and rotate on staff change.
- Plan app transfers around the 60-day
transfer_subwindow.
Standards and references
- Apple: Verifying a user
- Apple: id_token claims
- Apple: Communicating using the private email relay service
- Apple: Processing changes for Sign in with Apple accounts
- Apple: Token revocation
- Apple: Transferring your apps and users to another team
- Apple: Offering account deletion in your app
- NIST: SP 800-53 Rev. 5
Related NHI Mgmt Group resources: Social Login and Account Linking Security Guide · Social Login vs Native Accounts · Apple Platform Security Explained · Customer IAM (CIAM) Guide