G7 소셜 TOTP 패스키 인증 - Glitter Social TOTP Passkey

Gnuboard7용 소셜 로그인 · 필수 TOTP · Passkey(WebAuthn) 통합 인증 플러그인

버전 : 1.1.5 · 개발 : Glitter.kr · 라이선스 : MIT
GitHub : https://github.com/glitter-node/glitter-social_totp_passkey
릴리스 : https://github.com/glitter-node/glitter-social_totp_passkey/releases/tag/v1.1.5
다운로드 : GitHub Releases — 실제 첨부 파일명과 게시 여부는 릴리스 페이지에서 확인

소개

Glitter Social TOTP Passkey는 Gnuboard7에서 네이버·카카오·구글·페이스북·GitHub 소셜 로그인, 시간 기반 일회용 비밀번호(TOTP), 그리고 Passkey(WebAuthn) 인증을 하나의 독립 플러그인으로 제공하는 보안 중심 인증 확장입니다.

일반적인 소셜 로그인에 그치지 않고 신규 소셜 회원의 TOTP 등록, 기존 소셜 회원의 추가 인증, 명시적 계정 연결·해제, 복구 및 관리자 전환 정책을 제공합니다. Passkey를 이용한 비밀번호 없는 로그인, 재인증, 계정별 Credential 관리와 설정에 따른 소셜 TOTP 대체 인증도 지원합니다.

기존 glitter-social_login_totp와 별도 제품 계열로 개발되었으며, 플러그인 ID·설정·라우트·세션·캐시·로그·데이터베이스 테이블을 분리합니다. 기존 플러그인의 테이블을 공유하거나 기존 플러그인을 직접 수정하는 구조가 아닙니다.

주요 기능

TOTP란 무엇인가요?

**TOTP(Time-based One-Time Password)**는 일정 시간마다 새 인증번호를 생성하는 시간 기반 일회용 비밀번호입니다. 보통 인증 앱에 6자리 코드가 표시되고 약 30초마다 갱신됩니다. Google Authenticator, Microsoft Authenticator, 2FAS, Aegis 등 RFC 6238 호환 앱을 사용할 수 있습니다.

일반적인 소셜 로그인은 OAuth 인증이 성공하면 로그인이 완료되지만, 이 플러그인의 기본 소셜 인증 흐름은 OAuth 성공 이후 TOTP 확인을 추가로 요구합니다.

소셜 Provider 인증 → 추가 인증(TOTP 또는 허용된 Passkey 대체 방식) → 로그인 완료

TOTP 등록용 QR 코드는 서버에서 로컬 생성하며, QR 사용이 어려울 때 수동 등록키를 이용할 수 있습니다. TOTP는 계정 보안을 높이지만 피싱에 완전히 저항하는 방식은 아닙니다.

Passkey(WebAuthn)란 무엇인가요?

Passkey는 공개키 암호 방식의 WebAuthn 인증을 이용해 기기 잠금 해제, 생체 인식 또는 보안 키 등으로 로그인할 수 있게 하는 인증 수단입니다. 사이트가 비밀번호나 TOTP 숫자 코드를 직접 받지 않는 인증 경로를 제공하며, 일반적으로 피싱에 강한 인증 방식입니다.

이 플러그인은 다음 Passkey 기능을 지원합니다.

• Passkey 등록: 사용자 계정에 WebAuthn Credential 등록
• 독립 Passkey 로그인: 지원되는 discoverable credential을 이용한 로그인
• Passkey 재인증: 민감한 계정 작업에서 별도의 재인증 수행
• Credential 관리: 등록된 Passkey 조회, 이름 변경, 삭제
• 소셜 TOTP 대체: 관리자가 허용한 정책에 따라 Passkey로 추가 인증 수행
• 인증 정책: 사용자 검증(User Verification), 등록·로그인·재인증·추가 인증 관련 설정

Passkey 등록과 인증 가능 여부는 브라우저·운영체제·인증 장치 및 사이트의 HTTPS 환경에 따라 달라집니다. Passkey 지원이 모든 TOTP 정책을 자동으로 비활성화한다는 뜻은 아닙니다. 실제 적용은 관리자 설정과 인증 흐름에 따릅니다.

지원 OAuth Provider

소셜 계정 식별은 이메일 주소가 아닌 (provider, provider_user_id) 조합을 기준으로 합니다. 같은 이메일을 사용하더라도 기존 회원 계정에 자동 연결하지 않으며, 인증된 회원이 직접 시작하는 연결 절차를 따릅니다.

