Appearance
Apple sign-in
"Continue with Apple" lets visitors sign in with their Apple ID, on the website and in the app. You need an Apple Developer account, about 30 minutes, and a site running on https.
You need
- A paid Apple Developer Program membership (developer.apple.com/programs). An organisation membership shows your company name on Apple's sign-in screen.
- The site live on
httpson its final domain. Apple rejectshttp, IP addresses andlocalhost, so this can't be tested on a local copy. - Access to the server, to upload a key file and edit
.env.
You will collect four values on the way:
| Value | Looks like | Goes into |
|---|---|---|
| Team ID | A1B2C3D4E5 (10 characters) | APPLE_TEAM_ID |
| Services ID | com.yourdomain.signin | APPLE_CLIENT_ID |
| Key ID | XYZ987ABCD (10 characters) | APPLE_KEY_ID |
| Private key file | AuthKey_XYZ987ABCD.p8 | APPLE_PRIVATE_KEY (its path) |
Find your Team ID
Sign in at developer.apple.com/account → Membership details. Copy the Team ID.
Create an App ID
A Services ID (next step) must belong to an App ID. If you already published the iOS app, use its App ID and just turn on Sign in with Apple.
- Go to Certificates, Identifiers & Profiles → Identifiers → +.
- Choose App IDs → Continue → type App → Continue.
- Description: your exchange name. Bundle ID: Explicit, for example
com.yourdomain.app(the iOS app's bundle ID if you have one). - In Capabilities, tick Sign In with Apple (leave it as a primary App ID).
- Continue → Register.
Create the Services ID
The Services ID is what the website signs in as. It becomes APPLE_CLIENT_ID.
- Identifiers → + → Services IDs → Continue.
- Description: your exchange name (users see it on Apple's sign-in screen). Identifier: for example
com.yourdomain.signin. It must differ from the App ID. - Continue → Register.
- Open the new Services ID from the list, tick Sign In with Apple → Configure:
Primary App ID: the App ID from the previous step.
Domains and Subdomains:
yourdomain.com(nohttps://, no path). Addwww.yourdomain.comtoo if your site uses it.Return URLs:
texthttps://yourdomain.com/auth/apple/callbackNext → Done → Continue → Save.
If Apple asks you to verify the domain with a file, download it and place it where Apple says (under public/.well-known/ on the server), then click Verify.
Create the key
- Keys → +.
- Key Name:
Sign in with Apple. Tick Sign in with Apple → Configure → choose the same Primary App ID → Save. - Continue → Register, then Download. You can download the
.p8file only once. Store a backup somewhere safe. - Copy the Key ID shown on the page (it is also in the file name).
Put the key on the server
Upload the .p8 file outside the public folder, for example /var/www/yourdomain/storage/keys/AuthKey_XYZ987ABCD.p8, and let only the web server user read it:
bash
mkdir -p storage/keys
chmod 700 storage/keys
chmod 600 storage/keys/AuthKey_XYZ987ABCD.p8
chown -R www-data:www-data storage/keys # the user PHP runs asNever put it in public/ or commit it to git.
Fill in .env
ini
APPLE_AUTH_ENABLED=true
APPLE_CLIENT_ID=com.yourdomain.signin
APPLE_TEAM_ID=A1B2C3D4E5
APPLE_KEY_ID=XYZ987ABCD
APPLE_PRIVATE_KEY=/var/www/yourdomain/storage/keys/AuthKey_XYZ987ABCD.p8
APPLE_CLIENT_SECRET=
APPLE_PASSPHRASE=
APPLE_REDIRECT_URI=https://yourdomain.com/auth/apple/callbackAPPLE_CLIENT_IDis the Services ID, not the App ID.APPLE_PRIVATE_KEYis the absolute path to the.p8file. Pasting the key text itself also works, but a path is easier to get right.- Leave
APPLE_CLIENT_SECRETandAPPLE_PASSPHRASEempty. The site makes a fresh client secret from the key for every sign-in (it is valid for one hour), so it never expires on you. APPLE_REDIRECT_URImust equal the Return URL you entered..env.examplehashttp://localhost/..., so change it.
bash
php artisan config:clearUsers who hide their email
Apple lets users share a private relay address (…@privaterelay.appleid.com) instead of their real email. The site treats it like a normal email, but Apple only forwards mail from senders you registered. Without that, codes and notices to those users never arrive.
- Certificates, Identifiers & Profiles → Services → Sign in with Apple for Email Communication → Configure.
- Add the domain and the address your site sends from (
MAIL_FROM_ADDRESS), for example[email protected]. - Make sure that domain has SPF (and preferably DKIM) records for your mail provider, as Apple requires.
If Apple shares no email at all, the user goes through Complete sign-up and adds an email or phone number with a code (details).
Test it
- Open
https://yourdomain.com/loginin a private window → the Apple button → sign in with an Apple ID. - The first time, Apple asks to share the name and email (or hide the email). You come back signed in.
- In the app: Sign in → Apple works the same way.
Apple sends the name and email only once
Apple shares them only on the first sign-in. Later sign-ins are matched by the Apple account ID, so a user who deleted their account and comes back may have no email. To start over in testing, remove your site under Apple ID settings → Sign in with Apple on your device or at account.apple.com.
Common errors
| What you see | Cause and fix |
|---|---|
| Apple page: invalid_request: Invalid web redirect url | APPLE_REDIRECT_URI isn't in the Services ID's Return URLs, or the domain isn't listed. They must match exactly (https, www). |
| Apple page: invalid_client | APPLE_CLIENT_ID is the App ID instead of the Services ID, or Sign in with Apple isn't enabled on the Services ID. |
| Our page: Apple authentication failed. | The site couldn't finish the sign-in. Usual causes: wrong APPLE_TEAM_ID / APPLE_KEY_ID, the key file path is wrong or not readable by PHP, the key was revoked, or the site runs on http (the security cookie needs https). Check storage/logs/laravel-YYYY-MM-DD.log. |
| The Apple button doesn't show | APPLE_AUTH_ENABLED isn't true, or config:clear wasn't run. |
| Users with a hidden email never get codes | Register your sending domain for the private relay (above). |
