Примечание. Ограничение срока действия маркеров в настоящее время являются необязательной функцией и может быть изменено. Сведения о том, как отказаться от функции ограничения срока действия маркеров, см. в разделе Активация дополнительных функций для приложений. Дополнительные сведения см. в статье Ограничение срока действия маркеров доступа пользователей к серверу для приложений GitHub.
Когда приложение GitHub действует от имени пользователя, оно выполняет запросы между пользователями. Эти запросы должны быть авторизованы с помощью маркера доступа пользователя. Запросы типа "пользователь — сервер" включают запрос данных для пользователя, например определение того, какие репозитории отобразить определенному пользователю. Эти запросы также включают действия, инициированные пользователем, например запуск сборки.
Для укрепления защиты токенов доступа между пользователями и сервером можно использовать токены доступа, срок действия которых истекает через восемь часов, и токен обновления, который можно обменять на новый токен доступа. Дополнительные сведения см. в разделе Обновление токенов доступа между пользователями и сервером.
Идентификация пользователей на вашем сайте
Чтобы авторизовать пользователей для стандартных приложений, запущенных в браузере, используйте поток веб-приложений.
Чтобы авторизовать пользователей для автономных приложений без прямого доступа к браузеру, таких как инструменты CLI или менеджеры учетных данных Git, используйте поток устройства. Поток устройства использует предоставление разрешения авторизации устройства OAuth 2.0.
Процесс для веб-приложения
При использовании потока веб-приложения процесс идентификации пользователей на вашем сайте выглядит следующим образом:
- Пользователи перенаправляются для запроса удостоверения GitHub.
- Пользователи перенаправляются из GitHub обратно на сайт.
- Ваше приложение GitHub получает доступ к API с маркером доступа пользователя.
Если выбрать Запрашивать авторизацию пользователя (OAuth) во время установки при создании или изменении приложения, шаг 1 будет выполнен во время его установки. Дополнительные сведения см. в разделе Авторизация пользователей во время установки.
1. Запрос удостоверения GitHub пользователя
Направьте пользователя по следующему URL-адресу в его браузере:
GET http(s)://HOSTNAME/login/oauth/authorize
Когда приложение GitHub указывает параметр login
, оно предлагает пользователям определенную учетную запись для входа и авторизации приложения.
Параметры
Имя | Тип | Описание |
---|---|---|
client_id | string | Обязательный. Идентификатор клиента для вашего приложения GitHub. Его можно найти в параметрах приложения GitHub при выборе приложения. Примечание. Идентификатор приложения и идентификатор клиента не совпадают и не являются взаимозаменяемыми. |
redirect_uri | string | URL-адрес в приложении, на который пользователи будут направляться после авторизации. Он должен точно совпадать с одним из URL-адресов, которые вы указали в качестве URL-адреса обратного вызова при настройке приложения GitHub и не может содержать никаких дополнительных параметров. |
state | string | Он должен содержать случайную строку для защиты от атак в форме подделки и может содержать любые другие произвольные данные. |
login | string | Предлагает определенную учетную запись для входа и авторизации приложения. |
allow_signup | string | Будет ли пользователям, не прошедшим проверку подлинности, предлагаться возможность подписаться на 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_id | string | Обязательный. Идентификатор клиента для вашего приложения GitHub. |
client_secret | string | Обязательный. Секрет клиента для вашего приложения GitHub. |
code | string | Обязательный. Код, полученный в качестве ответа на шаге 1. |
redirect_uri | string | URL-адрес в приложении, на который пользователи будут направляться после авторизации. Он должен точно совпадать с одним из 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
Теги Git
Деревья Git
Шаблоны Gitignore
Установки
Уполномоченные по проблеме
Комментарии к проблеме
- Список комментариев к проблеме
- Создание комментария к проблеме
- Список комментариев к проблемам для репозитория
- Получение комментария к проблеме
- Обновление комментария к проблеме
- Удаление комментария к проблеме
События проблемы
Временная шкала проблем
Проблемы
- Список проблем, назначенных пользователю, прошедшему проверку подлинности
- Список уполномоченных
- Проверка возможности назначения пользователя
- Список проблем репозитория
- Создание проблемы
- Получение проблемы
- Обновление проблемы
- Блокировка проблемы
- Разблокировка проблемы
Метки
- Список меток для проблемы
- Добавление меток для проблемы
- Настройка меток для проблемы
- Удаление всех меток из проблемы
- Удаление метки из проблемы
- Список меток для репозитория
- Создание Label
- Получение метки
- Обновление метки
- Удаление метки
- Получение метки для каждой проблемы в вехе
Лицензии
Markdown
- Преобразование для просмотра документа Markdown
- Преобразование для просмотра документа Markdown в режиме RAW
Meta
Вехи
Перехватчики организации
- Список веб-перехватчиков организации
- Создание веб-перехватчика организации
- Получение веб-перехватчика организации
- Обновление веб-перехватчика организации
- Удаление веб-перехватчика организации
- Проверка связи с веб-перехватчиком организации
Участники организации
- Список участников организации
- Проверка членства пользователя в организации
- Удаление участника организации
- Получение членства в организации для пользователя
- Настройка членства в организации для пользователя
- Удаление членства в организации для пользователя
- Список участников общественных организаций
- Проверка членства пользователя в общественной организации
- Настройка членства в общедоступной организации для пользователя, прошедшего проверку подлинности
- Удаление членства в общедоступной организации для пользователя, прошедшего проверку подлинности
Организация сторонних участников совместной работы
- Список сторонних участников совместной работы для организации
- Преобразование участника организации в стороннего участника совместной работы
- Удаление стороннего участника совместной работы из организации
Перехватчики предварительного получения организации
- Список перехватчиков предварительного получения для организации
- Получение перехватчика предварительного получения для организации
- Обновление принудительного использования перехватчика предварительного получения для организации
- Отмена принудительного использования перехватчика предварительного получения для организации
Командные проекты организации
- Список командных проектов
- Проверка разрешений группы для проекта
- Добавление или обновление разрешений для командного проекта
- Удаление проекта из команды
Репозитории команды организации
- Список репозиториев команды
- Проверка разрешений команды для репозитория
- Добавление или обновление разрешений на репозиторий команды
- Удаление репозитория из команды
Команды организации
- Список команд
- Создание команды
- Получение команды по имени
- Обновление команды
- Удаление команды
- Список членов команды
- Получение членства в команде для пользователя
- Добавление или обновление членства в команде для пользователя
- Удаление членства в команде для пользователя
- Список дочерних команд
- Список команд для пользователя, прошедшего проверку подлинности
Организации
- Список организаций
- Добавление организации
- Обновление организации
- Список членства в организациях для пользователя, прошедшего проверку подлинности
- Получение членства в организации для пользователя, прошедшего проверку подлинности
- Обновление членства в организации для пользователя, прошедшего проверку подлинности
- Список организаций для пользователя, прошедшего проверку подлинности
- Список организаций для пользователя
Участники совместной работы проекта
- Список участников совместной работы проекта
- Добавление участника совместной работы проекта
- Удалить участника совместной работы проекта
- Получить разрешение проекта для пользователя
Проекты
- Список проектов организации
- Создание проекта организации
- Получение проекта
- Обновление проекта
- Удаление проекта
- Список столбцов проекта
- Создание столбца проекта
- Получение столбца проекта
- Обновление столбца проекта
- Удаление столбца проекта
- Список карточек проекта
- Создание карточки проекта
- Перемещение столбца проекта
- Получение карточки проекта
- Обновление карточки проекта
- Удаление карточки проекта
- Перемещение карточки проекта
- Список проектов репозитория
- Создание проекта репозитория
Комментарии к вытягиванию
- Список комментариев к проверке в запросе на вытягивание
- Создание комментария к проверке для запроса на вытягивание
- Список комментариев к проверке в репозитории
- Получение комментария к проверке для запроса на вытягивание
- Обновление комментария к проверке для запроса на вытягивание
- Удаление комментария к проверке для запроса на вытягивание
События проверки запроса на вытягивание
Запросы на проверку запроса на вытягивание
- Список запрашиваемых рецензентов для запроса на вытягивание
- Запрашивание у рецензентов запроса на вытягивание
- Удаление запрашиваемых рецензентов из запроса на вытягивание
Проверки запросов на вытягивание
- Список проверок для запроса на вытягивание
- Создание проверки для запроса на вытягивание
- Получение проверки для запроса на вытягивание
- Обновление проверки для запроса на вытягивание
- Список комментариев для проверки запроса на вытягивание
Запросы данных
- Список запросов на вытягивание
- Создание запроса на включение изменений
- Получение запроса на вытягивание
- Обновление запроса на вытягивание
- Список фиксаций в запросе на вытягивание
- Список файлов запросов на вытягивание
- Проверка объединения запроса на вытягивание
- Объединение запроса на вытягивание (кнопка "Объединить")
Реакции
- Удаление реакции
- Список реакций на комментарий фиксации
- Создание реакции на комментарий фиксации
- Список реакций на проблему
- Создание реакции на проблему
- Список реакций на комментарий к проблеме
- Создание реакции на комментарий к проблеме
- Список реакций на комментарий к проверке запроса на вытягивание
- Создание реакции на комментарий к проверке запроса на вытягивание
- Список реакций на комментарий в групповом обсуждении
- Создание реакции на комментарий в групповом обсуждении
- Список реакций для группового обсуждения
- Создание реакции для группового обсуждения
- Удаление реакции на комментарий фиксации
- Удаление реакции на проблему
- Удаление реакции на комментарий к фиксации
- Удаление реакции на комментарий к запросу на вытягивание
- Удаление реакции на групповое обсуждение
- Удаление реакции на комментарий в групповом обсуждении
Репозитории
- Список репозиториев организации
- Создание репозитория для пользователя, прошедшего проверку подлинности
- Получение репозитория
- Обновление репозитория
- Удаление репозитория
- Сравнение двух фиксаций
- Список участников репозитория
- Список вилок
- Создание вилки
- Список языков репозитория
- Список меток репозитория
- Список команд репозитория
- Перенос репозитория
- Список общедоступных репозиториев
- Список репозиториев для пользователя, прошедшего проверку подлинности
- Список репозиториев для пользователя
- Создание репозитория с использованием шаблона репозитория
Деятельность репозитория
- Список звездочетов
- Список наблюдателей
- Список репозиториев, отмеченных пользователем
- Проверка того, помечен ли репозиторий звездочкой пользователем, прошедшим проверку подлинности
- Пометка репозитория звездочкой для пользователя, прошедшего проверку подлинности
- Снятие пометки звездочкой с репозитория для пользователя, прошедшего проверку подлинности
- Список репозиториев, просмотренных пользователем
Ветви репозитория
- Список ветвей
- Получение ветви
- Получение защиты ветвей
- Обновление защиты ветвей
- Удаление защиты ветвей
- Получение защиты ветви администратора
- Настройка защиты ветви администратора
- Удаление защиты ветви администратора
- Получение защиты проверки запросов на вытягивание
- Обновление защиты проверки запросов на вытягивание
- Удаление защиты проверки запросов на вытягивание
- Получение защиты сигнатуры фиксации
- Создание защиты сигнатуры фиксации
- Удаление защиты сигнатуры фиксации
- Получение защиты проверки состояния
- Обновление защиты проверки состояния
- Удаление защиты проверки состояния
- Получение всех контекстов проверки состояния
- Добавление контекстов проверки состояния
- Добавление контекстов проверки состояния
- Удаление контекстов проверки состояния
- Получение ограничений доступа
- Удаление ограничений доступа
- Список команд с доступом к защищенной ветви
- Добавление ограничений доступа для команды
- Настройка ограничения доступа для команды
- Удаление ограничения доступа для команды
- Список пользовательских ограничений защищенной ветви
- Добавление ограничений доступа пользователя
- Настройка ограничений доступа пользователя
- Удаление ограничений доступа пользователя
- Слияние ветви
Участники совместной работы репозитория
- Список участников совместной работы репозитория
- Проверка того, является ли пользователь участником совместной работы репозитория
- Добавление участника совместной работы репозитория
- Удаление участника совместной работы репозитория
- Получение разрешений репозитория для пользователя
Комментарии фиксации репозитория
- Список комментариев фиксации для репозитория
- Получение комментария фиксации
- Обновление комментария фиксации
- Удаление комментария фиксации
- Список комментариев фиксации
- Создание комментария фиксации
Фиксации репозитория
- Вывод списка фиксаций
- Получение фиксации
- Список ветвей для головной фиксации
- Список запросов на вытягивание, связанных с фиксацией
Сообщество репозитория
Содержимое репозитория
- Скачивание архива репозитория
- Получение содержимого репозитория
- Создание или обновление содержимого файла
- Удаление файла
- Получение README репозитория
- Получение лицензии на репозиторий
Сообщения о событиях репозитория
Перехватчики репозитория
- Список веб-перехватчиков репозитория
- Создание веб-перехватчика репозитория
- Получение веб-перехватчика репозитория
- Обновление веб-перехватчика репозитория
- Удаление веб-перехватчика репозитория
- Проверка связи с веб-перехватчиком репозитория
- Тестирование отправки веб-перехватчика-репозитория
Приглашения репозитория
- Список приглашений репозитория
- Обновление приглашений репозитория
- Удаление приглашения репозитория
- Список приглашений в репозиторий для пользователя, прошедшего проверку подлинности
- Принятие приглашения в репозиторий
- Отклонение приглашения в репозиторий
Ключи репозитория
- Список ключей развертывания
- Создание ключа развертывания
- Получение ключа развертывания
- Удаление ключа развертывания
Страницы репозитория
- Получение сайта GitHub Pages
- Создание сайта GitHub Pages
- Обновление информации о сайте GitHub Pages
- Удаление сайта GitHub Pages
- Список сборок GitHub Pages
- Запрос сборки GitHub Pages
- Получение сборки GitHub Pages
- Получение последней сборки страниц
Перехватчики предварительного получения репозитория
- Список перехватчиков предварительного получения для репозитория
- Получение перехватчика предварительного получения для репозитория
- Обновление принудительного использования перехватчика предварительного получения для репозитория
- Удаление принудительного использования перехватчика предварительного получения для репозитория
Выпуски репозитория
- Вывод списка выпусков
- Создание выпуска
- Получение выпуска
- Обновление выпуска
- Удаление выпуска
- Список ресурсов выпуска
- Получение ресурса выпуска
- Обновление ресурса выпуска
- Удаление ресурса выпуска
- Получение последней версии
- Получение выпуска по имени метки
Статистика репозитория
- Получение еженедельной активности фиксации
- Получение активности фиксации за последний год
- Получение всех действий по фиксации участников
- Получение еженедельного количества фиксаций
- Получение почасового количества фиксаций за каждый день
Root
- Корневая конечная точка
- Эмодзи
- Получение сведений о состоянии ограничения скорости для пользователя, прошедшего проверку подлинности
Поиск
Состояния
- Получение сведений о комбинированном состоянии для конкретной ссылки
- Список состояний фиксации для справки
- Создание состояния фиксации
Обсуждения в команде
- Список обсуждений
- Создание обсуждения
- Получение обсуждения
- Обновление обсуждения
- Удаление обсуждения
- Список комментариев к обсуждениям
- Создание комментария к обсуждению
- Получение комментария к обсуждению
- Обновление комментария к обсуждению
- Удаление комментария к обсуждению
Разделы
Электронные письма для пользователей
- Список адресов электронной почты для пользователя, прошедшего проверку подлинности
- Добавление адресов электронной почты
- Удаление адресов электронной почты
- Список общедоступных адресов электронной почты для пользователя, прошедшего проверку подлинности
Подписчики пользователя
- Список подписчиков пользователя
- Список людей, на которых подписан пользователь
- Проверка того, подписан ли на человека пользователь, прошедший проверку подлинности
- Подписка на пользователя
- Отмена подписки на пользователя
- Проверка того, подписан ли пользователь на другого пользователя
Ключи GPG пользователя
- Список ключей GPG для пользователя, прошедшего проверку подлинности
- Создание ключа GPG для пользователя, прошедшего проверку подлинности
- Получение ключа GPG для пользователя, прошедшего проверку подлинности
- Удаление ключа GPG для пользователя, прошедшего проверку подлинности
- Список ключей GPG для пользователя
Открытые ключи пользователя
- Список открытых ключей SSH для пользователя, прошедшего проверку подлинности
- Создание открытых ключей SSH для пользователя, прошедшего проверку подлинности
- Получение открытых ключей SSH для пользователя, прошедшего проверку подлинности
- Удаление открытых ключей SSH для пользователя, прошедшего проверку подлинности
- Список открытых ключей для пользователя
Пользователи
- Получение пользователя, прошедшего проверку подлинности
- Список установок приложений, доступных для маркера доступа пользователя
- Список пользователей
- Получение пользователя