Поле email в ответе пользователя может быть null, даже если у аккаунта есть подтверждённая почта: профиль показывает публично видимый адрес. Для чтения приватного списка OAuth app запрашивает user:email и обращается к /user/emails. Не подставляйте login@users.noreply.github.com как подтверждённый контакт.

Локальную связь храните по числовому GitHub id вместе с provider=github. Email меняется, скрывается и иногда совпадает с адресом существующего пользователя; он подходит для контакта и подсказки при объединении, но не как единственный внешний идентификатор.

Три ответа имеют разный смысл

ИсточникЧто возвращаетКак использовать
GET /userПрофиль и публичный email либо nullПолучить stable id и display data
Token scope headersФактически выданные scopesПонять, разрешён ли запрос email
GET /user/emailsМассив адресов с primary и verifiedВыбрать контакт по явному правилу
Локальная БДСвязь provider + GitHub idНайти уже привязанный аккаунт
Форма приложенияАдрес, введённый человекомFallback с отдельной верификацией

Сначала читаются выданные разрешения

GET https://api.github.com/user/emails
Accept: application/vnd.github+json
Authorization: Bearer <token>
X-GitHub-Api-Version: 2022-11-28

choose first email where verified == true && primary == true
otherwise ask user for a contact email and verify it locally

Токен в журнал не попадает. Для OAuth app endpoint требует scope user:email; более широкий user включает его. Пользователь может выдать меньше прав или позже изменить разрешения, поэтому приложение обрабатывает 401/403 и пустой список как отдельные состояния, а не как «аккаунта нет».

Email выбирается по признакам, а не по позиции

  • Сначала verified=true и primary=true.
  • Если primary не подтверждён, не использовать его для доверенного объединения.
  • Публичный verified адрес допустим, но всё равно может измениться позже.
  • При отсутствии подходящего адреса показать короткую форму и отправить собственную проверку.
  • Сохранить источник и время проверки email отдельно от GitHub identity.

Первый элемент массива не обязан оставаться главным. Алгоритм должен быть детерминированным и тестироваться на нескольких адресах. В интерфейсе объясните, зачем нужен контакт, и не запрашивайте более широкий scope только ради удобства реализации.

GitHub id остаётся ключом связи

После callback сначала ищите provider_account по provider и provider_user_id. Если связь найдена, вход продолжается независимо от текущего email. Если связи нет, совпадение verified email с локальным аккаунтом не должно молча объединять профили: потребуйте вход в существующий аккаунт или другое подтверждение владения.

Такой порядок закрывает сценарий, где чужой или перераспределённый адрес приводит к неправильной привязке. Логин GitHub тоже может меняться, поэтому используйте его как отображаемое имя, а не постоянный ключ.

Повторная авторизация запрашивается осознанно

Если старый token создан без user:email, простое добавление scope в код не расширяет уже выданное разрешение автоматически. Отправьте пользователя через OAuth flow с понятным объяснением дополнительного доступа и после callback снова проверьте фактически выданные scopes. Отказ не должен блокировать вход, если приложение может запросить email само.

Граничные аккаунты входят без дублей

  1. Войти аккаунтом с публичным primary email и проверить существующую связь по GitHub id.
  2. Скрыть email в профиле и подтвердить, что /user возвращает null, а вход не ломается.
  3. Выдать user:email и выбрать verified primary из /user/emails.
  4. Отказать в дополнительном scope и пройти fallback с локальной верификацией.
  5. Сменить primary email в GitHub и не создать второй локальный аккаунт.
  6. Попробовать адрес уже существующего пользователя и потребовать безопасную привязку.

Для диагностики нужны тип приложения, запрошенные и фактически выданные scopes, HTTP-статусы /user и /user/emails, GitHub id в обезличенном виде и правило выбора адреса. Access token, OAuth code и реальные email передавать нельзя.

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