HandyCafe Docs
owner it-admin

OAuth 소셜 로그인 설정 방법

이 가이드는 고객이 Google, Facebook, Apple, X 또는 Discord 계정으로 클라이언트 PC에 로그인할 수 있도록 소셜 로그인을 구성하는 과정을 안내합니다. HandyCafe는 전체 브라우저가 없는 기기를 위해 설계된 기기 인증 부여 흐름(RFC 8628)을 사용합니다. 고객이 휴대폰으로 QR 코드를 스캔하여 인증합니다.

필요한 것

  • HandyCafe Server에 대한 관리자 접근 권한
  • Google Cloud Console 계정(Google OAuth용) 또는 기타 제공자에 대한 동등한 개발자 포털 접근 권한
  • HandyCafe Server가 실행 중이고 네트워크에서 접근 가능한 상태
  • 로그인 흐름을 테스트할 최소 하나의 연결된 클라이언트 PC

HandyCafe에서 OAuth 기기 흐름이 작동하는 방식

설정에 들어가기 전에 흐름을 요약합니다.

  1. 유휴 클라이언트 PC의 고객이 소셜 로그인 버튼(예: "Google로 로그인")을 클릭합니다.
  2. 클라이언트가 서버에 OAuth 시작 요청을 전송합니다.
  3. 서버가 제공자의 기기 인증 엔드포인트에 연결하여 기기 코드, 사용자 코드, 확인 URL을 수신합니다.
  4. 클라이언트가 대기 화면에 QR 코드와 사용자 코드를 표시합니다.
  5. 고객이 휴대폰으로 QR 코드를 스캔하고 제공자로 인증합니다.
  6. 서버가 인증 완료까지 제공자를 폴링합니다.
  7. 서버가 요청 페이지에 표시되는 OAuth 로그인 요청을 생성합니다.
  8. 관리자 또는 캐셔가 요청을 승인합니다.
  9. 새 회원 계정이 생성되거나 기존 계정이 연결되고 고객이 로그인됩니다.

Google OAuth 설정 방법

Google은 가장 일반적으로 사용되는 제공자입니다. 이 섹션은 Google Cloud 프로젝트 생성부터 첫 로그인 테스트까지 모든 단계를 다룹니다.

파트 A: Google Cloud 인증 정보 생성

  1. 브라우저에서 https://console.cloud.google.com 의 Google Cloud Console을 엽니다.
  2. 새 프로젝트를 만들거나 기존 프로젝트를 선택합니다. "HandyCafe OAuth" 같은 인식 가능한 이름을 지정합니다.
  3. APIs & Services > OAuth 동의 화면으로 이동합니다.
  4. 사용자 유형으로 외부를 선택합니다(Google Workspace 조직이 있어 내부만 원하는 경우 제외).
  5. 필수 필드를 입력합니다: 앱 이름("카페 이름"), 사용자 지원 이메일, 개발자 연락 이메일.
  6. 범위 및 테스트 사용자 섹션을 저장 후 계속으로 진행합니다. 특별한 범위를 추가할 필요가 없습니다. 기본 이메일 및 프로필 범위면 충분합니다.
  7. APIs & Services > 인증 정보로 이동합니다.
  8. 인증 정보 만들기 > OAuth 클라이언트 ID를 클릭합니다.
  9. 애플리케이션 유형으로 TV 및 제한된 입력 장치를 선택합니다. 이것이 중요합니다. HandyCafe는 이 특정 클라이언트 유형이 필요한 기기 인증 부여 흐름을 사용합니다.
  10. 클라이언트 이름을 입력합니다(예: "HandyCafe Device Flow").
  11. 만들기를 클릭합니다.
  12. 확인 대화 상자에서 클라이언트 ID와 클라이언트 시크릿을 복사합니다. 안전하게 보관합니다. 다음 섹션에서 두 값이 모두 필요합니다.

파트 B: HandyCafe Server 구성

  1. HandyCafe Server 애플리케이션을 엽니다.
  2. 왼쪽 사이드바의 기어 아이콘으로 설정으로 이동합니다.
  3. OAuth 탭을 선택합니다.
  4. 페이지 상단의 OAuth 토글을 활성화합니다. 모든 클라이언트 PC에서 소셜 로그인을 전역적으로 활성화합니다.
  5. 제공자 목록에서 Google 제공자 행을 찾습니다.
  6. Google 토글을 활성화합니다.
  7. 12단계의 클라이언트 ID를 클라이언트 ID 필드에 붙여넣습니다.
  8. 12단계의 클라이언트 시크릿을 클라이언트 시크릿 필드에 붙여넣습니다.
  9. 저장을 클릭하여 구성을 적용합니다.

