REST API에 인증

REST API에 인증하여 더 많은 엔드포인트에 액세스하고 더 높은 속도 제한을 가질 수 있습니다.

이 문서의 내용

인증 정보

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

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

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

참고: 대부분의 경우 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

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

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

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

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

기본 인증 사용

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

예시:

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

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

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

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

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 시작"을(를) 참조하세요. HOSTNAME을(를) GitHub Enterprise Server 인스턴스의 이름으로 바꿉니다.

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 시작"을(를) 참조하세요. HOSTNAME을(를) GitHub Enterprise Server 인스턴스의 이름으로 바꿉니다.

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"

JavaScript를 사용하여 GitHub Actions 워크플로에서 인증

JavaScript를 사용하여 GitHub Actions 워크플로에서 인증하는 방법의 예는 "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"

추가 참고 자료