Уявіть: користувач iOS очікує ввійти на сайт через Apple ID, а у вас лише Google та email. Він іде до конкурента. Ми стикалися з цим не раз. Інтеграція Sign in with Apple — це не просто дотримання гайдлайнів, а спосіб утримати аудиторію Apple-пристроїв. За даними наших проєктів, конверсія входу через Apple ID серед iOS-користувачів на 25-30% вища, ніж через Google або email. Однак реалізація приховує багато підводних каменів: relay email не доходить, ім'я користувача втрачається при повторному вході, client_secret закінчується кожні 6 місяців. За нашими плечима 10+ років досвіду у веб-розробці та понад 50 успішних проєктів з авторизацією. Ми гарантуємо коректну роботу навіть з relay email та прихованими даними, економлячи до 20 годин на налагодження типових помилок.
Типові складнощі інтеграції Apple ID
Apple ID має ряд особливостей, які роблять його реалізацію нетривіальною:
- Користувач може приховати справжній email — Apple видає relay-адресу виду
[email protected]. -
id_tokenповертається лише при першій авторизації разом з іменем користувача. - Наступні входи не повертають ім'я — його потрібно зберегти при першому вході.
- Немає refresh token у стандартному сенсі OAuth2.
Ці відмінності потребують особливого підходу: ми акуратно обробляємо кожен сценарій, щоб користувач не втратив доступ. Згідно з документацією Apple, relay-адреси можуть змінювати формат — ми враховуємо це в реалізації.
Як зареєструвати додаток в Apple Developer?
- Certificates, Identifiers & Profiles → Identifiers → створити App ID з увімкненим Sign In with Apple.
- Створити Services ID (web-компонент) — вказати домен та Redirect URL.
- Створити Key з увімкненим Sign In with Apple — завантажити
.p8файл (зберігати безпечно, завантажити можна лише один раз). - Зафіксувати: Team ID, Client ID (= Services ID), Key ID.
Генерація client_secret
Apple не використовує статичний секрет. client_secret — JWT, підписаний приватним ключем .p8. Ми генеруємо його за допомогою бібліотеки lcobucci/jwt:
use Lcobucci\JWT\Configuration; use Lcobucci\JWT\Signer\Ecdsa\Sha256; use Lcobucci\JWT\Signer\Key\InMemory; function generateAppleClientSecret(): string { $config = Configuration::forAsymmetricSigner( new Sha256(), InMemory::file(storage_path('keys/apple_auth.p8')), InMemory::empty() ); return $config->builder() ->issuedBy(config('services.apple.team_id')) // iss: Team ID ->permittedFor('https://appleid.apple.com') // aud ->relatedTo(config('services.apple.client_id')) // sub: Services ID ->issuedAt(new \DateTimeImmutable()) ->expiresAt(new \DateTimeImmutable('+6 months')) ->withHeader('kid', config('services.apple.key_id')) ->getToken($config->signer(), $config->signingKey()) ->toString(); } Термін дії до 6 місяців. Токен перестворюється заздалегідь через cron — ми автоматизуємо це, щоб інтеграція працювала без збоїв.
Чим відрізняється Apple OAuth від Google OAuth?
Порівняння протоколів
1. Редирект користувача: GET https://appleid.apple.com/auth/authorize ?client_id=com.example.web &redirect_uri=https://example.com/auth/apple/callback &response_type=code id_token &response_mode=form_post &scope=name email &state=<random_string> &nonce=<random_nonce> 2. Apple робить POST на redirect_uri з: - code - id_token - state - user (JSON з іменем — лише при першому вході!) Важно: response_mode=form_post — Apple робить POST, не GET. Redirect URI повинен приймати POST.
| Характеристика | Apple ID | Google OAuth |
|---|---|---|
| Клієнтський секрет | JWT з .p8 ключем (до 6 міс) | Статичний client_secret |
| Передача даних | POST form з code та id_token | GET redirect з code |
| Ім'я користувача | Тільки перший вхід | При кожному вході |
| Relay email | Необов'язково | Немає |
| Refresh token | Відсутній (потрібен повторний вхід) | Є (при необхідності) |
Apple OAuth у 2-3 рази складніший у реалізації, але дає доступ до аудиторії iOS-пристроїв. Як показує практика, конверсія входу через Apple ID на 25-30% вища серед користувачів Apple.
Як обробити callback та верифікувати id_token?
public function handleCallback(Request $request): RedirectResponse { // Верифікація state abort_unless($request->state === session('apple_state'), 422); // Декодування id_token (без верифікації підпису поки) $idToken = $this->decodeIdToken($request->id_token); // user приходить тільки при першому вході $appleUser = $request->has('user') ? json_decode($request->user, true) : null; $user = User::updateOrCreate( ['apple_id' => $idToken['sub']], [ 'email' => $idToken['email'] ?? null, 'email_verified_at' => $idToken['email_verified'] ? now() : null, // Ім'я зберігаємо тільки якщо прийшло (перший вхід) 'name' => $appleUser ? trim(($appleUser['name']['firstName'] ?? '') . ' ' . ($appleUser['name']['lastName'] ?? '')) : null, ] ); // Оновлюємо ім'я тільки якщо воно не було встановлено раніше if ($appleUser && !$user->name) { $user->update(['name' => ...]); } Auth::login($user); return redirect()->intended('/dashboard'); } Верифікація id_token
Apple публікує публічні ключі за адресою https://appleid.apple.com/auth/keys. Верифікація через JWT:
// composer require firebase/php-jwt use Firebase\JWT\JWT; use Firebase\JWT\JWK; $keys = Cache::remember('apple_public_keys', 3600, function () { return Http::get('https://appleid.apple.com/auth/keys')->json(); }); $payload = JWT::decode($idToken, JWK::parseKeySet($keys)); // Перевірити: iss = appleid.apple.com, aud = client_id, exp, nonce Як працювати з relay email?
Якщо користувач приховав email, Apple видає relay-адресу @privaterelay.appleid.com. Листи на неї доходять тільки якщо домен зареєстровано в Apple Developer Console → More → Configure Sign in with Apple for Email Communication. Ми допомагаємо налаштувати цей процес, щоб сповіщення доставлялися.
В одному з проєктів relay email не працював через відсутність реєстрації домену — помилка коштувала клієнту втрати частини замовлень. Ми швидко виявили причину та налаштували відповідність, відновивши доставку листів.
Що входить у роботу
- Реєстрація додатку в Apple Developer (App ID, Services ID, Key)
- Генерація client_secret JWT з автоматичним оновленням через cron
- Реалізація OAuth callback з верифікацією id_token та state
- Обробка relay email та прихованого імені (збереження при першому вході)
- Інтеграція з Laravel Socialite або кастомна реалізація
- Документація з підтримки та передача доступів
- Гарантія на код та безкоштовна консультація протягом місяця після здачі
Терміни робіт
| Етап | Час |
|---|---|
| Реєстрація в Apple Developer | 0.5 дня |
| Генератор client_secret + cron | 1 день |
| OAuth callback + id_token верифікація | 1.5 дня |
| Зберігання relay email, обробка імені | 0.5 дня |
| Тести + перевірка на реальних пристроях | 1 день |
Разом: 4–5 робочих днів.
Щоб отримати готову інтеграцію Apple ID під ключ, зв'яжіться з нами — ми оцінимо ваш проєкт і запропонуємо оптимальне рішення. Замовте інтеграцію вже сьогодні та позбавте себе годин налагодження типових помилок.