Skip to main content

Проверка подлинности с помощью приложений GitHub

Вы можете проверить подлинность приложения GitHub App или установки.

Проверка подлинности от имени GitHub App

Для вызовов API требуется server-to-server проверка подлинности в качестве GitHub App, которая позволяет GitHub App выполнять несколько действий:

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

Для проверки подлинности от имени GitHub App создайте закрытый ключ в формате PEM и скачайте его на локальный компьютер. Этот ключ используется для подписывания веб-маркера JSON (JWT) и его кодирования с помощью алгоритма RS256 . GitHub AE проверяет удостоверение приложения, проверяя маркер с помощью сохраненного открытого ключа приложения. Вы обменяете этот JWT на маркер установки, используемый для проверки подлинности приложения в качестве конкретной установки.

Перечисление установок для приложения

Чтобы получить список установок для приложения, включите JWT в заголовок авторизации в запросе API к GET /app/installations. Дополнительные сведения о создании JWT см. в разделе Полезные данные JWT.

$ curl -i -X GET \
-H "Authorization: Bearer YOUR_JWT" \
-H "Accept: application/vnd.github+json" \
https://HOSTNAME/api/v3/app/installations

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

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

Проверка подлинности в качестве установки позволяет приложению получить доступ к этой организации или пользователю через API, а также через общедоступные ресурсы в GitHub AE. Для проверки подлинности в качестве установки необходимо использовать маркер доступа к установке, который можно получить, отправив JWT в GitHub AE для подтверждения личности приложения. Убедитесь, что вы уже установили приложение GitHub по крайней мере в одной организации или учетной записи пользователя; невозможно создать маркер установки без установки. Дополнительные сведения см. в разделе Installing GitHub Apps (Установка приложений GitHub).

По умолчанию маркеры доступа к установке ограничены всеми репозиториями, к которым был предоставлен доступ для установки. Можно дополнительно ограничить область маркера доступа к установке определенными репозиториями с помощью repository_ids параметра . Маркеры доступа к установке имеют разрешения, настроенные GitHub App, и, как и доступ к репозиторию, также могут быть ограничены с помощью permissions параметра . Дополнительные сведения см. в документации по созданию маркера доступа установки для конечной точки приложения . Срок действия всех маркеров установки истекает через 1 час.

Чтобы создать маркер доступа к установке, включите JWT в заголовок Authorization в запросе API, заменив :installation_id на .id Дополнительные сведения о создании JWT см. в разделе Полезные данные JWT.

$ curl -i -X POST \
-H "Authorization: Bearer YOUR_JWT" \
-H "Accept: application/vnd.github+json" \
https://HOSTNAME/api/v3/app/installations/:installation_id/access_tokens

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

Для проверки подлинности с помощью маркера доступа установки включите его в заголовок авторизации в запросе API. Замените YOUR_INSTALLATION_ACCESS_TOKEN маркером доступа установки:

$ curl -i \
-H "Authorization: Bearer YOUR_INSTALLATION_ACCESS_TOKEN" \
-H "Accept: application/vnd.github+json" \
https://HOSTNAME/api/v3/installation/repositories

Примечание. В большинстве случаев передать маркер с помощью Authorization: Bearer или Authorization: token. Однако при передаче веб-токена JSON (JWT) необходимо использовать Authorization: Bearer.

Доступ к конечным точкам API от имени установки

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

Список конечных точек, связанных с установками, см. в разделе Installations (Установки).

Доступ к Git по протоколу HTTP от имени установки

Установки с разрешениями для репозитория contents могут использовать маркеры доступа для установки, чтобы выполнять проверку подлинности при доступе к Git. Используйте маркер доступа для установки в качестве пароля HTTP:

git clone https://x-access-token:<token>@github.com/owner/repo.git

Создание веб-токена JSON (JWT)

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

УтверждениеЗначениеСведения
iatВыдано вВремя создания JWT. Чтобы защититься от смещения часов, рекомендуется задать 60 секунд в прошлом.
expСрок действия истекаетВремя окончания срока действия JWT, по истечении которого его нельзя использовать для запроса маркера установки. Значение exp должно быть не более 10 минут в будущем.
issИздательИдентификатор приложения, используемый для поиска нужного открытого ключа для проверки подписи JWT.

Маркеры должны быть подписаны с помощью алгоритма RS256 с соответствующим alg утверждением RS256.

Использование Ruby

Ниже приведен скрипт Ruby, который можно использовать для создания JWT. Обратите внимание, что перед его использованием необходимо выполнить gem install jwt. Значения YOUR_PATH_TO_PEM и YOUR_APP_ID нужно заменить. Обязательно заключите значения в двойные кавычки.

require 'openssl'
require 'jwt'  # https://rubygems.org/gems/jwt

