Авторизация приложений OAuth

Реализация OAuth GitHubподдерживает стандартный тип предоставления кода авторизации и разрешение авторизации устройств OAuth 2.0 для приложений, которые не имеют доступа к веб-браузеру.

Если вы хотите пропустить стандартную авторизацию приложения, например при его тестировании, можно воспользоваться процессом не для веб-приложения.

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

•         [поток](#web-application-flow) веб-приложения: используется для авторизации пользователей для стандартных данных OAuth apps , которые выполняются в браузере. ([Тип неявного предоставления разрешений](https://tools.ietf.org/html/rfc6749#section-4.2) не поддерживается.)
  

•         [Процесс для устройства](#device-flow): используется для автономных приложений, таких как средства CLI.
  

Процесс для веб-приложения

Процесс для веб-приложения, позволяющий авторизовать пользователей для использования приложения, состоит из следующих шагов:

1. Пользователи перенаправляются для запроса своей идентификации GitHub
2. Пользователи перенаправляются обратно на ваш сайт через GitHub
3. Приложение обращается к API с маркером доступа пользователя.

1. Запросить идентификацию пользователя на GitHub

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

Эта конечная точка принимает следующие входные параметры.

Параметр запроса	Тип	Обязательное?	Description
client_id	string	Обязательное поле	Идентификатор клиента, который вы получили от GitHub, когда вы registered.
redirect_uri	string	Настоятельно рекомендуется	URL-адрес в приложении, на который пользователи будут направляться после авторизации. См. дополнительные сведения ниже о URL-адресах перенаправления.
login	string	Необязательно	Предлагает определенную учетную запись для входа и авторизации приложения.
scope	string	Зависимый от контекста	Разделенный пробелами список областей. Если значение не указано, по умолчанию scope представляет собой пустой список пользователей, которые не авторизовали ни одну область для приложения. Пользователям, авторизовавшим области для приложения, не будет отображаться страница авторизации OAuth со списком областей. Вместо этого данный шаг процесса будет автоматически завершен с набором областей, которые пользователь авторизовал для приложения. Например, если пользователь уже дважды выполнил веб-процесс и авторизовал один токен с областью user, а другой — с областью repo, третий веб-процесс без указания scope получит токен с областью user и repo.
state	string	Настоятельно рекомендуется	Случайная строка, которую сложно угадать. Используется для защиты от атак в форме подделки межсайтовых запросов.
code_challenge	string	Настоятельно рекомендуется	Используется для защиты потока проверки подлинности с помощью PKCE (ключ проверки подлинности для Exchange кода). Является обязательным, если указан параметр code_challenge_method. Должен быть 43 символом SHA-256 хэша случайной строки, созданной клиентом. Дополнительные сведения об этом расширении безопасности см. в rfC PKCE.
code_challenge_method	string	Настоятельно рекомендуется	Используется для защиты потока проверки подлинности с помощью PKCE (ключ проверки подлинности для Exchange кода). Является обязательным, если указан параметр code_challenge. Должно быть S256 : plain метод вызова кода не поддерживается.
allow_signup	string	Необязательно	Будет ли неаутентифицированным пользователям возможность зарегистрироваться на GitHub во время процесса OAuth. Значение по умолчанию — true. Используйте значение false, когда политика запрещает регистрацию.
prompt	string	Необязательно	Заставляет средство выбора учетной записи отображаться, если задано select_accountзначение . Средство выбора учетных записей также появится, если у приложения есть URI перенаправления, отличный от HTTP, или если у пользователя есть несколько учетных записей, вошедшего в систему.

В настоящее время запросы на предварительный полет CORS (OPTIONS) не поддерживаются.

2. Пользователи перенаправляются обратно на ваш сайт через GitHub

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

Код в параметре code обменивается на маркер доступа:

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

Эта конечная точка принимает следующие входные параметры.

Наименование параметра	Тип	Обязательное?	Description
client_id	string	Обязательное поле	Идентификатор клиента, полученный от GitHub для данных OAuth app.
client_secret	string	Обязательное поле	Секрет клиента, полученный от GitHub для данных OAuth app.
code	string	Обязательное поле	Код, полученный в качестве ответа на шаге 1.
redirect_uri	string	Настоятельно рекомендуется	URL-адрес в приложении, на который пользователи будут направляться после авторизации. Мы можем использовать это для сопоставления с универсальным кодом ресурса (URI), первоначально предоставленного при code выпуске, чтобы предотвратить атаки против вашей службы.
code_verifier	string	Настоятельно рекомендуется	Используется для защиты потока проверки подлинности с помощью PKCE (ключ проверки подлинности для Exchange кода). Требуется, если code_challenge он был отправлен во время авторизации пользователя. Должно быть исходное значение, используемое для создания code_challenge в запросе авторизации. Это может храниться в файле cookie вместе с state параметром или в переменной сеанса во время проверки подлинности в зависимости от архитектуры приложения.

По умолчанию ответ имеет следующую форму:

access_token=gho_16C7e42F292c6912E7710c838347Ae178B4a&scope=repo%2Cgist&token_type=bearer

Вы также можете получить ответ в разных форматах, указав формат в заголовке Accept. Например, Accept: application/json или Accept: application/xml:

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

Accept: application/xml
<OAuth>
  <token_type>bearer</token_type>
  <scope>repo,gist</scope>
  <access_token>gho_16C7e42F292c6912E7710c838347Ae178B4a</access_token>
</OAuth>

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

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

Authorization: Bearer OAUTH-TOKEN
GET https://api.github.com/user

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

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

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

Процесс для устройства

Поток устройств позволяет авторизовать пользователей для приложения без головы, например средства CLI или диспетчера учетных данных Git.

Прежде чем использовать процесс для устройства с целью авторизации и идентификации пользователей, необходимо сначала включить его в параметрах приложения. Дополнительные сведения о включении потока устройств в приложении см. в разделе [AUTOTITLE для GitHub Apps и Изменение регистрации приложения GitHub](/apps/oauth-apps/maintaining-oauth-apps/modifying-an-oauth-app) для OAuth apps.

Общая схема процесса для устройства

1. Приложение запрашивает коды проверки устройства и пользователя и получает URL-адрес авторизации, по которому пользователь должен будет ввести код проверки пользователя.
2. Приложение предлагает пользователю ввести код проверки пользователя на странице https://github.com/login/device.
3. Приложение опрашивает состояние проверки подлинности пользователя. После того как пользователь авторизует устройство, приложение сможет выполнять вызовы API с новым маркером доступа.

Шаг 1: Приложение запрашивает коды подтверждения устройства и пользователей у GitHub

POST https://github.com/login/device/code

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

Конечная точка принимает следующие входные параметры.

Наименование параметра	Тип	Description
client_id	string

          **Обязательно**. Идентификатор клиента, полученный от GitHub для вашего приложения.

scope | string | Список областей, к которым приложение запрашивает доступ. Дополнительные сведения см. в разделе Области для приложений OAuth.

По умолчанию ответ имеет следующую форму:

device_code=3584d83530557fdd1f46af8289938c8ef79f9dc5&expires_in=900&interval=5&user_code=WDJB-MJHT&verification_uri=https%3A%2F%2Fgithub.com%2Flogin%2Fdevice

Наименование параметра	Тип	Description
device_code	string	Код проверки устройства состоит из 40 символов и служит для проверки устройства.
user_code	string	Код проверки пользователя отображается на устройстве, чтобы пользователь мог ввести его в браузере. Он состоит из восьми символов с дефисом в середине.
verification_uri	string	URL-адрес проверки, по которому пользователи должны ввести user_code: https://github.com/login/device.
expires_in	integer	Количество секунд до окончания срока действия device_code и user_code. Значение по умолчанию равно 900 секундам или 15 минутам.
interval	integer	Минимальное количество секунд, которое должно пройти, прежде чем можно будет выполнить новый запрос маркера доступа (POST https://github.com/login/oauth/access_token) для завершения авторизации устройства. Например, если интервал равен пяти, вы не сможете выполнить новый запрос, пока не пройдут пять секунд. Если вы выполните более одного запроса в течение пяти секунд, то достигнете предела частоты запросов и получите ошибку slow_down.

Вы также можете получить ответ в разных форматах, указав формат в заголовке Accept. Например, Accept: application/json или Accept: application/xml:

Accept: application/json
{
  "device_code": "3584d83530557fdd1f46af8289938c8ef79f9dc5",
  "user_code": "WDJB-MJHT",
  "verification_uri": "https://github.com/login/device",
  "expires_in": 900,
  "interval": 5
}

Accept: application/xml
<OAuth>
  <device_code>3584d83530557fdd1f46af8289938c8ef79f9dc5</device_code>
  <user_code>WDJB-MJHT</user_code>
  <verification_uri>https://github.com/login/device</verification_uri>
  <expires_in>900</expires_in>
  <interval>5</interval>
</OAuth>

Шаг 2. Запрос на ввод кода проверки пользователя в браузере

Устройство отобразит код проверки пользователя и предложит пользователю ввести его на странице https://github.com/login/device.

Шаг 3: Приложение опрошивает GitHub, чтобы проверить, авторизировал ли пользователь устройство.

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

Приложение будет выполнять запросы на авторизацию устройства POST https://github.com/login/oauth/access_token, пока не истечет срок действия кода проверки устройства или пользователя либо пока пользователь не авторизует приложение успешно с помощью допустимого кода проверки пользователя. Чтобы избежать ошибок ограничения частоты запросов, приложение должно использовать минимальный интервал (interval) опроса, полученный на шаге 1. Дополнительные сведения см. в разделе "Ограничения скорости" для потока устройств.

Пользователь должен ввести действительный код в течение 15 минут (900 секунд). По истечении 15 минут вам потребуется запросить новый код авторизации устройства с помощью POST https://github.com/login/device/code.

После авторизации пользователем приложение получит маркер доступа, с помощью которого можно выполнять запросы к API от имени пользователя.

Конечная точка принимает следующие входные параметры.

Наименование параметра	Тип	Description
client_id	string

          **Обязательно**. Идентификатор клиента, полученный от GitHub для данных OAuth app.

device_code | string | Обязательно. Полученные device_code от POST https://github.com/login/device/code запроса. grant_type | string | Обязательно. Тип предоставления разрешения должен быть urn:ietf:params:oauth:grant-type:device_code.

По умолчанию ответ имеет следующую форму:

access_token=gho_16C7e42F292c6912E7710c838347Ae178B4a&token_type=bearer&scope=repo%2Cgist

Вы также можете получить ответ в разных форматах, указав формат в заголовке Accept. Например, Accept: application/json или Accept: application/xml:

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

Accept: application/xml
<OAuth>
  <access_token>gho_16C7e42F292c6912E7710c838347Ae178B4a</access_token>
  <token_type>bearer</token_type>
  <scope>gist,repo</scope>
</OAuth>

Ограничения частоты вызовов для процесса для устройства

Пользователь может отправлять код проверки в браузере не чаще чем 50 раз в час для каждого приложения.

При выполнении еще одного запроса маркера доступа (POST https://github.com/login/oauth/access_token) до истечения минимального интервала времени между запросами (или interval) будет достигнут предел частоты запросов и получен ответ с ошибкой slow_down. Ответ об ошибке slow_down добавляет пять секунд к последнему интервалу interval. Дополнительные сведения см. в кодах ошибок для потока устройства.

Коды ошибок процесса для устройства

Код ошибки	Description
authorization_pending	Эта ошибка возникает, если запрос авторизации ожидает завершения и пользователь еще не ввел код проверки пользователя. Приложение должно продолжать выполнять запрос POST https://github.com/login/oauth/access_token без превышения интервала interval, то есть перед следующим запросом должно пройти минимальное количество секунд.
slow_down	При получении ошибки slow_down к минимальному интервалу времени interval между запросами POST https://github.com/login/oauth/access_token добавляются пять дополнительных секунд. Например, если начальный требуемый интервал между запросами составлял пять секунд и вы получили ответ с ошибкой slow_down, необходимо подождать не менее 10 секунд, прежде чем выполнять новый запрос маркера доступа OAuth. В ответе с ошибкой указывается новый интервал interval, который необходимо выждать.
expired_token	Если истек срок действия кода устройства, возникнет ошибка token_expired. Необходимо запросить новый код устройства.
unsupported_grant_type	Тип предоставления разрешения должен быть urn:ietf:params:oauth:grant-type:device_code и включен в качестве входного параметра при запросе маркера OAuth POST https://github.com/login/oauth/access_token.
incorrect_client_credentials	Для процесса для устройства необходимо передать идентификатор клиента приложения, который можно найти на странице параметров приложения.

          `client_secret` не требуется для процесса для устройства.

| incorrect_device_code | Указанный код проверки устройства недействителен. | access_denied | Когда пользователь нажимает кнопку "Отменить" во время процесса авторизации, вы получите access_denied ошибку, и пользователь не сможет снова использовать код проверки. | device_flow_disabled | Процесс для устройства не включен в параметрах приложения. Дополнительные сведения см. в разделе "Поток устройств".

Дополнительные сведения см. в статье OAuth 2.0 Device Authorization Grant.

Процесс не для веб-приложения

Проверка подлинности не для веб-приложения доступна в некоторых ситуациях, таких как тестирование. Если вам нужно, можно использовать обычную проверку подлинности для создания personal access token с помощью страницы параметров personal access tokens. Этот метод позволяет пользователю отозвать доступ в любое время.

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

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

CALLBACK: http://example.com/path

GOOD: http://example.com/path
GOOD: http://example.com/path/subdir/other
GOOD: http://oauth.example.com/path
GOOD: http://oauth.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

URL-адреса перенаправления обратного цикла

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

Для URL-адреса обратного http://127.0.0.1/path вызова это можно использовать redirect_uri , если приложение прослушивает порт 1234:

http://127.0.0.1:1234/path

Обратите внимание, что OAuth RFC рекомендует не использовать localhost, а вместо этого использовать литерал 127.0.0.1 обратного цикла или IPv6 ::1.

Создание нескольких маркеров для OAuth apps

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

Это полезно, если ваш OAuth app поддерживает один рабочий процесс, который использует GitHub для входа и требует только базовой информации о пользователе. Другой рабочий процесс может требовать доступа к частным репозиториям пользователя. Используя несколько маркеров, данные OAuth app могут выполнять веб-поток для каждого варианта использования, запрашивая только необходимые области. Если пользователь использует приложение только для входа, они никогда не требуются для предоставления доступа к частным репозиториям OAuth app.

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

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

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

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

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

Устранение неполадок

•         [AUTOTITLE](/apps/oauth-apps/maintaining-oauth-apps/troubleshooting-authorization-request-errors)
  

•         [AUTOTITLE](/apps/oauth-apps/maintaining-oauth-apps/troubleshooting-oauth-app-access-token-request-errors)
  

•         [Ошибки потока устройства](#error-codes-for-the-device-flow)
  

•         [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/token-expiration-and-revocation)
  

Дополнительные материалы

•         [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/about-authentication-to-github)