GitHub 앱에 대한 사용자 식별 및 권한 부여

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

GitHub 앱이 사용자를 대신하여 작동하면 사용자-서버 요청을 수행합니다. 해당 요청은 사용자의 액세스 토큰을 사용하여 권한을 부여받아야 합니다. 사용자-서버 요청은 특정 사용자에게 표시할 리포지토리를 결정하는 것과 같은 사용자에 대한 데이터 요청을 포함합니다. 해당 요청에는 빌드 실행과 같이 사용자가 트리거하는 작업도 포함됩니다.

사용자-서버 액세스 토큰의 보안을 유지하기 위해 8시간 후에 만료되는 액세스 토큰과 새 액세스 토큰으로 교환할 수 있는 새로 고침 토큰을 사용할 수 있습니다. 자세한 내용은 “사용자-서버 액세스 토큰 새로 고침”을 참조하세요.

사이트에서 사용자 식별

사용자에게 브라우저에서 실행되는 표준 앱에 대한 권한을 부여하려면 웹 애플리케이션 흐름을 사용합니다.

CLI 도구 또는 Git 자격 증명 관리자와 같이 브라우저에 직접 액세스하지 않고 헤드리스 앱에 대해 사용자에게 권한을 부여하려면 디바이스 흐름을 사용합니다. 디바이스 흐름은 OAuth 2.0 디바이스 권한 부여를 사용합니다.

웹 애플리케이션 흐름

웹 애플리케이션 흐름을 사용하여 사이트에서 사용자를 식별하는 프로세스는 다음과 같습니다.

사용자는 GitHub ID를 요청하도록 리디렉션됩니다.
GitHub가 사용자를 사이트로 다시 리디렉션합니다.
GitHub 앱이 사용자의 액세스 토큰을 사용하여 API에 액세스합니다.

앱을 만들거나 수정할 때 설치 중에 OAuth(사용자 권한 부여 요청) 를 선택하면 앱 설치 중에 1단계가 완료됩니다. 자세한 내용은 “설치하는 동안 사용자에게 권한 부여”를 참조하세요.

1. 사용자의 GitHub ID 요청

브라우저에서 다음 URL로 사용자를 안내합니다.

GET http(s)://HOSTNAME/login/oauth/authorize

GitHub 앱이 login 매개 변수를 지정하면 앱에 로그인하고 권한을 부여하는 데 사용할 수 있는 특정 계정을 사용자에게 표시합니다.

매개 변수

이름	Type	설명
`client_id`	`string`	필수 사항입니다. GitHub 앱의 클라이언트 ID입니다. 앱을 선택할 때 GitHub 앱 설정에서 찾을 수 있습니다. 참고: 앱 ID와 클라이언트 ID는 동일하지 않으며 서로 교환할 수 없습니다.
`redirect_uri`	`string`	권한 부여 후에 사용자를 보낼 애플리케이션의 URL입니다. 이는 GitHub 앱을 설정할 때 콜백 URL로 제공한 URL 중 하나와 정확히 일치해야 하며 추가 매개 변수를 포함할 수 없습니다.
`state`	`string`	위조 공격으로부터 보호하기 위해 임의 문자열을 포함해야 하며 다른 임의 데이터를 포함할 수 있습니다.
`login`	`string`	앱에 로그인하고 권한을 부여하는 데 사용할 특정 계정을 제안합니다.
`allow_signup`	`string`	인증되지 않은 사용자에게 OAuth 흐름 중에 GitHub에 등록하는 옵션이 제공될지 여부입니다. 기본값은 `true`입니다. 정책에서 등록을 금지할 때 `false`를 사용합니다.

참고: 권한 부여 요청에 범위를 제공할 필요가 없습니다. 기존 OAuth와 달리 권한 부여 토큰은 GitHub 앱 및 사용자의 권한과 연결된 권한으로 제한됩니다.

2. GitHub가 사용자를 사이트로 다시 리디렉션

사용자가 요청을 수락하면 GitHub는 state 매개 변수의 이전 단계에서 제공한 상태뿐만 아니라 코드 매개 변수의 임시 code와 함께 사이트로 다시 리디렉션합니다. 상태가 일치하지 않으면 요청이 타사에 의해 만들어졌으며 프로세스를 중단해야 합니다.

