OAuth 로그인

HandyCafe는 기기 인증 부여(RFC 8628)를 사용한 소셜/OAuth 로그인을 지원합니다. 이 흐름은 고객이 공유 PC에서 자격 증명을 안전하게 입력할 수 없는 키오스크 및 공공 환경을 위해 설계되었습니다.

지원되는 제공자

각 제공자는 설정 > OAuth에서 개별적으로 활성화 또는 비활성화할 수 있습니다.

인증 흐름

기기 인증 흐름은 다음 단계로 진행됩니다.

1. 고객이 제공자를 선택합니다 -- 클라이언트 대기 화면에서 고객이 제공자 버튼(예: Google, Discord)을 탭합니다.
2. 클라이언트가 서버에 요청을 전송합니다 -- 클라이언트가 HandyCafe 서버에 OAuth 로그인이 시작되었음을 알립니다.
3. 서버가 기기 코드를 요청합니다 -- 서버가 선택된 제공자의 기기 인증 엔드포인트에 연결하여 기기 코드, 사용자 코드, 확인 URI를 수신합니다.
4. 클라이언트가 코드를 표시합니다 -- 클라이언트가 고객에게 user_code와 verification_uri를 표시하며, 일반적으로 쉬운 스캔을 위해 QR 코드로 렌더링됩니다.
5. 고객이 휴대폰으로 인증합니다 -- 고객이 개인 기기(휴대폰 또는 태블릿)로 QR 코드를 스캔하고 제공자 웹사이트에서 인증을 완료합니다.
6. 서버가 토큰을 폴링합니다 -- 서버가 제공자에게 토큰을 주기적으로 폴링합니다. 폴링 상태는 다음과 같습니다.
   • 대기 중 -- 고객이 아직 인증을 완료하지 않았습니다.
   • 속도 제한 -- 폴링이 너무 빈번합니다. 서버가 간격을 늘립니다.
   • 성공 -- 인증이 완료되었습니다. 토큰을 수신했습니다.
   • 만료됨 -- 인증 전에 기기 코드가 만료되었습니다.
   • 오류 -- 예상치 못한 오류가 발생했습니다.
7. 서버가 사용자 정보를 가져옵니다 -- 성공 시 서버가 토큰을 사용하여 제공자에서 provider_uid, email, name, avatar_url을 포함한 고객 프로필을 가져옵니다.
8. 관리자가 승인 또는 거부합니다 -- 로그인 요청이 요청 페이지에 나타납니다. 관리자 또는 캐셔가 요청을 검토하고 승인하거나 거부합니다.
9. 회원이 생성되거나 연결됩니다 -- 승인 시 새 회원 계정이 생성되거나 OAuth 신원이 기존 회원에 연결됩니다.
10. 클라이언트 세션이 시작됩니다 -- 클라이언트가 확인을 수신하고 고객의 세션이 시작됩니다.

보안 고려사항

• 자격 증명이 공유 PC에 접촉하지 않습니다. 고객은 개인 기기에서만 인증합니다. 비밀번호나 토큰이 클라이언트 머신에 입력되지 않습니다.
• 관리자 승인 게이트. 모든 OAuth 로그인 요청은 세션 시작 전에 관리자 또는 캐셔의 승인을 받아야 하며, 무단 접근을 방지합니다.
• 구성 가능한 크레딧 요구사항. "크레딧 없이 로그인 허용" 옵션을 활성화 또는 비활성화하여 고객이 OAuth를 통해 로그인할 때 양수 잔액이 필요한지 여부를 제어할 수 있습니다.

설정

OAuth 제공자는 설정 > OAuth에서 구성합니다. 각 제공자는 제공자의 개발자 콘솔에서 얻은 고유 클라이언트 자격 증명(클라이언트 ID 및 클라이언트 시크릿)이 필요합니다. 고객에게 제공하려는 제공자만 활성화합니다.