예상 결과: OAuth 탭에 Google이 인증 정보와 함께 활성화로 표시됩니다. 설정이 연결된 모든 클라이언트에 푸시됩니다.

파트 C: 로그인 흐름 테스트

  1. 연결된 클라이언트 PC로 이동합니다. 대기 화면에 Google 로그인 버튼이 있는 소셜 로그인 섹션이 표시됩니다.
  2. 클라이언트 대기 화면에서 Google 로그인 버튼을 클릭합니다.
  3. 클라이언트에 QR 코드와 사용자 코드(짧은 영숫자 문자열)가 표시됩니다.
  4. 휴대폰으로 QR 코드를 스캔합니다. Google의 기기 확인 페이지가 열립니다.
  5. Google 계정으로 로그인하고 프롬프트에 사용자 코드를 입력합니다.
  6. 애플리케이션을 인증합니다.

예상 결과: 서버에서 알림음이 재생되고 요청 페이지에 새 항목이 나타납니다. 요청에 Google 계정 이름, 이메일 주소, 로그인을 시작한 클라이언트 PC가 표시됩니다.

로그인 요청 승인 방법

모든 OAuth 로그인은 고객이 접근하기 전에 관리자 또는 캐셔의 승인이 필요한 요청을 생성합니다.

  1. 로그인 요청이 도착하면 서버에서 알림음이 재생되고 사이드바의 요청 페이지 아이콘에 배지가 나타납니다.
  2. 요청 페이지로 이동합니다.
  3. 대기 중인 요청에 다음이 표시됩니다.
    • 제공자 이름(예: Google)
    • 제공자의 표시 이름(예: "김철수")
    • 이메일 주소(예: "cheolsu@example.com")
    • 요청을 시작한 클라이언트 PC(호스트명 또는 표시 이름)
    • 타임스탬프
  4. 요청 세부 사항을 검토합니다. 클라이언트 PC의 사람이 계정 정보와 일치하는지 확인합니다.
  5. 승인을 클릭하여 요청을 수락합니다.

예상 결과: 이 OAuth 신원에 연결된 기존 회원 계정이 없으면 새 회원 계정이 자동으로 생성됩니다. 제공자의 표시 이름과 이메일이 사용됩니다. 고객이 로그인되고 클라이언트 PC가 대기 화면에서 온라인 페이지로 전환됩니다. 이전에 이 OAuth 신원에 연결된 회원 계정이 있으면 기존 회원으로 직접 로그인됩니다.

팁: 로그인 요청이 의심스러운 경우(예: PC가 무인이거나 자동화된 것으로 보이는 요청) 대신 거부를 클릭합니다. 고객에게 "접근 거부" 메시지가 표시되며 다시 시도할 수 있습니다.

Facebook OAuth 설정 방법

  1. https://developers.facebook.com 에서 Facebook 개발자 포털을 엽니다.
  2. 새 앱을 만듭니다. 소비자 앱 유형을 선택합니다.
  3. 앱의 설정 > 기본 페이지로 이동합니다. 앱 ID와 앱 시크릿을 기록합니다.
  4. 제품 추가로 이동하여 Facebook Login for Devices를 추가합니다.
  5. Facebook Login for Devices 설정에서 포털이 요구하는 경우 리디렉트 URI를 추가합니다.
  6. HandyCafe Server를 열고 설정 > OAuth로 이동합니다.
  7. Facebook 제공자 행을 찾습니다.
  8. Facebook 토글을 활성화합니다.
  9. 앱 ID를 클라이언트 ID 필드에 붙여넣습니다.
  10. 앱 시크릿을 클라이언트 시크릿 필드에 붙여넣습니다.
  11. 저장을 클릭합니다.

예상 결과: Facebook이 활성화된 제공자로 표시됩니다. 클라이언트 대기 화면에 다른 활성화된 제공자와 함께 Facebook 로그인 버튼이 표시됩니다.

Discord OAuth 설정 방법

  1. https://discord.com/developers/applications 에서 Discord 개발자 포털을 엽니다.
  2. 새 애플리케이션을 만듭니다. 카페 이름으로 지정합니다.
  3. 왼쪽 사이드바의 OAuth2 섹션으로 이동합니다.
  4. 클라이언트 ID를 복사하고 클라이언트 시크릿을 생성합니다. Discord는 시크릿을 한 번만 표시하므로 안전하게 보관합니다.
  5. HandyCafe Server를 열고 설정 > OAuth로 이동합니다.
  6. Discord 제공자 행을 찾습니다(기본적으로 비활성화됨).
  7. Discord 토글을 활성화합니다.
  8. 클라이언트 ID를 클라이언트 ID 필드에 붙여넣습니다.
  9. 클라이언트 시크릿을 클라이언트 시크릿 필드에 붙여넣습니다.
  10. 저장을 클릭합니다.

