GitHub OAuth - Scopes for OAuth Apps

https://docs.github.com/en/enterprise-server@2.21/developers/apps/building-oauth-apps/scopes-for-oauth-apps

 

GitHub OAuth - Scopes for OAuth Apps

• Scope(범위)는 당신이 정확히 어떤 종류의 접근을 필요로 하는지를 구체화해준다.
• scope는 OAuth 토큰의 접근을 제한한다.
• 사용자가 가진 권한 이상의 어떤 접근도 허용하지 않는다.

깃헙 OAuth 앱을 설정할 때, 요청되는 scope들이 사용자에게 보여진다.

scope 확인하기

내가 어떤 OAuth scope를 가지고 있고, API 동작이 어떤 scope를 승인하는지 확인하기 위해서는 헤더를 보면 된다.

$ curl -H "Authorization: token OAUTH-TOKEN" http(s)://[hostname]/api/v3/users/codertocat -I
HTTP/2 200
X-OAuth-Scopes: repo, user
X-Accepted-OAuth-Scopes: user

• X-OAuth-Scopes : 내 토큰이 인증받은 scope들의 리스트.
• X-Accepted-OAuth-Scopes : (API의)동작이 확인하는 scope들의 리스트.

사용 가능한 scope들

• (no scope) (scope 없음) : 공개적인 정보에 대한 읽기 전용 권한을 승인합니다. (사용자 프로필 정보, 저장소 정보, gist를 포함합니다)
• site_admin : GitHub Enterprise Server Administration API endpoints에 대한 사이트 관리자 접근을 승인합니다.
• repo : private 저장소를 포함한 모든 저장소 접근 권한을 승인합니다. 이는 코드에 대한 읽기/쓰기 접근, 커밋 상태, 저장소와 조직(organization) 프로젝트, invitation, collaborators, team memberships 추가하기, 배포 상태, 저장소와 조직에 대한 저장소 웹훅을 포함합니다. 또한 사용자 프로젝트를 관리하는 능력도 승인합니다.
  • repo:status : public 및 private 저장소의 커밋 상태에 대한 읽기/쓰기 접근을 승인합니다. 이 scope는 코드에 대한 접근 승인 없이, 오직 다른 사용자 또는 서비스가 private 저장소의 커밋 상태에 대해 접근하도록 할 때 필요합니다.
  • repo_deployment : public 및 private 저장소의 배포 상태에 대한 접근을 승인합니다. 이 scope는 코드에 대한 접근 승인 없이, 다른 사용자 또는 서비스가 배포 상태 에 접근하도록 할 때 필요합니다.
  • public_repo : 접근 권한을 public 저장소로 제한합니다. 이는 public 저장소 및 조직에 대한 코드 읽기/쓰기 접근, 커밋 상태, 저장소 프로젝트, collaborators, 배포 상태를 포함합니다. 또한 public 저장소를 star할 때도 필요합니다.
  • repo:invite : 저장소에 collaborator 초대에 대한 수락/거절 권한을 승인합니다. 이 scope는 코드에 대한 접근 승인 없이, 다른 사용자 또는 서비스가 초대 권한에 접근하도록 할 때 필요합니다.
• admin:repo_hook : public 및 private 저장소의 저장소 훅(repository hook)에 대한 읽기, 쓰기, ping, 삭제 접근을 승인합니다. repo와 public_repo scope는 저장소 훅을 포함한 모든 저장소 접근 권한을 승인합니다. 저장소 훅에 대해서만 접근을 제한하고 싶을 때 admin:repo_hook을 사용하십시오.
  • write:repo_hook : public 및 private 저장소의 저장소 훅(repository hook)에 대한 읽기, 쓰기, ping 접근을 승인합니다.
  • read:repo_hook : public 및 private 저장소의 저장소 훅(repository hook)에 대한 읽기, ping 접근을 승인합니다.
• admin:org : 조직(organization)과 그 팀, 프로젝트, 멤버십에 대한 모든 접근 권한을 갖습니다.
  • write:org : 조직 멤버십, 조직 프로젝트, 팀 멤버십에 대한 읽기/쓰기 접근입니다.
  • read:org : 조직 멤버십, 조직 프로젝트, 팀 멤버십에 대한 읽기 전용 접근입니다.