로그인 및 회원가입 흐름

기존 소셜 회원 로그인

1. 사용자가 OAuth Provider를 선택하고 인증합니다.
2. OAuth state, 브라우저 바인딩 및 Provider identity를 검증합니다.
3. 연결된 회원과 계정 상태를 확인합니다.
4. 추가 인증 정책에 따라 TOTP 또는 허용된 Passkey 대체 인증을 수행합니다.
5. 모든 인증 조건을 충족하면 일회성 exchange를 거쳐 최종 로그인 토큰을 발급합니다.

OAuth 인증 성공만으로 최종 로그인이 완료되지는 않습니다.

신규 소셜 회원가입

1. OAuth Provider에서 identity를 확인합니다.
2. 신규 회원 정보 및 필수 동의 사항을 확인합니다.
3. TOTP를 등록하고 최초 인증번호를 검증합니다.
4. 검증 후 회원·소셜 계정·TOTP 정보를 생성합니다.

신규 소셜 회원가입의 TOTP 등록은 기본 보안 정책의 핵심입니다. Passkey 등록 기능은 별도로 제공되며, 각 단계의 실제 표시 및 허용 범위는 관리자 설정에 따릅니다.

독립 Passkey 로그인

등록된 Passkey를 가진 사용자는 지원되는 WebAuthn 인증 흐름을 통해 소셜 Provider를 거치지 않고 로그인할 수 있습니다. 인증 과정에서는 서버가 발급한 challenge, RP ID 및 Origin 등 WebAuthn 보안 조건을 검증합니다.

인증 및 계정 보호 설계

기존 TOTP 구현의 대표적 정책으로 인증 실패 5회 제한, 15분 잠금, 300초 등록·인증 대기 제한이 사용되었습니다. 현재 배포 버전의 실제 정책값은 플러그인 설정 및 구현을 최종 기준으로 확인해야 합니다.

일회성 로그인 Exchange

OAuth callback 이후 최종 bearer token을 URL query로 직접 전달하지 않고, 단기 유효한 일회용 exchange code를 사용합니다. 기존 설계는 60초 유효시간, SHA-256 해시 저장, 시작 브라우저의 세션·쿠키 바인딩, 일회성 소비를 포함합니다. OAuth state 검증과 최종 로그인 교환은 별도의 보안 단계입니다.

TOTP 복구 및 관리자 전환

TOTP 인증 수단을 분실했을 때 이메일 소유 확인만으로 즉시 인증을 우회하지 않습니다. 별도 본인확인, 관리자 승인 및 일회성 복구 grant를 이용하는 절차를 제공합니다. 관리자 전환은 허용 대상, 기간, 마감 시각, 브라우저·계정 바인딩, 권한 검사 및 긴급 중지 정책을 포함합니다.

관리자 설정 및 UI

운영자는 사용할 OAuth Provider를 활성화하고 각 Provider의 Client ID/App ID와 Secret을 등록할 수 있습니다. Provider 개발자 콘솔에서 애플리케이션 생성 및 callback URL 등록이 별도로 필요합니다.

플러그인 API 경로는 기존 제품이 아닌 glitter-social_totp_passkey 식별자를 사용합니다. 예시 callback 경로 형식은 다음과 같습니다.

/api/plugins/glitter-social_totp_passkey/{provider}/callback

실제 경로와 설정 항목은 설치된 버전의 라우트 및 관리자 화면을 기준으로 확인하세요. 로그인·회원가입·마이페이지 UI와 한국어·영어 번역 리소스를 제공합니다.

관리자에서 Passkey 활성화하기

설정 명칭 안내: 아래는 플러그인에 제공되는 설정 기능을 기준으로 한 사용 순서입니다. 정확한 메뉴 이름, 토글 문구, 기본값은 설치된 Gnuboard7 관리자 화면을 기준으로 확인하세요. 현재 제공된 자료에는 관리자 화면의 실제 항목명이 모두 포함되어 있지 않습니다.