예상 결과: Discord가 클라이언트 대기 화면에서 로그인 옵션으로 사용 가능합니다.

크레딧 없이 로그인 허용 방법

기본적으로 HandyCafe는 OAuth로 인증된 고객이 지갑 잔액이나 시간 크레딧이 없어도 로그인할 수 있도록 허용합니다. 이 동작을 변경할 수 있습니다.

  1. 설정 > OAuth로 이동합니다.
  2. 크레딧 없이 로그인 허용 토글을 찾습니다.
  3. 활성화(기본값)하면 OAuth로 인증된 고객이 잔액에 관계없이 로그인할 수 있습니다. 캐셔가 후불 세션을 시작할 수 있습니다.
  4. 비활성화하면 고객이 로그인하려면 지갑 잔액이나 시간 크레딧이 있어야 합니다. 잔액이 0인 고객에게 캐셔를 방문하여 충전하라는 메시지가 표시됩니다.
  5. 토글 변경 후 저장을 클릭합니다.

예상 결과: 새 로그인 요청에 대해 동작이 즉시 적용됩니다. 기존 세션은 영향을 받지 않습니다.

OAuth 신원을 기존 회원에 연결하는 방법

고객이 이미 회원 계정을 가지고 있고(캐셔가 수동으로 생성) OAuth로 처음 로그인하는 경우, 승인 과정에서 OAuth 신원을 기존 계정에 연결할 수 있습니다.

  1. 요청 페이지에 OAuth 로그인 요청이 도착하면 이메일이 기존 회원과 일치하는지 확인합니다.
  2. 시스템이 일치를 감지하면 승인 대화 상자에서 새 계정을 만드는 대신 OAuth 신원을 기존 회원에 연결하는 옵션을 제공합니다.
  3. 연결 옵션이 선택된 상태로 요청을 승인합니다.

예상 결과: 기존 회원 계정이 OAuth 연결을 얻습니다. 이 제공자를 통한 향후 로그인은 승인 단계를 건너뛰고 회원을 직접 로그인합니다(첫 승인 이후).

일반적인 실수 방지

  • Google Cloud Console에서 잘못된 OAuth 클라이언트 유형을 사용하는 경우. OAuth 클라이언트 ID를 만들 때 반드시 "TV 및 제한된 입력 장치"를 선택해야 합니다. "웹 애플리케이션"이나 "데스크톱 앱"을 선택하면 기기 인증 흐름이 작동하지 않고 클라이언트가 기기 코드를 받지 못합니다.
  • 전역 OAuth 토글 활성화를 잊는 경우. 개별 제공자를 활성화하는 것만으로는 충분하지 않습니다. OAuth 설정 페이지 상단의 마스터 OAuth 토글도 켜져 있어야 합니다.
  • 로그인 요청을 승인하지 않는 경우. OAuth 로그인은 서버의 명시적 승인이 필요합니다. 아무도 요청 페이지를 모니터링하지 않으면 고객이 대기 화면에서 무기한 대기합니다. 바쁜 시간대에는 캐셔를 배정하여 요청을 모니터링하는 것을 고려합니다.
  • 기기 코드가 만료되는 경우. 기기 코드는 제한된 수명(일반적으로 5-10분)이 있습니다. 고객이 QR 코드를 스캔하고 인증하는 데 너무 오래 걸리면 코드가 만료되고 처음부터 다시 시작해야 합니다. 고객에게 즉시 스캔하도록 안내합니다.
  • 인증 정보에 추가 공백이 포함된 채 붙여넣는 경우. 제공자 콘솔에서 클라이언트 ID 또는 클라이언트 시크릿을 복사할 때 앞뒤에 공백이 포함되지 않도록 합니다. 추가 공백은 인증 실패를 유발합니다.
  • Google OAuth 앱을 게시하는 것을 잊는 경우. "테스트 중" 모드의 Google 앱은 제한된 수의 테스트 사용자만 허용합니다. 모든 고객이 로그인하도록 하려면 OAuth 동의 화면 페이지를 통해 앱을 게시하고 필요한 확인 단계를 완료해야 합니다.
  • 클라이언트 ID와 클라이언트 시크릿을 바꾸는 경우. 이것은 두 개의 다른 값입니다. 클라이언트 ID는 공개용이고, 클라이언트 시크릿은 기밀로 유지해야 합니다. 바꾸면 인증이 실패합니다.
  • 카페 이름을 구성하지 않는 경우. HandyCafe 설정의 카페 이름이 OAuth 흐름 중 클라이언트 대기 화면에 표시됩니다. 비어 있거나 기본 이름은 비전문적으로 보입니다. OAuth를 활성화하기 전에 설정 > 일반에서 카페 이름을 설정합니다.