Sign in with Apple

Apple Sign In is optional and controlled by APPLE_AUTH_ENABLED. When disabled, Apple endpoints return 503 Service Unavailable. Apple uses OpenID Connect with response_mode=form_post, meaning the callback is a POST (not a GET). The client secret is a short-lived JWT signed with your .p8 key — the passport-apple library handles this automatically. The user's stable ID (appleId) is the sub claim of the id_token. Apple provides the user's name and email only on the very first login; subsequent logins only deliver the id_token. Email may be a private relay address (*@privaterelay.appleid.com). JWTs are never placed in the redirect URL; the API issues a one-time exchangeCode (Redis, 60 seconds). The same POST /auth/exchange endpoint is shared with other social providers.

• • Feature-flagged via environment
• • passport-apple strategy + AppleAuthGuard
• • id_token decoded to extract sub (appleId) and email
• • POST callback (form_post) — not a GET redirect like other OAuth2 providers
• • User name sent by Apple on first login only via req.body.user JSON field
• • Email may be a private relay address — still usable as account identifier
• • Client secret is a JWT generated from your .p8 private key — handled by passport-apple
• • Redirect allowlist prevents open redirects
• • Same token response shape as POST /auth/login

Configure Sign in with Apple at developer.apple.com. You need an App ID, a Services ID (client ID), and a private key.

1. Open Certificates, Identifiers & Profiles in Apple Developer
2. Create an App ID (Identifiers → App IDs) and enable 'Sign In with Apple' capability
3. Create a Services ID (Identifiers → Services IDs) — this is your APPLE_CLIENT_ID (e.g. com.example.service). Enable 'Sign In with Apple', configure Domains & Subdomains and Return URLs to match APPLE_CALLBACK_URL
4. Create a Key (Keys → +) and enable 'Sign In with Apple'. Download the .p8 file — it is only available once
5. Note: Team ID (top-right of developer.apple.com/account), Key ID (listed next to the key), Services ID
6. Paste the .p8 file contents into APPLE_PRIVATE_KEY, replacing newlines with literal \n (Docker-safe)
7. APPLE_CALLBACK_URL must be an HTTPS URL registered in the Services ID return URLs — localhost is allowed only for development with ngrok or similar

Loaded from .env via src/config/apple-oauth.config.ts (namespace appleOAuth on ConfigService). See .env.example. Store APPLE_PRIVATE_KEY with literal \n between lines — the config replaces them with real newlines at startup.

APPLE_AUTH_ENABLED=true
APPLE_CLIENT_ID=com.example.service
APPLE_TEAM_ID=TEAM1234XX
APPLE_KEY_ID=ABCDEFGHIJ
APPLE_PRIVATE_KEY=-----BEGIN EC PRIVATE KEY-----\nMHQC...\n-----END EC PRIVATE KEY-----
APPLE_CALLBACK_URL=https://api.example.com/api/v1/auth/apple/callback
APPLE_REDIRECT_ALLOWLIST=myapp://success,https://app.example.com/auth/callback
APPLE_OAUTH_DEFAULT_ROLES=

New Apple users receive roles: [] by default (same as password register). Set APPLE_OAUTH_DEFAULT_ROLES in .env to a comma-separated list of Role values (e.g. user or user,manager). Existing users linked by appleId keep their current roles.

1. Client opens GET /api/v1/auth/apple?redirect=<allowlisted URL>
2. User consents on Apple; Apple POSTs to POST /api/v1/auth/apple/callback (form_post response mode)
3. API decodes id_token (sub → appleId, email), reads name from req.body.user on first login, upserts user, stores exchangeCode in Redis, and redirects to redirect?code=...
4. Client POSTs { code } to /api/v1/auth/exchange and receives JWTs

Same pattern as other OAuth providers: initiate login in the browser; your callback route reads code from the query string and calls exchange. Note: Apple's callback is a POST handled server-side — your frontend only ever sees the redirect with ?code=.

const API = 'http://localhost:3000/api/v1';
const redirect = encodeURIComponent(
  'http://localhost:5173/auth/callback'
);

