Skip to main content
We publish frequent updates to our documentation, and translation of this page may still be in progress. For the most current information, please visit the English documentation.
 

 

Идентификация и авторизация пользователей для приложений GitHub

In this article

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

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

Когда приложение GitHub действует от имени пользователя, оно выполняет запросы между пользователями. Эти запросы должны быть авторизованы с помощью маркера доступа пользователя. Запросы типа "пользователь — сервер" включают запрос данных для пользователя, например определение того, какие репозитории отобразить определенному пользователю. Эти запросы также включают действия, инициированные пользователем, например запуск сборки.

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

Идентификация пользователей на вашем сайте

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

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

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

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

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

Если выбрать Запрашивать авторизацию пользователя (OAuth) во время установки при создании или изменении приложения, шаг 1 будет выполнен во время его установки. Дополнительные сведения см. в разделе Авторизация пользователей во время установки.

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

Направьте пользователя по следующему URL-адресу в его браузере:

GET http(s)://HOSTNAME/login/oauth/authorize

Когда приложение GitHub указывает параметр login, оно предлагает пользователям определенную учетную запись для входа и авторизации приложения.

Параметры

ИмяТипОписание
client_idstringОбязательный. Идентификатор клиента для вашего приложения GitHub. Его можно найти в параметрах приложения GitHub при выборе приложения. Примечание. Идентификатор приложения и идентификатор клиента не совпадают и не являются взаимозаменяемыми.
redirect_uristringURL-адрес в приложении, на который пользователи будут направляться после авторизации. Он должен точно совпадать с одним из URL-адресов, которые вы указали в качестве URL-адреса обратного вызова при настройке приложения GitHub и не может содержать никаких дополнительных параметров.
statestringОн должен содержать случайную строку для защиты от атак в форме подделки и может содержать любые другие произвольные данные.
loginstringПредлагает определенную учетную запись для входа и авторизации приложения.
allow_signupstringБудет ли пользователям, не прошедшим проверку подлинности, предлагаться возможность подписаться на GitHub во время потока OAuth. Значение по умолчанию — true. Используйте значение false, когда политика запрещает регистрацию.

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

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

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

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

Обменяйте этот code на маркер доступа. Когда маркеры с истекающим сроком действия включены, срок действия маркера доступа истекает через 8 часов, а срок действия маркера обновления — через 6 месяцев. При каждом обновлении маркера вы получаете новый маркер обновления. Дополнительные сведения см. в разделе Обновление токенов доступа между пользователями и сервером.

Пользовательские маркеры с истекающим сроком действия на данный момент являются дополнительной функцией и могут быть изменены. Сведения о включении функции ограничения срока действия маркеров "пользователь —сервер" см. в разделе Активация дополнительных функций для приложений.

Отправьте запрос в следующую конечную точку для получения маркера доступа:

POST http(s)://HOSTNAME/login/oauth/access_token

Параметры

ИмяТипОписание
client_idstringОбязательный. Идентификатор клиента для вашего приложения GitHub.
client_secretstringОбязательный. Секрет клиента для вашего приложения GitHub.
codestringОбязательный. Код, полученный в качестве ответа на шаге 1.
redirect_uristringURL-адрес в приложении, на который пользователи будут направляться после авторизации. Он должен точно совпадать с одним из URL-адресов, которые вы указали в качестве URL-адреса обратного вызова при настройке приложения GitHub и не может содержать никаких дополнительных параметров.

Ответ

По умолчанию ответ принимает следующий вид. Параметры ответа expires_in, refresh_token и refresh_token_expires_in возвращаются только в том случае, если включено ограничение срока действия маркеров доступа "пользователь — сервер".

{
  "access_token": "ghu_16C7e42F292c6912E7710c838347Ae178B4a",
  "expires_in": 28800,
  "refresh_token": "ghr_1B4a2e77838347a7E420ce178F2E7c6912E169246c34E1ccbF66C46812d16D5B1A9Dc86A1498",
  "refresh_token_expires_in": 15811200,
  "scope": "",
  "token_type": "bearer"
}

3. Приложение GitHub обращается к API с маркером доступа пользователя

Маркер доступа пользователя позволяет приложению GitHub отправлять запросы к 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.

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

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

После получения токена OAuth для пользователя можно проверить, к каким установкам этот пользователь имеет доступ.

Authorization: Bearer OAUTH-TOKEN
GET /user/installations

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

Authorization: Bearer OAUTH-TOKEN
GET /user/installations/:installation_id/repositories

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

Обработка отозванной авторизации приложения GitHub

Если пользователь отзывает свою авторизацию приложения GitHub, приложение по умолчанию получит веб-перехватчик github_app_authorization. Приложения GitHub не могут отменить подписку на это событие. Любой пользователь может отменить авторизацию приложения GitHub со своей страницы параметров учетной записи GitHub. Отмена авторизации приложения GitHub не деинсталлирует приложение GitHub. Стоит запрограммировать приложение GitHub таким образом, чтобы при получении этого веб-перехватчика оно переставало вызывать API от имени пользователя, который отозвал маркер. Если приложение GitHub продолжает использовать отозванный маркер доступа, оно получит ошибку 401 Bad Credentials.

Разрешения уровня пользователя

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

Разрешения уровня пользователя можно выбрать в параметрах приложения GitHub в разделе Разрешения пользователя на странице Разрешения и веб-перехватчики. Дополнительные сведения о выборе разрешений см. в статье Изменение разрешений приложения GitHub.

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

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

Запросы между пользователем и сервером

Хотя большая часть вашего взаимодействия с API должна происходить с использованием ваших маркеров доступа установки от сервера к серверу, некоторые конечные точки позволяют выполнять действия с помощью API с использованием маркера доступа пользователя. Ваше приложение может выполнять следующие запросы, используя конечные точки GraphQL или REST.

Поддерживаемые конечные точки

Проверка запусков

Проверить пакеты

Правила поведения

Состояния развертывания

Развернутые приложения

События

Веб-каналы

Большие двоичные объекты Git

Фиксация Git

Ссылки на Git

Теги Git

Деревья Git

Шаблоны Gitignore

Установки

Уполномоченные по проблеме

Комментарии к проблеме

События проблемы

Временная шкала проблем

Проблемы

Метки

Лицензии

Markdown

Meta

Вехи

Перехватчики организации

Участники организации

Организация сторонних участников совместной работы

Перехватчики предварительного получения организации

Командные проекты организации

Репозитории команды организации

Команды организации

Организации

Участники совместной работы проекта

Проекты

Комментарии к вытягиванию

События проверки запроса на вытягивание

Запросы на проверку запроса на вытягивание

Проверки запросов на вытягивание

Запросы данных

Реакции

Репозитории

Деятельность репозитория

Ветви репозитория

Участники совместной работы репозитория

Комментарии фиксации репозитория

Фиксации репозитория

Сообщество репозитория

Содержимое репозитория

Сообщения о событиях репозитория

Перехватчики репозитория

Приглашения репозитория

Ключи репозитория

Страницы репозитория

Перехватчики предварительного получения репозитория

Выпуски репозитория

Статистика репозитория

Root

Поиск

Состояния

Обсуждения в команде

Разделы

Электронные письма для пользователей

Подписчики пользователя

Ключи GPG пользователя

Открытые ключи пользователя

Пользователи

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