1. 관리자 계정으로 로그인한 뒤 Gnuboard7의 플러그인 관리 화면으로 이동합니다.
2. glitter-social_totp_passkey 플러그인이 설치 및 활성화되어 있는지 확인하고 해당 플러그인의 설정 화면을 엽니다.
3. Passkey 전체 활성화에 해당하는 설정을 켭니다. 전체 기능이 꺼져 있다면 개별 로그인·등록 옵션을 켜더라도 사용이 제한될 수 있습니다.
4. 필요한 기능을 선택적으로 활성화합니다. 다음 표의 설정은 서로 다른 인증 흐름에 영향을 줍니다.
5. 사용자 검증(User Verification) 정책을 확인합니다. 기기 잠금 해제, 생체 인식 또는 PIN 요구 수준은 서비스 보안 정책과 호환성을 고려해 선택합니다.
6. 설정을 저장하고 새로 연 로그인·회원가입·마이페이지 화면에서 실제 노출 여부를 확인합니다. 표시되지 않으면 플러그인 활성 상태, 레이아웃 반영 및 캐시 상태를 점검합니다.

권장 활성화 순서: 전체 Passkey 활성화 → 등록 허용 → 시험 계정으로 등록 확인 → 독립 로그인 허용 → 실제 로그인 확인 → 필요한 경우 소셜 TOTP 대체와 재인증 정책 활성화. 이는 운영 도입을 위한 권장 순서이며 플러그인의 강제 설정 순서를 뜻하지 않습니다.

HTTPS 및 도메인 확인

• WebAuthn은 보안 컨텍스트를 요구합니다. 운영 사이트는 유효한 HTTPS로 제공하세요.
• 플러그인은 구성된 HTTPS app.url을 기준으로 RP ID와 허용 Origin을 결정합니다. 실제 접속 도메인과 설정이 일치해야 합니다.
• 도메인 변경이나 프록시 구성 변경 후 Passkey가 실패하면 Origin/RP ID와 HTTPS 설정을 우선 확인합니다.
• 운영 중인 기존 Passkey의 RP ID를 변경하면 인증에 영향을 줄 수 있으므로 도메인 정책 변경 전에 영향을 검토하세요.

회원이 Passkey 등록하는 방법

1. 관리자가 Passkey 전체 기능과 등록을 허용했는지 확인합니다.
2. 회원이 기존 방식으로 로그인한 뒤 마이페이지의 Passkey 관리 영역으로 이동합니다.
3. Passkey 등록 동작을 선택하고 필요 시 재인증을 완료합니다.
4. 브라우저·운영체제가 표시하는 Passkey 생성 창에서 Windows Hello, 기기 잠금 해제 또는 지원 보안 키를 사용합니다.
5. 등록이 끝나면 Credential 목록에 새 항목이 나타나는지 확인합니다.
6. 이름 변경 기능으로 구분하기 쉬운 이름을 지정할 수 있습니다. 이름 변경은 서버의 기존 name API 계약을 유지합니다.

주의: 장치를 분실하거나 Passkey를 삭제하기 전에 다른 사용 가능한 인증·복구 수단을 확보하세요. 마지막 인증 수단 삭제 보호 정책이 적용됩니다.

Passkey로 로그인하는 방법

1. 관리자가 독립 Passkey 로그인을 허용했는지 확인합니다.
2. 로그인 화면에서 Passkey 로그인 동작을 선택합니다.
3. 브라우저가 제시하는 등록된 Passkey를 선택하고 기기 잠금 해제 등 사용자 검증을 수행합니다.
4. 로그인 완료 여부를 확인합니다. 브라우저·운영체제·Credential 종류에 따라 UI와 선택 과정이 달라질 수 있습니다.

소셜 로그인과 TOTP 대체 인증

• 기본 소셜 인증은 OAuth Provider 인증 후 추가 인증을 요구합니다.
• 관리자가 Passkey를 통한 TOTP 대체를 허용한 경우, 해당 인증 흐름에서 등록된 Passkey를 추가 인증 수단으로 사용할 수 있습니다.
• Passkey 대체 허용은 신규 소셜 회원의 TOTP 등록 정책이나 다른 추가 인증 요구를 자동으로 제거한다는 뜻이 아닙니다.
• Provider별 Client ID·Secret 및 OAuth callback URL도 별도로 설정해야 합니다.

관리자 설정 후 점검표

• 플러그인 활성화 및 저장된 Passkey 정책 확인
• HTTPS app.url 및 접속 도메인 일치
• 마이페이지에서 Passkey 등록 및 목록 표시
• Passkey 이름 변경 후 정상 저장
• 독립 Passkey 로그인 성공
• 기존 TOTP 인증 및 복구 경로 유지
• 소셜 TOTP 대체를 사용하는 경우 해당 흐름 확인
• 다른 인증 수단 없이 마지막 Credential을 제거할 수 없는지 확인

