본문으로 건너뛰기

Google 소셜 로그인을 설정하세요

Google OAuth 2.0 인증 시스템을 통합하여 Google로 로그인, 계정 연결, Google API에 대한 안전한 접근을 활성화하세요.

팁:

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

시작하기​

Google 커넥터를 사용하면 OAuth 2.0 통합을 통해 애플리케이션에서 다음을 할 수 있습니다:

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

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

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

1단계: Google Auth Platform에서 프로젝트 생성​

Google을 인증 (Authentication) 제공자로 사용하기 전에, Google Cloud Console에서 프로젝트를 설정하여 OAuth 2.0 자격 증명을 받아야 합니다. 이미 프로젝트가 있다면 이 단계는 건너뛰어도 됩니다.

  1. Google Cloud Console에 방문하여 Google 계정으로 로그인하세요.
  2. 상단 메뉴 바에서 프로젝트 선택 버튼을 클릭한 후, 새 프로젝트 버튼을 클릭하여 프로젝트를 생성하세요.
  3. 새로 생성한 프로젝트에서 API 및 서비스 > OAuth 동의 화면으로 이동하여 앱을 구성하세요:
    • 앱 정보: 동의 화면에 표시될 애플리케이션 이름과 지원 이메일을 입력하세요.
    • 대상 (Audience): 원하는 대상 유형을 선택하세요:
      • 내부 - 조직 내 Google Workspace 사용자만 사용 가능
      • 외부 - 모든 Google 사용자 사용 가능 (프로덕션 사용 시 검증 필요)
    • 연락처 정보: Google이 프로젝트 변경 사항을 알릴 수 있도록 이메일 주소를 입력하세요.
    • Google 정책에 동의합니다를 체크하여 기본 설정을 완료하세요.
  4. 선택적으로, 브랜딩 섹션으로 이동하여 제품 정보 및 앱 로고를 업로드할 수 있습니다. 이 로고는 OAuth 동의 화면에 표시되어 사용자가 앱을 인식하는 데 도움이 됩니다.
팁:

외부 대상 유형을 선택한 경우, 개발 중에는 테스트 사용자를 추가해야 하며, 프로덕션 사용을 위해 앱을 게시해야 합니다.

2단계: OAuth 2.0 자격 증명 생성​