참고: 앱을 만들거나 수정할 때 설치 중에 OAuth(사용자 권한 부여 요청) 를 선택하는 경우 GitHub에서 액세스 토큰을 교환해야 하는 임시 code를 반환합니다. 앱을 설치하는 동안 GitHub에서 OAuth 흐름을 시작할 때 state 매개 변수가 반환되지 않습니다.

이 code를 액세스 토큰으로 교환합니다. 만료 토큰을 사용하도록 설정하면 액세스 토큰은 8시간 후에 만료되고 새로 고침 토큰은 6개월 후에 만료됩니다. 토큰을 새로 고칠 때마다 새 새로 고침 토큰이 발생합니다. 자세한 내용은 “사용자-서버 액세스 토큰 새로 고침”을 참조하세요.

만료된 사용자 토큰은 현재 선택적 기능이며 변경될 수 있습니다. 사용자-서버 토큰 만료 기능을 옵트인하려면 “앱에 선택적 기능 활성화”를 참조하세요.

다음 엔드포인트에 액세스 토큰을 받도록 요청합니다.

POST http(s)://HOSTNAME/login/oauth/access_token

매개 변수

이름	Type	설명
`client_id`	`string`	필수 사항입니다. GitHub 앱의 클라이언트 ID입니다.
`client_secret`	`string`	필수 사항입니다. GitHub 앱의 클라이언트 암호입니다.
`code`	`string`	필수 사항입니다. 1단계에 대한 응답으로 받은 코드입니다.
`redirect_uri`	`string`	권한 부여 후에 사용자를 보낼 애플리케이션의 URL입니다. 이는 GitHub 앱을 설정할 때 콜백 URL로 제공한 URL 중 하나와 정확히 일치해야 하며 추가 매개 변수를 포함할 수 없습니다.

응답

기본적으로 응답은 다음 형식을 사용합니다. 응답 매개 변수 expires_in, refresh_token, refresh_token_expires_in은 만료되는 사용자-서버 액세스 토큰을 사용하도록 설정할 때만 반환됩니다.

{
  "access_token": "ghu_16C7e42F292c6912E7710c838347Ae178B4a",
  "expires_in": 28800,
  "refresh_token": "ghr_1B4a2e77838347a7E420ce178F2E7c6912E169246c34E1ccbF66C46812d16D5B1A9Dc86A1498",
  "refresh_token_expires_in": 15811200,
  "scope": "",
  "token_type": "bearer"
}

3. GitHub 앱이 사용자의 액세스 토큰을 사용하여 API에 액세스

사용자의 액세스 토큰을 사용하면 GitHub 앱이 사용자를 대신하여 API에 요청할 수 있습니다.

Authorization: Bearer OAUTH-TOKEN
GET http(s)://HOSTNAME/api/v3/user

예를 들어 curl에서 다음과 같이 인증 헤더를 설정할 수 있습니다.

curl -H "Authorization: Bearer OAUTH-TOKEN" http(s)://HOSTNAME/api/v3/user

디바이스 흐름

참고: 디바이스 흐름은 퍼블릭 베타 상태이며 변경될 수 있습니다.

디바이스 흐름을 사용하면 CLI 도구 또는 Git 자격 증명 관리자와 같은 헤드리스 앱의 사용자에게 권한을 부여할 수 있습니다.

디바이스 흐름을 사용하여 사용자를 식별하고 권한을 부여하려면 먼저 앱 설정에서 사용하도록 설정해야 합니다. 디바이스 흐름을 사용하도록 설정하는 방법에 대한 자세한 내용은 “GitHub 앱 수정”을 참조하세요. 디바이스 흐름을 사용하여 사용자에게 권한을 부여하는 방법에 대한 자세한 내용은 “OAuth 앱 권한 부여”를 참조하세요.

사용자가 액세스할 수 있는 설치 리소스 확인

사용자에 대한 OAuth 토큰이 있으면 사용자가 액세스할 수 있는 설치를 확인할 수 있습니다.

Authorization: Bearer OAUTH-TOKEN
GET /user/installations

설치를 위해 사용자가 액세스할 수 있는 리포지토리를 확인할 수도 있습니다.

Authorization: Bearer OAUTH-TOKEN
GET /user/installations/:installation_id/repositories

자세한 내용은 사용자 액세스 토큰에 액세스할 수 있는 앱 설치 나열 및 사용자 액세스 토큰에 액세스할 수 있는 목록 리포지토리에서 찾을 수 있습니다.

