REST API에 인증

인증 정보

인증된 경우 많은 REST API 엔드포인트에 인증이 필요하거나 추가 정보를 반환해야 합니다. 또한 인증 시 시간당 더 많은 요청을 수행할 수 있습니다.

요청을 인증하려면 필요한 범위 또는 권한이 포함된 인증 토큰을 제공해야 합니다. 토큰을 가져오는 몇 가지 방법은 다음과 같습니다. personal access token을(를) 만들거나, GitHub App을(를) 사용하여 토큰을 생성하거나, GitHub Actions 워크플로에서 기본 제공 GITHUB_TOKEN을 사용할 수 있습니다.

토큰을 생성한 후 요청의 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"

참고: 대부분의 경우 Authorization: Bearer 또는 Authorization: token을 사용하여 전달할 수 있습니다. 그러나 JWT(JSON 웹 토큰)를 전달하는 경우 Authorization: Bearer를 사용해야 합니다.

토큰 없이 또는 권한이 부족한 토큰으로 REST API 엔드포인트를 사용하려고 하면 404 Not Found 또는 403 Forbidden 응답을 받게 됩니다. 잘못된 자격 증명으로 인증하면 401 Unauthorized 응답이 반환됩니다.

짧은 기간 내에 잘못된 자격 증명을 사용한 여러 요청을 검색하면 API는 403 Forbidden 응답을 나타내며 해당 사용자에 대한 모든 인증 시도(유효한 자격 증명을 사용한 시도 포함)를 일시적으로 거부합니다. 자세한 내용은 "REST API에 대한 트래픽률 제한"을(를) 참조하세요.

personal access token을(를) 사용하여 인증

개인용으로 GitHub REST API를 사용하려는 경우 personal access token를 만들 수 있습니다. 가능하면 GitHub에서는 personal access token (classic) 대신 fine-grained personal access token을(를) 사용하는 것이 좋습니다. personal access token을(를) 만드는 방법에 대한 자세한 내용은 "개인용 액세스 토큰 관리"을 참조하세요.

fine-grained personal access token을(를) 사용하는 경우 각 REST API 엔드포인트에 액세스하려면 fine-grained personal access token에 특정 권한이 필요합니다. 각 엔드포인트에 대한 REST API 참조 문서는 엔드포인트가 fine-grained personal access tokens에서 작동하는지 여부 및 토큰이 엔드포인트를 사용하기 위해 필요한 권한을 명시합니다. 일부 엔드포인트에는 여러 권한이 필요할 수 있으며 일부 엔드포인트에는 여러 권한 중 하나가 필요할 수 있습니다. 각 권한으로 fine-grained personal access token에서 액세스할 수 있는 REST API 엔드포인트에 대한 개요는 "세분화된 개인용 액세스 토큰에 필요한 권한"을 참조하세요.

personal access token (classic)을(를) 사용하는 경우 각 REST API 엔드포인트에 액세스하려면 특정 범위가 필요합니다. 선택할 범위에 대한 일반적인 지침은 "OAuth 앱에 대한 범위"을 참조하세요.

Personal access tokens 및 SAML SSO

personal access token (classic)을(를) 사용하여 인증을 위해 SAML SSO(Single Sign-On)를 적용하는 조직에 액세스하는 경우 생성 후 토큰에 권한을 부여해야 합니다. Fine-grained personal access token는 조직에 대한 액세스 권한이 부여되기 전에 토큰을 만드는 동안 권한이 부여됩니다. 자세한 내용은 "SAML Single Sign-On에 사용할 개인용 액세스 토큰 권한 부여"을(를) 참조하세요.

SAML SSO를 적용하는 단일 조직에 액세스하기 전에 SAML SSO에 대해 personal access token (classic)에 권한을 부여하지 않으면 404 Not Found 또는 403 Forbidden 오류가 발생할 수 있습니다. 403 Forbidden 오류가 발생하면 X-GitHub-SSO 머리글에 토큰에 권한을 부여하기 위해 따라갈 수 있는 URL이 포함됩니다. URL은 1시간 후에 만료됩니다.

여러 조직에 액세스하는 데 사용하기 전에 SAML SSO에 대해 personal access token (classic)에 권한을 부여하지 않으면 API가 SAML SSO가 필요한 조직의 결과를 반환하지 않으며, X-GitHub-SSO 머리글에 personal access token (classic)의 SAML SSO 권한 부여가 필요한 조직의 ID가 표시됩니다. 예: X-GitHub-SSO: partial-results; organizations=21955855,20582480

앱에서 생성한 토큰으로 인증

조직 또는 다른 사용자를 대신하여 API를 사용하려는 경우 GitHub에서 GitHub App을(를) 사용하는 것이 좋습니다. 자세한 내용은 "GitHub 앱을 사용한 인증 정보"을(를) 참조하세요.

