OAuth

OAuth2 – это протокол, который позволяет внешним приложениям запрашивать авторизацию на доступ к личным данным в учетной записи GitHub пользователя без получения пароля. Это предпочтительнее обычной аутентификации , поскольку токены могут быть ограничены определенными типами данных и могут быть отозваны пользователями в любое время.

Все разработчики должны зарегистрировать свое приложение перед началом работы. Зарегистрированному приложению OAuth присваивается уникальный идентификатор клиента и секрет клиента. Секрет клиента не должен быть разглашен.

Поток веб-приложений

Это описание потока OAuth2 со сторонних веб-сайтов.

1. Перенаправить пользователей для запроса доступа к GitHub

GET https://github.com/login/oauth/authorize

Параметры

Имя	Тип	Описание
client_id	string	Требуется . Идентификатор клиента, который вы получили от GitHub при регистрации .
redirect_uri	string	URL-адрес в вашем приложении, куда будут отправляться пользователи после авторизации. Подробнее об URL-адресах перенаправления см. ниже .
scope	string	Список областей, разделенных запятыми . Если он не указан, scopeпо умолчанию используется пустой список областей для пользователей, у которых нет действительного токена для приложения. Для пользователей, у которых уже есть действительный токен для приложения, пользователю не будет показана страница авторизации OAuth со списком областей. Вместо этого этот шаг потока будет автоматически завершен с теми же областями, которые использовались в прошлый раз, когда пользователь завершал поток.
state	string	Не угадываемая случайная строка. Он используется для защиты от атак с подделкой межсайтовых запросов.

2. GitHub перенаправляет обратно на ваш сайт

Если пользователь принимает ваш запрос, GitHub перенаправляет обратно на ваш сайт с временным кодом в параметре, codeа также с состоянием, которое вы указали на предыдущем шаге в stateпараметре. Если состояния не совпадают, запрос был создан третьей стороной, и процесс следует прервать.

Обменяйте это на токен доступа:

POST https://github.com/login/oauth/access_token

Параметры  

Имя	Тип	Описание
client_id	string	Требуется . Идентификатор клиента, который вы получили от GitHub при регистрации .
client_secret	string	Требуется . Секрет клиента, который вы получили от GitHub при регистрации .
code	string	Требуется .Код, который вы получили в ответ на шаг 1 .
redirect_uri	string	URL-адрес в вашем приложении, куда будут отправляться пользователи после авторизации. Подробнее об URL-адресах перенаправления см. ниже .

Ответ

По умолчанию ответ будет иметь следующий вид:

access_token=e72e16c7e42f292c6912e7710c838347ae178b4a&scope=user%2Cgist&token_type=bearer

Вы также можете получать контент в разных форматах в зависимости от заголовка Accept:

Accept: application/json
{"access_token":"e72e16c7e42f292c6912e7710c838347ae178b4a", "scope":"repo,gist", "token_type":"bearer"}

Accept: application/xml

  bearer
  repo,gist
  e72e16c7e42f292c6912e7710c838347ae178b4a

Запрошенные области и предоставленные области

Атрибут scopeперечисляет области действия, прикрепленные к маркеру, которые были предоставлены пользователем. Обычно эти области будут идентичны тем, которые вы запросили. Однако вскоре пользователи смогут редактировать свои области действия , фактически предоставив вашему приложению меньший доступ, чем вы запрашивали изначально. Кроме того, пользователи также смогут редактировать области маркеров после завершения потока OAuth. Вы должны знать об этой возможности и соответствующим образом настроить поведение своего приложения.

Важно обрабатывать случаи ошибок, когда пользователь решает предоставить вам меньший доступ, чем вы изначально запросили. Например, приложения могут предупреждать или иным образом сообщать своим пользователям, что они увидят ограниченную функциональность или не смогут выполнять некоторые действия.

Кроме того, приложения всегда могут снова отправить пользователей обратно по потоку, чтобы получить дополнительное разрешение, но не забывайте, что пользователи всегда могут сказать «нет».

Ознакомьтесь с руководством по основам аутентификации , в котором содержатся советы по работе с изменяемыми областями действия токенов.

Нормализованные области

При запросе нескольких областей маркер будет сохранен с нормализованным списком областей, отбрасывая те, которые неявно включены в другую запрошенную область. Например, запрос user,gist,user:emailприведет к токену с областями userи gistтолько потому, что доступ, предоставленный с user:emailобластью , включен в userобласть.

3. Используйте токен доступа для доступа к API

Токен доступа позволяет делать запросы к API от имени пользователя.

GET https://api.github.com/user?access_token=...

Вы можете передать токен в параметрах запроса, как показано выше, но более чистый подход — включить его в заголовок авторизации.

Authorization: token OAUTH-TOKEN

