외부 계정 로그인(OIDC / OAuth / LDAP)

외부 계정 로그인은 QQ, Google, Microsoft, GitHub, 호환 OIDC ID 제공자 또는 LDAP / Active Directory 디렉터리 계정을 TOTP 자격 증명에 연결합니다. TOTP 로그인 모드에서만 사용할 수 있으며 로그인에 성공한 뒤에도 fn-knock 세션, 연결된 TOTP의 서비스 범위 및 로그인 후 IP 접근 정책을 사용합니다.

OIDC / OAuth는 브라우저를 외부 사이트로 이동해 권한을 승인합니다. LDAP는 fn-knock 서버가 LDAPS 또는 StartTLS로 디렉터리에 연결합니다. 두 방식 모두 기존 TOTP에 먼저 연결해야 하며 fn-knock ID를 자동으로 만들지 않습니다.

QQ 내장 연동

QQ는 fn-knock에 내장된 공용 제공자이므로 QQ 애플리케이션 등록, 클라이언트 ID, 클라이언트 시크릿, 발급자(Issuer) 입력 또는 콜백 URL 수동 등록이 필요하지 않습니다. 제공자를 추가한 뒤에는 사용자별 QQ 계정을 대상 TOTP 자격 증명에 연결합니다.

전체 사전 요구 사항, 연결 초대, 콜백 요구 사항 및 연결 해제 방법은 QQ 빠른 로그인 연결을 참고합니다.

Google, Microsoft, GitHub 및 사용자 지정 OIDC

1. 인증 Host가 인터넷에서 접속 가능한 HTTPS 주소로 설정되어 있는지 확인합니다.
2. 인증 설정 상단 작업 메뉴의 OIDC 설정에서 제공자를 추가합니다.
3. fn-knock에 표시된 콜백 URL을 변경하지 말고 외부 제공자의 콜백 주소 목록에 그대로 입력합니다.
4. 제공자가 요구하는 클라이언트 ID와 클라이언트 시크릿을 입력합니다. Microsoft는 common, organizations 또는 테넌트 ID를 지정할 수 있고, 사용자 지정 OIDC에는 발급자(Issuer)도 필요합니다.
5. 범위(Scopes)를 확인합니다. 공백이나 쉼표로 구분하여 입력할 수 있으며, 제공자가 사용자를 식별하는 데 필요한 openid와 필수 사용자 정보 범위를 최소한 유지합니다.
6. 대상 TOTP 자격 증명의 빠른 로그인 관리 → 외부 계정 연결에서 초대를 생성하고 인증을 완료하여 계정을 연결합니다.
7. 로그인 페이지를 시크릿 창에서 검증한 뒤 해당 TOTP의 서비스 범위도 확인합니다.

콜백 URL에는 방문자에게 실제로 보이는 인증 Host를 사용합니다. localhost, 컨테이너 이름, LAN IP 또는 잘못된 포트를 사용하면 외부 제공자가 콜백을 거부합니다. QQ의 동적 콜백은 시스템에서 처리하므로 이 절의 수동 등록 단계가 적용되지 않습니다.

일반 제공자는 필수 연결 매개변수가 모두 있으면 활성화된 상태로 생성됩니다. 매개변수가 빠지면 설정 필요 초안으로 저장됩니다. 편집할 때 클라이언트 시크릿을 비워 두면 기존 값을 유지합니다. 제공자를 비활성화하면 로그인 엔드포인트를 숨기거나 거부하지만 나중에 다시 활성화할 수 있도록 설정은 남겨 둡니다.

LDAP / Active Directory

인증 설정 → OIDC 설정으로 이동하여 LDAP / Active Directory 제공자에서 OpenLDAP, Active Directory 또는 사용자 지정 LDAP를 추가합니다. 디렉터리 연결은 항상 TLS 인증서를 검증하며 평문 LDAP는 지원하지 않습니다. 사설 CA를 사용한다면 발급 체인의 PEM 인증서를 사설 CA PEM에 붙여 넣습니다.

