GitHub 앱에 대한 사용자 액세스 토큰 생성

사용자 액세스 토큰 정보

Note

만료되는 사용자 액세스 토큰은 현재 선택적 기능이며 변경될 수 있습니다. 토큰 만료 기능을 옵트인하거나 옵트아웃하려면 "GitHub 앱의 선택적 기능 활성화"을 참조하세요. 자세한 내용은 "GitHub 앱에 대한 사용자-서버 액세스 토큰 만료" 항목을 참조하세요.

사용자가 GitHub App에 권한을 부여한 후 조직 소유의 리소스를 볼 수 없다고 보고하고 조직에서 SAML SSO를 사용하는 경우 다시 인증하기 전에 조직에 대해 활성 SAML 세션을 시작하도록 사용자에게 명령합니다. 자세한 내용은 GitHub Enterprise Cloud 설명서의 "SAML 및 GitHub 앱"을 참조하세요.

사용자 액세스 토큰은 OAuth 토큰의 한 유형입니다. 기존 OAuth 토큰과 달리 사용자 액세스 토큰은 범위를 사용하지 않습니다. 대신 세분화된 사용 권한을 사용합니다. 사용자 액세스 토큰에는 사용자와 앱 모두에 있는 권한만 있습니다. 예를 들어 앱에 리포지토리의 콘텐츠를 쓸 수 있는 권한이 부여되었지만 사용자가 콘텐츠를 읽기만 할 수 있는 경우, 사용자 액세스 토큰은 콘텐츠만 읽을 수 있습니다.

마찬가지로 사용자 액세스 토큰은 사용자와 앱이 모두 액세스할 수 있는 리소스에만 액세스할 수 있습니다. 예를 들어 앱에 A 및 B 리포지토리에 대한 액세스 권한이 부여되고 사용자가 B 및 C 리포지토리에 액세스할 수 있는 경우 사용자 액세스 토큰은 B 리포지토리에 액세스할 수 있지만 A 및 C 의 경우 그렇지 않을 수도 있습니다. REST API를 사용하여 사용자 액세스 토큰이 액세스할 수 있는 설치 및 설치 내의 리포지토리를 검사할 수 있습니다. 자세한 내용은 GitHub App 설치에 대한 REST API 엔드포인트의 GET /user/installations 및 GET /user/installations/{installation_id}/repositories을(를) 참조하세요.

사용자 액세스 토큰을 사용하여 API 요청을 하면 사용자 액세스 토큰에 대한 트래픽률 제한이 적용됩니다. 자세한 내용은 GitHub 앱의 트래픽률 제한을(를) 참조하세요.

기본적으로 사용자 액세스 토큰은 8시간 후에 만료됩니다. 새로 고침 토큰을 사용하여 사용자 액세스 토큰을 다시 생성할 수 있습니다. 자세한 내용은 사용자 액세스 토큰 새로 고침을(를) 참조하세요.

사용자는 GitHub App 에 대한 권한 부여를 철회할 수 있습니다. 자세한 내용은 토큰 만료 및 해지을(를) 참조하세요. 사용자가 GitHub App의 권한 부여를 철회하면 앱은 기본적으로 github_app_authorization 웹후크를 받습니다. GitHub App은(는) 이 이벤트에서 수신을 거부할 수 없습니다. 앱에서 이 웹후크를 받으면 토큰을 철회한 사용자를 대신하여 API 호출을 중지하도록 해야 합니다. 앱이 철회한 액세스 토큰을 계속 사용하는 경우 401 Bad Credentials 오류가 발생합니다. 이 웹후크에 대한 자세한 내용은 웹후크 이벤트 및 페이로드을(를) 참조하세요.

사용자 액세스 토큰을 유지하고 토큰을 안전히 새로 고침해야 합니다. 자세한 내용은 GitHub App을 만드는 모범 사례을(를) 참조하세요.

웹 애플리케이션 흐름을 사용하여 사용자 액세스 토큰 생성

앱이 브라우저에서 실행되는 경우 웹 애플리케이션 흐름을 사용하여 사용자 액세스 토큰을 생성해야 합니다. 웹 애플리케이션 흐름 사용에 대한 자습서는 GitHub 앱을 사용하여 "GitHub로 로그인" 단추 빌드을(를) 참조하세요.

