GitHub App을 통한 GitHub 소셜 로그인을 설정하세요

GitHub App을 통합하여 GitHub로 로그인, 계정 연결, 세분화된 권한 및 리프레시 토큰을 통한 GitHub API의 안전한 접근을 활성화하세요.

팁:

이 가이드는 Logto 커넥터에 대한 기본적인 이해를 전제로 합니다. 익숙하지 않은 분들은 커넥터 가이드를 참조하여 시작하세요.

GitHub App vs OAuth App

GitHub는 인증 (Authentication) 및 API 접근을 위해 GitHub App과 OAuth App 두 가지 유형의 앱을 제공합니다. 아래 비교를 참고하여 선택하세요:

기능	GitHub App	OAuth App
권한	세분화된 권한 — 특정 리소스에만 접근 요청 가능	광범위한 스코프 — 종종 필요 이상으로 많은 접근 권한 부여
권한 관리	GitHub 대시보드에서만 설정; Logto의 Scope 필드는 비워둘 수 있음	Logto 커넥터에서 스코프를 통해 설정
리프레시 토큰	OAuth 플로우 중 항상 발급됨	지원하지 않음 — 토큰은 취소되지 않는 한 만료되지 않음
토큰 만료	액세스 토큰은 8시간 후 만료; 리프레시 토큰은 6개월간 유효	액세스 토큰은 만료되지 않음
사용자 제어	사용자가 앱이 접근할 수 있는 리포지토리를 선택 가능	사용자가 접근할 수 있는 모든 리포지토리에 접근
요청 제한	설치 수에 따라 확장되는 더 높은 요청 제한	더 낮은 요청 제한 (사용자당 시간당 5,000회)
설치	계정/조직에 설치, 리포지토리별 세분화된 접근 권한	사용자가 광범위한 접근 권한으로 승인
Webhook	내장된 중앙 집중식 Webhook 지원	각 리포지토리마다 별도로 설정 필요
독립적 동작	자체적으로 동작 가능 (서버 간)	항상 사용자를 대신하여 동작

GitHub App을 사용할 때:

• 권한 및 리포지토리 접근을 세분화하여 제어해야 할 때
• 장기적인 API 접근을 위한 리프레시 토큰이 필요할 때
• 더 높은 API 요청 제한이 필요할 때
• 사용자 세션과 독립적으로 자동화 작업을 수행해야 할 때

OAuth App을 사용할 때:

• 최소한의 API 접근만 필요한 간단한 로그인 통합
• 만료되지 않는 토큰이 필요한 경우 (레거시 통합)
• 엔터프라이즈 수준 리소스에 접근해야 할 때 (GitHub App은 아직 엔터프라이즈 권한 미지원)

팁:

GitHub는 향상된 보안 기능과 세분화된 권한 때문에 대부분의 사용 사례에서 OAuth App보다 GitHub App 사용을 권장합니다. GitHub App과 OAuth App의 차이점에 대해 자세히 알아보세요.

시작하기

GitHub App 커넥터는 OAuth 2.0 통합을 지원하여 애플리케이션에서 다음을 할 수 있습니다:

• "GitHub로 로그인" 인증 (Authentication) 추가
• 사용자 계정을 GitHub 아이덴티티에 연결
• GitHub에서 사용자 프로필 정보 동기화
• Logto Secret Vault에 안전하게 저장된 토큰을 통해 GitHub API에 접근하여 자동화 작업 수행 (예: 이슈 생성, 앱에서 리포지토리 관리)
• 리프레시 토큰(GitHub App에서 항상 발급)을 사용하여 사용자가 재인증하지 않아도 장기적인 API 접근 유지

이러한 인증 (Authentication) 기능을 설정하려면 먼저 Logto에서 GitHub 커넥터를 생성하세요:

1. Logto 콘솔 > 커넥터 > 소셜 커넥터로 이동하세요.
2. 소셜 커넥터 추가를 클릭하고, GitHub App을 선택한 후 다음을 클릭하여 단계별 튜토리얼을 따라 통합을 완료하세요.

1단계: GitHub 앱 생성하기

