Переход с OAuth Apps на GitHub Apps

В этой статье приведены рекомендации для существующих интеграторов, которые позволяют выполнять переход с OAuth Apps на GitHub Apps.

Причины перехода на GitHub Apps

GitHub Apps — это официально рекомендуемый способ интеграции с GitHub, так как это решение предлагает множество преимуществ по сравнению с чистой интеграцией на основе OAuth:

• Избирательные разрешения предназначены для предоставления GitHub Apps доступа к определенной информации, что позволяет более широко использовать приложение людьми и организациями с политиками безопасности по сравнению с OAuth Apps без ограничивающих разрешений.
• Кратковременные токены обеспечивают более безопасный метод аутентификации по сравнению с токенами OAuth. Срок действия токена OAuth не истекает до тех пор, пока лицо, которое авторизовало экземпляр OAuth Apps, не отзовет токен. В GitHub Apps используются токены с коротким сроком действия, что значительно сокращает время использования скомпрометированных токенов.
• Встроенные централизованные веб-перехватчики получают события для всех репозиториев и организаций, к которым может получить доступ приложение. И наоборот, в OAuth Apps требуется настройка веб-перехватчика для каждого репозитория и организации, доступных пользователю.
• Учетные записи ботов не занимают рабочие места GitHub AE и остаются установленными, даже если пользователь, изначально установивший приложение, покидает организацию.
• Встроенная поддержка OAuth по-прежнему доступна для приложений GitHub, использующих конечные точки с маркером доступа пользователя.
• Выделенные ограничения скорости API для учетных записей ботов масштабируются с учетом вашей интеграции.
• Владельцы репозиториев могут устанавливать GitHub Apps в репозиториях организации. Если конфигурация GitHub Apps имеет разрешения, запрашивающие ресурсы организации, владелец организации должен одобрить установку.
• Поддержка сообщества с открытым кодом доступна через библиотеки Octokit и другие платформы, такие как Probot.
• Интеграторы, создающие GitHub Apps, имеют возможность использовать более ранний доступ к API.

Преобразование OAuth Apps в GitHub Apps

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

1. Просмотр доступных конечных точек API для GitHub Apps
2. Проектирование для ограничения скорости API
3. Регистрация нового приложения в GitHub Apps
4. Определение необходимых разрешений для приложения
5. Подписка на веб-перехватчики
6. Знакомство с разными методами проверки подлинности
7. Предложение пользователям установить ваш экземпляр GitHub Apps
8. Удаление ненужных перехватчиков репозитория
9. Предложение пользователям отозвать доступ к экземпляру OAuth Apps
10. Удаление экземпляра OAuth Apps

Просмотр доступных конечных точек API для GitHub Apps

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

Рекомендуется как можно раньше просмотреть список конечных точек API. Сообщите в службу поддержки, если вам нужна конечная точка, которая еще не включена для GitHub Apps.

Проектирование для ограничения скорости API

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

Регистрация нового приложения в GitHub Apps

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

Определение необходимых разрешений для приложения

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

В параметрах GitHub Apps можно указать, требуется ли вашему приложению доступ к No Access, Read-only или Read & Write для каждого типа разрешений. Избирательные разрешения позволяют вашему приложению получать целевой доступ к набору необходимых вам данных. Мы рекомендуем указать минимально возможный набор разрешений, обеспечивающий желаемую функциональность.

Подписка на веб-перехватчики

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

Знакомство с разными методами проверки подлинности

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

• JSON Web Token (JWT) выполняет проверку подлинности как экземпляр GitHub Apps. Например, можно выполнить проверку подлинности с помощью JWT, чтобы получить сведения об установке приложения или обменять JWT на маркер доступа установки.
• Маркер доступа к установке проходит проверку подлинности как определенная установка приложения GitHub. Например, вы можете выполнить проверку подлинности с помощью маркера доступа установки, чтобы открыть проблему или отправить отзыв по запросу на вытягивание.
• Маркер доступа пользователя может пройти проверку подлинности в качестве пользователя приложения GitHub. Например, вы можете использовать маркер доступа OAuth для проверки подлинности пользователя, когда экземпляру GitHub Apps необходимо подтвердить личность пользователя или действовать от его имени.

Наиболее распространенным сценарием является проверка подлинности в качестве конкретной установки с помощью маркера доступа установки.

Предложение пользователям установить ваш экземпляр GitHub Apps

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

Параметры запроса

Имя	Описание
suggested_target_id	Обязательный. Идентификатор пользователя или организации, устанавливающей GitHub Apps.
repository_ids[]	Массив идентификаторов репозитория. Если этот параметр опущен, мы выбираем все репозитории. Максимальное число репозиториев, которые можно предварительно выбрать, — 100.

Пример URL-адреса

https://github.com/apps/YOUR_APP_NAME/installations/new/permissions?suggested_target_id=ID_OF_USER_OR_ORG&repository_ids[]=REPO_A_ID&repository_ids[]=REPO_B_ID

Вам нужно будет изменить YOUR_APP_NAME на имя вашего экземпляра GitHub Apps, ID_OF_USER_OR_ORG на идентификатор вашего целевого пользователя или организации и включить до 100 идентификаторов репозитория (REPO_A_ID и REPO_B_ID). Чтобы получить список репозиториев, к которым у вашего экземпляра OAuth Apps есть доступ, используйте конечные точки Перечисление репозиториев для аутентифицированных пользователей и Перечисление репозиториев организации.

Удаление ненужных перехватчиков репозитория

Когда вы установите экземпляр GitHub Apps в репозитории, удалите ненужные веб-перехватчики, созданные устаревшим экземпляром OAuth Apps. Если оба приложения будут установлены в репозитории, они могут дублировать функции для пользователя. Чтобы удалить веб-перехватчики, можно прослушивать веб-перехватчик installation_repositories с repositories_added помощью действия и удалить веб-перехватчик репозитория в этих репозиториях, созданных экземпляром OAuth Apps.

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

С расширением базы установки GitHub Apps рекомендуется поощрять пользователей отменять доступ к устаревшей интеграции OAuth. Дополнительные сведения см. в разделе Авторизация приложений OAuth.

Удаление экземпляра OAuth Apps

Чтобы избежать злоупотребления учетными данными экземпляра OAuth Apps, рекомендуется удалить этот экземпляр OAuth Apps. Это действие также отменит все оставшиеся разрешения экземпляра OAuth Apps. Дополнительные сведения см. в разделе Удаление приложения OAuth.