REST API에 인증

이 문서의 내용

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

인증 정보

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

요청의 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 응답을 받게 됩니다.

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에 특정 권한이 필요합니다. 각 엔드포인트에 필요한 권한에 대한 자세한 내용은 "세분화된 개인용 액세스 토큰에 필요한 권한"을 참조하세요. personal access token (classic)을(를) 사용하는 경우 각 REST API 엔드포인트에 액세스하려면 personal access token (classic)에 특정 범위가 필요합니다. 선택할 범위에 대한 일반적인 지침은 "OAuth 앱에 대한 범위"을 참조하세요.

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시간 후에 만료됩니다. 여러 조직에서 올 수 있는 데이터를 요청한 경우 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 앱을 사용한 인증 정보"을 참조하세요.

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를 찾고 앱의 설정 페이지에서 클라이언트 암호를 생성할 수 있습니다. 앱의 설정 페이지로 이동하려면 다음을 수행합니다.

  1. GitHub Enterprise Cloud의 페이지 오른쪽 위 모서리에서 프로필 사진을 클릭합니다.
  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에 대한 사용 권한을 부여할 수 있습니다. 자세한 내용은 "자동 토큰 인증"을 참조하세요.

사용자 이름 및 암호를 사용하여 인증

사용자 이름 및 암호를 사용한 인증증은 지원되지 않습니다. 사용자 이름 및 암호로 인증하려고 하면 4xx 오류가 발생합니다.

추가 참고 자료