Сведения о веб-маркерах JSON (JWT)
Чтобы пройти проверку подлинности в качестве приложения или создать маркер доступа к установке, необходимо создать веб-токен JSON (JWT). Если для конечной точки REST API требуется JWT, в документации по этой конечной точке будет указано, что для доступа к конечной точке необходимо использовать JWT.
JWT должен быть подписан с помощью алгоритма RS256
и содержать следующие утверждения.
Утверждение | Значение | Сведения |
---|---|---|
iat | Выдано в | Время создания JWT. Чтобы защититься от смещения часов, рекомендуется задать 60 секунд в прошлом и убедиться, что дата и время сервера заданы точно (например, с помощью протокола сетевого времени). |
exp | Срок действия истекает | Время окончания срока действия JWT, по истечении которого его нельзя использовать для запроса маркера установки. Время должно быть не более 10 минут в будущем. |
iss | Издатель | Идентификатор GitHub App. Это значение используется для поиска нужного открытого ключа для проверки подписи JWT. Идентификатор приложения можно найти с помощью конечной GET /app точки REST API. Дополнительные сведения см. в разделе Приложения в документации по REST API. |
alg | Алгоритм кода проверки подлинности сообщения | Это должно быть так, RS256 что JWT должен быть подписан с помощью алгоритма RS256 . |
Чтобы использовать JWT, передайте его в Authorization
заголовок запроса API. Пример:
curl --request GET \
--url "http(s)://HOSTNAME/api/v3/app" \
--header "Accept: application/vnd.github+json" \
--header "Authorization: Bearer YOUR_JWT"
В большинстве случаев передать маркер с помощью Authorization: Bearer
или Authorization: token
. Однако при передаче веб-токена JSON (JWT) необходимо использовать Authorization: Bearer
.
Создание веб-токена JSON (JWT)
Большинство языков программирования имеют пакет, который может создать JWT. Во всех случаях необходимо иметь закрытый ключ и идентификатор GitHub App. Дополнительные сведения о создании закрытого ключа см. в разделе Управление закрытыми ключами для приложений GitHub. Идентификатор приложения можно найти с помощью конечной GET /app
точки REST API. Дополнительные сведения см. в разделе Приложения в документации по REST API.
Примечание. Вместо создания JWT можно использовать пакеты SDK Octokit для GitHub для проверки подлинности в качестве приложения. Пакет SDK позаботится о создании JWT и повторно создаст JWT после истечения срока действия маркера. Дополнительные сведения см. в разделе Создание скриптов с помощью REST API и JavaScript.
Пример. Использование Ruby для создания JWT
Примечание: Чтобы использовать этот скрипт, необходимо выполнить команду gem install jwt
, чтобы установить jwt
пакет.
В следующем примере замените YOUR_PATH_TO_PEM
на путь к файлу, в котором хранится закрытый ключ. Замените YOUR_APP_ID
идентификатором приложения. Обязательно заключите значения для 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
Пример. Создание JWT с помощью Python
Примечание: Чтобы использовать этот скрипт, необходимо выполнить команду pip install jwt
, чтобы установить jwt
пакет.
#!/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}")
Этот скрипт запросит путь к файлу, в котором хранится закрытый ключ, и идентификатор приложения. Кроме того, эти значения можно передать в виде встроенных аргументов при выполнении скрипта.