Добавьте вход через Apple

Прохождение для начинающих

Предварительные условия: веб-приложение работает локально (Запуск за 5 минут), мигрированная база данных для реальных аккаунтов (Настройка базы данных) и членство в Apple Developer Program — тот же аккаунт за $99 в год, который регистрирует руководство по мобильным аккаунтам, поэтому завершите этот шаг перед продолжением, если ещё этого не сделали. Всё внутри портала разработчика ниже не стоит ничего дополнительно.

Почему это важно: проверка App Store требует Sign in with Apple всякий раз, когда iOS-приложение предлагает сторонний социальный вход, такой как Google или GitHub, и это также надёжная кнопка с низким порогом в вебе — пользователи Apple входят с аккаунтом, уже есть на их устройствах.

Кратко о терминах: App ID — зарегистрированный идентификатор вашего приложения (com.yourcompany.yourapp). Services ID — второй идентификатор, который Apple выдаёт для веб- и серверного входа — именно он становится вашим client ID. Return URL — точный адрес, на который Apple может отправлять вошедшего пользователя — колбэк Better Auth комплекта. Секретный ключ — файл .p8, который Apple выдаёт один раз; вы сами превращаете его в client secret.

1. Зарегистрируйте App ID с возможностью Sign in with Apple. 2. Зарегистрируйте Services ID, указывающий на него и хранящий ваш домен плюс return URL. 3. Создайте ключ Sign in with Apple и скачайте файл .p8. 4. Превратите ключ в client-secret JWT и установите три значения env.

Честное ограничение: return URL Apple должны быть абсолютными https://-адресами на зарегистрированном домене — localhost и простой http отклоняются, поэтому кнопку нельзя полностью проверить на голом локальном сервере. Проверяйте на развёрнутом URL или откройте локальный сервер через https-туннель (например, cloudflared tunnel или ngrok) и зарегистрируйте домен туннеля плюс его колбэк на время тестирования.

• Создайте аккаунт Apple Developer
• Настройте базу данных

Регистрация App ID

1. Откройте developer.apple.com/account и войдите аккаунтом, владеющим членством Developer Program.

2. Откройте Certificates, Identifiers & Profiles → Identifiers и нажмите синюю кнопку +.

3. Выберите App IDs → Continue, оставьте тип App → Continue.

4. Description: название вашего продукта. Bundle ID: выберите Explicit и введите форму обратного домена com.yourcompany.yourapp — если вы поставляете iOS-приложение, используйте точно ios.bundleIdentifier из apps/mobile/app.json, чтобы обе платформы делили один App ID.

5. В списке возможностей отметьте Sign in with Apple → Continue → Register.

Ожидается: идентификатор появляется в списке Identifiers с включённой возможностью Sign in with Apple. Переиспользуйте этот один App ID — Services ID и ключ привязываются к нему как к основному приложению.

Регистрация Services ID и return URL

1. Вернувшись в Identifiers, снова нажмите +, выберите Services IDs → Continue.

2. Description: что-то вроде yourapp web sign-in. Identifier: ещё одно имя обратного домена — com.yourcompany.yourapp.web — по соглашению, намеренно отличающееся от App ID. Этот Services ID — client ID, который сервер использует для веб-входа; скопируйте его точно, затем Continue → Register.

3. Выберите новый Services ID в списке, отметьте Sign in with Apple и нажмите Configure.

4. В диалоге установите Primary App ID в App ID из предыдущего раздела. В Website URLs добавьте ваш домен (например, yourdomain.com), а в Return URLs добавьте https://yourdomain.com/api/auth/callback/apple — этот путь является колбэком Better Auth комплекта, {APP_URL}/api/auth/callback/apple. Save → Continue → Save.

Каждый return URL должен быть абсолютным https://-адресом на зарегистрированном домене: localhost, голые IP-адреса и http отклоняются. Для локальной разработки запустите приложение за https-туннелем, добавьте домен туннеля в Services ID, зарегистрируйте https://<tunnel-domain>/api/auth/callback/apple и установите APP_URL в URL туннеля на время тестирования.

Ожидается: Services ID показывает Sign in with Apple → Enabled. Если портал отклоняет ваш домен, сначала завершите проверку владения доменом на странице аккаунта.

Создание ключа Sign in with Apple

1. Откройте Keys в левой боковой панели → +. Назовите ключ (например, yourapp sign-in key), отметьте Sign in with Apple, нажмите Configure, выберите App ID как Primary App ID → Save → Continue → Register.

2. На экране подтверждения запишите Key ID, затем нажмите Download — файл .p8 предлагается ровно один раз. Если вы его потеряете, отзовите ключ и создайте другой; Apple не хранит копию.

3. Запишите также свой Team ID — он напечатан в правом верхнем углу страниц аккаунта разработчика, рядом с именем аккаунта.

Ожидается: теперь у вас есть три значения — файл .p8, Key ID и Team ID. Держите файл .p8 вне Git: он подписывает от имени вашего аккаунта разработчика.

Добавьте значения в приложение

Комплект ожидает ровно три строки ниже — ту же пару clientId/clientSecret, которую использует каждый социальный провайдер. APPLE_CLIENT_ID — это Services ID (com.yourcompany.yourapp.web), а не App ID.

Apple не выдаёт статический client secret, поэтому APPLE_CLIENT_SECRET — это JWT, который вы сами подписываете из Team ID, Key ID и приватного ключа .p8 — документация Better Auth поставляет короткий скрипт-генератор для него. Подписанный секрет остаётся действительным максимум шесть месяцев: поставьте напоминание сгенерировать его заново и обновить значение env, потому что вход падает в момент его истечения. Никогда не вставляйте содержимое файла .p8 или сырой Key ID в env — там должен быть только сгенерированный JWT.

Client secret и файл .p8 — только для сервера: никогда в переменных NEXT_PUBLIC_/EXPO_PUBLIC_ и никогда в коммитах — в продакшене устанавливайте их через хранилище секретов вашего хоста. Перезапустите dev-сервер после редактирования; изменения env читаются при запуске.

# apps/web/.env.local
AUTH_APPLE_ENABLED=true
APPLE_CLIENT_ID=com.yourcompany.yourapp.web   # the Services ID, not the App ID
APPLE_CLIENT_SECRET=<JWT signed with Team ID + Key ID + .p8>

Проверка и устранение неполадок

Откройте ваш APP_URL — развёрнутый URL или https-туннель — на /auth, нажмите кнопку Apple, войдите любым Apple ID (не обязательно аккаунтом разработчика) и подтвердите, что вы возвращаетесь вошедшим.

Большинство сбоев — одна из трёх путаниц: Services ID против App ID — client ID должен быть Services ID для веб-входа; несовпадение return URL — колбэк должен точно равняться зарегистрированному Return URL, включая протокол, домен и путь; или истёкший/недействительный client secret — перегенерируйте JWT, который является только подписанным токеном, а не содержимым .p8.

Пока не установлено AUTH_APPLE_ENABLED=true, опция Apple на /auth остаётся отключённой — проверьте имена env и перезапустите. Включение флага без обоих APPLE_CLIENT_ID и APPLE_CLIENT_SECRET роняет запуск и называет отсутствующую переменную.

iOS-приложение достигает этого же бэкенда — поставляйте Sign in with Apple внутри него, чтобы проверка App Store приняла другие социальные кнопки. Руководство по мобильным аккаунтам объясняет, что ищет проверка.

• Создайте мобильные аккаунты
• Далее добавьте платежи Stripe
• Обзор OAuth-провайдеров