После переноса приложения прежний `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_subApple для прежней командынайти существующий профиль до переноса
transfer_submigration endpoint для пары командбезопасно передать соответствие получателю
new_subApple для новой командыосновной идентификатор после обмена
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 configurationApp ID, Services ID, grouping
unauthorized_client в webredirect 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 маскируйте. Так видно, где закончилась конфигурация и началось сопоставление пользователя.

Вывод в прод идёт партиями с контролем дублей

  1. На тестовых аккаунтах подтвердить native и web-вход до переноса и записать внутренние user_id.
  2. Сгенерировать transfer_sub, проверить уникальность и передать получателю защищённым каналом.
  3. Обменять идентификаторы небольшой партии и проверить, что user_id и данные аккаунта не меняются.
  4. Запустить повтор той же партии: новые профили и вторые связи не должны появиться.
  5. Проверить пользователя с Hide My Email, пользователя без email в повторном ответе и давно не входившего пользователя.
  6. Сравнить количество подготовленных, обменянных, привязанных и ошибочных записей.
  7. После полной сверки переключить основной поиск на new_sub, сохранив ограниченный аудит старой связи.

Для внешнего разбора подготовьте дату принятия трансфера, идентификаторы App ID/Services ID без секретов, Team ID обеих сторон, обезличенный old/new/transfer mapping и точный Apple error code. Исправление считается завершённым, когда контрольный пользователь попадает в прежний профиль на всех платформах, повторная миграция безопасна, а число неразобранных записей равно нулю или имеет явный владелец и план.

Проверенные источники