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

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

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

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

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

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

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

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

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

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

Проверка подлинности в качестве установки позволяет приложению получить доступ к этой организации или пользователю через API, а также к общедоступным ресурсам в GitHub Enterprise Server. Чтобы пройти проверку подлинности в качестве установки, необходимо использовать маркер доступа установки, который вы получаете, отправив JWT в GitHub Enterprise Server для подтверждения удостоверения приложения. Убедитесь, что приложение 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" \
http(s)://HOSTNAME/api/v3/app/installations/:installation_id/access_tokens

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

Чтобы пройти проверку подлинности с помощью маркера доступа установки, включите его в заголовок Authorization в запросе API. Замените YOUR_INSTALLATION_ACCESS_TOKEN маркером доступа установки:

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

Доступ к конечным точкам 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, используемый для проверки подлинности приложения, состоит из нескольких утверждений, а также подписи, которая используется для проверки подлинности приложения. Эти утверждения:

Маркеры должны быть подписаны с помощью алгоритма 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-файла и идентификатор приложения или вы можете передать их в качестве встроенных аргументов при выполнении скрипта.

#!/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" http(s)://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/enterprise/3.6/rest"
}

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

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

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

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

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

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

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

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

   

2. На левой боковой панели щелкните Параметры разработчика.

3. На левой боковой панели щелкните Приложения GitHub. 1. Справа от GitHub App, которые нужно изменить, щелкните Изменить.

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

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

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

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

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

1. Найдите отпечаток для проверяемой пары закрытого и открытого ключей в разделе "Закрытые ключи" на странице параметров разработчика GitHub App. Дополнительные сведения см. в разделе Создание закрытого ключа.
2. Создайте отпечаток закрытого ключа (PEM) локально с помощью следующей команды:

   $ openssl rsa -in PATH_TO_PEM_FILE -pubout -outform DER | openssl sha256 -binary | openssl base64

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

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

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