Google Cloud Console의 자격 증명 페이지로 이동하여 애플리케이션용 OAuth 자격 증명을 생성하세요.

  1. 자격 증명 만들기 > OAuth 클라이언트 ID를 클릭하세요.
  2. 애플리케이션 유형으로 웹 애플리케이션을 선택하세요.
  3. OAuth 클라이언트의 이름을 입력하세요. 이 이름은 자격 증명을 식별하는 데 도움이 되며, 최종 사용자에게는 표시되지 않습니다.
  4. 허용된 URI를 구성하세요:
    • 허용된 JavaScript 원본: Logto 인스턴스의 origin을 추가하세요 (예: https://your-logto-domain.com)
    • 허용된 리디렉션 URI: Logto Callback URI를 추가하세요 (Logto Google 커넥터에서 복사)
  5. 만들기를 클릭하여 OAuth 클라이언트를 생성하세요.

3단계: Logto 커넥터에 자격 증명 설정​

OAuth 클라이언트를 생성하면 Google이 자격 증명이 표시된 모달을 보여줍니다:

  1. 클라이언트 ID를 복사하여 Logto의 clientId 필드에 붙여넣으세요.
  2. 클라이언트 시크릿을 복사하여 Logto의 clientSecret 필드에 붙여넣으세요.
  3. Logto에서 저장 및 완료를 클릭하여 아이덴티티 시스템을 Google과 연결하세요.
경고:

클라이언트 시크릿은 안전하게 보관하고, 클라이언트 측 코드에 노출하지 마세요. 유출 시 즉시 새로 생성하세요.

4단계: 스코프(Scope) 설정​

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

Google Cloud Console에서 스코프 설정​

  1. API 및 서비스 > OAuth 동의 화면 > 스코프로 이동하세요.
  2. 스코프 추가 또는 제거를 클릭하고, 앱에 필요한 스코프만 선택하세요:
    • 인증 (Authentication) (필수):
      • https://www.googleapis.com/auth/userinfo.email
      • https://www.googleapis.com/auth/userinfo.profile
      • openid
    • API 접근 (선택 사항): 앱에 필요한 추가 스코프를 추가하세요 (예: Drive, Calendar, YouTube). 사용 가능한 서비스를 찾으려면 Google API 라이브러리를 참조하세요. 앱이 기본 권한 외에 Google API 접근이 필요하다면, Google API 라이브러리에서 해당 API (예: Google Drive API, Gmail API, Calendar API)를 먼저 활성화하세요.
  3. 업데이트를 클릭하여 선택을 확인하세요.
  4. 저장 및 계속을 클릭하여 변경 사항을 적용하세요.

Logto에서 스코프 설정​

필요에 따라 다음 중 한 가지 방법을 선택하세요:

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

  • Logto Google 커넥터의 Scopes 필드를 비워 두세요.
  • 기본 스코프 openid profile email이 요청되어 Logto가 기본 사용자 정보를 올바르게 가져올 수 있습니다.

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

  • 원하는 모든 스코프를 Scopes 필드에 공백으로 구분하여 입력하세요.
  • 여기에 입력한 스코프는 기본값을 덮어쓰므로, 항상 인증 (Authentication) 스코프를 포함해야 합니다: https://www.googleapis.com/auth/userinfo.email https://www.googleapis.com/auth/userinfo.profile openid.
  • 전체 스코프 URL을 사용하세요. 예시: https://www.googleapis.com/auth/calendar.readonly.

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

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

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

팁:

앱이 Google API에 접근하여 작업을 수행하려면, Logto Google 커넥터에서 지속적인 API 접근을 위한 토큰 저장을 활성화하세요. 자세한 내용은 다음 섹션을 참고하세요.

5단계: 인증 (Authentication) 프롬프트 맞춤 설정​

Logto에서 Prompts를 구성하여 사용자 인증 경험을 제어하세요. Prompts는 사용자 상호작용 유형을 지정하는 문자열 배열입니다:

  • none - 인가 (Authorization) 서버가 인증 (Authentication) 또는 동의 화면을 표시하지 않습니다. 사용자가 이미 인증되어 있지 않거나 요청된 스코프에 대해 사전 동의하지 않은 경우 오류를 반환합니다. 기존 인증 및/또는 동의 여부를 확인할 때 사용하세요.
  • consent - 인가 (Authorization) 서버가 정보를 클라이언트에 반환하기 전에 사용자에게 동의를 요청합니다. Google API 접근을 위한 오프라인 접근을 활성화하려면 필요합니다.
  • select_account - 인가 (Authorization) 서버가 사용자에게 계정 선택을 요청합니다. 여러 Google 계정을 가진 사용자가 인증에 사용할 계정을 선택할 수 있습니다.

6단계: 일반 설정​

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

프로필 정보 동기화​

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

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

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

Google API에 접근하여 사용자 권한으로 작업을 수행하려면 (소셜 로그인 또는 계정 연동 방식 모두), Logto가 특정 API 스코프를 받아 토큰을 저장해야 합니다.

  1. Google Cloud Console OAuth 동의 화면 구성과 Logto Google 커넥터에 필요한 스코프를 추가하세요.
  2. Logto Google 커넥터에서 지속적인 API 접근을 위한 토큰 저장을 활성화하세요. Logto는 Google 액세스 토큰 및 리프레시 토큰을 Secret Vault에 안전하게 저장합니다.
  3. 리프레시 토큰이 반환되도록 하려면 Logto Google 커넥터를 다음과 같이 구성하세요:
    • Prompts에 consent를 포함하세요.
    • 오프라인 접근을 활성화하세요.
경고:

Logto의 Scope 필드에 offline_access를 추가할 필요가 없습니다. 추가하면 오류가 발생할 수 있습니다. Google은 오프라인 접근이 활성화되면 자동으로 access_type=offline을 사용합니다.

7단계: Google One Tap 활성화 (선택 사항)​

Google One Tap은 팝업 인터페이스를 통해 사용자가 Google 계정으로 웹사이트에 간편하게 로그인할 수 있는 안전한 방법입니다.

Google 커넥터 설정이 완료되면, 커넥터 상세 페이지에서 Google One Tap 카드가 표시됩니다. 스위치를 토글하여 Google One Tap을 활성화하세요.

Google One Tap 구성 옵션​

  • 가능하다면 자격 증명 자동 선택 - 특정 조건이 충족되면 Google 계정으로 자동 로그인합니다.
  • 사용자가 바깥을 클릭/탭하면 프롬프트 취소 - 사용자가 프롬프트 바깥을 클릭하거나 탭하면 Google One Tap 프롬프트를 닫습니다. 비활성화 시, 사용자가 닫기 버튼을 클릭해야 프롬프트가 사라집니다.
  • ITP 브라우저에서 업그레이드된 One Tap UX 활성화 - Intelligent Tracking Prevention (ITP) 브라우저에서 업그레이드된 Google One Tap 사용자 경험을 활성화합니다. 자세한 내용은 이 문서를 참고하세요.
경고:

OAuth 클라이언트 구성의 허용된 JavaScript 원본 섹션에 도메인을 반드시 추가하세요. 그렇지 않으면 Google One Tap이 표시되지 않습니다.

Google One Tap의 중요한 제한 사항​

지속적인 API 접근을 위한 토큰 저장과 Google One Tap을 동시에 활성화하면, 액세스 토큰이나 요청한 스코프를 자동으로 받을 수 없습니다.

Google One Tap 로그인은 (일반 "Google로 로그인" 버튼과 달리) OAuth 액세스 토큰을 발급하지 않습니다. 대신, 사용자의 아이덴티티를 검증하는 ID 토큰 (서명된 JWT)만 반환하며, API 접근 권한은 부여하지 않습니다.

Google One Tap 사용자가 Google API에 접근하려면, Logto의 Social Verification API를 사용하여 사용자가 Google One Tap으로 로그인한 후 페더레이티드 소셜 인가 (Authorization) 플로우를 다시 시작할 수 있습니다. 이를 통해 필요한 추가 스코프를 요청하고 사용자의 저장된 토큰 세트를 업데이트할 수 있으며, Logto Google 커넥터에 미리 스코프를 입력할 필요가 없습니다. 이 방식은 점진적 인가 (Authorization)를 가능하게 하여, 앱이 실제로 필요할 때만 추가 권한을 요청하도록 합니다.

공식 문서에서 Google One Tap의 제한 사항에 대해 더 알아보세요.

8단계: 앱 테스트 및 게시​

내부 앱의 경우​

Google에서 대상 (Audience) 유형이 내부로 설정된 경우, 앱은 조직 내 Google Workspace 사용자만 사용할 수 있습니다. 조직 계정으로 테스트할 수 있습니다.

외부 앱의 경우​

대상 (Audience) 유형이 외부인 경우:

  1. 개발 중: OAuth 동의 화면 > 테스트 사용자로 이동하여 테스트 사용자 이메일 주소를 추가하세요. 이 사용자만 앱에 로그인할 수 있습니다.
  2. 프로덕션용: OAuth 동의 화면 섹션에서 앱 게시를 클릭하여 모든 Google 계정 사용자가 사용할 수 있도록 하세요.
노트:

민감하거나 제한된 스코프를 사용하는 앱은 게시 전에 Google의 검증이 필요할 수 있습니다. 이 과정은 몇 주가 소요될 수 있습니다.

Google 커넥터 활용하기​

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

"Google로 로그인" 활성화​

  1. Logto 콘솔에서 로그인 경험 > 회원가입 및 로그인으로 이동하세요.
  2. 소셜 로그인 섹션에서 Google 커넥터를 추가하여 사용자가 Google로 인증할 수 있도록 하세요.
  3. 선택적으로, 로그인 및 회원가입 페이지에서 Google One Tap을 활성화하여 간편한 인증 경험을 제공할 수 있습니다.

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

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

팁:

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

Google API 접근 및 작업 수행​

애플리케이션은 Secret Vault에서 저장된 Google 액세스 토큰을 가져와 Google API를 호출하고 백엔드 작업을 자동화할 수 있습니다 (예: Google Drive 파일 관리, Calendar 이벤트 생성, Gmail을 통한 이메일 발송 등). API 접근을 위한 저장된 토큰 조회 가이드를 참고하세요.

사용자의 Google 아이덴티티 관리​

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

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

참고 자료​

Google Identity: OAuth 2.0 설정

Google Identity Services (One Tap)

 Google Cloud Console