철회한 GitHub 앱 권한 부여 처리

사용자가 GitHub 앱의 권한 부여를 철회하면 앱은 기본적으로 github_app_authorization 웹후크를 받습니다. GitHub 앱은 이 이벤트에서 구독을 취소할 수 없습니다. 누구나 GitHub 계정 설정 페이지에서 GitHub 앱의 권한 부여를 취소할 수 있습니다. GitHub 앱의 권한 부여를 취소해도 GitHub 앱이 제거되지 않습니다. 이 웹후크를 받으면 토큰을 철회한 사용자를 대신하여 API 호출을 중지하도록 GitHub 앱을 프로그래밍해야 합니다. GitHub 앱이 철회한 액세스 토큰을 계속 사용하는 경우 401 Bad Credentials 오류가 발생합니다.

사용자 수준 권한

GitHub 앱에 사용자 수준 권한을 추가하여 사용자 권한 부여 흐름의 일부로 개별 사용자가 부여한 사용자 메일과 같은 사용자 리소스에 액세스할 수 있습니다. 사용자 수준 권한은 조직 또는 개인 계정에 설치할 때 부여되는 리포지토리 및 조직 수준 권한과 다릅니다.

사용 권한 및 웹후크 페이지의 사용자 권한 섹션의 GitHub 앱의 설정 내에서 사용자 수준 권한을 선택할 수 있습니다. 사용 권한 선택에 대한 자세한 내용은 “GitHub 앱 사용 권한 편집”을 참조하세요.

사용자가 자신의 계정에 앱을 설치하면 설치 프롬프트에 앱이 요청하는 사용자 수준 권한이 나열되고 앱이 개별 사용자에게 사용 권한을 요청할 수 있음을 설명합니다.

사용자 수준 권한은 개별 사용자별로 부여되므로 업그레이드하라는 메시지가 표시되지 않아도 기존 앱에 추가할 수 있습니다. 그러나 사용자 권한 부여 흐름을 통해 기존 사용자를 보내 새 권한을 부여하고 해당 요청에 대한 새 사용자-서버 토큰을 가져와야 합니다.

사용자-서버 요청

대부분의 API 상호 작용은 서버 간 설치 액세스 토큰을 사용하여 발생해야 하지만 특정 엔드포인트를 사용하면 사용자 액세스 토큰을 사용하여 API를 통해 작업을 수행할 수 있습니다. 앱은 GraphQL 또는 REST 엔드포인트를 사용하여 다음 요청을 수행할 수 있습니다.

GitHub 앱에 대한 사용자 식별 및 권한 부여

이 문서의 내용

사이트에서 사용자 식별

웹 애플리케이션 흐름

1. 사용자의 GitHub ID 요청

매개 변수

2. GitHub가 사용자를 사이트로 다시 리디렉션

매개 변수

응답

3. GitHub 앱이 사용자의 액세스 토큰을 사용하여 API에 액세스

디바이스 흐름

사용자가 액세스할 수 있는 설치 리소스 확인

철회한 GitHub 앱 권한 부여 처리

사용자 수준 권한

사용자-서버 요청

지원되는 엔드포인트

실행 확인

체크 스위트

사용 규정

배포 상태

배포

이벤트

피드

Git Blob

Git 커밋

Git 참조

Git 태그

Git 트리

Gitignore 템플릿

설치

문제 담당자

문제 주석

문제 이벤트

문제 타임라인

문제

레이블

라이선스

Markdown

Meta

마일스톤

조직 후크

조직 구성원

조직 외부 협력자

조직 사전 수신 후크

조직 팀 프로젝트

조직 팀 리포지토리

조직 팀

조직

프로젝트 협력자

프로젝트

끌어오기 주석

끌어오기 요청 검토 이벤트

끌어오기 요청 검토 요청

끌어오기 요청 검토

끌어오기

반응

리포지토리

리포지토리 작업

리포지토리 분기

리포지토리 협력자

리포지토리 커밋 주석

리포지토리 커밋

리포지토리 커뮤니티

리포지토리 콘텐츠

리포지토리 이벤트 디스패치

리포지토리 후크

리포지토리 초대

리포지토리 키

리포지토리 페이지

리포지토리 사전 수신 후크

리포지토리 릴리스

리포지토리 통계

Root

검색

상태

팀 토론

토픽

사용자 전자 메일

사용자 팔로워

사용자 Gpg 키