본문으로 건너뛰기

GitHub 소셜 로그인을 설정하세요 (Set up social login with GitHub)

GitHub OAuth 앱을 통합하여 GitHub로 로그인, 계정 연결, 그리고 GitHub API에 대한 안전한 접근을 활성화하세요.

팁:

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

시작하기 (Get started)​

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

  • "GitHub로 로그인" 인증 (Authentication) 추가
  • 사용자 계정을 GitHub 아이덴티티에 연결
  • GitHub에서 사용자 프로필 정보 동기화
  • Logto Secret Vault에 안전하게 저장된 토큰을 통해 GitHub API에 접근하여 자동화 작업 수행 (예: GitHub 이슈 생성, 앱에서 저장소 관리 등)

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

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

1단계: GitHub에서 OAuth 앱 생성하기​

GitHub를 인증 (Authentication) 제공자로 사용하기 전에, GitHub에서 OAuth 앱을 생성하여 OAuth 2.0 자격 증명을 받아야 합니다.

  1. GitHub에 접속하여 계정으로 로그인하거나, 필요하다면 새 계정을 만드세요.
  2. Settings > Developer settings > OAuth apps로 이동하세요.
  3. New OAuth App을 클릭하여 새 애플리케이션을 등록하세요:
    • Application name: 앱의 설명이 잘 드러나는 이름을 입력하세요.
    • Homepage URL: 애플리케이션의 홈페이지 URL을 입력하세요.
    • Authorization callback URL: Logto GitHub 커넥터에서 Callback URI를 복사하여 여기에 붙여넣으세요. 사용자가 GitHub로 로그인하면, 이곳으로 리디렉션되어 Logto가 인증 (Authentication)을 완료하는 데 사용하는 인가 코드가 전달됩니다.
    • Application description: (선택 사항) 앱에 대한 간단한 설명을 추가하세요.
  4. Register application을 클릭하여 OAuth 앱을 생성하세요.
노트:

Enable Device Flow 박스는 체크하지 않는 것을 권장합니다. GitHub 모바일 기기에서 로그인하는 사용자는 GitHub 모바일 앱에서 최초 로그인 동작을 확인해야 합니다. 많은 GitHub 사용자가 휴대폰에 GitHub 모바일 앱을 설치하지 않기 때문에, 이로 인해 로그인 흐름이 차단될 수 있습니다. 최종 사용자가 GitHub 모바일 앱을 통해 로그인 흐름을 확인할 것으로 예상되는 경우에만 활성화하세요. 디바이스 플로우에 대한 자세한 내용을 참고하세요.

GitHub OAuth 앱 설정에 대한 자세한 내용은 Creating an OAuth App을 참고하세요.

2단계: Logto 커넥터 설정하기​

GitHub에서 OAuth 앱을 생성한 후, 상세 페이지로 리디렉션되어 Client ID를 복사하고 Client secret을 생성할 수 있습니다.

  1. GitHub OAuth 앱에서 Client ID를 복사하여 Logto의 clientId 필드에 붙여넣으세요.
  2. GitHub에서 Generate a new client secret을 클릭하여 새 시크릿을 생성한 뒤, 이를 복사하여 Logto의 clientSecret 필드에 붙여넣으세요.
  3. Logto에서 Save and Done을 클릭하여 아이덴티티 시스템을 GitHub와 연결하세요.
경고:

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

3단계: 스코프 설정 (선택 사항)​

스코프 (Scope)는 앱이 사용자로부터 요청하는 권한을 정의하며, 앱이 사용자의 GitHub 계정에서 접근할 수 있는 데이터를 제어합니다.

Logto의 Scopes 필드를 사용하여 GitHub에서 추가 권한을 요청할 수 있습니다. 필요에 따라 다음 중 한 가지 방법을 선택하세요:

옵션 1: 추가 API 스코프가 필요 없는 경우​

  • Logto GitHub 커넥터의 Scopes 필드를 비워 두세요.
  • 기본 스코프인 read:user가 요청되어 Logto가 기본 사용자 정보(예: 이메일, 이름, 아바타)를 제대로 가져올 수 있습니다.

