Проверка подлинности в REST API

Об аутентификации

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

Чтобы выполнить проверку подлинности запроса, необходимо предоставить маркер проверки подлинности с необходимыми областями или разрешениями. Вы можете создать маркер personal access token, создать маркер с помощью GitHub Appили использовать встроенный GITHUB_TOKEN рабочий процесс GitHub Actions.

После создания маркера можно выполнить проверку подлинности запроса, отправив маркер в заголовке Authorization запроса. Например, в следующем запросе замените YOUR-TOKEN ссылку на токен:

curl --request GET \
--url "http(s)://HOSTNAME/api/v3/octocat" \
--header "Authorization: Bearer YOUR-TOKEN" \
--header "X-GitHub-Api-Version: 2022-11-28"

Note

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

Если вы пытаетесь использовать конечную точку REST API без маркера или маркера, имеющего недостаточно разрешений, вы получите 404 Not Found или 403 Forbidden ответ. Проверка подлинности с недопустимыми учетными данными изначально возвращает 401 Unauthorized ответ.

После обнаружения нескольких запросов с недопустимыми учетными данными в течение короткого периода API временно отклоняет все попытки проверки подлинности для этого пользователя (включая те, с допустимыми учетными данными) с ответом 403 Forbidden . Дополнительные сведения см. в разделе Ограничения скорости для REST API.

Проверка подлинности с помощью personal access token

Если вы хотите использовать REST API GitHub для личного использования, можно создать personal access token. По возможности GitHub рекомендует использовать fine-grained personal access token вместо personal access token (classic). Дополнительные сведения о создании personal access tokenсм. в разделе Управление личными маркерами доступа.

Если вы используете fine-grained personal access token, для доступа к каждой конечной точке REST API требуются определенные разрешения для fine-grained personal access token. Справочный документ REST API для каждой конечной точки указывает, работает ли конечная точка с fine-grained personal access tokens и указывает, какие разрешения необходимы для использования маркера. Для некоторых конечных точек может потребоваться несколько разрешений, а для некоторых конечных точек может потребоваться одно из нескольких разрешений. Общие сведения о том, к каким конечным точкам REST API предоставляет доступ fine-grained personal access token с каждым разрешением, см. в разделе Разрешения, необходимые для подробных персональных маркеров доступа.

Если вы используете personal access token (classic), для доступа к каждой конечной точке REST API требуются определенные области. Общие рекомендации по выбору областей см. в разделе Области для приложений OAuth.

Personal access tokens и единого входа SAML

Проверка подлинности с помощью маркера, созданного приложением

Если вы хотите использовать API для организации или от имени другого пользователя, GitHub рекомендует использовать GitHub App. Дополнительные сведения см. в разделе Сведения о проверке подлинности с помощью приложения GitHub.

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

Вы также можете создать маркер OAuth с помощью OAuth app для доступа к REST API. Однако GitHub рекомендует использовать вместо этого GitHub App . GitHub Apps позволяют более контролировать доступ и разрешение, которое имеет приложение.

Использование обычной аутентификации

Некоторые конечные точки REST API для GitHub Apps и OAuth apps требуют использования базовой проверки подлинности для доступа к конечной точке. Идентификатор клиента приложения будет использоваться в качестве имени пользователя и секрета клиента приложения в качестве пароля.

Например:

curl --request POST \
--url "http(s)://HOSTNAME/api/v3/applications/YOUR_CLIENT_ID/token" \
--user "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
--header "Accept: application/vnd.github+json" \
--header "X-GitHub-Api-Version: 2022-11-28" \
--data '{
  "access_token": "ACCESS_TOKEN_TO_CHECK"
}'

Идентификатор клиента и секрет клиента связаны с приложением, а не с владельцем приложения или пользователем, авторизованным приложением. Они используются для выполнения операций от имени приложения, например создания маркеров доступа.

Если вы являетесь владельцем GitHub App или OAuth app, или если вы являетесь менеджером приложений для GitHub App, вы можете найти идентификатор клиента и создать секрет клиента на странице параметров приложения. Чтобы перейти на страницу параметров приложения, выполните следующие действия.

