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

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

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

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

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

curl --request GET \
--url "https://api.github.com/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

Если вы используете personal access token (classic) для доступа к организации, которая применяет единый вход SAML для проверки подлинности, вам потребуется авторизовать маркер после создания. Fine-grained personal access tokens авторизованы во время создания маркера перед предоставлением доступа к организации. Дополнительные сведения см. в разделе Авторизация личного токена доступа для использования с документами единого входа SAML.

Если вы не авторизуете personal access token (classic) для единого входа SAML, прежде чем пытаться использовать его для доступа к одной организации, которая применяет единый вход SAML, может появиться 404 Not Found сообщение об ошибке или ошибке 403 Forbidden . Если появится сообщение об ошибке 403 Forbidden , X-GitHub-SSO заголовок будет содержать URL-адрес, который можно выполнить для авторизации маркера. Срок действия URL-адреса истекает через час.

Если вы не авторизуете personal access token (classic) для единого входа SAML, прежде чем пытаться использовать его для доступа к нескольким организациям, API не вернет результаты от организаций, которым требуется единый вход SAML, и X-GitHub-SSO заголовок будет указывать идентификатор организаций, которым требуется авторизация единого входа SAML для вашего personal access token (classic). Например: X-GitHub-SSO: partial-results; organizations=21955855,20582480.

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

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

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

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

Маркеры доступа, созданные приложениями, автоматически авторизованы для единого входа SAML.

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

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

Например:

curl --request POST \
--url "https://api.github.com/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.com.{ % 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.com.{ % endif %}

YAML

jobs:
  use_api:
    runs-on: ubuntu-latest
    permissions: {}
    steps:
      - env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          curl --request GET \
          --url "https://api.github.com/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 "https://api.github.com/PATH" \
          --header "Authorization: Bearer $GH_TOKEN"

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

В этой статье