После переноса приложения прежний `sub` нельзя считать вечным идентификатором пользователя: Sign in with Apple выдаёт team-scoped значения. Если backend новой команды ищет только старый `sub`, вход заканчивается «пользователь не найден» или создаёт второй профиль. Не связывайте записи по email — особенно по адресу Private Relay. Используйте предусмотренный Apple `transfer_sub`.
У Apple есть 60-дневный период миграции после принятия App Transfer. За это время передающая команда получает transfer identifier для каждого пользователя, а принимающая обменивает его на свой team-scoped `sub`. До изменений сохраните резервную копию таблицы связей и запретите автоматическое создание нового профиля, если токен похож на пользователя в процессе переноса.
Три идентификатора выполняют разные роли
| Поле | Кто выдаёт | Как использовать |
|---|---|---|
| old_sub | Apple для прежней команды | найти существующий профиль до переноса |
| transfer_sub | migration endpoint для пары команд | безопасно передать соответствие получателю |
| new_sub | Apple для новой команды | основной идентификатор после обмена |
| email / relay | пользователь и Private Relay | контакт, но не ключ объединения |
Добавьте отдельную таблицу миграции с `user_id`, хешированным old_sub для аудита, transfer_sub, new_sub, статусом, временем попытки и кодом ответа Apple. Unique constraint ставится на каждый внешний идентификатор. Тогда повторный импорт становится идемпотентным, а спорную запись можно разобрать без раскрытия токенов и приватных адресов в логах.
Передающая команда готовит мост до отключения старого доступа
Передатчик получает client credentials с `scope=user.migration`, затем для каждого прежнего `sub` вызывает `userMigrationInfo`, передавая Team ID получателя как `target`. В экспорт уходит только transfer identifier и внутренний обезличенный ключ. Apple прямо предписывает исключить из передаваемого набора team-scoped identifier и private email address.
POST https://appleid.apple.com/auth/usermigrationinfo
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/x-www-form-urlencoded
sub=OLD_TEAM_SUB&
target=RECIPIENT_TEAM_ID&
client_id=APP_OR_SERVICE_ID&
client_secret=SIGNED_CLIENT_SECRET
# response
{"transfer_sub":"TRANSFER_IDENTIFIER"}Пример показывает форму запроса, а не готовый скрипт: секрет подписывается приватным ключом команды и не хранится в исходниках или выгрузке. Для партии ведите счётчики `prepared`, `failed`, `delivered`; ошибку одной записи не скрывайте массовым успешным статусом. Повторная попытка должна обновлять ту же строку миграции.
Получатель обменивает transfer_sub на свой sub
Новая команда выпускает собственный client secret, получает migration access token и отправляет `transfer_sub` в тот же endpoint. Ответ содержит team-scoped identifier получателя и, когда применимо, данные private relay для новой команды. Затем backend в одной транзакции добавляет `new_sub` к существующему `user_id` и помечает transfer_sub как использованный.
POST https://appleid.apple.com/auth/usermigrationinfo
Authorization: Bearer RECIPIENT_ACCESS_TOKEN
Content-Type: application/x-www-form-urlencoded
transfer_sub=TRANSFER_IDENTIFIER&
client_id=TRANSFERRED_APP_OR_SERVICE_ID&
client_secret=RECIPIENT_SIGNED_SECRETНе удаляйте old_sub сразу. На время контролируемого перехода он нужен для аудита и отката, но не должен оставаться единственным ключом входа. Если пользователь авторизуется после переноса, ID token может содержать `transfer_sub`; это дополнительный мост, а не повод пропустить серверную проверку подписи, issuer, audience, expiration и nonce.
Web, Services ID и группы проверяются отдельно
Native-приложение использует App ID как client identifier, веб-версия — Services ID. При группировке приложений перед трансфером есть дополнительные шаги: Apple описывает ungroup/regroup, а связанный Services ID переносится вместе с primary App ID при указанных условиях. Составьте инвентаризацию App ID, Services ID, primary grouping, redirect URI, key id и Team ID обеих сторон; одна неверная строка даёт `invalid_client` или `unauthorized_client`.
- Сравнить client_id посимвольно с зарегистрированным App ID или Services ID.
- Проверить redirect_uri для web-входа: он должен совпадать с конфигурацией сервиса.
- Убедиться, что client secret подписан ключом нужной команды и содержит правильный sub.
- Не выводить authorization code, identity token, access token и private key в общий лог.
- Проверить состояние `.transferred` через AuthenticationServices для native-сценария.
Сбой классифицируется по моменту появления
| Наблюдение | Вероятный слой | Следующая проверка |
|---|---|---|
| invalid_client до экрана согласия | client_id или team configuration | App ID, Services ID, grouping |
| unauthorized_client в web | redirect URI | точное зарегистрированное значение |
| Apple вход успешен, профиль новый | не сопоставлен new_sub | таблица transfer_sub → user_id |
| письмо на relay не доходит | старый relay/домен отправителя | мигрированный адрес и relay registration |
| часть пользователей входит | неполная партия миграции | статусы по каждой записи |
TN3107 полезен для OAuth-ошибок, но не заменяет сверку данных миграции. Сохраняйте HTTP status, Apple error code, client_id, роль команды и внутренний migration row id. Значения токенов и полный email маскируйте. Так видно, где закончилась конфигурация и началось сопоставление пользователя.
Вывод в прод идёт партиями с контролем дублей
- На тестовых аккаунтах подтвердить native и web-вход до переноса и записать внутренние user_id.
- Сгенерировать transfer_sub, проверить уникальность и передать получателю защищённым каналом.
- Обменять идентификаторы небольшой партии и проверить, что user_id и данные аккаунта не меняются.
- Запустить повтор той же партии: новые профили и вторые связи не должны появиться.
- Проверить пользователя с Hide My Email, пользователя без email в повторном ответе и давно не входившего пользователя.
- Сравнить количество подготовленных, обменянных, привязанных и ошибочных записей.
- После полной сверки переключить основной поиск на new_sub, сохранив ограниченный аудит старой связи.
Для внешнего разбора подготовьте дату принятия трансфера, идентификаторы App ID/Services ID без секретов, Team ID обеих сторон, обезличенный old/new/transfer mapping и точный Apple error code. Исправление считается завершённым, когда контрольный пользователь попадает в прежний профиль на всех платформах, повторная миграция безопасна, а число неразобранных записей равно нулю или имеет явный владелец и план.