사용자를 이 URL로 안내하고 다음 매개 변수 목록에서 필요한 쿼리 매개 변수(https://github.com/login/oauth/authorize)를 추가합니다. 예를 들어 이 URL은 client_id 및 state 매개 변수(https://github.com/login/oauth/authorize?client_id=12345&state=abcdefg)를 지정합니다.

쿼리 매개 변수	Type	필수 여부	설명
`client_id`	`string`	필수	GitHub App용 클라이언트 ID입니다. 클라이언트 ID는 앱 ID와 다릅니다. 앱의 설정 페이지에서 클라이언트 ID를 찾을 수 있습니다. GitHub App의 설정 페이지로 이동하는 방법에 대한 자세한 내용은 GitHub 앱 등록 수정을(를) 참조하세요.
`redirect_uri`	`string`	매우 권장	권한 부여 후에 사용자를 보낼 애플리케이션의 URL입니다. 이는 앱 설정에서 "콜백 URL"로 제공한 URL 중 하나와 정확히 일치해야 하며 추가 매개 변수를 포함할 수 없습니다.
`state`	`string`	매우 권장	지정되면 위조 공격으로부터 보호하기 위해 값에 임의 문자열을 포함해야 하며 다른 임의 데이터를 포함할 수도 있습니다.
`login`	`string`	선택 사항	지정되면 앱 애플리리케이션 플로우에서 앱에 로그인하고 권한을 부여하는 데 사용할 수 있는 특정 계정을 사용자에게 프롬프트로 표시합니다.
`allow_signup`	`boolean`	선택 사항	인증되지 않은 사용자에게 OAuth 흐름 중에 GitHub에 등록하는 옵션이 제공될지 여부입니다. 기본값은 `true`입니다. 정책에서 등록을 금지할 때 `false`를 사용합니다.
`prompt`	`string`	선택 사항	`select_account`로 설정된 경우 계정 선택기를 강제로 표시합니다. 애플리케이션에 HTTP가 아닌 리디렉션 URI가 있거나 사용자가 로그인한 계정이 여러 개 있는 경우에도 계정 선택기가 표시됩니다.

사용자가 권한 부여 요청을 수락하면 GitHub은(는) 사용자를 앱 설정의 콜백 URL 중 하나로 리디렉션하고 다음 단계에서 사용자 액세스 토큰을 만드는 데 사용할 수 있는 code 쿼리 매개 변수를 제공합니다. 이전 단계에서 redirect_uri을(를) 지정한 경우 해당 콜백 URL이 사용됩니다. 그렇지 않으면 앱 설정 페이지의 첫 번째 콜백 URL이 사용됩니다.

이전 단계에서 state 매개 변수를 지정한 경우 GitHub에도 state 매개 변수가 포함됩니다. state 매개 변수가 이전 단계에서 보낸 state 매개 변수와 일치하지 않으면 요청을 신뢰할 수 없으며 웹 애플리케이션 흐름을 중단해야 합니다.

https://github.com/login/oauth/access_token 쿼리 매개 변수와 함께 이 URL에 POST를 요청하여 이전 단계의 code를 사용자 액세스 토큰으로 교환합니다.

쿼리 매개 변수	Type	설명
`client_id`	`string`	필수입니다. GitHub App용 클라이언트 ID입니다. 클라이언트 ID는 앱 ID와 다릅니다. 앱의 설정 페이지에서 클라이언트 ID를 찾을 수 있습니다. GitHub App의 설정 페이지로 이동하는 방법에 대한 자세한 내용은 "GitHub 앱 등록 수정"을 참조하세요.
`client_secret`	`string`	필수입니다. GitHub App용 클라이언트 비밀입니다. 앱의 설정 페이지에서 클라이언트 암호를 생성할 수 있습니다.
`code`	`string`	필수입니다. 이전 단계에서 받은 코드입니다.
`redirect_uri`	`string`	권한 부여 후에 사용자를 보낼 애플리케이션의 URL입니다. GitHub App을(를) 설정할 때 "콜백 URL"로 제공한 URL 중 하나와 정확히 일치해야 하며 추가 매개 변수를 포함할 수 없습니다.
`repository_id`	`string`	사용자 액세스 토큰이 액세스할 수 있는 단일 리포지토리의 ID입니다. GitHub App 또는 사용자가 리포지토리에 액세스할 수 없는 경우 무시됩니다. 이 매개 변수를 사용하여 사용자 액세스 토큰의 액세스를 추가로 제한합니다.

GitHub은(는) 다음 매개 변수를 포함하는 응답을 제공합니다.

응답 매개 변수	Type	설명
`access_token`	`string`	사용자 액세스 토큰입니다. 토큰은 `ghu_`로 시작합니다.
`expires_in`	`integer`	`access_token`이 만료될 때까지 시간(초) 수입니다. 사용자 액세스 토큰의 만료를 사용하지 않도록 설정한 경우 이 매개 변수는 생략됩니다. 값은 항상 `28800`(8시간)입니다 .
`refresh_token`	`string`	새로 고침 토큰입니다. 사용자 액세스 토큰의 만료를 사용하지 않도록 설정한 경우 이 매개 변수는 생략됩니다. 토큰은 `ghr_`로 시작합니다.
`refresh_token_expires_in`	`integer`	`refresh_token`이 만료될 때까지 시간(초) 수입니다. 사용자 액세스 토큰의 만료를 사용하지 않도록 설정한 경우 이 매개 변수는 생략됩니다. 값은 항상 `15897600`(6개월)이 됩니다.
`scope`	`string`	토큰에 있는 범위입니다. 이 값은 항상 빈 문자열입니다. 기존 OAuth 토큰과 달리 사용자 액세스 토큰은 앱과 사용자가 모두 가진 권한으로 제한됩니다.
`token_type`	`string`	토큰의 형식입니다. 값은 항상 `bearer`가 됩니다.

이전 단계의 사용자 액세스 토큰을 사용하여 사용자를 대신하여 API 요청을 만듭니다. API 요청의 Authorization 헤더에 사용자 액세스 토큰을 포함합니다. 예시:

curl --request GET \
--url "https://api.github.com/user" \
--header "Accept: application/vnd.github+json" \
--header "Authorization: Bearer USER_ACCESS_TOKEN" \
--header "X-GitHub-Api-Version: 2022-11-28"

디바이스 흐름을 사용하여 사용자 액세스 토큰 생성

Note

장치 흐름은 공개 미리 보기 버전이며 변경될 수 있습니다.

앱이 비입력 시스템이거나 브라우저에 액세스할 수 없는 경우 디바이스 흐름을 사용하여 사용자 액세스 토큰을 생성해야 합니다. 예를 들어 CLI 도구, 간단한 라즈베리 파이 및 데스크톱 애플리케이션은 디바이스 흐름을 사용해야 합니다. 디바이스 흐름을 사용하는 자습서는 GitHub 앱을 사용하여 CLI 빌드을(를) 참조하세요.

디바이스 흐름을 사용하기 전에 먼저 앱 설정에서 사용하도록 설정해야 합니다. 디바이스 흐름을 사용하도록 설정하는 방법에 대한 자세한 내용은 GitHub 앱 등록 수정을(를) 참조하세요.

디바이스 흐름은 OAuth 2.0 디바이스 권한 부여를 사용합니다.

client_id 쿼리 매개 변수와 함께 POST 요청을 https://github.com/login/device/code 에 보냅니다. 클라이언트 ID는 앱 ID와 다릅니다. 앱의 설정 페이지에서 클라이언트 ID를 찾을 수 있습니다. GitHub App의 설정 페이지로 이동하는 방법에 대한 자세한 내용은 GitHub 앱 등록 수정을(를) 참조하세요.

GitHub은(는) 다음 쿼리 매개 변수를 포함하는 응답을 제공합니다.

응답 매개 변수	Type	설명
`device_code`	`string`	디바이스를 확인하는 데 사용되는 확인 코드입니다. 이 코드의 길이는 40자입니다.
`user_code`	`string`	사용자가 브라우저에서 코드를 입력할 수 있도록 애플리케이션이 표시해야 하는 확인 코드입니다. 이 코드는 8자이며 중간에 하이픈이 있습니다. 예들 들어 `WDJB-MJHT`입니다.
`verification_uri`	`string`	사용자가 `user_code` 에 입력해야 하는 URL입니다. URL은 `https://github.com/login/device` 입니다.
`expires_in`	`integer`	`device_code` 및 `user_code`의 만료 전 시간(초)입니다. 기본값은 900초(또는 15분)입니다.
`interval`	`integer`	디바이스 권한 부여를 완료하려면 새 액세스 토큰을 요청하기 전에 경과해야 하는 최소 시간(초)입니다(`POST https://github.com/login/oauth/access_token`). 이 간격이 지나기 전에 요청을 하면 트래픽률 제한에 도달하고 `slow_down` 오류가 발생합니다. 기본값은 5초입니다.

https://github.com/login/device의 user_code 에서 이전 단계를 입력하라는 프롬프트를 표시합니다.

expires_in 시간이 지나기 전에 사용자가 코드를 입력하지 않으면 코드가 유효하지 않습니다. 이 경우 디바이스 흐름을 다시 시작해야 합니다.

디바이스 및 사용자 코드가 만료되거나 사용자가 user_code을(를) 입력하여 앱에 성공적으로 권한을 부여할 때까지 (아래에 설명된) client_id, device_code, grant_type 쿼리 매개 변수와 함께 POST https://github.com/login/oauth/access_token을(를) 폴링합니다.

쿼리 매개 변수	형식	설명
`client_id`	`string`	필수입니다. GitHub App용 클라이언트 ID입니다.
`device_code`	`string`	필수입니다. 이전 단계에서 받은 디바이스 확인 코드입니다.
`grant_type`	`string`	필수입니다. 권한 부여 유형은 `urn:ietf:params:oauth:grant-type:device_code`이어야 합니다.
`repository_id`	`string`	사용자 액세스 토큰이 액세스할 수 있는 단일 리포지토리의 ID입니다. GitHub App 또는 사용자가 리포지토리에 액세스할 수 없는 경우 무시됩니다. 이 매개 변수를 사용하여 사용자 액세스 토큰의 액세스를 추가로 제한합니다.

interval 에 표시된 빈도보다 높은 빈도로 이 엔드포인트를 폴링하지 마세요. 이 경우 트래픽률 제한에 도달하고 slow_down 오류가 발생합니다. slow_down 오류 응답은 마지막 interval에 5초를 추가합니다.

사용자가 코드를 입력할 때까지 GitHub은(는) 200개의 상태 및 error 의 응답 쿼리 매개 변수로 응답합니다.

오류 이름	설명
`authorization_pending`	이 오류는 권한 부여 요청이 보류 중이고 사용자가 사용자 코드를 아직 입력하지 않은 경우에 발생합니다. 앱은 `interval` 에서 지정된 빈도보다 더 빠른 빈도로 `POST https://github.com/login/oauth/access_token` 폴링을 유지해야 합니다.
`slow_down`	`slow_down` 오류를 수신하는 경우 `POST https://github.com/login/oauth/access_token`을 사용하여 요청 간 필요한 최소 `interval` 또는 기간에 5초가 더 추가됩니다. 예를 들어 시작 간격이 요청 사이에 5초 이상 필요하고 `slow_down` 오류 응답을 수신하는 경우 토큰을 새로 요청하기 전에 최소 10초 동안 기다려야 합니다. 오류 응답에는 사용해야 하는 새 `interval`이 포함됩니다.
`expired_token`	디바이스 코드가 만료되면 `token_expired` 오류가 표시됩니다. 이 경우 디바이스 코드를 새로 요청해야 합니다.
`unsupported_grant_type`	OAuth 토큰 요청 `POST https://github.com/login/oauth/access_token`을 폴링할 때 권한 부여 형식은 `urn:ietf:params:oauth:grant-type:device_code`이며 입력 매개 변수로 포함되어야 합니다.
`incorrect_client_credentials`	디바이스 흐름의 경우 앱 설정 페이지에서 찾을 수 있는 앱의 클라이언트 ID를 전달해야 합니다. 클라이언트 ID는 앱 ID 및 클라이언트 암호와 다릅니다.
`incorrect_device_code`	제공된 `device_code`이(가) 잘못되었습니다.
`access_denied`	권한 부여 프로세스 중에 사용자가 취소를 클릭하면 `access_denied` 오류를 수신하게 되고 사용자는 확인 코드를 다시 사용할 수 없습니다.
`device_flow_disabled`	앱 설정에서 디바이스 흐름을 사용하도록 설정하지 않았습니다. 디바이스 흐름을 사용하도록 설정하는 방법에 대한 자세한 내용은 GitHub 앱 등록 수정을(를) 참조하세요.

사용자가 user_code을(를) 입력하면 GitHub에서 다음 쿼리 매개 변수를 포함하는 응답을 제공합니다.

응답 매개 변수	Type	설명
`access_token`	`string`	사용자 액세스 토큰입니다. 토큰은 `ghu_`로 시작합니다.
`expires_in`	`integer`	`access_token`이 만료될 때까지 시간(초) 수입니다. 사용자 액세스 토큰의 만료를 사용하지 않도록 설정한 경우 이 매개 변수는 생략됩니다. 값은 항상 `28800`(8시간)입니다 .
`refresh_token`	`string`	새로 고침 토큰입니다. 사용자 액세스 토큰의 만료를 사용하지 않도록 설정한 경우 이 매개 변수는 생략됩니다. 토큰은 `ghr_`로 시작합니다.
`refresh_token_expires_in`	`integer`	`refresh_token`이 만료될 때까지 시간(초) 수입니다. 사용자 액세스 토큰의 만료를 사용하지 않도록 설정한 경우 이 매개 변수는 생략됩니다. 값은 항상 `15897600`(6개월)이 됩니다.
`scope`	`string`	토큰에 있는 범위입니다. 이 값은 항상 빈 문자열입니다. 기존 OAuth 토큰과 달리 사용자 액세스 토큰은 앱과 사용자가 모두 가진 권한으로 제한됩니다.
`token_type`	`string`	토큰의 형식입니다. 값은 항상 `bearer`가 됩니다.

이전 단계의 사용자 액세스 토큰을 사용하여 사용자를 대신하여 API 요청을 만듭니다. API 요청의 Authorization 헤더에 사용자 액세스 토큰을 포함합니다. 예시:

curl --request GET \
--url "https://api.github.com/user" \
--header "Accept: application/vnd.github+json" \
--header "Authorization: Bearer USER_ACCESS_TOKEN" \
--header "X-GitHub-Api-Version: 2022-11-28"

사용자가 앱을 설치할 때 사용자 액세스 토큰 생성

앱 설정에서 설치 중 OAuth(사용자 권한 부여 요청) 를 선택하면 사용자가 앱을 설치한 직후 GitHub에서 웹 애플리케이션 흐름을 시작합니다.

앱이 사용자 계정 또는 조직 계정에 설치되어 있는지 여부에 관계없이 이 메서드를 사용하여 사용자 액세스 토큰을 생성할 수 있습니다. 그러나 앱이 조직 계정에 설치된 경우 웹 애플리케이션 흐름 또는 디바이스 흐름을 사용하여 조직의 다른 사용자에 대한 사용자 액세스 토큰을 생성해야 합니다.

사용자가 앱을 설치하면 GitHub에서 사용자를 앱의 클라이언트 ID가 CLIENT_ID 인 https://github.com/login/oauth/authorize?client_id=CLIENT_ID 위치로 리디렉션합니다.
사용자가 권한 부여 요청을 수락하면 GitHub에서 사용자를 앱 설 정의 첫 번째 콜백 URL로 리디렉션하고 code 쿼리 매개 변수를 제공합니다.

사용되는 콜백 URL을 제어하려면 설치 중에 OAuth(사용자 권한 부여 요청) 를 선택하지 마세요. 대신 전체 웹 애플리케이션 흐름을 통해 사용자를 직접 지정하고 redirect_uri 매개 변수를 지정합니다.

https://github.com/login/oauth/access_token 쿼리 매개 변수와 함께 이 URL에 POST를 요청하여 이전 단계의 code를 사용자 액세스 토큰으로 교환합니다.

쿼리 매개 변수	Type	설명
`client_id`	`string`	필수입니다. GitHub App용 클라이언트 ID입니다. 클라이언트 ID는 앱 ID와 다릅니다. 앱의 설정 페이지에서 클라이언트 ID를 찾을 수 있습니다. GitHub App의 설정 페이지로 이동하는 방법에 대한 자세한 내용은 "GitHub 앱 등록 수정"을 참조하세요.
`client_secret`	`string`	필수입니다. GitHub App용 클라이언트 비밀입니다. 앱의 설정 페이지에서 클라이언트 암호를 생성할 수 있습니다.
`code`	`string`	필수입니다. 이전 단계에서 받은 코드입니다.
`redirect_uri`	`string`	권한 부여 후에 사용자를 보낼 애플리케이션의 URL입니다. GitHub App을(를) 설정할 때 "콜백 URL"로 제공한 URL 중 하나와 정확히 일치해야 하며 추가 매개 변수를 포함할 수 없습니다.
`repository_id`	`string`	사용자 액세스 토큰이 액세스할 수 있는 단일 리포지토리의 ID입니다. GitHub App 또는 사용자가 리포지토리에 액세스할 수 없는 경우 무시됩니다. 이 매개 변수를 사용하여 사용자 액세스 토큰의 액세스를 추가로 제한합니다.

GitHub은(는) 다음 매개 변수를 포함하는 응답을 제공합니다.

응답 매개 변수	Type	설명
`access_token`	`string`	사용자 액세스 토큰입니다. 토큰은 `ghu_`로 시작합니다.
`expires_in`	`integer`	`access_token`이 만료될 때까지 시간(초) 수입니다. 사용자 액세스 토큰의 만료를 사용하지 않도록 설정한 경우 이 매개 변수는 생략됩니다. 값은 항상 `28800`(8시간)입니다 .
`refresh_token`	`string`	새로 고침 토큰입니다. 사용자 액세스 토큰의 만료를 사용하지 않도록 설정한 경우 이 매개 변수는 생략됩니다. 토큰은 `ghr_`로 시작합니다.
`refresh_token_expires_in`	`integer`	`refresh_token`이 만료될 때까지 시간(초) 수입니다. 사용자 액세스 토큰의 만료를 사용하지 않도록 설정한 경우 이 매개 변수는 생략됩니다. 값은 항상 `15897600`(6개월)이 됩니다.
`scope`	`string`	토큰에 있는 범위입니다. 이 값은 항상 빈 문자열입니다. 기존 OAuth 토큰과 달리 사용자 액세스 토큰은 앱과 사용자가 모두 가진 권한으로 제한됩니다.
`token_type`	`string`	토큰의 형식입니다. 값은 항상 `bearer`가 됩니다.

이전 단계의 사용자 액세스 토큰을 사용하여 사용자를 대신하여 API 요청을 만듭니다. API 요청의 Authorization 헤더에 사용자 액세스 토큰을 포함합니다. 예시:

curl --request GET \
--url "https://api.github.com/user" \
--header "Accept: application/vnd.github+json" \
--header "Authorization: Bearer USER_ACCESS_TOKEN" \
--header "X-GitHub-Api-Version: 2022-11-28"

GitHub 앱에 대한 사용자 액세스 토큰 생성

이 문서의 내용

사용자 액세스 토큰 정보

웹 애플리케이션 흐름을 사용하여 사용자 액세스 토큰 생성

디바이스 흐름을 사용하여 사용자 액세스 토큰 생성

사용자가 앱을 설치할 때 사용자 액세스 토큰 생성

새로 고침 토큰을 사용하여 사용자 액세스 토큰 생성

문제 해결

잘못된 클라이언트 자격 증명

리디렉션 URI 불일치

잘못된 확인 코드

잘못된 새로 고침 토큰

지원되지 않는 권한 부여 유형

확인되지 않은 사용자 이메일