🌐 OAuth 앱 만들기 모범 사례 - GitHub Docs

GitHub App을(를) 대신 사용

가능하면 OAuth app 대신 GitHub App을(를) 사용하는 것이 좋습니다. 일반적으로 GitHub Apps은(는) OAuth apps보다 선호됩니다. GitHub Apps은(는) 세분화된 사용 권한으로 사용자가 앱이 액세스할 수 있는 리포지토리를 더 잘 제어할 수 있으며 수명이 짧은 토큰을 사용합니다. 이러한 속성은 앱의 자격 증명이 유출될 경우에 발생 가능한 손상을 제한하여 앱의 보안을 강화할 수 있습니다.

OAuth apps와(과) 마찬가지로 GitHub Apps은(는) 여전히 OAuth 2.0을 사용하고 OAuth 토큰 유형(사용자 액세스 토큰)을 생성하여 사용자 대신 작업을 수행할 수 있습니다. 그러나 GitHub Apps은(는) 사용자와 독립적으로 작동할 수도 있습니다.

GitHub Apps에 대한 자세한 내용은 GitHub 앱 만들기 정보을(를) 참조하세요.

기존 OAuth app을(를) GitHub App(으)로 마이그레이션하는 방법에 대한 자세한 내용은 OAuth 앱을 GitHub 앱으로 마이그레이션을(를) 참조하세요.

최소 범위 사용

OAuth app은(는) 앱이 의도한 기능을 수행하는 데 필요한 범위만 요청해야 합니다. 앱의 토큰이 손상되면 발생할 수 있는 손상의 양이 제한됩니다. 자세한 내용은 OAuth 앱 권한 부여을(를) 참조하세요.

철저하고 지속성 있는 권한 부여

사용자에 로그인한 후 앱 개발자는 사용자가 시스템의 데이터에 액세스할 수 있도록 추가 단계를 수행해야 합니다. 각 로그인에는 멤버십, 액세스 및 현재 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 조직의 코드 및 분석을 계속 볼 수 있나요?

따라서 앱이 저장하는 데이터의 원본을 추적하는 것이 중요합니다. 그렇지 않으면 앱이 조직에 대한 데이터 보호 위협이며 앱이 데이터를 올바르게 보호한다고 신뢰할 수 없는 경우 앱을 금지할 수 있습니다.

사용자의 앱 액세스 권한 확인

사용자의 OAuth 앱에 액세스할 수 있습니다. 조직 또는 엔터프라이즈의 구성원만 앱을 사용하길 원하는 경우 사용자가 앱에 로그인할 때 사용자의 멤버 자격 상태를 검사해야 합니다.

사용자가 구성원인 조직 목록을 찾으려면 "인증된 사용자에 대한 조직 나열" 엔드포인트를 사용할 수 있습니다. 그런 다음 앱에서 승인된 조직 목록과 대조하여 이 목록의 유효성을 검사할 수 있습니다. 자세한 내용은 조직에 대한 REST API 엔드포인트을(를) 참조하세요.

앱의 자격 증명 보호

클라이언트 암호를 사용하면 앱에서 사용자에게 권한을 부여하고 사용자 액세스 토큰을 생성할 수 있습니다. 이러한 토큰은 사용자를 대신하여 API 요청을 만드는 데 사용할 수 있습니다.

앱의 클라이언트 암호와 생성된 모든 토큰을 안전하게 저장해야 합니다. 스토리지 메커니즘과 상대적 보안 수준은 통합 아키텍처 및 실행되는 플랫폼에 따라 달라질 수 있습니다. 일반적으로 사용 중인 플랫폼에 중요한 데이터를 저장하기 위한 스토리지 메커니즘을 사용해야 합니다.

클라이언트 비밀

앱이 디바이스 흐름을 사용하지 않는 한, 앱의 사용자 액세스 토큰을 생성하려면 클라이언트 비밀이 필요합니다. 자세한 내용은 OAuth 앱 권한 부여을(를) 참조하세요.

앱이 기밀 클라이언트인 경우, 클라이언트 비밀을 안전하게 유지할 수 있습니다. 이를 위해, 클라이언트 비밀을 키 자격 증명 모음(예: Azure Key Vault)에 저장하거나 암호화된 환경 변수 또는 비밀로 서버에 저장하는 것을 권장합니다.

앱이 퍼블릭 클라이언트(사용자 디바이스에서 실행되는 네이티브 앱, CLI 유틸리티, 싱글 페이지 웹 애플리케이션 등)인 경우, 클라이언트 비밀을 안전하게 보호할 수 없습니다. 애플리케이션의 코드에서 클라이언트 비밀을 제공해야 하며, PKCE를 사용하여 인증 흐름을 보다 안전하게 보호해야 합니다. 앱에서 생성한 토큰을 기반으로 자체 서비스에 대한 접근을 제한할 계획이라면 주의가 필요합니다. 퍼블릭 클라이언트는 쉽게 스푸핑이 가능하기 때문입니다. 누구나 앱의 클라이언트 ID를 재사용하여 로그인할 수 있습니다.

이유 없이 디바이스 흐름을 활성화하지 마세요.

퍼블릭 클라이언트에서 클라이언트 비밀을 사용하는 것이 우려된다면, 디바이스 흐름보다는 PKCE가 포함된 권한 부여 코드를 사용하는 것이 더 바람직합니다. 디바이스 흐름에는 리디렉션 URI가 전혀 필요하지 않으므로 공격자가 디바이스 흐름을 악용하여 원격으로 앱을 가장하는 피싱 공격을 수행할 수 있습니다. 따라서, 제약된 환경(CLI, IoT 디바이스, 헤드리스 시스템 등)에서 앱을 사용하는 경우가 아니라면 애플리케이션에 디바이스 흐름을 활성화하지 마세요.

사용자 액세스 토큰

앱이 웹 사이트 또는 웹앱인 경우 백 엔드에서 토큰을 암호화하고 토큰에 액세스할 수 있는 시스템과 관련된 보안이 있는지 확인해야 합니다. 활성 액세스 토큰과 별도의 위치에 새로 고침 토큰을 저장하는 것이 좋습니다.

앱이 네이티브 클라이언트, 클라이언트 쪽 앱 또는 사용자 디바이스에서 실행되는 경우(서버에서 실행되지 않음) 서버에서 실행되는 앱뿐만 아니라 토큰도 보호하지 못할 수 있습니다. 앱 플랫폼에 권장되는 메커니즘을 통해 토큰을 저장하고 스토리지 메커니즘의 보안이 완전하지 않을 수 있다는 점에 유의해야 합니다.