Например, в curl вы можете установить заголовок Authorization следующим образом:

curl -H "Authorization: token OAUTH-TOKEN" https://api.github.com/user

Поток не-веб-приложений

Используйте обычную аутентификацию , чтобы создать токен OAuth2, используя приведенный ниже интерфейс . При использовании этого метода имя пользователя и пароль не нужно хранить постоянно, и пользователь может отозвать доступ в любое время. (Убедитесь, что понимаете, как работать с двухфакторной аутентификацией, если вы или ваши пользователи включили двухфакторную аутентификацию.)

URL-адреса перенаправления

Параметр redirect_uriявляется необязательным. Если его не указать, GitHub будет перенаправлять пользователей на URL-адрес обратного вызова, указанный в настройках приложения OAuth. Если указано, хост и порт URL-адреса перенаправления должны точно соответствовать URL-адресу обратного вызова. Путь URL-адреса перенаправления должен ссылаться на подкаталог URL-адреса обратного вызова.

CALLBACK: http://example.com/path

GOOD: http://example.com/path
GOOD: http://example.com/path/subdir/other
BAD:  http://example.com/bar
BAD:  http://example.com/
BAD:  http://example.com:8080/path
BAD:  http://oauth.example.com:8080/path
BAD:  http://example.org

Сферы

Области позволяют точно указать, какой тип доступа вам нужен. Области ограничивают доступ к токенам OAuth. Они не предоставляют никаких дополнительных разрешений помимо тех, которые уже есть у пользователя.

Для веб-потока запрошенные области будут отображаться пользователю в форме авторизации.

Проверьте заголовки, чтобы узнать, какие области OAuth у вас есть и что принимает действие API.

$ curl -H "Authorization: token OAUTH-TOKEN" https://api.github.com/users/technoweenie -I
HTTP/1.1 200 OK
X-OAuth-Scopes: repo, user
X-Accepted-OAuth-Scopes: user

X-OAuth-Scopesперечисляет области действия, разрешенные вашим токеном. X-Accepted-OAuth-Scopesперечисляет области, которые проверяет действие.

Имя	Описание
(no scope)	Предоставляет доступ только для чтения к общедоступной информации (включая информацию общедоступного профиля пользователя, информацию об общедоступном репозитории и суть)
user	Предоставляет доступ для чтения/записи только к информации профиля. Обратите внимание, что эта область включает user:emailи user:follow.
user:email	Предоставляет доступ для чтения к адресам электронной почты пользователя.
user:follow	Предоставляет доступ к подписке или отмене подписки на других пользователей.
public_repo	Предоставляет доступ для чтения и записи к коду, состояниям фиксации и состояниям развертывания для общедоступных репозиториев и организаций.
repo	Предоставляет доступ для чтения и записи к коду, состояния фиксации и состояния развертывания для общедоступных и частных репозиториев и организаций.
repo_deployment	Предоставляет доступ к статусам развертывания для общедоступных и частных репозиториев. Эта область необходима только для предоставления другим пользователям или службам доступа к статусам развертывания без предоставления доступа к коду.
repo:status	Предоставляет доступ для чтения/записи к состояниям фиксации общедоступного и частного репозитория. Эта область необходима только для предоставления другим пользователям или службам доступа к статусам фиксации частного репозитория без предоставления доступа к коду.
delete_repo	Предоставляет доступ для удаления управляемых репозиториев.
notifications	Предоставляет доступ для чтения к уведомлениям пользователя. repoтакже предоставляет этот доступ.
gist	Предоставляет доступ для записи к gists.
read:repo_hook	Предоставляет доступ для чтения и проверки связи к хукам в общедоступных или частных репозиториях.
write:repo_hook	Предоставляет доступ для чтения, записи и проверки связи к хукам в общедоступных или частных репозиториях.
admin:repo_hook	Предоставляет доступ на чтение, запись, проверку связи и удаление к хукам в общедоступных или частных репозиториях.
admin:org_hook	Предоставляет доступ на чтение, запись, проверку связи и удаление к крючкам организации. Примечание. Токены OAuth смогут выполнять эти действия только с хуками организации, созданными приложением OAuth. Токены личного доступа смогут выполнять эти действия только с хуками организации, созданными пользователем.
read:org	Доступ только для чтения к организации, командам и членству.
write:org	Публиковать и не публиковать членство в организации.
admin:org	Полностью управляйте организацией, командами и членством.
read:public_key	Перечислите и просмотрите сведения об открытых ключах.
write:public_key	Создавайте, перечисляйте и просматривайте сведения об открытых ключах.
admin:public_key	Полностью управляйте открытыми ключами.

ПРИМЕЧАНИЕ. Ваше приложение может запрашивать области в начальном перенаправлении. Вы можете указать несколько областей, разделив их запятой:

https://github.com/login/oauth/authorize?
  client_id=...&
  scope=user,public_repo

Распространенные ошибки при запросе авторизации

Есть несколько вещей, которые могут пойти не так в процессе получения токена OAuth для пользователя. На начальном этапе запроса авторизации вы можете увидеть следующие ошибки:

Приложение приостановлено

Если настроенное вами приложение OAuth было приостановлено (из-за сообщений о злоупотреблениях, спаме или неправильном использовании API), GitHub перенаправит на зарегистрированный URL-адрес обратного вызова со следующими параметрами, обобщающими ошибку:

http://your-application.com/callback?error=application_suspended
  &error_description=Your+application+has+been+suspended.+Contact+support@github.com.
  &error_uri=https://developer.github.com/v3/oauth/%23application-suspended
  &state=xyz

Обратитесь в службу поддержки для решения проблем с приостановленными приложениями.

Несоответствие URI перенаправления

Если вы предоставите redirect_uri, который не соответствует тому, что вы зарегистрировали в своем приложении, GitHub перенаправит на зарегистрированный URL-адрес обратного вызова со следующими параметрами, обобщающими ошибку:

http://your-application.com/callback?error=redirect_uri_mismatch
  &error_description=The+redirect_uri+MUST+match+the+registered+callback+URL+for+this+application.
  &error_uri=https://developer.github.com/v3/oauth/%23redirect-uri-mismatch
  &state=xyz

Чтобы исправить эту ошибку, либо укажите redirect_uri, соответствующий тому, что вы зарегистрировали, либо оставьте этот параметр, чтобы использовать параметр по умолчанию, зарегистрированный в вашем приложении.

В доступе отказано

Если пользователь отклонит доступ к вашему приложению, GItHub перенаправит на зарегистрированный URL-адрес обратного вызова со следующими параметрами, обобщающими ошибку:

http://your-application.com/callback?error=access_denied
  &error_description=The+user+has+denied+your+application+access.
  &error_uri=https://developer.github.com/v3/oauth/%23access-denied
  &state=xyz

Здесь вы ничего не можете сделать, поскольку пользователи могут не использовать ваше приложение. Чаще всего пользователи просто закрывают окно или нажимают в своем браузере, поэтому вполне вероятно, что вы никогда не увидите эту ошибку.

Распространенные ошибки при запросе токена доступа

На втором этапе обмена кодом на токен доступа может возникнуть дополнительный набор ошибок. Формат этих ответов определяется передаваемым заголовком accept. В следующих примерах показаны только ответы JSON.

Неправильные учетные данные клиента

Если client_id и/или client_secret, которые вы передаете, неверны, вы получите этот ответ об ошибке.

{
  "error": "incorrect_client_credentials",
  "error_description": "The client_id and/or client_secret passed are incorrect.",
  "error_uri": "https://developer.github.com/v3/oauth/#incorrect-client-credentials"
}

Чтобы устранить эту ошибку, вернитесь и убедитесь, что у вас есть правильные учетные данные для вашего приложения oauth. Дважды проверьте client_idи, client_secretчтобы убедиться, что они верны и правильно передаются на GitHub.

Несоответствие URI перенаправления(2)

Если вы предоставите redirect_uri, который не соответствует тому, что вы зарегистрировали в своем приложении, вы получите следующее сообщение об ошибке:

{
  "error": "redirect_uri_mismatch",
  "error_description": "The redirect_uri MUST match the registered callback URL for this application.",
  "error_uri": "https://developer.github.com/v3/oauth/#redirect-uri-mismatch(2)"
}

Чтобы исправить эту ошибку, либо укажите redirect_uri, соответствующий тому, что вы зарегистрировали, либо оставьте этот параметр, чтобы использовать параметр по умолчанию, зарегистрированный в вашем приложении.

Неверный код подтверждения

{
  "add_scopes": [
    "repo"
  ],
  "note": "admin script"
}

Если проверочный код, который вы передаете, неверен, просрочен или не соответствует тому, что вы получили в первом запросе на авторизацию, вы получите эту ошибку.

{
  "error": "bad_verification_code",
  "error_description": "The code passed is incorrect or expired.",
  "error_uri": "https://developer.github.com/v3/oauth/#bad-verification-code"
}

Чтобы устранить эту ошибку, запустите процесс OAuth с самого начала и получите новый код.

Направление пользователей на проверку их доступа к приложению

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

Чтобы создать эту ссылку, вам понадобится ваше приложение OAuth, которое client_idвы получили от GitHub при регистрации приложения .

https://github.com/settings/connections/applications/:client_id

Советы по обнаружению ресурсов, к которым ваше приложение может получить доступ для пользователя, обязательно ознакомьтесь с нашим руководством .