설정	동작
서버 URL	한 줄에 하나씩 입력합니다. LDAPS는 ldaps://ldap.example.com:636, StartTLS는 ldap://ldap.example.com:389를 사용하며 사용할 수 없는 서버를 순서대로 시도합니다
Base DN	사용자 검색 루트 DN입니다. 예: dc=example,dc=com
검색 후 바인드	서비스 계정으로 Base DN 아래에서 사용자를 정확히 한 명 찾은 뒤 해당 사용자 DN과 비밀번호로 검증합니다
직접 바인드	{username} 템플릿으로 DN 또는 UPN을 만들고 비밀번호를 검증한 뒤 Base DN 아래에서 ID 속성을 읽습니다
사용자 필터	{username}을 반드시 포함하며 입력값은 LDAP 필터 값으로 이스케이프됩니다
안정 ID 속성	같은 디렉터리 ID를 지속적으로 식별합니다. OpenLDAP 기본값은 entryUUID, Active Directory 기본값은 objectGUID입니다

제공자를 활성화하기 전에 테스트를 실행합니다. 검색 후 바인드는 연결과 서비스 계정을 테스트합니다. 직접 바인드는 일회성 테스트용 디렉터리 계정을 요청하며 테스트 자격 증명은 저장하지 않습니다. 연결 시간 초과, 인증서 이름 또는 사설 CA 오류, 잘못된 Base DN, 필터가 사용자를 찾지 못하거나 여러 명을 반환하면 로그인이 실패합니다.

디렉터리 계정 연결

1. 인증 설정에서 대상 TOTP의 빠른 로그인을 엽니다.
2. 외부 계정 연결에서 초대를 만들고 활성화된 LDAP 제공자를 선택합니다.
3. 디렉터리 사용자가 30분 안에 초대 링크를 열고 봇 검증을 완료한 뒤 사용자 이름과 비밀번호를 입력합니다.
4. 빠른 로그인 페이지로 돌아와 제공자, 계정, 주체(Subject), 마지막 사용 시각을 확인하고 시크릿 창에서 로그인을 검증합니다.

초대 링크는 검증에 성공한 디렉터리 ID를 지정한 TOTP에 연결하는 민감한 인증 자료입니다. 같은 제공자의 디렉터리 ID 하나를 여러 TOTP에 동시에 연결할 수 없습니다. 연결을 삭제해도 fn-knock 내부 연결만 제거되며 디렉터리 계정은 변경되지 않습니다. 제공자를 삭제하면 해당 제공자의 모든 연결도 함께 삭제됩니다.

접근 범위

OIDC와 LDAP는 독립된 관리자 ID가 아닙니다. 연결된 TOTP의 서브도메인과 프로토콜 매핑 범위를 상속합니다. 연결을 해제하면 외부 계정으로 더 이상 로그인할 수 없지만 TOTP 자체는 삭제되지 않습니다. 제공자를 삭제하면 해당 제공자의 외부 계정 연결도 모두 제거되므로 모든 사용자에게 TOTP 또는 다른 복구 수단이 있는지 먼저 확인합니다.

연결 초대는 30분 동안 유효하며 인증을 완료한 외부 ID를 현재 TOTP에 연결합니다. 초대 링크는 민감한 인증 자료이므로 단체 채팅방, 지원 티켓 또는 공개 페이지에 올리면 안 됩니다. 연결 후 빠른 로그인 관리 페이지에서 제공자, 계정, 주체(Subject) 및 마지막 사용 시각을 확인합니다.

자주 발생하는 문제

증상	확인할 항목
로그인 페이지에 외부 계정 항목이 없음	현재 TOTP 로그인 모드이고 제공자가 활성화되었으며 필수 설정이 모두 완료되었는지 확인
제공자가 콜백을 거부함	콜백 URL, HTTPS, 허용된 리디렉션 URI, 도메인 및 포트 확인
콜백 후 연결되지 않았다고 표시됨	먼저 fn-knock에서 외부 계정과 TOTP 연결 완료
LDAP 서비스를 사용할 수 없다고 표시됨	fn-knock 실행 환경에서 디렉터리 DNS, 포트, TLS 인증서 체인 및 시스템 시간 확인
LDAP 자격 증명이 맞지만 로그인 실패	Base DN, 사용자 필터, 바인드 모드, 안정 ID 및 사용자 이름 속성을 확인하며 검색 결과는 하나여야 함
로그인 후에도 거부됨	연결된 TOTP의 서비스 범위와 대상 Host 정책 확인

• QQ 빠른 로그인 연결
• TOTP 인증기
• 패스키
• 인증, 세션 및 서비스 범위