외부 계정 로그인(OIDC / OAuth)
외부 계정 로그인은 QQ, Google, Microsoft, GitHub 또는 호환 OIDC ID 제공자를 TOTP 자격 증명에 연결합니다. TOTP 로그인 모드에서만 사용할 수 있으며 외부 로그인에 성공한 뒤에도 fn-knock의 세션과 서비스 범위를 사용합니다.
QQ 내장 연동
QQ는 fn-knock에 내장된 공용 제공자이므로 QQ 애플리케이션 등록, 클라이언트 ID, 클라이언트 시크릿, 발급자(Issuer) 입력 또는 콜백 URL 수동 등록이 필요하지 않습니다. 제공자를 추가한 뒤에는 사용자별 QQ 계정을 대상 TOTP 자격 증명에 연결합니다.
전체 사전 요구 사항, 연결 초대, 콜백 요구 사항 및 연결 해제 방법은 QQ 빠른 로그인 연결을 참고합니다.
Google, Microsoft, GitHub 및 사용자 지정 OIDC
- 인증 Host가 인터넷에서 접속 가능한 HTTPS 주소로 설정되어 있는지 확인합니다.
- 인증 설정 상단 작업 메뉴의
OIDC 설정에서 제공자를 추가합니다. - fn-knock에 표시된 콜백 URL을 변경하지 말고 외부 제공자의 콜백 주소 목록에 그대로 입력합니다.
- 제공자가 요구하는 클라이언트 ID와 클라이언트 시크릿을 입력합니다. Microsoft는
common,organizations또는 테넌트 ID를 지정할 수 있고, 사용자 지정 OIDC에는 발급자(Issuer)도 필요합니다. - 범위(Scopes)를 확인합니다. 공백이나 쉼표로 구분하여 입력할 수 있으며, 제공자가 사용자를 식별하는 데 필요한
openid와 필수 사용자 정보 범위를 최소한 유지합니다. - 대상 TOTP 자격 증명의
빠른 로그인 관리 → 외부 계정 연결에서 초대를 생성하고 인증을 완료하여 계정을 연결합니다. - 로그인 페이지를 시크릿 창에서 검증한 뒤 해당 TOTP의 서비스 범위도 확인합니다.
콜백 URL에는 방문자에게 실제로 보이는 인증 Host를 사용합니다. localhost, 컨테이너 이름, LAN IP 또는 잘못된 포트를 사용하면 외부 제공자가 콜백을 거부합니다. QQ의 동적 콜백은 시스템에서 처리하므로 이 절의 수동 등록 단계가 적용되지 않습니다.
일반 제공자는 필수 연결 매개변수가 모두 있으면 활성화된 상태로 생성됩니다. 매개변수가 빠지면 설정 필요 초안으로 저장됩니다. 편집할 때 클라이언트 시크릿을 비워 두면 기존 값을 유지합니다. 제공자를 비활성화하면 로그인 엔드포인트를 숨기거나 거부하지만 나중에 다시 활성화할 수 있도록 설정은 남겨 둡니다.
접근 범위
OIDC는 독립된 관리자 ID가 아닙니다. 연결된 TOTP의 서브도메인 범위를 상속합니다. 연결을 해제하면 외부 계정으로 더 이상 로그인할 수 없지만 TOTP 자체는 삭제되지 않습니다. 제공자를 삭제하면 해당 제공자의 외부 계정 연결도 모두 제거되므로 모든 사용자에게 TOTP 또는 다른 복구 수단이 있는지 먼저 확인합니다.
연결 초대는 30분 동안 유효하며 인증을 완료한 외부 ID를 현재 TOTP에 연결합니다. 초대 링크는 민감한 인증 자료이므로 단체 채팅방, 지원 티켓 또는 공개 페이지에 올리면 안 됩니다. 연결 후 빠른 로그인 관리 페이지에서 제공자, 계정, 주체(Subject) 및 마지막 사용 시각을 확인합니다.
자주 발생하는 문제
| 증상 | 확인할 항목 |
|---|---|
| 로그인 페이지에 외부 계정 버튼이 없음 | 현재 TOTP 로그인 모드이고 제공자가 활성화되어 있는지 확인 |
| 제공자가 콜백을 거부함 | 콜백 URL, HTTPS, 허용된 리디렉션 URI, 도메인 및 포트 확인 |
| 콜백 후 연결되지 않았다고 표시됨 | 먼저 fn-knock에서 외부 계정과 TOTP 연결 완료 |
| 로그인 후에도 거부됨 | 연결된 TOTP의 서비스 범위와 대상 Host 정책 확인 |