GitHub을 인증 (Authentication) 제공자로 사용하려면, 먼저 GitHub에서 GitHub 앱을 생성하여 OAuth 2.0 자격 증명을 얻어야 합니다.

1. GitHub에 접속하여 계정으로 로그인하거나, 필요하다면 새 계정을 만드세요.
2. 설정 > 개발자 설정 > GitHub Apps로 이동하세요.
3. New GitHub App을 클릭하여 새 애플리케이션을 등록하세요:
   • GitHub App name: 앱의 고유한 이름을 입력하세요. 이름은 34자를 초과할 수 없으며 GitHub 전체에서 고유해야 합니다.
   • Homepage URL: 애플리케이션의 홈페이지 URL을 입력하세요.
   • Callback URL: Logto GitHub 커넥터에서 Callback URI를 복사하여 여기에 붙여넣으세요. 필요하다면 여러 개의 콜백 URL을 추가할 수 있습니다. 사용자가 GitHub로 로그인하면, 인가 코드와 함께 이곳으로 리디렉션되며, Logto가 인증 (Authentication)을 완료하는 데 사용합니다.
   • Expire user authorization tokens: 이 옵션을 체크된 상태로 유지하세요 (권장). 이 설정은 토큰 만료 및 리프레시 토큰을 활성화하여 보안을 강화합니다.
   • Request user authorization (OAuth) during installation: 설치 중에 사용자가 앱을 인가하도록 요청하려면 선택적으로 체크하세요.
   • Webhook: Webhook 이벤트가 필요 없다면 Active를 체크 해제하세요. 인증 (Authentication)만 사용하는 경우, 일반적으로 Webhook은 필요하지 않습니다.
4. Permissions에서 앱에 필요한 권한을 설정하세요 (아래 2단계 참고).
5. **Where can this GitHub App be installed?**에서 모든 GitHub 계정 사용자가 인증 (Authentication)에 앱을 사용할 수 있도록 하려면 Any account를 선택하세요.
6. Create GitHub App을 클릭하여 GitHub 앱을 생성하세요.

노트:

OAuth 앱과 달리, GitHub 앱은 광범위한 스코프 대신 세분화된 권한을 사용합니다. 앱 생성 시 GitHub 대시보드에서 권한을 설정하며, 사용자는 인가 (Authorization) 시 특정 리포지토리에 대한 접근을 허용합니다.

GitHub 앱 설정에 대한 자세한 내용은 Registering a GitHub App 을 참고하세요.

2단계: GitHub에서 권한 설정하기

GitHub 앱은 OAuth 스코프 대신 세분화된 권한을 사용합니다. GitHub 앱을 생성하거나 수정할 때 GitHub 대시보드에서 권한을 설정해야 합니다. 이 권한은 앱이 어떤 데이터에 접근할 수 있는지 결정합니다.

GitHub 앱 권한 이해하기

권한은 세 가지 유형으로 분류됩니다:

• 리포지토리 권한: 리포지토리 수준 리소스 (코드, 이슈, 풀 리퀘스트 등)에 대한 접근
• 조직 권한: 조직 수준 리소스 (멤버, 팀, 프로젝트 등)에 대한 접근
• 계정 권한: 사용자 계정 데이터 (이메일, 프로필, 팔로워 등)에 대한 접근

각 권한마다 다음 중 하나를 선택할 수 있습니다:

• No access: 앱이 이 리소스에 접근할 수 없음
• Read-only: 앱이 이 리소스를 읽을 수만 있음
• Read & write: 앱이 이 리소스를 읽고 수정할 수 있음

인증 (Authentication)에 권장되는 권한

기본적인 "GitHub로 로그인" 기능을 위해서는 최소한 다음 계정 권한을 설정하세요:

권한	접근 수준	목적
Email addresses	Read-only	계정 생성을 위한 사용자의 이메일 주소 획득

팁:

GitHub 앱은 사용자를 대신하여 동작할 때 공개 프로필 정보(사용자명, 아바타, 공개 프로필 URL 등)를 읽을 수 있는 권한을 암묵적으로 가집니다. 기본 프로필 데이터에 대해 별도의 권한 요청이 필요하지 않습니다.

API 접근을 위한 추가 권한

