QQ 빠른 로그인 연동
QQ 빠른 로그인은 하나의 QQ 계정을 지정한 TOTP 자격 증명에 연결합니다. 연결 후 방문자는 로그인 페이지에서 QQ를 선택해 인증을 마칠 수 있습니다. 이 로그인은 해당 TOTP의 서비스 범위와 세션 정책을 그대로 따르며, 별도의 사용자나 관리자 ID가 아닙니다.
fn-knock에는 QQ 연동 기능이 내장되어 있습니다. QQ 오픈 플랫폼에 애플리케이션을 등록하거나 클라이언트 ID, 클라이언트 시크릿, 발급자(Issuer) 또는 콜백 주소를 입력할 필요가 없습니다.
연결에 성공하면 로그인 페이지에 “QQ로 로그인”이 표시됩니다. 방문자는 사람 확인을 마친 뒤 연결된 QQ 계정으로 로그인할 수 있습니다.
사용 전 확인
- 현재
TOTP 로그인 모드를 사용합니다. 계정 비밀번호 로그인 모드에서는 QQ 로그인이 표시되지 않으며 사용할 수도 없습니다. - 대상 TOTP 자격 증명과 사용 가능한 다른 TOTP 또는 복구 수단을 준비합니다. QQ를 유일한 복구 수단으로 두면 안 됩니다.
- 인증 Host에는 외부에서 최종적으로 접근할 수 있는 HTTPS 주소를 지정합니다. 예를 들면
https://auth.example.com입니다.localhost, 컨테이너 이름, 사설 IP 또는 잘못된 포트는 사용할 수 없습니다. - fn-knock가 실행되는 기기에서
https://api.fnknock.cn에 접근 가능한지 확인합니다. QQ를 추가할 때 이 서비스의 OIDC 디스커버리 정보를 읽습니다.
인증 Host는 QQ 로그인 과정에 필요한 콜백과 클라이언트 메타데이터도 동적으로 제공합니다. CDN이나 리버스 프록시에서 /api/auth/oidc/ 아래의 동적 응답을 캐시하지 말고, 콜백 경로에 별도의 로그인 보호도 추가하지 않습니다. 앞단 프록시는 방문자가 실제로 사용한 Host와 외부 공개 프로토콜을 유지합니다.
1. QQ 제공자 추가
관리자 페이지에서 다음 순서로 이동합니다.
인증 설정 → 상단 작업 메뉴의 OIDC 설정 → 제공자 추가 → QQ → 추가QQ에는 직접 입력하는 연결 필드가 없습니다. 저장하면 시스템은 먼저 제공자를 비활성화 상태로 유지한 채 디스커버리를 테스트하며, 테스트에 성공하면 자동으로 활성화합니다. 테스트에 실패하면 기기에서 api.fnknock.cn까지의 DNS, 네트워크 또는 TLS 문제를 해결한 뒤 다시 추가합니다.
테스트 성공은 내장 서비스를 찾을 수 있다는 뜻일 뿐이며, 아래의 인터넷 콜백 검증을 대신하지는 않습니다.
2. QQ를 TOTP 자격 증명에 연결
인증 설정의TOTP 관리로 돌아갑니다.- 권한을 부여할 TOTP 자격 증명 행에서
빠른 로그인 관리를 클릭합니다. 외부 계정 연결에서연결 초대 생성을 클릭하고QQ를 선택한 다음생성을 클릭합니다.- 대상 QQ 계정을 사용하는 브라우저에서 생성된 링크를 열고 “QQ로 연결”을 선택해 승인을 마칩니다.
- 관리 페이지로 돌아와 “외부 계정 연결” 목록에 QQ 레코드가 표시되는지 확인합니다.
초대 링크는 30분 동안만 유효하며 한 번 성공적으로 사용하면 바로 만료됩니다. 이 링크는 QQ 계정을 해당 TOTP의 권한에 연결하는 민감한 자격 증명과 같습니다. 단체 채팅방, 지원 티켓 또는 관계없는 사람에게 보내지 않습니다. 만료되었거나 잘못 보냈다면 새로 생성하면 됩니다.
같은 QQ ID를 다른 TOTP에 동시에 연결할 수는 없습니다. 연결 대상을 바꾸려면 먼저 기존 TOTP의 “외부 계정 연결”에서 이전 연결을 삭제한 뒤 새 TOTP에서 초대를 생성합니다.
3. 로그인 확인
시크릿 창이나 로그인하지 않은 브라우저에서 인증 Host 또는 보호된 서비스 Host를 직접 엽니다. 로그인 페이지에 QQ로 로그인이 표시되면 QQ 승인을 마친 뒤 원래 서비스 주소로 돌아오는지 확인합니다.
마지막으로 해당 TOTP의 서비스 범위를 확인합니다. QQ 로그인으로는 이 TOTP에 접근이 허용된 Host만 열 수 있습니다. LAN이나 루프백 출발지는 local_exempt를 적용받을 수 있으므로, 모바일 네트워크 같은 실제 외부 연결에서 최종 확인합니다.
콜백 주소를 직접 등록하지 않아도 되는 이유
QQ 내장 제공자는 현재 인증 Host를 기준으로 다음과 같은 주소를 자동 생성합니다.
https://auth.example.com/api/auth/oidc/callback/<provider-id>시스템은 현재 인스턴스의 클라이언트 메타데이터도 QQ 서비스에 제공합니다. 따라서 서드파티 콘솔에 콜백 URL을 복사하거나 자체 QQ 애플리케이션을 등록할 필요가 없습니다. 도메인, 포트 또는 앞단 프록시를 이전한 뒤에는 인증 Host의 HTTPS, Host 전달 및 외부 접근 가능 여부를 다시 확인하고 QQ 로그인을 재시험합니다.
연결 해제 및 문제 해결
QQ 연결을 삭제하면 해당 QQ 계정으로 즉시 로그인할 수 없게 되지만 TOTP 자체는 삭제되지 않습니다. QQ 제공자나 연결된 TOTP를 삭제해도 해당 연결이 제거됩니다. TOTP를 보관해 두면 QQ 승인 실패, 계정 변경 또는 기기 분실 시 접근을 복구할 수 있습니다.
| 증상 | 먼저 확인할 항목 |
|---|---|
| 로그인 페이지에 QQ 버튼이 없음 | 현재 TOTP 로그인 모드인지, QQ 제공자가 테스트에 성공해 활성화되었는지 확인 |
| QQ 추가 시 테스트 실패 | fn-knock에서 api.fnknock.cn까지의 DNS, 네트워크 연결 및 TLS 확인 |
| QQ 승인 후 콜백 실패 | 인증 Host가 최종 인터넷 공개 HTTPS 주소인지, 리버스 프록시가 Host를 유지하는지, 동적 OIDC 경로가 캐시되거나 차단되지 않았는지 확인 |
| QQ가 다른 자격 증명에 연결되었다고 표시됨 | 기존 TOTP의 “빠른 로그인 관리”에서 이전 연결을 삭제한 뒤 다시 연결 |
| 로그인에 성공해도 서비스에 들어갈 수 없음 | 연결된 TOTP의 서비스 범위와 대상 Host의 접근 정책 확인 |