# Private key contents
private_pem = File.read("YOUR_PATH_TO_PEM")
private_key = OpenSSL::PKey::RSA.new(private_pem)

# Generate the JWT
payload = {
  # issued at time, 60 seconds in the past to allow for clock drift
  iat: Time.now.to_i - 60,
  # JWT expiration time (10 minute maximum)
  exp: Time.now.to_i + (10 * 60),
  # GitHub App's identifier
  iss: "YOUR_APP_ID"
}

jwt = JWT.encode(payload, private_key, "RS256")
puts jwt

Использование Python

Ниже приведен аналогичный скрипт для создания JWT в Python. Обратите внимание, что для использования этого скрипта вам придется использовать pip install jwt . Этот скрипт запросит расположение PEM-файла и идентификатор приложения, или вы можете передать их в качестве встроенных аргументов при выполнении скрипта.

python
#!/usr/bin/env python3
import jwt
import time 
import sys

# Get PEM file path
if len(sys.argv) > 1:
    pem = sys.argv[1]
else:
    pem = input("Enter path of private PEM file: ")    

# Get the App ID
if len(sys.argv) > 2:
    app_id = sys.argv[2]
else:
    app_id = input("Enter your APP ID: ") 

# Open PEM
with open(pem, 'rb') as pem_file:
    signing_key = jwt.jwk_from_pem(pem_file.read())
    
payload = {
    # Issued at time
    'iat': int(time.time()),
    # JWT expiration time (10 minutes maximum)
    'exp': int(time.time()) + 600, 
    # GitHub App's identifier
    'iss': app_id 
}
    
# Create JWT
jwt_instance = jwt.JWT()
encoded_jwt = jwt_instance.encode(payload, signing_key, alg='RS256')
     
print(f"JWT:  ", encoded_jwt)

Используйте идентификатор GitHub App (YOUR_APP_ID) в качестве значения для утверждения JWT iss (издатель). Идентификатор GitHub App можно получить сразу после создания приложения при начальной проверке связи с веб-перехватчиком или в любое другое время на странице параметров приложения в пользовательском интерфейсе GitHub.com.

После создания JWT поместите его в параметр Header запроса к API:

$ curl -i -H "Authorization: Bearer YOUR_JWT" -H "Accept: application/vnd.github+json" https://HOSTNAME/api/v3/app

YOUR_JWT — это значение, которое нужно заменить.

В приведенных выше примерах используется максимальное время окончания срока действия в 10 минут, после чего API начнет возвращать ошибку 401 :

{
  "message": "'Expiration' claim ('exp') must be a numeric value representing the future time at which the assertion expires.",
  "documentation_url": "https://docs.github.com/github-ae@latest/rest"
}

После истечения срока действия потребуется создать новый JWT.

Доступ к конечным точкам API от имени GitHub App

Список конечных точек REST API, которые можно использовать для получения общих сведений о GitHub App, см. в разделе GitHub Apps (Приложения GitHub).

Создание закрытого ключа

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

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

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

  1. В правом верхнем углу любой страницы щелкните фотографию профиля, а затем выберите Параметры.

    Значок "Настройки" на панели пользователя

  2. На левой боковой панели щелкните Developer settings (Параметры разработчика). Параметры разработчика 1. На левой боковой панели щелкните Приложения GitHub. Раздел "Приложения GitHub" 1. Справа от GitHub App, которые нужно изменить, щелкните Изменить. Выбор приложения

  3. В разделе "Закрытые ключи" щелкните Создать закрытый ключ. Создание закрытого ключа

  4. Вы увидите скачанный на компьютер закрытый ключ в формате PEM. Не забудьте сохранить этот файл, поскольку GitHub хранит только открытую часть ключа.

Примечание. Если вы используете библиотеку, для которой требуется определенный формат файлов, скачанный файл PEM будет иметь формат PKCS#1 RSAPrivateKey.

Проверка закрытых ключей

GitHub AE создает отпечаток для каждой пары закрытого и открытого ключей с помощью хэш-функции SHA-256. Вы можете проверить, соответствует ли закрытый ключ открытому ключу, хранящемуся в GitHub AE, создав отпечаток закрытого ключа и сравнив его с отпечатком в GitHub AE.

Для проверки закрытого ключа выполните следующее.

  1. Найдите отпечаток для проверяемой пары закрытого и открытого ключей в разделе "Закрытые ключи" на странице параметров разработчика GitHub App. Дополнительные сведения см. в разделе Создание закрытого ключа. Отпечаток закрытого ключа
  2. Создайте отпечаток закрытого ключа (PEM) локально с помощью следующей команды:
    $ openssl rsa -in PATH_TO_PEM_FILE -pubout -outform DER | openssl sha256 -binary | openssl base64
  3. Сравните результаты локально созданного отпечатка с отпечатком, который отображается в GitHub AE.

Удаление закрытых ключей

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