docs: Improve Apple Sign-In setup with missing steps and troubleshooting by Zfinix · Pull Request #473 · serverpod/serverpod_docs

Zfinix · 2026-04-29T10:38:26Z

Summary

Added missing Apple JS SDK script tag for Web setup
Added --dart-define instructions for Web/Android client configuration
Added troubleshooting entries for missing JS SDK and macOS sandbox conflict
Organized troubleshooting checklist by category (Portal / Server / Client)
Consolidated 3 back-to-back admonitions into 1 tip
Fixed broken link and removed $ prefix from bash commands

Test plan

Followed every step from a fresh serverpod create project
Verified Apple Sign-In on Safari (Web) and macOS native
Confirmed each new troubleshooting entry matches a real failure mode

Swiftaxe

Found some things to improve above. Will continue review later.

…zations, and troubleshooting

…g domain requirements in troubleshooting

Swiftaxe · 2026-05-06T12:33:03Z

+The `webAuthenticationCallbackRoutePath` must match the **Return URL** you registered on your Service ID. The `revokedNotificationRoutePath` is called by Apple when a user revokes access from their Apple ID settings.

+:::tip
+If you need more control over how the credentials are loaded, you can use `AppleIdpConfig(...)` with manual `pod.getPassword()` calls instead. See the [customizations](./customizations) page for details.


This tip has slipped down to the web routes section. It belongs under "Add the Apple identity provider".

Moved the tip up under "Add the Apple identity provider" right after the AppleIdpConfigFromPasswords() example, where it actually applies.

…omization options, and troubleshooting details

Swiftaxe · 2026-05-07T08:15:42Z

 ### Add the Apple identity provider

-Your server's `server.dart` file (e.g., `my_project_server/lib/server.dart`) should already contain a `pod.initializeAuthServices()` call if your project was created with the Serverpod project template (`serverpod create`). If it's not there, verify that `serverpod_auth_idp_server` is in your server's `pubspec.yaml` and see [Setup](../../setup) to configure the auth module and JWT settings.
+In your server project directory, add the auth IDP server package:


Under prerequisites we expect this to be installed. Now we add it. Is this in case they skipped the prerequisites? Please explain.

You're right. Reframed the step as a fallback for users on upgraded projects that don't have it yet, instead of presenting it as required.

Swiftaxe · 2026-05-08T11:10:46Z

+```

-Add the Apple import and `AppleIdpConfigFromPasswords()` to the existing `identityProviderBuilders` list:
+`AppleIdpConfigFromPasswords()` reads the eight `apple*` keys from `config/passwords.yaml` (or the corresponding `SERVERPOD_PASSWORD_` environment variables), so you do not have to wire up each credential manually. In your server's `server.dart`, import it and add it to the existing `identityProviderBuilders` list on `pod.initializeAuthServices()`:


It is a bit confusing to lead with an explanation of the FromPasswords function, before it gets introduced. (AppleIdpConfigFromPasswords() reads the eight apple* keys from...)

We could let this paragraph only instruct the user to add the import and the FromPasswords, then comes the code sample and then we explain the FromPasswords.

Move the explanation sentence to after the code example and rephrase this paragraph.

Restructured: now the paragraph just tells the reader to add the import + provider, then the code block, then a short sentence explaining what AppleIdpConfigFromPasswords() does. Reads in the right order now.

Swiftaxe · 2026-05-08T11:16:25Z

+
+Before you start, make sure you have:
+
+- A Flutter project created with `serverpod create` (so the auth module and project template are in place).


This is true for most users, but not if you created the project with a an older framework version (<3.4?)
A user might not now what the auth module and project templates means. They should be able to quickly check off that they fulfill the prerequisites. And what to do if they don't (ie missing the new auth module).

The same goes for all providers.

Good catch. Updated the prerequisite to call this out explicitly: new projects (Serverpod 3.4+) get the auth module via serverpod create, and older projects are pointed at the auth module setup guide first. Will mirror this on the other providers.

Swiftaxe · 2026-05-08T11:22:31Z

+In your server project directory, add the auth IDP server package:
+
+```bash
+dart pub add serverpod_auth_idp_server


Do they need to do this if they fulfilled the prerequisites above? (ie have the auth module installed)

Reworded the step as a fallback for upgraded projects rather than a required install.