옵션 2: 로그인 시 추가 스코프 요청​

  • GitHub OAuth 앱용 스코프 전체 목록을 참고하여 앱에 필요한 스코프만 추가하세요.
  • 원하는 모든 스코프를 Scopes 필드에 공백으로 구분하여 입력하세요.
  • 여기에 입력한 스코프는 기본값을 덮어쓰므로, 항상 인증 (Authentication) 스코프인 read:user를 포함해야 합니다.
  • 자주 사용되는 추가 스코프 예시:
    • repo: 비공개 저장소 전체 제어
    • public_repo: 공개 저장소 접근
    • user:email: 사용자 이메일 주소 접근
    • notifications: 알림 접근
  • 모든 스코프가 정확하게 입력되었는지, 유효한지 확인하세요. 잘못되었거나 지원되지 않는 스코프는 GitHub에서 "Invalid scope" 오류를 발생시킵니다.

옵션 3: 나중에 점진적으로 스코프 요청​

  • 사용자가 로그인한 후, 필요에 따라 추가 스코프를 요청하려면 소셜 인가 (Authorization) 플로우를 다시 시작하고 사용자의 저장된 토큰 세트를 업데이트하세요.
  • 이러한 추가 스코프는 Logto GitHub 커넥터의 Scopes 필드에 입력할 필요가 없으며, Logto의 Social Verification API를 통해 구현할 수 있습니다.

이 단계들을 따르면, Logto GitHub 커넥터는 앱에 꼭 필요한 권한만 요청하게 됩니다.

팁:

앱이 GitHub API에 접근하여 작업을 수행하기 위해 이러한 스코프를 요청한다면, Logto GitHub 커넥터에서 Store tokens for persistent API access를 반드시 활성화하세요. 자세한 내용은 다음 섹션을 참고하세요.

4단계: 일반 설정​

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

프로필 정보 동기화​

GitHub 커넥터에서 사용자 이름, 아바타 등 프로필 정보 동기화 정책을 설정할 수 있습니다. 다음 중에서 선택하세요:

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

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

소셜 로그인 또는 계정 연동을 통해 사용자 인가 (Authorization)로 GitHub API에 접근하고 작업을 수행하려면, Logto가 특정 API 스코프를 받아 토큰을 저장해야 합니다.

  1. 위의 안내에 따라 필요한 스코프를 추가하세요.
  2. Logto GitHub 커넥터에서 Store tokens for persistent API access를 활성화하세요. Logto는 GitHub 액세스 토큰을 Secret Vault에 안전하게 저장합니다.
노트:

이 튜토리얼에서 설명한 GitHub OAuth App을 사용할 때는, GitHub에서 리프레시 토큰 (Refresh token)을 받을 수 없습니다. GitHub의 액세스 토큰 (Access token)은 사용자가 직접 취소하지 않는 한 만료되지 않기 때문입니다. 따라서 Scopes 필드에 offline_access를 추가할 필요가 없으며, 추가할 경우 오류가 발생할 수 있습니다.

액세스 토큰이 만료되거나 리프레시 토큰을 사용하고 싶다면, 대신 GitHub App 연동을 고려하세요. GitHub Apps와 OAuth Apps의 차이점을 참고하세요.

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

실서비스에 적용하기 전에 GitHub 연동을 테스트하세요:

  1. Logto 개발 테넌트에서 커넥터를 사용하세요.
  2. 사용자가 GitHub로 로그인할 수 있는지 확인하세요.
  3. 올바른 스코프가 요청되는지 확인하세요.
  4. 토큰을 저장하는 경우 API 호출도 테스트하세요.

GitHub OAuth 앱은 모든 GitHub 사용자 계정에서 즉시 작동합니다. 다른 플랫폼처럼 테스트 사용자나 앱 승인 절차가 필요하지 않습니다.

GitHub 커넥터 활용하기 (Utilize the GitHub connector)​

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

"GitHub로 로그인" 활성화​

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

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

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

팁:

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

GitHub API 접근 및 작업 수행​

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

사용자의 GitHub 아이덴티티 관리 (Manage user's GitHub identity)​

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

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

GitHub의 액세스 토큰 (Access token) 응답에는 구체적인 스코프 (Scope) 정보가 포함되어 있지 않으므로, Logto는 사용자가 부여한 권한 (Permission) 목록을 직접 표시할 수 없습니다. 하지만 사용자가 인가 (Authorization) 과정에서 요청된 스코프 (Scope)에 동의했다면, 애플리케이션은 GitHub API에 접근할 때 해당 권한 (Permission)을 갖게 됩니다.

참고 자료 (Reference)​

GitHub 개발자 문서 - 앱 소개 (GitHub Developer Documentation - About Apps)

GitHub 개발자 문서 - OAuth 앱 생성 (GitHub Developer Documentation - Creating an OAuth App)

GitHub OAuth 앱 스코프 문서 (GitHub OAuth App Scopes Documentation)