В правом верхнем углу любой страницы на GitHubщелкните фото профиля.
Перейдите к настройкам учетной записи.
- Для приложения, принадлежащих личная учетная запись, нажмите кнопку "Параметры".
- Для приложения, принадлежащих организации:
  1. Щелкните Your organizations (Ваши организации).
  2. Справа от организации нажмите кнопку "Параметры".
На левой боковой панели щелкните Параметры разработчика.
На левой боковой панели щелкните GitHub Apps или OAuth apps.
Для GitHub Appsсправа от GitHub App нажмите кнопку "Изменить". Для OAuth appsщелкните приложение, к которому требуется получить доступ.
Рядом с идентификатором клиента вы увидите идентификатор клиента для приложения.
Рядом с секретами клиента нажмите кнопку "Создать новый секрет клиента", чтобы создать секрет клиента для приложения.

Проверка подлинности в рабочем процессе GitHub Actions

Если вы хотите использовать API в рабочем процессе GitHub Actions, GitHub рекомендует выполнять проверку подлинности с помощью встроенного GITHUB_TOKEN вместо создания маркера. Вы можете предоставить разрешения для GITHUB_TOKEN с помощью ключа permissions. Дополнительные сведения см. в разделе Автоматическая проверка подлинности токенов.

Если это невозможно, вы можете сохранить маркер в виде секрета и использовать имя секрета в рабочем процессе GitHub Actions . Дополнительные сведения о секретах см. в разделе Использование секретов в GitHub Actions.

Проверка подлинности в рабочем процессе GitHub Actions с помощью GitHub CLI

Чтобы выполнить прошедший проверку подлинности запрос к API в рабочем процессе GitHub Actions с помощью GitHub CLI, можно сохранить значение GITHUB_TOKEN в переменной среды и использовать run ключевое слово для выполнения подкоманда GitHub CLI api . Дополнительные сведения о ключевом слове run см. в разделе Синтаксис рабочего процесса для GitHub Actions.

В следующем примере рабочего процесса замените PATH путь к конечной точке. Дополнительные сведения о пути см. в разделе Начало работы с REST API.{ %ifversion ghes %} Замените HOSTNAME именем ваш экземпляр GitHub Enterprise Server.{ % endif %}

jobs:
  use_api:
    runs-on: ubuntu-latest
    permissions: {}
    steps:
      - env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          gh api /PATH

Проверка подлинности в рабочем процессе GitHub Actions с помощью `curl`

Чтобы выполнить прошедший проверку подлинности запрос к API в рабочем процессе GitHub Actions с помощью curl, можно сохранить значение GITHUB_TOKEN в качестве переменной среды и использовать run ключевое слово для выполнения curl запроса к API. Дополнительные сведения о ключевом слове run см. в разделе Синтаксис рабочего процесса для GitHub Actions.

В следующем примере рабочего процесса замените PATH путь к конечной точке. Дополнительные сведения о пути см. в разделе Начало работы с REST API.{ %ifversion ghes %} Замените HOSTNAME именем ваш экземпляр GitHub Enterprise Server.{ % endif %}

YAML

jobs:
  use_api:
    runs-on: ubuntu-latest
    permissions: {}
    steps:
      - env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          curl --request GET \
          --url "http(s)://HOSTNAME/api/v3/PATH" \
          --header "Authorization: Bearer $GH_TOKEN"

jobs:
  use_api:
    runs-on: ubuntu-latest
    permissions: {}
    steps:
      - env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          curl --request GET \
          --url "http(s)://HOSTNAME/api/v3/PATH" \
          --header "Authorization: Bearer $GH_TOKEN"

Проверка подлинности в рабочем процессе GitHub Actions с помощью JavaScript

Пример проверки подлинности в рабочем процессе GitHub Actions с помощью JavaScript см. в разделе Скриптирование с помощью REST API и JavaScript.

Проверка подлинности с помощью имени пользователя и пароля

GitHub рекомендует использовать маркер для проверки подлинности в REST API вместо пароля. У вас есть больше контроля над тем, что может сделать маркер, и вы можете отозвать токен в любое время. Однако вы также можете пройти проверку подлинности в REST API с помощью имени пользователя и пароля для базовой проверки подлинности. Для этого вы передайте имя пользователя и пароль с параметром --user :

curl --request GET \
--url "http(s)://HOSTNAME/api/v3/user" \
--user USERNAME:PASSWORD \
--header "X-GitHub-Api-Version: 2022-11-28"