It is better now. However, a user having an old project still has to follow the full guide to install the auth module, right?

Is it better to refer to the full setup guide instead?
We do that under prerequisites, but if they rushed past it, this is good place to remind them.

Swiftaxe · 2026-05-08T11:23:16Z

+In your Flutter app's directory, add the auth IDP Flutter package:
+
+```bash
+flutter pub add serverpod_auth_idp_flutter


This should be installed if prerequisites are met, right?

Correction on my earlier reply, you were right. Verified that serverpod create adds serverpod_auth_idp_flutter to the Flutter pubspec by default. Reframed the flutter pub add line as a fallback ("if your app doesn't have this, e.g. you're upgrading an older project, add it") instead of a required step.

If this step doesn´t cover the whole setup for the client, we should refer to the auth module setup page instead, as noted in the server section as well.

Swiftaxe · 2026-05-08T12:42:48Z

+
+### Set production credentials
+
+Switch from the `development:` values you used during setup to production ones. Pick the path that matches your deployment:


The normal use case is not to "Switch" credentials, right? You want to add the production ones so they are in use when running in production, and dev credentials will still be used in development. Rephrase this so it's clear for new backend devs to not replace the dev credentials.

Rewrote the section. It now leads with "production runs out of the production: section, separate from development:" so it's clear that adding production credentials does not replace dev ones. Both stay and Serverpod picks the right set per run mode.

Swiftaxe · 2026-05-08T13:05:52Z

 );
 ```

-:::info


Is this outdated as it was removed? (That an exception here would abort the account creation)

Verified in serverpod_auth_core_server: onAfterAuthUserCreated does run inside the same transaction as the auth user creation (the handler is called with the same transaction and exceptions propagate out, aborting the create). Re-added the info note under the example, rephrased for the user-level callback.

…ions, customization tips, and additional notes on credential management

`serverpod create` already ships `serverpod_auth_idp_server` and `serverpod_auth_idp_flutter` in the generated pubspecs, so the bare `pub add` steps were redundant for users on the standard template.

Zfinix requested a review from Swiftaxe April 29, 2026 10:38

Swiftaxe reviewed May 1, 2026

View reviewed changes

Swiftaxe reviewed May 4, 2026

View reviewed changes

Zfinix force-pushed the chore/update-sign-in-with-apple-docs branch from 7b94a3d to 132800b Compare May 4, 2026 16:48

docs: Update Apple Sign-In documentation with enhanced setup, customi…

12648da

…zations, and troubleshooting

Zfinix force-pushed the chore/update-sign-in-with-apple-docs branch from 910cc7e to 12648da Compare May 4, 2026 16:54

docs: Clarify Apple Sign-In setup and customization details, includin…

9330e95

…g domain requirements in troubleshooting

Zfinix requested a review from Swiftaxe May 5, 2026 08:20

Swiftaxe reviewed May 6, 2026

View reviewed changes

docs: Refine Sign in with Apple documentation, clarifying setup, cust…

7922026

…omization options, and troubleshooting details

Swiftaxe reviewed May 8, 2026

View reviewed changes

Zfinix added 2 commits May 11, 2026 03:25

docs: Enhance Apple Sign-In documentation with updated setup instruct…

39f870e

…ions, customization tips, and additional notes on credential management

docs: Frame IDP package install as upgrade fallback in Apple setup

0a60858

`serverpod create` already ships `serverpod_auth_idp_server` and `serverpod_auth_idp_flutter` in the generated pubspecs, so the bare `pub add` steps were redundant for users on the standard template.

Zfinix requested a review from Swiftaxe May 12, 2026 08:09


		Before you start, make sure you have:

		- A Flutter project created with `serverpod create` (so the auth module and project template are in place).


		### Set production credentials

		Switch from the `development:` values you used during setup to production ones. Pick the path that matches your deployment:

               );
               ```
-              :::info

Conversation

Zfinix commented Apr 29, 2026

Summary

Test plan

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Swiftaxe left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Zfinix May 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Zfinix May 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Zfinix May 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Zfinix May 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Swiftaxe left a comment •

edited

Loading

Zfinix May 11, 2026 •

edited

Loading

Zfinix May 11, 2026 •

edited

Loading

Zfinix May 11, 2026 •

edited

Loading

Zfinix May 11, 2026 •

edited

Loading