애플리케이션이 인증 (Authentication) 외에 GitHub API에 접근해야 한다면, GitHub 대시보드에서 해당 권한을 추가하세요. 다음은 일반적인 예시입니다:

권한 유형	권한	접근 수준	사용 사례
리포지토리	Contents	Read-only / Read & write	리포지토리 파일 및 코드 접근
리포지토리	Issues	Read & write	이슈 생성 및 관리
리포지토리	Pull requests	Read & write	풀 리퀘스트 생성 및 관리
리포지토리	Metadata	Read-only	리포지토리 메타데이터 접근 (많은 작업에 필요)
조직	Members	Read-only	조직 멤버 목록 조회
계정	Followers	Read-only	사용자의 팔로워 및 팔로잉 정보 접근

이 목록은 전체가 아니며, GitHub 앱은 훨씬 더 많은 세분화된 권한을 지원합니다. 전체 목록은 Permissions required for GitHub Apps 를 참고하세요.

OAuth 앱과의 주요 차이점:

OAuth 앱에서는 Logto 커넥터에서 스코프를 설정하지만, GitHub 앱 권한은 전적으로 GitHub 대시보드에서 관리됩니다. Logto GitHub 커넥터의 Scope 필드는 비워두어도 됩니다 — GitHub 앱은 기존 OAuth 스코프를 사용하지 않기 때문입니다.

필요한 권한을 GitHub에서 설정하면, 사용자는 인가 (Authorization) 과정에서 접근 허용을 요청받게 됩니다.

3단계: Logto 커넥터 설정하기

GitHub 앱을 생성한 후, 설정 페이지로 이동하면 자격 증명을 얻을 수 있습니다.

1. GitHub 앱의 설정 페이지에서 Client ID를 복사하여 Logto의 clientId 필드에 붙여넣으세요.
2. Client secrets에서 Generate a new client secret을 클릭하세요. 생성된 시크릿을 복사하여 Logto의 clientSecret 필드에 붙여넣으세요.
3. Logto에서 Save and Done을 클릭하여 아이덴티티 시스템을 GitHub와 연결하세요.

경고:

Client secret은 안전하게 보관하고, 클라이언트 측 코드에 노출하지 마세요. GitHub client secret을 분실하면 복구할 수 없으므로, 새로 생성해야 합니다.

노트:

GitHub 앱의 Client ID는 App ID와 다릅니다. 반드시 설정 페이지에 "Client ID"로 표시된 값을 사용하세요. App ID가 아닙니다.

4단계: 일반 설정

다음은 GitHub 연결에는 영향을 주지 않지만, 최종 사용자 인증 (Authentication) 경험에 영향을 줄 수 있는 일반 설정입니다.

프로필 정보 동기화

GitHub 커넥터에서 GitHub 사용자 정보의 프로필 정보를 Logto 사용자 프로필로 어떻게 동기화할지 설정할 수 있습니다. name, avatar, email 등이 포함됩니다. 다음 옵션 중에서 선택하세요:

• 가입 시에만 동기화: 사용자가 처음 로그인할 때 한 번만 프로필 정보를 가져옵니다.
• 매 로그인 시마다 동기화: 사용자가 로그인할 때마다 프로필 정보를 업데이트합니다.

GitHub API 접근을 위한 토큰 저장 (선택 사항)

GitHub API에 접근하거나 사용자 인가 (Authorization)로 작업을 수행하려면 (소셜 로그인 또는 계정 연동을 통해), Logto에서 토큰 저장을 활성화하세요:

1. GitHub 앱 설정에서 필요한 권한을 구성하세요 (2단계 참고).
2. Logto GitHub 커넥터에서 Store tokens for persistent API access를 활성화하세요. Logto는 액세스 토큰과 리프레시 토큰을 Secret Vault에 안전하게 저장합니다.

노트:

GitHub 앱은 항상 리프레시 토큰을 발급하므로, Logto는 두 토큰을 자동으로 저장합니다. 액세스 토큰은 8시간 후 만료되지만, Logto는 리프레시 토큰을 사용해 새로운 액세스 토큰을 받아 최대 6개월간 API 접근을 지속할 수 있습니다.

5단계: 통합 테스트하기 (선택 사항)

