OAuth apps에서 GitHub Apps(으)로 마이그레이션할 경우의 혜택
GitHub Apps은(는) GitHub와 마이그레이션하는 데 권장되는 방법입니다. GitHub Apps은(는) OAuth apps에 비해 다음을 포함한 많은 이점을 제공합니다.
- 세분화된 사용 권한, 리포지토리 액세스에 대한 선택 및 단기 실행 토큰과 같은 향상된 보안 기능
- 사용자와 독립적으로 또는 사용자를 대신하여 작업할 수 있는 기능
- 확장성 있는 트래픽률 제한
- 기본 제공 웹후크
자세한 내용은 "GitHub 앱 만들기 정보"을(를) 참조하세요.
OAuth app을(를) GitHub App(으)로 변환
다음 단계에서는 OAuth app에서 GitHub App(으)로 마이그레이션하는 방법에 대한 개요를 제공합니다. 특정 단계는 앱에 따라 달라집니다.
1. OAuth apps의 검토
OAuth app에 대한 코드를 다시 숙지합니다. OAuth app에 대한 API 요청은 GitHub App에 대해 선택할 권한을 결정하는 데 도움이 됩니다.
또한 OAuth apps에 사용할 수 없는 몇 가지 REST API 엔드포인트가 있습니다. "GitHub 앱 설치 액세스 토큰에 사용할 수 있는 엔드포인트" 을 검토하여 GitHub Apps에 사용하는 REST 엔드포인트를 사용할 수 있는지 확인합니다.
2. GitHub App 등록
새료운 GitHub App 등록 자세한 내용은 "GitHub 앱 등록"을(를) 참조하세요.
OAuth app에 비해 GitHub App 설정을 더 잘 제어할 수 있습니다. 몇 가지 주요 추가 사항은 다음과 같습니다.
-
항상 사용자를 대신하는 OAuth app 와(과) 달리 GitHub App에서 사용자로 혹은 사용자 대신 동작을 수행하게 할 수 있습니다. 새 GitHub App이(가) 사용자를 대신하여 동작을 수행하지 않도록 하려면 "사용자 식별 및 권한 부여" 설정을 건너뛸 수 있습니다. 자세한 내용은 "GitHub 앱을 사용한 인증 정보"을(를) 참조하세요.
-
웹후크를 사용하여 특정 이벤트가 발생할 때 GitHub App에 알릴 수 있습니다. 각 리포지토리 또는 조직의 API를 통해 구성해야 하는 OAuth apps의 웹후크와 달리 웹후크는 GitHub Apps에 기본 제공됩니다. GitHub App을(를) 등록할 때 수신하려는 웹후크 이벤트를 선택할 수 있습니다. 또한 OAuth app에서 현재 폴링을 사용하여 이벤트가 발생했는지 확인하는 경우 대신 웹후크를 구독하여 GitHub App이(가) 트래픽률 제한 내에서 유지되도록 하는 것이 좋습니다. 자세한 내용은 "GitHub 앱에 웹후크 사용"을(를) 참조하세요.
-
OAuth app에서는 사용자가 앱에 권한을 부여할 때 범위를 요청합니다. GitHub App에서는 앱 설정에서 사용 권한을 지정합니다. 이러한 권한은 범위보다 세분화되어 있으며 앱에 필요한 권한만 선택할 수 있도록 합니다. 또한 이러한 권한은 REST API 엔드포인트 및 웹후크 이벤트에 매핑되므로 특정 REST API 엔드포인트에 액세스하거나 특정 웹후크를 구독하기 위해 GitHub App에 필요한 권한을 쉽게 확인할 수 있습니다. GraphQL 요청에 대한 사용 권한은 현재 문서화되어 있지 않습니다. 자세한 내용은 "GitHub 앱의 권한 선택"을(를) 참조하세요.
3. 앱의 코드 수정
GitHub App을(를) 등록한 후 이전 OAuth app의 코드를 조정하여 새 GitHub App을(를) 사용합니다.
인증 업데이트
GitHub App에 대한 API 인증을 처리하도록 앱의 코드를 업데이트해야 합니다. GitHub App은(는) 다음과 같은 세 가지 방법으로 인증할 수 있습니다.
- 앱 자체로서 GitHub App 등록에 대한 세부 정보를 가져오거나 수정합니다. 또는 설치 액세스 토큰을 만듭니다. 자세한 내용은 "GitHub 앱으로 인증"을(를) 참조하세요.
- 앱 설치는 스스로를 대신하여 동작을 수행합니다. 자세한 내용은 "GitHub 앱 설치로 인증"을(를) 참조하세요.
- 사용자를 대신하여 사용자에게 작업을 할당합니다. 자세한 내용은 "사용자를 대신하여 GitHub 앱으로 인증"을(를) 참조하세요.
GitHub의 공식 Octokit.js 라이브러리를 사용하는 경우 기본 제공 App 개체를 사용하여 인증할 수 있습니다. 예는 "REST API 및 JavaScript를 사용하여 스크립팅" 및 "웹후크 이벤트에 응답하는 GitHub 앱 빌드"을(를) 참조하세요.
트래픽률 제한 검토
OAuth apps 와 GitHub Apps의 트래픽률 제한 차이를 검토합니다. GitHub Apps은(는) 트래픽률 제한의 슬라이딩 규칙을 사용하며 이는 조직의 리포지토리 및 사용자 수에 따라 증가할 수 있습니다. 자세한 내용은 "GitHub 앱의 트래픽률 제한"을(를) 참조하세요.
가능하면 트래픽률 제한 내에서 유지하는 데 도움이 되도록 폴링 대신 조건부 요청을 사용하고 웹후크를 구독하는 것이 좋습니다. 조건부 요청에 관한 자세한 내용은 "REST API 사용에 대한 모범 사례"을(를) 참조하세요. GitHub App에서 웹후크를 사용하는 방법에 대한 자세한 내용은 "GitHub 앱에 웹후크 사용" 및 "웹후크 이벤트에 응답하는 GitHub 앱 빌드"을(를) 참조하세요.
코드 테스트
새 GitHub App을(를) 테스트하여 코드가 예상대로 작동하는지 확인합니다.
4. 새 GitHub App 공개
다른 계정에서 새 GitHub App을(를) 사용할 수 있도록 하려면 앱이 공개되어 있는지 확인합니다. 자세한 내용은 "공개 또는 비공개 GitHub 앱 만들기"을(를) 참조하세요.
5. 사용자에게 마이그레이션 지시
새 GitHub App이(가) 준비되면 이전 OAuth app의 사용자에게 새 GitHub App으(로) 마이그레이션하도록 지시합니다. 사용자를 자동으로 마이그레이션하는 방법은 없습니다. 각 사용자는 GitHub App을(를) 직접 설치하거나 권한을 부여해야 합니다.
앱 소유자는 사용자가 새 GitHub App을(를) 설치/승인하고 이전 OAuth app에 대한 권한 부여를 취소하도록 권장하는 작업 호출을 포함해야 합니다. 설명서 또는 사용자 인터페이스 요소도 업데이트해야 합니다.
GitHub App을(를) 설치하라는 프롬프트를 사용자에게 표시합니다.
GitHub App을(를) 대신하여 API 요청을 하거나 조직 또는 리포지토리 리소스에 액세스하려면 사용자가 GitHub App을(를) 설치해야 합니다. 사용자가 계정 또는 조직에 GitHub App을(를) 설치할 때 앱이 액세스할 수 있는 리포지토리를 선택하고 앱에 요청한 조직 및 리포지토리 권한을 부여합니다.
사용자가 GitHub App을(를) 설치할 수 있도록 클릭하여 GitHub App을(를) 설치할 수 있는 앱의 웹 페이지에 대한 링크를 추가할 수 있습니다. 설치 URL의 형식은 http(s)://HOSTNAME/github-apps/YOUR_APP_NAME/installations/new와 같습니다. GitHub App의 설정 페이지의 "공개 링크" 필드에서 찾을 수 있는 GitHub App의 슬러그화된 이름으로 YOUR_APP_NAME을(를) 바꿉니다.
OAuth app에서 액세스할 수 있는 리포지토리를 미리 선택하려면 설치 URL에 /permissions 및 쿼리 매개 변수를 추가할 수 있습니다. 이렇게 하면 사용자가 OAuth app에 이미 액세스할 수 있는 리포지토리에 GitHub App에 대한 액세스 권한을 부여할 수 있습니다. 쿼리 매개 변수는 다음과 같습니다.
suggested_target_id: GitHub App을(를) 설치하는 사용자 또는 조직의 ID입니다. 이 매개 변수는 필수입니다.repository_ids[]: 설치를 위해 선택할 리포지토리 ID입니다. 생략되는 경우 모든 리포지토리를 선택합니다. 미리 선택할 수 있는 최대 리포지토리 수는 100개입니다. OAuth app 앱에서 액세스할 수 있는 리포지토리의 목록을 얻으려면 인증된 사용자의 리포지토리 열거 및 조직 리포지토리 열거 엔드포인트를 사용합니다.
예: http(s)://HOSTNAME/github-apps/YOUR_APP_NAME/installations/new/permissions?suggested_target_id=ID_OF_USER_OR_ORG&repository_ids[]=REPO_A_ID&repository_ids[]=REPO_B_ID
GitHub Apps을(를) 설치하는 방법에 대한 자세한 내용은 "타사에서 GitHub 앱 설치" 및 "자신만의 GitHub 앱 설치" 을(를) 참조하세요.
사용자에게 앱에 권한을 부여하라는 프롬프트 표시
GitHub App에서 사용자를 대신하여 API 요청을 하려면 사용자가 앱에 권한을 부여해야 합니다. 사용자가 앱에 권한을 부여하면 앱이 대신 사용할 수 있는 권한을 부여하고 앱에서 요청한 계정 권한을 부여합니다. 앱이 조직 계정에 설치된 경우 해당 조직 내의 각 사용자는 앱이 대신 작동하도록 앱에 권한을 부여해야 합니다.
사용자에게 앱에 권한을 부여하라는 프롬프트를 표시하려면 웹 애플리케이션 흐름 또는 디바이스 흐름을 통해 사용자를 안내합니다. 자세한 내용은 "GitHub 앱에 대한 사용자 액세스 토큰 생성"을(를) 참조하세요.
자세한 내용은 GitHub Apps에서 "GitHub 앱에 권한 부여"을(를) 참조하세요.
사용자가 OAuth app 액세스를 철회하도록 권장
또한 사용자가 이전 OAuth app에 대한 액세스 권한을 철회하도록 권장해야 합니다. 이렇게 하면 OAuth app에서 완전히 전환하는 데 도움이 되며 사용자의 데이터를 안전하게 유지하는 데 도움이 됩니다. 자세한 내용은 "권한 있는 OAuth 앱 검토"을(를) 참조하세요.
인터페이스 또는 설명서 업데이트
OAuth app에서 GitHub App으(로) 변경된 내용을 반영하도록 앱과 관련된 사용자 인터페이스 또는 설명서를 업데이트해야 합니다.
6. 이전 OAuth app에 대한 웹후크 제거
사용자가 GitHub App을(를) 설치하고 리포지토리에 대한 액세스 권한을 부여하는 경우 이전 OAuth app 에 대한 웹후크를 제거해야 합니다. 새 GitHub App 및 이전 OAuth app이(가) 동일한 이벤트에 대한 웹후크에 응답하는 경우 사용자는 중복 동작을 관찰할 수 있습니다.
리포지토리 웹후크를 제거하려면 added 작업으로 installation_repositories 웹후크를 수신 대기 할 수 있습니다. GitHub App이(가) 해당 이벤트를 수신하면 REST API를 사용하여 OAuth app에 대한 리포지토리의 웹후크를 삭제할 수 있습니다. 자세한 내용은 "웹후크 이벤트 및 페이로드" 및 "리포지토리 웹후크에 대한 REST API 엔드포인트"을(를) 참조하세요.
마찬가지로 조직 웹후크를 제거하려면 created 작업으로 installation 웹후크를 수신 대기 할 수 있습니다. GitHub App이(가) 조직에 대해 해당 이벤트를 수신하면 REST API를 사용하여 해당 조직의 웹후크 및 OAuth app에 대한 해당 리포지토리를 삭제할 수 있습니다. 자세한 내용은 "웹후크 이벤트 및 페이로드", "조직 웹후크에 대한 REST API 엔드포인트", "리포지토리 웹후크에 대한 REST API 엔드포인트"을(를) 참조하세요.
7. 이전 OAuth app 삭제
사용자가 새 GitHub App으(로) 마이그레이션되면 이전 OAuth app을(를) 삭제해야 합니다. 이렇게 하면 OAuth app의 자격 증명이 남용되지 않도록 방지할 수 있습니다. 이 작업은 OAuth app 앱의 나머지 권한 부여도 모두 철회합니다. 자세한 내용은 "OAuth 앱 삭제"을(를) 참조하세요. OAuth app이(가) GitHub Marketplace에 나열된 경우 먼저 GitHub 지원에 문의하여 마켓플레이스에서 앱을 제거해야 할 수 있습니다.