OAuth 앱 권한 부여

GitHub Enterprise Server의 OAuth 구현은 웹 브라우저에 액세스할 수 없는 앱의 표준 권한 부여 코드 부여 유형 및 OAuth 2.0 디바이스 권한 부여를 지원합니다.

앱을 테스트할 때와 같이 표준 방식으로 앱에 대한 권한을 건너뛰려면 비 웹 애플리케이션 흐름을 사용할 수 있습니다.

OAuth app에 권한을 부여하려면 앱에 가장 적합한 권한 부여 흐름을 고려하세요.

• 웹 애플리케이션 흐름: 브라우저에서 실행되는 표준 OAuth apps에 대해 사용자에게 권한을 부여하는 데 사용됩니다. (암시적 허용 유형은 지원되지 않습니다.)
• 디바이스 흐름: CLI 도구와 같은 헤드리스 앱에 사용됩니다.

웹 애플리케이션 흐름

앱 사용자에게 권한을 부여하는 웹 애플리케이션 흐름은 다음과 같습니다.

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

1. 사용자의 GitHub ID 요청

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

이 끝점은 다음 입력 매개 변수를 사용합니다.

쿼리 매개 변수	Type	필수 여부	설명
client_id	string	필수	registered 시 GitHub에서 받은 클라이언트 ID입니다.
redirect_uri	string	매우 권장	권한 부여 후에 사용자를 보낼 애플리케이션의 URL입니다. url 리디렉션에 대한 자세한 내용은 아래를 참조하세요.
login	string	선택 사항	앱에 로그인하고 권한을 부여하는 데 사용할 특정 계정을 제안합니다.
scope	string	컨텍스트 종속	공백으로 구분되는 범위 목록입니다. 제공되지 않은 경우 scope는 애플리케이션의 범위에 권한을 부여하지 않은 사용자의 빈 목록으로 기본 설정됩니다. 애플리케이션의 범위에 권한을 부여하지 않은 사용자의 경우 사용자에게 범위 목록이 포함된 OAuth 권한 부여 페이지가 표시되지 않습니다. 대신, 이 흐름 단계는 사용자가 애플리케이션에 대해 권한을 부여한 범위 집합으로 자동으로 완료됩니다. 예를 들어 사용자가 이미 웹 흐름을 두 번 수행하고 user 범위의 토큰 하나와 repo 범위의 다른 토큰에 권한을 부여한 경우, scope를 제공하지 않는 세 번째 웹 흐름은 user 및 repo 범위의 토큰을 수신합니다.
state	string	매우 권장	추측할 수 없는 임의 문자열입니다. 교차 사이트 요청 위조 공격에서 보호하는 데 사용됩니다.
allow_signup	string	선택 사항	인증되지 않은 사용자에게 OAuth 흐름 중에 GitHub에 등록하는 옵션이 제공되는지 여부입니다. 기본값은 true입니다. 정책에서 등록을 금지할 때 false를 사용합니다.

PKCE(코드 교환용 증명 키) 매개 변수 code_challenge 및 code_challenge_method는 현재 지원되지 않습니다. 현재 CORS pre-flight 요청(OPTIONS)은 지원되지 않습니다.

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

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

이 code를 액세스 토큰으로 교환합니다.

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

이 끝점은 다음 입력 매개 변수를 사용합니다.

매개 변수 이름	Type	필수 여부	설명
client_id	string	필수	OAuth app에 사용하기 위해 GitHub Enterprise Server에서 받은 클라이언트 ID입니다.
client_secret	string	Required	OAuth app에 사용하기 위해 GitHub Enterprise Server에서 받은 클라이언트 암호입니다.
code	string	Required	1단계에 대한 응답으로 받은 코드입니다.
redirect_uri	string	매우 권장	권한 부여 후 사용자가 전송되는 애플리케이션의 URL입니다. 이를 사용하여 code가 발급될 때 원래 제공된 URI와 대조하여 서비스에 대한 공격을 방지할 수 있습니다.

기본적으로 응답의 형식은 다음과 같습니다.

access_token=gho_16C7e42F292c6912E7710c838347Ae178B4a&scope=repo%2Cgist&token_type=bearer