• admin:public_key : 공개 키 (public key)에 대한 모든 접근 권한을 갖습니다.
  • write:public_key : 공개 키 (public key)에 대한 생성, 리스트, 상세보기 접근 권한을 갖습니다.
  • read:public_key : 공개 키 (public key)에 대한 리스트, 상세보기 접근 권한을 갖습니다.
• admin:org_hook : 조직 훅(organization hooks)에 대한 읽기, 쓰기, ping, 삭제 접근 권한을 승인합니다. (참고 : OAuth 토큰은 OAuth 앱에 의해 생성된 조직 훅 동작에 대해서만 실행 가능합니다. Personal access token은 사용자에 의해 생성된 조직 훅 동작을 실행할 때만 사용할 수 있습니다.)
• gist : gist에 대한 쓰기 접근을 승인합니다.
• notifications : 다음을 승인합니다 - 사용자의 notification에 대한 읽기 접근, 쓰레드에 대해 읽기 표시를 하는 접근, 저장소 접근을 보기/보지 않기, 그리고 쓰레드 구독에 대한 읽기/쓰기/삭제 접근.
• user : 프로필 정보에 대한 읽기/쓰기 접근을 승인합니다. 이 scope가 user:email과 user:follow를 포함함에 유의하십시오.
  • read:user : 사용자의 프로필 정보 읽기 접근을 승인합니다.
  • user:email : 사용자의 이메일 주소 읽기 접근을 승인합니다.
  • user:follow : 다른 사용자에 대한 follow / unfollow 접근을 승인합니다.
• delete_repo : 관리 가능한 저장소의 삭제 접근을 승인합니다.
• write:discussion : team discussion에 대한 읽기/쓰기 접근을 허용합니다.
  • read:discussion : team discussion에 대한 읽기 접근을 허용합니다.
• admin:gpg_key : GPG 키에 대한 완전한 관리 권한.
  • write:gpg_key : GPG 키에 대한 생성, 리스트, 상세보기 권한.
  • read:gpg_key : GPG 키에 대한 리스트, 상세보기 권한.

참고

당신의 OAuth 앱은 첫 리다이렉션에서 scope를 요청할 수 있습니다. %20을 공백으로 하여 여러 개의 scope를 명시할 수 있습니다:

https://github.com/login/oauth/authorize?
  client_id=...&
  scope=user%20repo_deployment

요청된 scope와 승인된 scope

scope 특성은 토큰에 대해 사용자에 의해 승인된 범위를 나타냅니다. 일반적으로, 이 범위는 당신이 요청한 것과 동일합니다. 하지만, 사용자는 그들의 scope를 수정할 수 있으며, 당신의 앱이 당신이 처음 요청한 것 보다 더 적은 접근권한을 갖도록 할 수 있습니다. 또한, 사용자는 OAuth 흐름이 완료된 후에 토큰 scope를 수정할 수 있습니다. 당신은 이 가능성에 대해 유의하며 당신의 앱의 동작을 적절히 조정해야 합니다.

당신이 처음 요청한 것보다 적은 접근권한을 승인받도록 사용자가 선택했을 때의 에러 케이스를 처리하는 것은 중요합니다. 예를 들어, 앱은 사용자에게 경고하거나 안내를 함으로써 그들이 사용할 수 있는 기능이 줄어들거나 어떤 동작을 실행할 수 없음을 알릴 수 있습니다.

또한, 앱은 사용자에게 추가적인 승인을 다시 받기 위해 OAuth 흐름으로 되돌아가도록 사용자를 보낼 수 있습니다. 하지만 사용자는 언제나 거절할 수 있음을 잊지 마십시오.

Basics of Authentication guide를 확인하십시오. 이 가이드는 수정 가능한 토큰 scope를 처리하는 팁을 제공합니다.

정규화된 scope

여러 scope들을 요청할 때, 토큰은 scope의 정규화된 리스트로 저장되며, 요청한 다른 scope에서 이미 포함하는 scope는 암묵적으로 삭제합니다. 예를 들어, user,gist,user:email 을 요청하는 것은 토큰에 user와 gist scope만을 남길 것입니다. 왜냐하면 user scope에 user:emailscope의 접근이 승인되어 있기 때문입니다.