Skip to main content
Sign in with Apple uses OAuth 2.0 with a few Apple-specific requirements: the client secret is a JWT you generate from a private key, and Apple only returns the user’s name on the very first authorization.
createAppleProvider does not currently complete a sign-in through the oauth() plugin. Apple has no userinfo endpoint, so the provider reads the user from the id_token, but the plugin calls getUserInfo with the access token only, and the provider throws Apple getUserInfo requires the id_token from the token response. Apple also posts the callback (response_mode=form_post), while the plugin registers GET /auth/oauth/callback/apple only. The provider builds the authorization URL and exchanges the code, so you can use it with your own callback route, but the steps below do not give you a working end-to-end flow with oauth() alone.

Get credentials from Apple

1

Register an App ID

  1. Sign in to Apple Developer and go to Certificates, Identifiers & Profiles.
  2. Under Identifiers, click + and choose App IDs.
  3. Select App as the type, then fill in your bundle identifier (e.g. com.example.app).
  4. Scroll to Capabilities and enable Sign In with Apple.
  5. Save the App ID.
2

Create a Services ID

The Services ID is your OAuth client_id for web and non-iOS flows.
  1. Under Identifiers, click + and choose Services IDs.
  2. Enter a description and an identifier (e.g. com.example.app.auth).
  3. Enable Sign In with Apple.
  4. Click Configure next to Sign In with Apple:
    • Set your Primary App ID to the one you just created.
    • Add your domain (e.g. auth.example.com, no trailing slash, no protocol).
    • Add your Return URL (e.g. https://auth.example.com/auth/oauth/callback/apple).
  5. Save and register.
3

Create a private key

  1. Under Keys, click +.
  2. Name the key and enable Sign In with Apple.
  3. Click Configure and select your Primary App ID.
  4. Download the .p8 key file, you can only download it once.
  5. Note your Key ID and Team ID (visible at the top right of the developer portal).
Store the .p8 file somewhere safe and never commit it to version control. You will use it to sign a JWT locally, then discard the file from your build environment.

Configuration

lib/theauth.ts
The provider requests the name and email scopes by default and sends a PKCE challenge. Scopes you pass are added to those.

Generate the client secret

Apple does not accept a static client secret. Instead, you generate a JWT signed with your .p8 private key. The JWT is valid for up to 6 months, so you can generate it once and rotate it before it expires.
scripts/generate-apple-secret.ts
Run this script locally once, copy the output JWT, and set it as your APPLE_CLIENT_SECRET environment variable. Re-run before the 6-month window closes.
The jose library is a dependency of theAuth. Install it in your own project if your script imports it directly.

Environment variables

.env
Only APPLE_CLIENT_ID and APPLE_CLIENT_SECRET are needed at runtime. The Team ID and Key ID are only used when regenerating the secret.

iOS native apps

The provider has no separate setting for native apps. A native flow would use the App ID (bundle identifier) as the client ID, but no endpoint in the oauth() plugin accepts a code obtained by Apple’s native SDK, so native Sign in with Apple is not supported by the plugin today.

Localhost and development

Apple requires HTTPS for redirect URIs. localhost will not work. Options:
  • ngrok, ngrok http 3000 gives you a public HTTPS URL instantly.
  • cloudflared tunnel, persistent tunnel with a stable subdomain.
  • mkcert + local proxy, run a local HTTPS reverse proxy with a self-signed cert trusted by your browser.
Update both your Apple Services ID redirect URI and your baseUrl config to match the tunnel URL while developing.

User data

Apple embeds user claims in the id_token JWT returned from the token endpoint. The provider decodes it without verifying the signature, and throws if the sub or email claim is missing.
Apple returns the name only once, on the very first sign-in, in a user form-post field alongside the authorization code. The provider returns name: undefined, so you must capture that field in your own callback handler if you need it.

Endpoints

The oauth() plugin registers the same routes for every provider:

OAuth overview

Generic OAuth 2.0 setup and account linking behavior.

Google

Another popular sign-in provider using OIDC.

Microsoft

Sign in with Microsoft Entra ID for personal and work accounts.

Authentication overview

All sign-in methods available in theAuth.
Last modified on October 7, 2026