이 절차는 사용 설명이며, 관리자 UI의 정확한 토글 명칭과 초기 설정값을 확인한 실측 화면 설명은 아닙니다.

독립 Vendor Bundle과 코어 호환성

v1.1.4부터 플러그인 내부의 사설 Composer 의존성을 다음 네임스페이스로 격리합니다.

Glitter\SocialTotpPasskey\Vendor\

예를 들어 코어의 Brick\Math\RoundingMode와 플러그인의 Glitter\SocialTotpPasskey\Vendor\Brick\Math\RoundingMode가 서로 다른 버전으로 공존할 수 있습니다.

이 변경은 플러그인 autoloader가 코어와 다른 확장의 동일한 FQCN을 선점해 발생할 수 있는 충돌을 줄이기 위한 것입니다. WebAuthn·CBOR·COSE·Socialite 등 사설 의존성은 선택적으로 격리하고, Laravel·PSR 등 공용 통합 계약은 공유합니다.

• 코어 Composer 의존성 수정 불필요
• 독립 vendor-bundle.zip 배포 유지
• PHP-Scoper 기반 재현 가능한 빌드
• 오토로더 등록 순서별 회귀 검사
• Vendor Bundle 무결성 및 결정론적 빌드 검증

주의: 공유 프레임워크 API와의 호환성은 여전히 필요하며, 모든 미래의 코어 업데이트와 무조건 호환된다는 의미는 아닙니다.

v1.1.5 주요 변경 사항

Passkey Credential 이름 변경 수정

• 이름 변경 API에서 CSRF 검증 전에 API 세션을 시작하도록 미들웨어 순서 수정
• Credential 이름 변경 Form의 name 속성 충돌 해결 (passkey_name 사용)

Passkey 등록 및 소셜 회원가입 Form 수정

• Passkey 등록 Form의 입력 이름 충돌 해결 (passkey_name 사용)
• 소셜 회원가입 Form의 입력 이름 충돌 해결 (registration_name 사용)
• 클라이언트 입력 필드 이름을 분리하면서 서버 API의 name 요청 키는 유지

배포 및 버전 관리

• plugin, Composer, npm, 설정·라우트·관리자 레이아웃 등 버전 선언을 1.1.5로 동기화
• 공식 scoped vendor 번들 재생성 및 무결성 검증
• 운영에서 1.1.4 → 1.1.5 업데이트 명령 성공 확인 (전체 인증 회귀 테스트 완료를 의미하지 않음)

v1.1.4 주요 변경 사항

Vendor 의존성 충돌 방지

• 사설 Vendor 라이브러리를 전용 네임스페이스로 격리
• 서로 다른 brick/math 버전 공존 검증
• vendor-scope.php 빌드·검증 도구 및 회귀 테스트 추가

Passkey 인증 보안 강화

• WebAuthn assertion 검증 후 Credential 보안 상태 저장이 false를 반환하면 인증 실패 처리
• 저장 중 예외가 발생해도 인증 실패 처리
• Credential 저장 성공 전 인증 성공 결과를 생성하지 않도록 개선

소셜 Provider 순서 캐시 개선

• Provider 표시 순서가 실제로 변경될 때만 서버 레이아웃 캐시 무효화
• 레이아웃 캐시 정리 후 코어 확장 캐시 버전 갱신
• 변경 없는 저장 또는 provider_order 없는 저장의 불필요한 캐시 갱신 방지

설치 및 업데이트

Plugin ID: glitter-social_totp_passkey
Version: 1.1.5
Repository: https://github.com/glitter-node/glitter-social_totp_passkey

Gnuboard7 관리자 플러그인 관리 기능 또는 공식 플러그인 lifecycle을 이용합니다. 활성 설치본을 파일 복사만으로 덮어쓰는 방식은 권장하지 않습니다.

공식 bundled 1.1.5 원본이 준비된 환경에서 기존 설치를 업데이트하는 예시:

cd /ProjectRoot
php artisan plugin:update glitter-social_totp_passkey --force --source=bundled --vendor-mode=bundled --layout-strategy=keep
php artisan optimize:clear

위 경로와 PHP 실행 파일은 예시 운영 환경 기준이며, 설치 환경에 맞게 변경해야 합니다. 업데이트 전에 백업과 복구 절차를 확보하세요.

개발자용 Vendor Bundle 재생성