실서비스에 적용하기 전에, GitHub 앱 통합을 테스트하세요:

1. Logto 개발 테넌트에서 커넥터를 사용하세요.
2. 사용자가 GitHub로 로그인할 수 있는지 확인하세요.
3. 인가 (Authorization) 과정에서 올바른 권한 요청이 표시되는지 확인하세요.
4. 토큰 저장을 활성화했다면, 액세스 토큰 (및 리프레시 토큰)이 올바르게 저장되는지 확인하세요.
5. 저장된 토큰을 사용해 API 호출을 테스트하여 권한이 정상적으로 동작하는지 확인하세요.

GitHub 앱은 모든 GitHub 사용자 계정과 즉시 작동합니다 — 다른 플랫폼처럼 테스트 사용자나 앱 승인 절차가 필요하지 않습니다. 단, 앱이 조직에 설치된 경우 조직 소유자가 설치 승인을 해야 할 수 있습니다.

GitHub 커넥터 활용하기

GitHub 커넥터를 생성하고 GitHub와 연결한 후, 엔드유저 플로우에 적용할 수 있습니다. 필요에 맞는 옵션을 선택하세요:

"GitHub로 로그인" 활성화

1. Logto 콘솔에서 로그인 경험 > 회원가입 및 로그인으로 이동하세요.
2. 소셜 로그인 섹션에서 GitHub 커넥터를 추가하여 사용자가 GitHub로 인증 (Authentication)할 수 있도록 하세요.

소셜 로그인 경험에 대해 더 알아보세요.

GitHub 계정 연결 또는 연결 해제

Account API를 사용하여 앱 내에 맞춤형 계정 센터를 구축하고, 로그인한 사용자가 자신의 GitHub 계정을 연결하거나 연결 해제할 수 있도록 하세요. Account API 튜토리얼을 따라하세요

팁:

GitHub 커넥터를 소셜 로그인용으로 활성화하지 않고, 계정 연결 및 API 접근만을 위해 활성화하는 것도 가능합니다.

GitHub API 접근 및 작업 수행

애플리케이션은 Secret Vault에서 저장된 GitHub 토큰을 가져와 GitHub API를 호출하고 백엔드 작업을 자동화할 수 있습니다 (예: 이슈 생성, 리포지토리 관리, 워크플로우 자동화 등). API 접근을 위한 저장된 토큰 가져오기 가이드를 참고하세요.

GitHub App은 OAuth 플로우 중 항상 리프레시 토큰을 발급하므로, Logto는 액세스 토큰과 리프레시 토큰을 모두 저장합니다. 액세스 토큰은 8시간 후 만료되지만, Logto가 자동으로 리프레시 토큰(6개월 유효)을 사용해 새로운 액세스 토큰을 받아오므로 API 접근이 중단되지 않습니다.

사용자의 GitHub 아이덴티티 관리하기

사용자가 자신의 GitHub 계정을 연결한 후, 관리자는 Logto 콘솔에서 해당 연결을 관리할 수 있습니다:

1. Logto 콘솔 > 사용자 관리로 이동하여 사용자의 프로필을 엽니다.
2. 소셜 연결 항목에서 GitHub 항목을 찾아 관리를 클릭하세요.
3. 이 페이지에서 관리자는 사용자의 GitHub 연결을 관리하고, GitHub 계정에서 부여 및 동기화된 모든 프로필 정보를 확인하며, 액세스 토큰 및 리프레시 토큰 상태를 확인할 수 있습니다.

노트:

스코프를 사용하는 OAuth App과 달리, GitHub App은 GitHub 대시보드에서 설정하는 세분화된 권한을 사용합니다. 사용자 액세스 토큰은 앱과 사용자가 모두 가진 권한으로 제한됩니다. Logto는 권한 목록을 직접 표시할 수 없지만, 애플리케이션은 GitHub App 설정에서 구성한 권한에 따라 접근할 수 있습니다.

참고 자료

GitHub 개발자 문서 - GitHub App 소개

GitHub 개발자 문서 - GitHub App 등록

GitHub 개발자 문서 - 사용자 액세스 토큰 생성

GitHub 개발자 문서 - 사용자 액세스 토큰 갱신

GitHub App vs OAuth App