Примечание. Рассмотрите возможность создания GitHub App вместо OAuth App.
Как OAuth Apps, так и GitHub App используют OAuth 2.0.
GitHub Apps может действовать от имени пользователя, аналогично OAuth App, или от имени себя, что полезно для автоматизации, не требующей ввода данных пользователем. Кроме того, GitHub App используют детализированные разрешения, предоставляют пользователю больший контроль над репозиториями, к которым приложение может получить доступ, и используют кратковременные маркеры. Дополнительные сведения см. в разделах Различия между приложениями GitHub и приложениями OAuth и Сведения о создании приложений GitHub.
Реализация OAuth в GitHub Enterprise Server поддерживает стандартный тип предоставления кода авторизации и предоставление авторизации устройствам OAuth 2.0 для приложений, у которых нет доступа к веб-браузеру.
Если вы хотите пропустить стандартную авторизацию приложения, например при его тестировании, можно воспользоваться процессом не для веб-приложения.
Решите, какой процесс авторизации лучше всего подходит вашему приложению OAuth.
- Процесс для веб-приложения: служит для авторизации пользователей для стандартных приложений OAuth, работающих в браузере. (Тип неявного предоставления разрешений не поддерживается.)
- Процесс для устройства: используется для автономных приложений, таких как средства CLI.
Процесс для веб-приложения
Примечание. Если вы создаете приложение GitHub, то также можете использовать процесс для веб-приложения OAuth, но в процедуре настройки есть ряд важных отличий. Дополнительные сведения см. в разделе Проверка подлинности с помощью Приложение GitHub от имени пользователя.
Процесс для веб-приложения, позволяющий авторизовать пользователей для использования приложения, состоит из следующих шагов:
- Пользователи перенаправляются для запроса удостоверения GitHub.
- Пользователи перенаправляются из GitHub обратно на сайт.
- Приложение обращается к API с маркером доступа пользователя.
1. Запрос удостоверения GitHub пользователя
GET http(s)://HOSTNAME/login/oauth/authorize
Эта конечная точка принимает следующие входные параметры.
Имя параметра | Тип | Описание |
---|---|---|
client_id | string | Обязательно. Идентификатор клиента, полученный от GitHub при регистрации. |
redirect_uri | string | URL-адрес в приложении, на который пользователи будут направляться после авторизации. См. дополнительные сведения ниже о URL-адресах перенаправления. |
login | string | Предлагает определенную учетную запись для входа и авторизации приложения. |
scope | string | Разделенный пробелами список областей. Если значение не указано, по умолчанию scope представляет собой пустой список пользователей, которые не авторизовали ни одну область для приложения. Пользователям, авторизовавшим области для приложения, не будет отображаться страница авторизации OAuth со списком областей. Вместо этого данный шаг процесса будет автоматически завершен с набором областей, которые пользователь авторизовал для приложения. Например, если пользователь уже дважды выполнил веб-процесс и авторизовал один токен с областью user , а другой — с областью repo , третий веб-процесс без указания scope получит токен с областью user и repo . |
state | string | Случайная строка, которую сложно угадать. Используется для защиты от атак в форме подделки межсайтовых запросов. |
allow_signup | string | Предоставляется ли пользователям, не прошедшим проверку подлинности, возможность регистрации на GitHub во время процесса OAuth. Значение по умолчанию — true . Используйте значение false , когда политика запрещает регистрацию. |
Параметры code_challenge
PKCE (proof key for Code Exchange) и code_challenge_method
в настоящее время не поддерживаются. Предварительные запросы CORS (OPTIONS) в настоящее время не поддерживаются.
2. Перенаправление пользователей из GitHub обратно на ваш сайт
Если пользователь принимает запрос, GitHub Enterprise Server перенаправляет его обратно на ваш сайт с временным кодом в параметре code
, а также с состоянием, указанным на предыдущем шаге в параметре state
. Срок действия временного кода истекает через 10 минут. Если состояния не совпадают, значит запрос создала третья сторона и следует прервать процесс.
Код в параметре code
обменивается на маркер доступа:
POST http(s)://HOSTNAME/login/oauth/access_token
Эта конечная точка принимает следующие входные параметры.
Имя параметра | Тип | Описание |
---|---|---|
client_id | string | Обязательный. Идентификатор клиента, полученный из GitHub Enterprise Server для OAuth App. |
client_secret | string | Обязательный. Секрет клиента, полученный из GitHub Enterprise Server для OAuth App. |
code | string | Обязательный. Код, полученный в качестве ответа на шаге 1. |
redirect_uri | string | URL-адрес в приложении, на который пользователи будут направляться после авторизации. |
По умолчанию ответ имеет следующую форму:
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 http(s)://HOSTNAME/api/v3/user
Например, в curl можно задать заголовок авторизации следующим образом:
curl -H "Authorization: Bearer OAUTH-TOKEN" http(s)://HOSTNAME/api/v3/user
Процесс для устройства
Примечание. Процесс для устройства находится в стадии общедоступной бета-версии и может быть изменен.
Процесс для устройства позволяет авторизовать пользователей для автономного приложения, например средства CLI или диспетчера учетных данных GIT.
Общая схема процесса для устройства
- Приложение запрашивает коды проверки устройства и пользователя и получает URL-адрес авторизации, по которому пользователь должен будет ввести код проверки пользователя.
- Приложение предлагает пользователю ввести код проверки пользователя на странице
http(s)://HOSTNAME/login/device
. - Приложение опрашивает состояние проверки подлинности пользователя. После того как пользователь авторизует устройство, приложение сможет выполнять вызовы API с новым маркером доступа.
Шаг 1. Приложение запрашивает коды проверки устройства и пользователя на GitHub
POST http(s)://HOSTNAME/login/device/code
Приложение должно запросить код проверки пользователя и URL-адрес проверки, который приложение будет использовать для запроса проверки подлинности пользователя на следующем шаге. Запрос также возвращает код проверки устройства, который приложение должно использовать для получения маркера доступа и проверки состояния проверки подлинности пользователя.
Конечная точка принимает следующие входные параметры.
Имя параметра | Тип | Описание |
---|---|---|
client_id | string | Обязательный. Идентификатор клиента, полученный из GitHub Enterprise Server для приложения. |
scope | string | Разделенный пробелами список областей, к которым приложение запрашивает доступ. Дополнительные сведения см. в разделе Области для приложений OAuth. |
По умолчанию ответ имеет следующую форму:
device_code=3584d83530557fdd1f46af8289938c8ef79f9dc5&expires_in=900&interval=5&user_code=WDJB-MJHT&verification_uri=https%3A%2F%HOSTNAME%2Flogin%2Fdevice
Имя параметра | Тип | Описание |
---|---|---|
device_code | string | Код проверки устройства состоит из 40 символов и служит для проверки устройства. |
user_code | string | Код проверки пользователя отображается на устройстве, чтобы пользователь мог ввести его в браузере. Он состоит из восьми символов с дефисом в середине. |
verification_uri | string | URL-адрес проверки, по которому пользователи должны ввести user_code : http(s)://HOSTNAME/login/device . |
expires_in | integer | Количество секунд до окончания срока действия device_code и user_code . Значение по умолчанию равно 900 секундам или 15 минутам. |
interval | integer | Минимальное количество секунд, которое должно пройти, прежде чем можно будет выполнить новый запрос маркера доступа (POST http(s)://HOSTNAME/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": "http(s)://HOSTNAME/login/device",
"expires_in": 900,
"interval": 5
}
Accept: application/xml
<OAuth>
<device_code>3584d83530557fdd1f46af8289938c8ef79f9dc5</device_code>
<user_code>WDJB-MJHT</user_code>
<verification_uri>http(s)://HOSTNAME/login/device</verification_uri>
<expires_in>900</expires_in>
<interval>5</interval>
</OAuth>
Шаг 2. Запрос на ввод кода проверки пользователя в браузере
Устройство отобразит код проверки пользователя и предложит пользователю ввести его на странице http(s)://HOSTNAME/login/device
.
Шаг 3. Опрос GitHub приложением с целью проверки авторизации устройства пользователем
POST http(s)://HOSTNAME/login/oauth/access_token
Приложение будет выполнять запросы на авторизацию устройства POST http(s)://HOSTNAME/login/oauth/access_token
, пока не истечет срок действия кода проверки устройства или пользователя либо пока пользователь не авторизует приложение успешно с помощью допустимого кода проверки пользователя. Чтобы избежать ошибок ограничения частоты запросов, приложение должно использовать минимальный интервал (interval
) опроса, полученный на шаге 1. Дополнительные сведения см. в разделе Ограничения частоты запросов для процесса для устройства.
Пользователь должен ввести действительный код в течение 15 минут (900 секунд). По истечении 15 минут вам потребуется запросить новый код авторизации устройства с помощью POST http(s)://HOSTNAME/login/device/code
.
После авторизации пользователем приложение получит маркер доступа, с помощью которого можно выполнять запросы к API от имени пользователя.
Конечная точка принимает следующие входные параметры.
Имя параметра | Тип | Описание |
---|---|---|
client_id | string | Обязательный. Идентификатор клиента, полученный из GitHub Enterprise Server для OAuth App. |
device_code | string | Обязательный. Код проверки устройства, полученный в ответ на запрос POST http(s)://HOSTNAME/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 http(s)://HOSTNAME/login/oauth/access_token
) до истечения минимального интервала времени между запросами (или interval
) будет достигнут предел частоты запросов и получен ответ с ошибкой slow_down
. Ответ об ошибке slow_down
добавляет пять секунд к последнему интервалу interval
. Дополнительные сведения см. в разделе Коды ошибок процесса для устройства.
Коды ошибок процесса для устройства
Код ошибки | Описание |
---|---|
authorization_pending | Эта ошибка возникает, если запрос авторизации ожидает завершения и пользователь еще не ввел код проверки пользователя. Приложение должно продолжать выполнять запрос POST http(s)://HOSTNAME/login/oauth/access_token без превышения интервала interval , то есть перед следующим запросом должно пройти минимальное количество секунд. |
slow_down | При получении ошибки slow_down к минимальному интервалу времени interval между запросами POST http(s)://HOSTNAME/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 http(s)://HOSTNAME/login/oauth/access_token . |
incorrect_client_credentials | Для процесса для устройства необходимо передать идентификатор клиента приложения, который можно найти на странице параметров приложения. client_secret не требуется для процесса для устройства. |
incorrect_device_code | Указанный код проверки устройства недействителен. |
access_denied | Если пользователь нажимает кнопку "Отмена" в процессе авторизации, вы получаете ошибку access_denied и пользователь больше не сможет использовать код проверки. |
Дополнительные сведения см. в разделе Предоставление разрешения на авторизацию устройства OAuth 2.0.
Процесс не для веб-приложения
Проверка подлинности не для веб-приложения доступна в некоторых ситуациях, таких как тестирование. При необходимости можно использовать обычную проверку подлинности , чтобы создать personal access token на странице параметров personal access tokens. Этот метод позволяет пользователю отозвать доступ в любое время.
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
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
:
http://127.0.0.1:1234/path
Обратите внимание, что OAuth RFC рекомендует не использовать localhost
, а вместо этого использовать литерал 127.0.0.1
замыкания на себя или IPv6 ::1
.
Создание нескольких токенов для приложений OAuth
Вы можете создать несколько токенов для определенных сочетаний пользователя, приложения и области, которые будут предназначены для конкретных вариантов использования.
Это полезно, если один из рабочих процессов, поддерживаемых приложением OAuth, использует GitHub для входа и требует только базовых сведений о пользователе. Другой рабочий процесс может требовать доступа к частным репозиториям пользователя. Используя несколько токенов, приложение OAuth может выполнять веб-процесс для каждого варианта использования, запрашивая только необходимые области. Если пользователь использует приложение только для входа, ему никогда не требуется предоставлять приложению OAuth доступ к частным репозиториям.
На одного пользователя, приложение или область действия можно использовать до десяти токенов. Если приложение создает больше десяти токенов для одного и того пользователя и одних и тех же областей, самые старые токены с одним и тем же сочетанием пользователя, приложения и областей отзываются.
Предупреждение. Отзыв всех разрешений от OAuth App удаляет все ключи SSH, созданные приложением от имени пользователя, включая ключи развертывания.
Перенаправление пользователей для проверки доступа
Вы можете предоставлять ссылку на сведения об авторизации для приложения OAuth, чтобы пользователи могли просматривать и отзывать авторизации.
Чтобы создать эту ссылку, вам потребуется идентификатор client_id
приложения OAuth, полученный от GitHub при регистрации приложения.
http(s)://HOSTNAME/settings/connections/applications/:client_id
Совет: Дополнительные сведения о ресурсах, к которым ваш Приложение OAuth может получить доступ для пользователя, см. в разделе Обнаружение ресурсов для пользователя.
Устранение неполадок
- "Устранение ошибок запросов на авторизацию"
- "Устранение ошибок при запросе маркеров доступа для приложения OAuth"
- "Ошибки потока устройств"
- "Истечение срока действия и отзыв маркера"