auth4.dev

Apple sign-in

Players choose Apple on the hosted login page, sign in on Apple's own page, and return signed in. You need an Apple Developer Program membership, a Services ID and a Sign in with Apple key.

1. Set up Sign in with Apple

Do these steps in Certificates, Identifiers & Profiles in your Apple Developer account.

  1. App ID. Open an existing App ID for your game, or register a new one, and enable the Sign in with Apple capability. This is the primary App ID the other steps point to.
  2. Services ID. Register a new Services ID with a reverse-DNS identifier, such ascom.example.game.signin. This identifier is the client ID auth4.dev uses. Enable Sign in with Appleon it and configure it:
    • Primary App ID: the App ID from the previous step.
    • Domains and subdomains: auth.auth4.dev
    • Return URLs: this URL, replacing {projectId} with your Project ID:
      https://auth.auth4.dev/t/{projectId}/identity/apple/callback
    The console shows the exact URL with a copy button on the Apple card. It must match exactly.
  3. Key. Under Keys, create a key with Sign in with Apple enabled and configured for the same primary App ID. Download the .p8 file. Apple lets you download it only once, so keep it somewhere safe and out of source control. Note the key's 10-character Key ID.
  4. Team ID. Copy your 10-character team ID from the membership details of your Apple Developer account.

2. Connect it in the console

On the project's sign-in methods page, under Apple:

  1. Enter the Services ID identifier in Services ID.
  2. Enter your team ID in Team ID and the key's ID in Key ID.
  3. Open the .p8 file in a text editor and paste all of it, including the BEGIN PRIVATE KEY and END PRIVATE KEY lines, into Private key.
  4. Tick Enable Apple sign-in.
  5. Select Save Apple settings.

Only project owners can change these settings; admins and viewers see them read-only. The private key is write-only: it is stored encrypted and can't be viewed again. Apple's client secret is a short-lived token that auth4.dev signs with your key for each sign-in, so there is no client secret to copy or renew.

To rotate the key, create a new Sign in with Apple key, enter its key ID and paste it into Replace private key, save, and then revoke the old key at Apple. Changing the Services ID, team ID or key ID always needs the private key again.

Once Apple is on, players see it in three places:

  • Continue with Apple on the hosted login page.
  • Link an Apple account on the page where guests save their progress.
  • Continue with Apple on the device approval page.

Untick the box and save to turn Apple off. The option disappears from all three pages.

What identity data you get

  • Players are identified by the ID Apple gives them for your team (the ID token's sub). It stays the same across the apps and Services IDs of one team, but not across teams. It is stored as the player's Apple identity and isn't put in your tokens. Key game data by your auth4.dev sub.
  • Apple shares an email address, which auth4.dev marks verified when Apple says it is. Players can choose Hide My Email, in which case the address is a private relay address ending in privaterelay.appleid.com that forwards to them. To send mail to relay addresses, register your sending domains with Apple's private email relay service.
  • Under the default setting, the verified email step is skipped when Apple says the address is verified. Apple's address never becomes the emailclaim; only an address verified with auth4.dev does.
  • Apple sends the player's name only on their first sign-in. auth4.dev doesn't ask for it or store it.
  • An Apple account and an email-code, Discord, Google or Microsoft account with the same address are separate players. They are joined only through account linking in the email step.
  • Apple's tokens and your private key stay on the server. Your application only receives auth4.dev tokens.

Sending players straight to Apple

For a Sign in with Apple button, pass the provider to the browser SDK. The hosted login page then goes straight to Apple:

await auth4.login({ provider: "apple" });

login() sends provider_hint=apple. The Next.js SDK takes the same provider. If you build the authorization request yourself, add that parameter. If Apple is off for the application, the player sees the usual list instead. See theAPI reference.

Linking Apple to a guest

A guest can save their progress by linking an Apple account. They keep the same user ID and stop being a guest. Call upgradeGuest() or, in Unity, UpgradeGuestAsync without a provider, and the upgrade page offersLink an Apple account with the other enabled methods. Only an Apple account that is new to your project moves to the guest; otherwise the upgrade fails with identity_in_use. Accounts are never merged.

Device approval

When Apple is on, the device approval page offers Continue with Apple. After Apple, the player comes back to the same code to approve or deny it. Nothing changes on the game's side.

When something goes wrong

  • If the player cancels on Apple, the page says that Apple sign-in was cancelled and lets them choose another method.
  • If Apple is unreachable or refuses the request, the page reports a temporary problem and offers a retry. A wrong team ID, key ID or private key shows up this way, as does a key that was revoked at Apple.
  • If Apple shows an error on its own page before the player can sign in, the Services ID or its return URL doesn't match. Check both against the console card.
  • If the Apple option doesn't appear, check that the box is ticked and all four values are saved. Incomplete configuration fails closed rather than showing a broken button.

Testing locally

Apple only returns to registered HTTPS return URLs, which is the auth4.dev callback, so your app itself can still run on localhost. You need a real Apple Account to sign in. Use a separate auth4.dev project for testing. To run the auth4.dev API itself against a local stand-in, see Testing locally on the Google page; the same setting covers Apple.