각 엔드포인트에 대한 REST API 참조 문서는 엔드포인트가 GitHub Apps에서 작동하는지 여부 및 앱이 엔드포인트를 사용하기 위해 필요한 권한을 명시합니다. 일부 엔드포인트에는 여러 권한이 필요할 수 있으며 일부 엔드포인트에는 여러 권한 중 하나가 필요할 수 있습니다. GitHub App에서 각 권한으로 액세스할 수 있는 REST API 엔드포인트에 대한 자세한 내용은 “GitHub 앱에 필요한 권한”을 참조하세요.

OAuth app(으)로 OAuth 토큰을 만들어 REST API에 액세스할 수도 있습니다. 그러나 GitHub에서는 대신 GitHub App을(를) 사용하는 것을 권장합니다. GitHub Apps을(를) 사용하면 앱에 있는 액세스 및 권한을 더 많이 제어할 수 있습니다.

앱에서 만든 액세스 토큰은 SAML SSO에 대해 자동으로 권한이 부여됩니다.

기본 인증 사용

GitHub Apps 및 OAuth apps에 대한 일부 REST API 엔드포인트에서는 기본 인증을 사용하여 엔드포인트에 액세스해야 합니다. 앱의 클라이언트 ID를 사용자 이름으로 사용하고 앱의 클라이언트 암호를 암호로 사용합니다.

예시:

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"
}'

클라이언트 ID 및 클라이언트 암호는 앱 소유자 또는 앱에 권한을 부여한 사용자가 아닌 앱과 연결됩니다. 액세스 토큰 만들기와 같은 앱을 대신하여 작업을 수행하는 데 사용됩니다.

GitHub App 또는 OAuth app의 소유자이거나 GitHub App의 앱 관리자인 경우 클라이언트 ID를 찾고 앱의 설정 페이지에서 클라이언트 암호를 생성할 수 있습니다. 앱의 설정 페이지로 이동하려면 다음을 수행합니다.

GitHub Enterprise Cloud의 페이지 오른쪽 위 모서리에서 프로필 사진을 클릭합니다.
계정 설정으로 이동합니다.
- 개인 계정 소유한 앱의 경우 설정을 클릭합니다.
- 조직이 소유한 앱의 경우:
  1. 사용자의 조직을 클릭합니다.
  2. 그런 다음, 조직 오른쪽에 있는 설정을 클릭합니다.
왼쪽 사이드바에서 개발자 설정을 클릭합니다.
왼쪽 사이드바에서 GitHub Apps 또는 OAuth apps 을(를) 클릭합니다.
GitHub Apps의 경우 액세스하려는 GitHub App의 오른쪽에 있는 편집을 클릭합니다. OAuth apps의 경우 액세스하려는 앱을 클릭합니다.
클라이언트 ID 옆에 앱의 클라이언트 ID가 표시됩니다.
클라이언트 비밀 옆에 있는 새 클라이언트 암호 생성을 클릭하여 앱에 대한 클라이언트 비밀을 생성합니다.

GitHub Actions 워크플로에서 인증

GitHub Actions 워크플로에서 API를 사용하려면 GitHub에서 토큰을 만드는 대신 기본 제공 GITHUB_TOKEN으로 인증하는 것이 좋습니다. permissions 키를 사용하여 GITHUB_TOKEN에 대한 사용 권한을 부여할 수 있습니다. 자세한 내용은 "자동 토큰 인증"을(를) 참조하세요.

이렇게 할 수 없는 경우 토큰을 비밀로 저장하고 GitHub Actions 워크플로에서 비밀의 이름을 사용할 수 있습니다. 비밀에 대한 자세한 내용은 "GitHub Actions에서 비밀 사용" 항목을 참조하세요.

GitHub CLI을(를 사용하여 GitHub Actions 워크플로에서 인증

GitHub CLI을(를) 사용하여 GitHub Actions 워크플로에서 API에 인증된 요청을 하려면 GITHUB_TOKEN 값을 환경 변수로 저장하고 run 키워드를 사용하여 GitHub CLI api 하위 명령을 실행할 수 있습니다. run 키워드에 대한 자세한 내용은 "GitHub Actions에 대한 워크플로 구문" 항목을 참조하세요.

다음 예제 워크플로에서 PATH를 엔드포인트의 경로로 바꿉니다. 경로에 대한 자세한 정보는 "REST API 시작"을(를) 참조하세요.

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

`curl`을(를) 사용하여 GitHub Actions 워크플로에서 인증

curl을(를) 사용하여 GitHub Actions 워크플로에서 API에 인증된 요청을 하려면 환경 변수로 GITHUB_TOKEN 값을 저장하고 run 키워드를 사용하여 API에 대한 curl 요청을 실행할 수 있습니다. run 키워드에 대한 자세한 내용은 "GitHub Actions에 대한 워크플로 구문" 항목을 참조하세요.

다음 예제 워크플로에서 PATH를 엔드포인트의 경로로 바꿉니다. 경로에 대한 자세한 정보는 "REST API 시작"을(를) 참조하세요.

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"

이 문서의 내용