원시 plugin:vendor-bundle --force만으로 생성한 ZIP은 네임스페이스 격리가 적용되지 않은 중간 산출물입니다. 최종 배포용 Bundle은 전용 wrapper를 통해 생성하고 검증해야 합니다.

php plugins/_bundled/glitter-social_totp_passkey/tools/vendor-scope.php build
php plugins/_bundled/glitter-social_totp_passkey/tools/vendor-scope.php verify

필요한 PHP-Scoper 빌드 도구는 저장소의 tools/php-scoper/ 및 README 안내를 따릅니다.

설치 후 확인

1. 플러그인 활성화와 관리자 설정을 확인합니다.
2. OAuth Provider별 앱 자격 증명과 callback URL을 등록합니다.
3. TOTP 등록·인증 및 QR 코드 표시를 확인합니다.
4. Passkey 등록·로그인·재인증·삭제를 지원 브라우저에서 시험합니다.
5. 카카오·네이버 등 OAuth callback과 계정 연결·해제를 점검합니다.
6. 기존 모듈의 API가 Vendor 충돌 없이 정상 동작하는지 확인합니다.

테스트 및 검증 현황

v1.1.4 기반 소스·독립 실행 검증에서 확인된 항목

• 코어/플러그인 autoloader 두 등록 순서에서 격리된 Brick Math 공존
• WebAuthn options·Serializer 객체 생성 및 CBOR·COSE 클래스 로딩
• TOTP QR SVG 생성
• Socialite·Kakao·Naver 타입 연결
• Passkey Credential 저장 성공·실패·예외 처리 계약
• Vendor Bundle 검증 및 반복 빌드 동일 해시
• PHP 문법 및 정적 계약 검사
• vendor-scope.php verify: PASS
• verify-production-readonly.sh: SUMMARY PASS (제공된 실행 결과 기준)

v1.1.5 빌드 및 운영 업데이트에서 추가 확인된 항목

• 공식 vendor-scope.php build 및 verify 통과 (사용자 제공 실행 보고 기준)
• vendor-bundle.zip SHA-256: 5e4d565525949ad36228b53a5581a569924a4070553d8c7e689f616cd8a9c065
• ZIP 내부 Composer root 버전 1.1.5 확인
• 운영 plugin:update에서 1.1.4 → 1.1.5 성공 및 optimize:clear 완료
• Passkey 브라우저 등록·로그인·이름 변경은 업데이트 이전 사용자 확인 이력이 있으며, 업데이트 이후 전체 회귀 검증은 별도 필요

별도 운영 통합 검증이 필요한 항목

• 실제 브라우저 Passkey 등록·인증
• 실제 서명된 WebAuthn assertion 검증
• 실제 TOTP 코드 인증
• 실제 OAuth Provider callback
• 운영 서비스 프로바이더 전체 bootstrap 및 HTTP API 복구

위 결과는 독립·정적 검증을 뜻하며, 전체 브라우저 E2E 또는 보안 침투 테스트 완료를 의미하지 않습니다.

기존 제품과의 관계

기존 플러그인을 단순히 이름만 바꾼 제품이 아니며, 별도 식별자와 데이터 구조를 가진 독립 플러그인입니다.

유의 사항

• OAuth 인증만으로 최종 소셜 로그인이 완료되지 않으며 추가 인증 정책이 적용됩니다.
• 동일 이메일만으로 기존 회원 계정에 자동 연결하지 않습니다.
• Passkey 이용 가능 여부는 HTTPS, 브라우저, 기기 및 사용자 설정에 영향을 받습니다.
• TOTP는 피싱에 완전히 안전한 인증 수단이 아닙니다.
• OAuth 애플리케이션 등록과 비밀키 관리는 사이트 운영자가 수행해야 합니다.
• Vendor 네임스페이스 격리는 확인된 FQCN 충돌을 방지하지만 모든 향후 프레임워크 호환성을 보장하지 않습니다.
• 실제 운영 배포 후에는 인증 기능과 주요 HTTP API를 별도로 검증해야 합니다.

Glitter Social TOTP Passkey v1.1.5는 Gnuboard7에서 **5종 소셜 로그인, 필수 TOTP, Passkey(WebAuthn)**를 통합하고, 계정 보호와 독립 Vendor 배포 안정성을 강화한 인증 플러그인입니다.

GitHub: https://github.com/glitter-node/glitter-social_totp_passkey
Release: https://github.com/glitter-node/glitter-social_totp_passkey/releases/tag/v1.1.5
License: MIT