Accept 헤더에 형식을 제공하는 경우 다른 형식으로 응답을 받을 수도 있습니다. 예를 들어 Accept: application/json 또는 Accept: application/xml입니다.

Accept: application/json
{
  "access_token":"gho_16C7e42F292c6912E7710c838347Ae178B4a",
  "scope":"repo,gist",
  "token_type":"bearer"
}

Accept: application/xml
<OAuth>
  <token_type>bearer</token_type>
  <scope>repo,gist</scope>
  <access_token>gho_16C7e42F292c6912E7710c838347Ae178B4a</access_token>
</OAuth>

3. 액세스 토큰을 사용하여 API에 액세스

액세스 토큰을 사용하면 사용자를 대신하여 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

액세스 토큰을 받을 때마다 토큰을 사용하여 사용자의 ID 유효성을 다시 검사해야 합니다. 사용자는 앱에 권한을 부여하기 위해 로그인할 때 로그인한 계정을 변경할 수 있으며, 로그인할 때마다 사용자 ID의 유효성을 검사하지 않으면 사용자 데이터가 혼용될 위험이 있습니다.

디바이스 흐름

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

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

디바이스 흐름 개요

1. 앱은 디바이스 및 사용자 확인 코드를 요청하고 사용자가 사용자 확인 코드를 입력할 권한 부여 URL을 가져옵니다.
2. 앱은 사용자에게 http(s)://HOSTNAME/login/device에 사용자 확인 코드를 입력하라는 메시지를 표시합니다.
3. 앱은 사용자 인증 상태를 폴링합니다. 사용자가 디바이스에 권한을 부여하면 앱은 새 액세스 토큰으로 API 호출을 수행할 수 있습니다.

1단계: 앱이 GitHub에서 디바이스 및 사용자 확인 코드를 요청합니다.

POST http(s)://HOSTNAME/login/device/code

앱은 사용자에게 다음 단계에서 인증하라는 메시지를 표시하는 데 사용할 사용자 확인 코드 및 확인 URL을 요청해야 합니다. 또한 이 요청은 앱이 액세스 토큰을 수신하고 사용자 인증 상태를 확인하는 데 사용해야 하는 디바이스 확인 코드를 반환합니다.

끝점은 다음 입력 매개 변수를 사용합니다.

매개 변수 이름	Type	설명
client_id	string	필수입니다. 앱에 사용하기 위해 GitHub Enterprise Server에서 받은 클라이언트 ID입니다.
scope	string	앱이 액세스를 요청하는 범위의 공백으로 구분된 목록입니다. 자세한 내용은 OAuth 앱에 대한 범위을(를) 참조하세요.

기본적으로 응답의 형식은 다음과 같습니다.

device_code=3584d83530557fdd1f46af8289938c8ef79f9dc5&expires_in=900&interval=5&user_code=WDJB-MJHT&verification_uri=https%3A%2F%2FHOSTNAME%2Flogin%2Fdevice

