Set up Sign in with Apple

Sign in with Apple puts an Apple button on your hosted sign-in page. The person confirms with their Apple Account, often with Face ID or Touch ID on an iPhone or Mac, and comes back to your app signed in. They can share their real email address or let Apple hide it behind a forwarding one. It suits apps with many iPhone and Mac users. Apple asks for more than other providers: a paid developer membership, an identifier for your website sign-in (a Services ID), and a private key file that BuildBase signs with.

What goes where

Only the key file is secret. There is no client secret to copy: Apple's client secret is a short-lived token signed with your key, and BuildBase makes it for you.

1. Make the identifiers and the key at Apple

These are the steps the console shows under How to get your Apple keys.

1. Sign in to your Apple Developer account.
2. Under Certificates, Identifiers & Profiles, register an App ID with Sign in with Apple turned on, if you do not have one. If you have an iPhone app, its App ID will do.
3. Register a Services ID, such as com.acme.analytics.signin, with a description such as Acme Analytics sign-in. That identifier is the Services ID BuildBase asks for. It is not the App ID.
4. Under Keys, make a key with Sign in with Apple turned on, linked to that App ID. Download its .p8 file (Apple lets you do this only once) and note its Key ID. The file is named AuthKey_ followed by the Key ID.
5. Your Team ID is under Membership details in your Apple Developer account.

2. Add Apple in the BuildBase console

1. In the console, open User management, then Authentication under Access, and the Methods tab.
2. Press Add auth method and choose Apple. The dialog says what Apple needs and opens How to get your Apple keys.

3. Fill in the form:
   • Title: your own name for the method, shown in the console only. The button always says Apple.
   • Services ID, Team ID and Key ID: as in the table above.
   • Private key (.p8): open the .p8 file in a text editor such as Notepad or TextEdit and paste all of it, from -----BEGIN PRIVATE KEY----- to -----END PRIVATE KEY-----.
   • Scopes: keep name email.

BuildBase checks the key when you press Create. Pasting the file's name, or part of the file, is refused at once:

4. Press Create. The dialog says One step left and shows two values: the domain under Domains and Subdomains and the return URL under Return URLs, each with Copy.

5. Press Done.
6. At Apple, open the Services ID, turn on Sign in with Apple, and choose Configure. Pick your App ID as the primary App ID, and add the domain under Domains and Subdomains and the return URL under Return URLs. Save the Services ID.

The return URL has this shape, and the domain is its host:

https://api.console.buildbase.app/api/v1/auth/social/apple/<orgId>/<methodId>/callback

It starts with your BuildBase server, https://api.console.buildbase.app{/* @endstat */} on BuildBase's cloud. Apple sends the person back to it with a form POST, not a redirect, so on a self-hosted server anything in front of BuildBase must let POST requests through to that path.

The key is write-only. When you edit the method later, the key box is empty and says a private key is saved. Leave it empty to keep it, or paste a new key file to replace it, with its new Key ID.

3. Attach it to your app

1. Open the Settings tab and press Edit on Acme Analytics.
2. Under Methods, tick Apple and press Update.

4. Check the preview

The Preview on the Sign-in page tab shows your look with sample GitHub and Google buttons, whatever your app offers. Press Open the live page for Acme Analytics above it to see the real page with the Apple button.

5. What people see

The hosted sign-in and register pages now have an Apple button.

Pressing it opens Apple's page. The first time, Apple asks the person whether to share their name, and whether to share their email address or hide it. Then Apple sends them back, and the sign-in page carries on as after any sign-in: a second step if your two-step policy asks social sign-ins for one, Trust this device?, and the passkey offer if your app offers passkeys.

The first sign-in

• The name arrives once. Apple sends the person's name only the first time they authorize your Services ID, and BuildBase saves it then. Later sign-ins carry an ID and an email address, and no name. To see the first time again while you test, remove your app under Sign in with Apple in the settings of the Apple Account you test with.
• Hide My Email. A person who hides their address gets one at privaterelay.appleid.com, such as [email protected], which forwards to their real inbox. That relay address matches no account they made another way, so where sign-up is open their first Apple sign-in makes a new account. Someone who already has an account should sign in as before and connect Apple from the Security screen.
• Mail to relay addresses is forwarded only from senders you register with Apple. Under Certificates, Identifiers & Profiles, then Services, register the domain or address your app's email comes from under Sign in with Apple for Email Communication. Until you do, magic links, sign-in codes and every other email to those people bounce.
• Finding the account: by the person's Apple user ID first, then by email address when Apple says it is verified (relay addresses count as verified), then as a new account if sign-up is open to them and your plan has room.
• The ID is per team. Apple gives the same person a different user ID, and a different relay address, in each developer team. If you import users with their Apple sign-ins, use a Services ID in the same team as before. Otherwise they are found by email address, which fails for anyone who hid theirs.

In your app

Nothing changes in your code. People connect and remove Apple on the SDK's Security screen: see Account security screens.

import { useSaaSAuth } from '@buildbase/sdk/react';

export function SecurityButton() {
  const { openWorkspaceSettings } = useSaaSAuth();
  return (
    <button onClick={() => openWorkspaceSettings('security')}>Security</button>
  );
}

Check it works

• Apple is in the Login methods list.
• The Services ID has Sign in with Apple on, with the domain and the return URL from the console.
• Your sending domain is registered under Sign in with Apple for Email Communication.
• Apple is ticked on your app, and Open the live page on your deployed server shows the button.
• A first sign-in creates a user with a name; a second reaches the same user.

Things to watch out for

• The name comes once, and is lost if that sign-in is refused. Apple sends the person's name only the first time they authorize your Services ID. If that first sign-in is turned away (sign-up closed, an address not on your allowlist, the waitlist, a full plan), the account made later is named after the first part of its email address, which for a hidden address is a string of random letters. The person can fix it on the Account screen.
• Hidden addresses bounce your email until you register your sender. Under Sign in with Apple for Email Communication, register the domain your email comes from. Apple checks it with SPF or DKIM, and the domain must match the sending domain exactly. If you send from a Gmail or other address on a domain you do not own, register that single address instead.
• A hidden address matches nothing you already have. It matches no account made another way and no domain on your allowlist, so where sign-up is open, the first Apple sign-in of someone who hid their address makes a new account.
• Apple needs a public HTTPS server. It refuses localhost and IP addresses as return URLs, so test on a deployed BuildBase server.
• User IDs and hidden addresses belong to one developer team. Make every Services ID for this app in the same Apple developer team, or people who hid their address cannot be found again.
• Finish at Apple within 10 minutes. A sign-in left open on Apple's page for more than 10 minutes cannot finish: BuildBase sends the browser to your sign-in page, with a note that the sign-in expired. Start again from your app's Sign in button.

If something goes wrong

Next steps

• Social providers - the reference for every provider.
• Importing users - bring people over with their Apple sign-ins.
• Account security screens - connected accounts inside your app.
• Set up sign-in, step by step - every sign-in guide, and the order to set them up in.