// Full-page redirect to Nest → Apple → back to SPA
window.location.href = `${API}/auth/apple?redirect=${redirect}`;

// /auth/callback on the SPA
const params = new URLSearchParams(window.location.search);
const code = params.get('code');
if (!code) throw new Error('Missing exchange code');

const res = await fetch('http://localhost:3000/api/v1/auth/exchange', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ code }),
});
if (!res.ok) throw new Error(await res.text());

const { user, accessToken, refreshToken } = await res.json();
// persist tokens as your app requires
sessionStorage.setItem('accessToken', accessToken);
// Use appleId as the stable identifier — email may be private relay
console.log('signed in', user.appleId);

• • Add your frontend callback URL to APPLE_REDIRECT_ALLOWLIST (e.g. https://app.example.com/auth/callback)
• • APPLE_CALLBACK_URL must be an HTTPS URL pointing at the Nest API (registered in Apple Developer)
• • Apple only sends name on the first login — store it immediately; it will not be sent again
• • Email may be a private relay address — use appleId as the stable identifier, not email
• • Store accessToken / refreshToken securely (memory + httpOnly cookie patterns as you prefer)

Use a custom scheme (or universal link) in the allowlist. After Apple Sign In, the API redirects to myapp://success?code=.... The app opens, parses the code, and calls exchange. On iOS you may also use the native AuthenticationServices ASWebAuthenticationSession.

import * as Linking from 'expo-linking';
import * as WebBrowser from 'expo-web-browser';

const API = 'https://api.example.com/api/v1';
const redirect = encodeURIComponent('myapp://success');

async function signInWithApple() {
  const url = `${API}/auth/apple?redirect=${redirect}`;
  await WebBrowser.openAuthSessionAsync(url, 'myapp://success');
}

import * as Linking from 'expo-linking';

async function exchangeFromUrl(url) {
  const { queryParams } = Linking.parse(url);
  const code = queryParams?.code;
  if (!code) return;

  const res = await fetch(`${API}/auth/exchange`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ code }),
  });
  const data = await res.json();
  // data.accessToken, data.refreshToken, data.user
  return data;
}

Linking.addEventListener('url', ({ url }) => {
  exchangeFromUrl(url);
});

• • Register the scheme in the OS / Expo app.json
• • Prefer Linking.addEventListener('url', ...) and getInitialURL()
• • Exchange over HTTPS against your API base URL
• • Identify users by appleId — not by email (may be private relay or change if user revokes)

• • Redirect URLs must match APPLE_REDIRECT_ALLOWLIST prefixes
• • Exchange codes are single-use and expire in 60 seconds (Redis)
• • APPLE_PRIVATE_KEY is a secret — never commit it to version control
• • The JWT client secret is generated per-request from the private key by passport-apple
• • Apple sends name and email only on the first consent — subsequent logins only deliver id_token
• • Private relay emails (*@privaterelay.appleid.com) are real and deliverable, but tied to the user's Apple ID
• • Users can revoke Apple Sign In from device settings — handle account deactivation via isActive
• • Apple-only users have password null — password login / change-password will fail until a password is set

Postgres entity / interface fields used by Apple Sign In:

• • appleId — unique nullable Apple subject ID (sub from id_token)
• • email — from id_token; may be a private relay address
• • firstName / lastName — from req.body.user on first login; defaults to 'Apple' / '' on subsequent logins
• • password — nullable for OAuth-only accounts
• • isActive — set true for new Apple users
• • roles — from APPLE_OAUTH_DEFAULT_ROLES env (default [])

• Social Authentication hub
• Google OAuth2 guide
• Facebook OAuth2 guide
• X / Twitter OAuth2 guide
• GitHub OAuth2 guide
• Figma OAuth2 guide
• LinkedIn OpenID Connect guide
• Slack OpenID Connect guide
• Atlassian OAuth 2.0 (3LO) guide
• GitLab OAuth2 guide
• Bitbucket OAuth2 guide
• Discord OAuth2 guide
• Twitch OAuth2 guide
• Steam OpenID 2.0 guide
• Reddit OAuth2 guide
• Auth & JWT