필요한 최소 권한을 선택하기
GitHub App을 등록할 때 GitHub App에 필요한 최소 권한을 선택합니다. 앱의 키 또는 토큰 중 하나라도 손상되면 발생할 수 있는 손상의 양을 제한합니다. 권한 선택 방법에 대한 자세한 내용은 "GitHub 앱의 권한 선택"를 참조하세요.
GitHub App에서 설치 액세스 토큰 또는 사용자 액세스 토큰을 만들 때 앱이 액세스할 수 있는 리포지토리와 토큰에 있는 권한을 추가로 제한할 수 있습니다. 자세한 내용은 "GitHub 앱에 대한 설치 액세스 토큰 생성" 및 "GitHub 앱에 대한 사용자 액세스 토큰 생성"을 참조하세요.
트래픽률 제한 내에서 유지
데이터에 대한 API를 폴링하는 대신 웹후크 이벤트를 구독합니다. 이렇게 하면 GitHub App을 API 트래픽률 제한 내에서 유지하는 데 도움이 됩니다. 자세한 내용은 "GitHub 앱에 웹후크 사용" 및 "웹후크 이벤트에 응답하는 GitHub 앱 빌드"을 참조하세요.
트래픽률 제한 내에서 유지하는 데 도움이 되도록 조건부 요청을 사용하는 것이 좋습니다. 조건부 요청에 대한 자세한 내용은 "REST API 사용에 대한 모범 사례"을 참조하세요.
가능하면 트래픽률 제한 내에서 유지하기 위해 REST API 요청 대신 통합된 GraphQL 쿼리를 사용하는 것이 좋습니다. 자세한 내용은 "GitHub의 REST API 및 GraphQL API 비교" 및 "GitHub GraphQL API 설명서"을 참조하세요.
트래픽률 제한에 도달했는데 API 요청을 다시 시도해야 하는 경우 x-ratelimit-reset 또는 Retry-After 응답 헤더를 사용합니다. 이러한 헤더를 사용할 수 없는 경우 재시도 사이에 기하급수적으로 증가하는 시간을 기다렸다가 특정 횟수의 재시도 후 오류를 throw합니다. 자세한 내용은 "REST API 사용에 대한 모범 사례"을(를) 참조하세요.
앱의 자격 증명 보호
GitHub App에 대한 프라이빗 키 및 클라이언트 비밀을 생성할 수 있습니다. 이러한 자격 증명을 사용하여 앱은 설치 액세스 토큰, 사용자 액세스 토큰 및 새로 고침 토큰을 생성할 수 있습니다. 이러한 토큰은 앱 설치 또는 사용자를 대신하여 API 요청을 만드는 데 사용할 수 있습니다.
이러한 자격 증명을 안전하게 저장해야 합니다. 스토리지 메커니즘은 통합 아키텍처 및 실행되는 플랫폼에 따라 달라집니다. 일반적으로 사용 중인 플랫폼에 중요한 데이터를 저장하기 위한 스토리지 메커니즘을 사용해야 합니다.
프라이빗 키
GitHub App의 프라이빗 키는 앱이 설치된 모든 계정에 대한 액세스 권한을 부여합니다.
GitHub App의 프라이빗 키를 Azure Key Vault와 같은 키 자격 증명 모음에 저장하고 서명 전용으로 만드는 것이 좋습니다.
또는 키를 환경 변수로 저장할 수 있습니다. 그러나 키 자격 증명 모음에 키를 저장하는 것만큼 강력하지는 않습니다. 공격자가 환경에 액세스하는 경우 프라이빗 키를 읽고 GitHub App(으)로 영구 인증을 받을 수 있습니다.
코드가 프라이빗 리포지토리에 저장된 경우에도 절대 앱에서 프라이빗 키를 하드 코딩해서는 안 됩니다. 앱이 네이티브 클라이언트, 클라이언트 쪽 앱 또는 사용자 디바이스에서 실행되는 경우(서버에서 실행되지 않음) 절대 앱과 함께 프라이빗 키를 제공해서는 안 됩니다.
필요한 것보다 더 많은 프라이빗 키를 생성해서는 안 됩니다. 더 이상 필요하지 않은 프라이빗 키는 삭제해야 합니다. 자세한 내용은 "GitHub 앱에 대한 프라이빗 키 관리"을(를) 참조하세요.
클라이언트 암호
클라이언트 암호는 앱이 디바이스 흐름을 사용하지 않는 한 앱에 대한 사용자 액세스 토큰을 생성하는 데 사용됩니다. 자세한 내용은 "GitHub 앱에 대한 사용자 액세스 토큰 생성"을(를) 참조하세요.
앱이 웹 사이트 또는 웹앱인 경우 클라이언트 암호를 Azure Key Vault와 같은 키 자격 증명 모음에 저장하거나 서버의 암호화된 환경 변수 또는 암호로 저장하는 것이 좋습니다.
앱이 네이티브 클라이언트, 클라이언트 쪽 앱이거나 사용자 디바이스에서 실행되는 경우 (서버에서 실행되지 않음) 클라이언트 암호를 보호할 수 없습니다. 앱에서 생성된 토큰을 기반으로 고유의 서비스에 대한 액세스를 제어하려는 경우 누구나 클라이언트 암호에 액세스하여 토큰을 생성할 수 있으므로 주의해야 합니다.
설치 액세스 토큰, 사용자 액세스 토큰 및 새로 고침 토큰
설치 액세스 토큰은 앱 설치를 대신하여 API 요청을 만드는 데 사용됩니다. 사용자 액세스 토큰은 사용자를 대신하여 API 요청을 만드는 데 사용됩니다. 새로 고침 토큰은 사용자 액세스 토큰을 다시 생성하는 데 사용됩니다. 앱은 프라이빗 키를 사용하여 설치 액세스 토큰을 생성할 수 있습니다. 앱은 클라이언트 암호를 사용하여 사용자 액세스 토큰 및 새로 고침 토큰을 생성할 수 있습니다.
앱이 웹 사이트 또는 웹앱인 경우 백 엔드에서 토큰을 암호화하고 토큰에 액세스할 수 있는 시스템과 관련된 보안이 있는지 확인해야 합니다. 활성 액세스 토큰과 별도의 위치에 새로 고침 토큰을 저장하는 것이 좋습니다.
앱이 네이티브 클라이언트, 클라이언트 쪽 앱 또는 사용자 디바이스에서 실행되는 경우(서버에서 실행되지 않음) 서버에서 실행되는 앱만큼 토큰을 보호하지 못할 수 있습니다. 이렇게 하려면 프라이빗 키가 필요하므로 설치 액세스 토큰을 생성해서는 안 됩니다. 대신 사용자 액세스 토큰을 생성해야 합니다. 앱 플랫폼에 권장되는 메커니즘을 통해 토큰을 저장해야 하며, 스토리지 메커니즘이 완전히 안전하지 않을 수 있다는 점에 유의해야 합니다.
적절한 토큰 형식 사용하기
GitHub Apps은 인증된 API 요청을 만들기 위해 설치 액세스 토큰 또는 사용자 액세스 토큰을 생성할 수 있습니다.
설치 액세스 토큰은 앱에 대한 작업의 특성을 지정합니다. 이는 사용자와 독립적으로 작동하는 자동화에 유용합니다.
사용자 액세스 토큰은 사용자와 앱에 대한 작업의 특성을 지정합니다. 이는 사용자 입력을 기반으로 하거나 사용자를 대신하여 작업을 수행하는 데 유용합니다.
설치 액세스 토큰은 GitHub App의 권한 및 액세스에 따라 제한됩니다. 사용자 액세스 토큰은 GitHub App의 권한 및 액세스와 사용자의 권한 및 액세스 모두에 따라 제한됩니다. 따라서 GitHub App이(가) 사용자를 대신하여 작업을 수행하는 경우 설치 액세스 토큰 대신 항상 사용자 액세스 토큰을 사용해야 합니다. 그렇지 않으면 앱에서 표시되면 안되거나 할 수 없는 작업을 사용자가 보거나 수행할 수 있도록 허용할 수 있습니다.
앱은 인증을 위해 personal access token 또는 GitHub 암호를 사용하면 안 됩니다.
철저하고 지속성 있는 권한 부여
사용자에 로그인한 후 앱 개발자는 사용자가 시스템의 데이터에 액세스할 수 있도록 추가 단계를 수행해야 합니다. 각 로그인에는 멤버십, 액세스 및 현재 SSO 상태에 대한 새로운 검사가 필요합니다.
사용자를 저장하기 위해 내구성이 뛰어나고 고유한 id를 사용합니다.
사용자가 로그인하여 애플리케이션에서 작업을 수행하는 경우 다음에 로그인할 때 동일한 리소스에 대한 액세스 권한을 부여하기 위해 해당 작업을 수행한 사용자를 기억해야 합니다.
데이터베이스에 사용자를 올바르게 저장하려면 항상 사용자의 id를 사용합니다. 이 값은 사용자에 대해 변경되지 않거나 다른 사용자를 가리키는 데 사용되지 않으므로 원하는 사용자에 대한 액세스를 제공합니다. GET /user REST API 엔드포인트를 사용하여 사용자의 id를 찾을 수 있습니다. "사용자에 대한 REST API 엔드포인트" 항목을 참조하세요.
리포지토리, 조직 및 기업에 대한 참조를 저장하는 경우 해당 id를 사용하고 링크가 정확하게 유지되도록 합니다.
사용자 핸들, 조직 슬러그 또는 이메일 주소를 포함하여 시간이 지남에 따라 변경할 수 있는 식별자를 사용하지 마세요.
모든 새 인증에 대한 조직 액세스 유효성 검사
사용자 액세스 토큰을 사용하는 경우 토큰에 권한이 부여된 조직을 추적해야 합니다. 조직에서 SAML SSO를 사용하고 사용자가 SAML SSO를 수행하지 않은 경우 사용자 액세스 토큰은 해당 조직에 액세스할 수 없습니다. GET /user/installations REST API 엔드포인트를 사용하여 사용자 액세스 토큰이 액세스할 수 있는 조직을 확인할 수 있습니다. 사용자가 조직에 액세스할 권한이 없는 경우 SAML SSO를 수행할 때까지 해당 애플리케이션 내에서 조직 소유 데이터에 대한 액세스를 방지해야 합니다. 자세한 내용은 "GitHub App 설치에 대한 REST API 엔드포인트"을(를) 참조하세요.
조직 및 엔터프라이즈 컨텍스트를 사용하여 사용자 데이터 저장
id 필드를 통해 사용자 ID를 추적하는 것 외에도 각 사용자가 운영하는 조직 또는 엔터프라이즈에 대한 데이터를 유지해야 합니다. 이렇게 하면 사용자가 역할을 전환하는 경우 중요한 정보가 누출되지 않도록 할 수 있습니다.
예시:
- 사용자는 SAML SSO가 필요한
Mona조직에 있으며 SSO를 수행한 후 앱에 로그인합니다. 이제 앱은 사용자가Mona내에서 수행하는 모든 항목에 액세스할 수 있습니다. - 사용자는
Mona의 리포지토리에서 많은 코드를 가져와서 분석을 위해 앱에 저장합니다. - 나중에 사용자가 작업을 전환하고
Mona조직에서 제거됩니다.
사용자가 앱에 액세스할 때 사용자 계정에서 Mona 조직의 코드 및 분석을 계속 볼 수 있나요?
따라서 앱이 저장하는 데이터의 원본을 추적하는 것이 중요합니다. 그렇지 않으면 앱이 조직에 대한 데이터 보호 위협이며 앱이 데이터를 올바르게 보호한다고 신뢰할 수 없는 경우 앱을 금지할 수 있습니다.
토큰 만료
GitHub에서는 만료되는 사용자 액세스 토큰을 사용하는 것이 좋습니다. 만료되었지만 이 기능을 다시 사용하도록 설정하려는 사용자 액세스 토큰 사용을 이전에 옵트아웃한 경우 "GitHub 앱의 선택적 기능 활성화"을 참조하세요.
설치 액세스 토큰은 1시간 후에 만료되고, 만료되는 사용자 액세스 토큰은 8시간 후에 만료되며, 새로 고침 토큰은 6개월 후에 만료됩니다. 그러나 토큰이 더 이상 필요하지 않은 즉시 토큰을 철회할 수도 있습니다. 자세한 내용은 "DELETE /installation/token" 항목을 참조하여 설치 액세스 토큰을 철회하고 "DELETE /applications/{client_id}/token" 항목을 참조하여 사용자 액세스 토큰을 철회할 수 있습니다.
토큰 캐시
사용자 액세스 토큰 및 설치 액세스 토큰은 만료될 때까지 사용됩니다. 만든 토큰을 캐시해야 합니다. 새 토큰을 만들기 전에 캐시를 검사하여 유효한 토큰이 이미 있는지 확인합니다. 토큰을 다시 사용하면 토큰 생성에 더 적은 수의 요청을 수행하기 때문에 앱이 더 빨라집니다.
보안 위반을 처리하기 위한 계획 수립
보안 위반을 적시에 처리할 수 있도록 계획이 있어야 합니다.
앱의 프라이빗 키 또는 비밀이 손상된 경우 새 키 또는 비밀을 생성하고, 새 키 또는 비밀을 사용하도록 앱을 업데이트하며, 이전 키 또는 비밀을 삭제해야 합니다.
설치 액세스 토큰, 사용자 액세스 토큰 또는 새로 고침 토큰이 손상된 경우 이러한 토큰을 즉시 철회해야 합니다. 자세한 내용은 "DELETE /installation/token" 항목을 참조하여 설치 액세스 토큰을 철회하고 "DELETE /applications/{client_id}/token" 항목을 참조하여 사용자 액세스 토큰을 철회할 수 있습니다.
정기적인 취약성 검사 수행
앱에 대한 정기적인 약점 검사를 수행해야 합니다. 예를 들어 앱의 코드를 호스트하는 리포지토리에 대한 코드 검사 및 비밀 검사를 설정할 수 있습니다. 자세한 내용은 "코드 검사 정보" 및 비밀 검사 정보을 참조하세요.
적절한 환경 선택하기
앱이 서버에서 실행되는 경우 서버 환경이 안전한지, 앱에서 예상하는 트래픽 양을 처리할 수 있는지 확인합니다.
최소 웹후크 구독하기
앱에 필요한 웹후크 이벤트만 구독합니다. 이렇게 하면 앱이 필요하지 않은 페이로드를 받지 않으므로 대기 시간을 줄이는 데 도움이 됩니다.
웹후크 비밀 사용하기
GitHub App에 대한 웹후크 비밀을 설정하고 들어오는 웹후크 이벤트의 서명이 비밀과 일치하는지 확인해야 합니다. 이렇게 하면 들어오는 웹후크 이벤트가 유효한 GitHub 이벤트인지 확인하는 데 도움이 됩니다.
자세한 내용은 "GitHub 앱에 웹후크 사용"을(를) 참조하세요. 예는 "웹후크 이벤트에 응답하는 GitHub 앱 빌드"을(를) 참조하세요.
사용자가 새 권한을 수락할 시간 허용하기
GitHub App에 리포지토리 또는 조직 권한을 추가하면 개인 계정 또는 조직에 앱을 설치한 사용자는 새 권한을 검토하라는 이메일을 받게 됩니다. 사용자가 새 권한을 승인할 때까지 앱 설치는 이전 권한만 받습니다.
권한을 업데이트할 때 사용자에게 새 권한을 수락할 시간을 주기 위해 앱을 이전 버전과 호환되도록 하는 것이 좋습니다. new_permissions_accepted 작업 속성과 함께 설치 웹후크를 사용하여 사용자가 앱에 대한 새 권한을 수락하는 시기를 알 수 있습니다.
안전한 방식으로 서비스 사용하기
앱에서 제3자 서비스를 사용하는 경우 안전한 방식으로 사용해야 합니다.
- 앱에서 사용되는 모든 서비스에는 고유한 로그인 및 암호가 있어야 합니다.
- 앱은 SaaS 서비스를 관리하기 위해 이메일 또는 데이터베이스 서비스와 같은 서비스 계정을 공유해서는 안 됩니다.
- 관리 업무를 수행하는 직원만 앱을 호스트하는 인프라에 대한 관리자 액세스 권한을 가져야 합니다.
로깅 및 모니터링 추가
앱에 대한 로깅 및 모니터링 기능을 추가하는 것이 좋습니다. 보안 로그에는 다음이 포함될 수 있습니다.
- 인증 및 권한 부여 이벤트
- 서비스 구성 변경 내용
- 데이터 읽기 및 쓰기
- 사용자 및 그룹 권한 변경
- 관리자로 역할 상승
로그는 각 이벤트에 대해 일관된 타임스탬프를 사용해야 하며 기록된 모든 이벤트에 대한 사용자, IP 주소, 호스트 이름을 기록해야 합니다.
데이터 삭제 활성화
GitHub App을 다른 사용자 또는 조직에서 사용할 수 있는 경우 사용자와 조직 소유자 데이터를 삭제할 수 있는 방법을 제공해야 합니다. 사용자가 데이터를 삭제하기 위해 지원 담당자에게 이메일을 보내거나 전화를 걸 필요가 없어야 합니다.