Поле 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 само.
Граничные аккаунты входят без дублей
- Войти аккаунтом с публичным primary email и проверить существующую связь по GitHub id.
- Скрыть email в профиле и подтвердить, что /user возвращает null, а вход не ломается.
- Выдать user:email и выбрать verified primary из /user/emails.
- Отказать в дополнительном scope и пройти fallback с локальной верификацией.
- Сменить primary email в GitHub и не создать второй локальный аккаунт.
- Попробовать адрес уже существующего пользователя и потребовать безопасную привязку.
Для диагностики нужны тип приложения, запрошенные и фактически выданные scopes, HTTP-статусы /user и /user/emails, GitHub id в обезличенном виде и правило выбора адреса. Access token, OAuth code и реальные email передавать нельзя.