매개 변수 이름	Type	설명
device_code	string	디바이스 확인 코드는 40자이며 디바이스를 확인하는 데 사용됩니다.
user_code	string	사용자가 브라우저에서 코드를 입력할 수 있도록 사용자 확인 코드가 디바이스에 표시됩니다. 이 코드는 8자이며 중간에 하이픈이 있습니다.
verification_uri	string	사용자가 user_code를 입력해야 하는 확인 URL( http(s)://HOSTNAME/login/device)입니다.
expires_in	integer	device_code 및 user_code의 만료 전 시간(초)입니다. 기본값은 900초(또는 15분)입니다.
interval	integer	디바이스 권한 부여를 완료하려면 새 액세스 토큰을 요청하기 전에 경과해야 하는 최소 시간(초)입니다(POST http(s)://HOSTNAME/login/oauth/access_token). 예를 들어 간격이 5이면 5초가 지나야 새로 요청할 수 있습니다. 5초 동안 두 번 이상 요청하면 속도 제한에 도달하면서 slow_down 오류를 수신합니다.

Accept 헤더에 형식을 제공하는 경우 다른 형식으로 응답을 받을 수도 있습니다. 예를 들어 Accept: application/json 또는 Accept: application/xml입니다.

Accept: application/json
{
  "device_code": "3584d83530557fdd1f46af8289938c8ef79f9dc5",
  "user_code": "WDJB-MJHT",
  "verification_uri": "http(s)://HOSTNAME/login/device",
  "expires_in": 900,
  "interval": 5
}

Accept: application/xml
<OAuth>
  <device_code>3584d83530557fdd1f46af8289938c8ef79f9dc5</device_code>
  <user_code>WDJB-MJHT</user_code>
  <verification_uri>http(s)://HOSTNAME/login/device</verification_uri>
  <expires_in>900</expires_in>
  <interval>5</interval>
</OAuth>

2단계: 사용자에게 브라우저에서 사용자 코드를 입력하라는 메시지를 표시합니다.

디바이스에 사용자 확인 코드가 표시되고 http(s)://HOSTNAME/login/device에 코드를 입력하라는 메시지가 표시됩니다.

3단계: 앱이 GitHub를 폴링하여 사용자가 디바이스에 권한을 부여했는지 확인합니다.

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

디바이스 및 사용자 코드가 만료되거나 사용자가 유효한 사용자 코드로 앱에 권한을 성공적으로 부여할 때까지 앱은 POST http(s)://HOSTNAME/login/oauth/access_token을 폴링하는 디바이스 권한 부여 요청을 합니다. 앱이 속도 제한 오류를 방지하려면 1단계에서 검색된 최소 폴링 interval을 사용해야 합니다. 자세한 내용은 디바이스 흐름에 대한 속도 제한을 참조하세요.

사용자는 15분(또는 900초) 이내에 유효한 코드를 입력해야 합니다. 15분이 지나면 POST http(s)://HOSTNAME/login/device/code를 사용하여 새 디바이스 권한 부여 코드를 요청해야 합니다.

사용자가 권한을 부여하면 앱은 사용자를 대신하여 API에 요청하는 데 사용할 수 있는 액세스 토큰을 받게 됩니다.

끝점은 다음 입력 매개 변수를 사용합니다.

매개 변수 이름	Type	설명
client_id	string	필수입니다. OAuth app에 사용하기 위해 GitHub Enterprise Server에서 받은 클라이언트 ID입니다.
device_code	string	필수입니다. POST http(s)://HOSTNAME/login/device/code 요청에서 받은 device_code입니다.
grant_type	string	필수입니다. 권한 부여 유형은 urn:ietf:params:oauth:grant-type:device_code이어야 합니다.

기본적으로 응답의 형식은 다음과 같습니다.

access_token=gho_16C7e42F292c6912E7710c838347Ae178B4a&token_type=bearer&scope=repo%2Cgist

Accept 헤더에 형식을 제공하는 경우 다른 형식으로 응답을 받을 수도 있습니다. 예를 들어 Accept: application/json 또는 Accept: application/xml입니다.

Accept: application/json
{
 "access_token": "gho_16C7e42F292c6912E7710c838347Ae178B4a",
  "token_type": "bearer",
  "scope": "repo,gist"
}

Accept: application/xml
<OAuth>
  <access_token>gho_16C7e42F292c6912E7710c838347Ae178B4a</access_token>
  <token_type>bearer</token_type>
  <scope>gist,repo</scope>
</OAuth>

디바이스 흐름의 속도 제한

사용자가 브라우저에서 확인 코드를 제출하는 경우 애플리케이션당 1시간에 50개의 제출 속도 제한이 있습니다.

요청 간에 필요한 최소 기간 내(또는 interval)에 둘 이상의 액세스 토큰 요청(POST http(s)://HOSTNAME/login/oauth/access_token)을 하는 경우 속도 제한에 도달하고 slow_down 오류 응답을 수신하게 됩니다. slow_down 오류 응답은 마지막 interval에 5초를 추가합니다. 자세한 내용은 디바이스 흐름의 오류 코드를 참조하세요.

디바이스 흐름의 오류 코드

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

자세한 내용은 OAuth 2.0 디바이스 권한 부여를 참조하세요.

비 웹 애플리케이션 흐름

비 웹 인증은 테스트와 같은 제한된 상황에서 사용할 수 있습니다. 필요한 경우 기본 인증을 사용하여 personal access token의 설정 페이지를 사용하여 personal access token을(를) 만들 수 있습니다. 이 방법으로 사용자는 언제든지 액세스를 철회할 수 있습니다.

리디렉션 URL

redirect_uri 매개 변수는 선택 사항입니다. 매개 변수가 제외되는 경우 GitHub는 OAuth app 설정에 구성된 콜백 URL로 사용자를 리디렉션합니다. 반면 매개 변수가 제공되는 경우 리디렉션 URL의 호스트(서브 도메인 제외) 및 포트가 콜백 URL과 정확히 일치해야 합니다. 리디렉션 URL의 경로는 콜백 URL의 하위 디렉터리를 참조해야 합니다.

CALLBACK: http://example.com/path

GOOD: http://example.com/path
GOOD: http://example.com/path/subdir/other
GOOD: http://oauth.example.com/path
GOOD: http://oauth.example.com/path/subdir/other
BAD:  http://example.com/bar
BAD:  http://example.com/
BAD:  http://example.com:8080/path
BAD:  http://oauth.example.com:8080/path
BAD:  http://example.org

루프백 리디렉션 URL

선택적 redirect_uri 매개 변수는 데스크톱 컴퓨터에서 실행되는 원시 애플리케이션에 유용한 루프백 URL에도 사용할 수 있습니다. 애플리케이션이 루프백 URL 및 포트를 지정하는 경우 애플리케이션에 권한을 부여한 후 사용자는 제공된 URL 및 포트로 리디렉션됩니다. redirect_uri은 앱의 콜백 URL에 지정된 포트와 일치할 필요가 없습니다.

http://127.0.0.1/path 콜백 URL의 경우 애플리케이션이 1234 포트에서 수신 대기 중이면 해당 redirect_uri을(를) 사용할 수 있습니다.

http://127.0.0.1:1234/path

OAuth RFC는 루프백 리터럴 127.0.0.1 또는 IPv6 ::1을 사용하고 localhost를 사용하지 않는 것이 좋습니다.

OAuth apps용으로 여러 개의 토큰 만들기

사용자/애플리케이션/범위 조합에 여러 토큰을 만들어 특정 사용 사례를 위한 토큰을 만들 수 있습니다.

이는 OAuth app이(가) 로그인에 GitHub를 사용하고 기본 사용자 정보만 필요한 단일 워크플로를 지원하는 경우에 유용합니다. 다른 워크플로에서는 사용자의 프라이빗 리포지토리에 액세스해야 할 수 있습니다. OAuth app은(는) 여러 토큰을 사용해 필요한 범위만 요청하여 사용 사례마다 웹 흐름을 수행할 수 있습니다. 사용자가 애플리케이션을 사용하여 로그인하는 경우 OAuth app에 프라이빗 리포지토리에 대한 액세스 권한을 부여할 필요가 없습니다.

사용자/애플리케이션/범위 조합별로 발급되는 토큰은 10개로 제한되며, 시간당 만들어지는 트래픽률 제한은 10개입니다. 애플리케이션이 동일한 사용자 및 동일한 범위에 대해 10개 이상의 토큰을 만드는 경우 동일한 사용자/애플리케이션/범위 조합에서 가장 오래된 토큰이 철회됩니다. 그러나 시간당 트래픽률 제한에 도달하면 가장 오래된 토큰이 철회되지 않습니다. 대신 브라우저 내에서 다시 권한 부여 프롬프트를 트리거하여 사용자에게 앱에 부여하는 권한을 재확인하도록 요청합니다. 앱이 1시간 이내에 사용자로부터 10개의 토큰을 요청할 이유가 거의 없거나 전혀 없는 만큼, 이 프롬프트는 앱 작동 중단의 원인이 되는 잠재적인 무한 루프를 방지하기 위한 것입니다.

사용자에게 액세스 권한을 검토하도록 지시

OAuth app에 대한 권한 부여 정보에 연결하면 사용자가 애플리케이션 권한 부여를 검토하고 철회할 수 있습니다.

연결 링크를 빌드하려면 애플리케이션을 등록할 때 GitHub에서 받은 OAuth app client_id가 필요합니다.

http(s)://HOSTNAME/settings/connections/applications/:client_id

문제 해결

• 권한 부여 요청 오류 문제 해결
• OAuth 앱 액세스 토큰 요청 오류 문제 해결
• 디바이스 흐름 오류
• 토큰 만료 및 해지

추가 참고 자료

• GitHub에 대한 인증 정보