TsgcWSAPIServer_WebAuthn 컴포넌트는 HTTPS 위에서 WebAuthn 프로토콜의 의존 당사자(relying-party) 측을 구현하는 Delphi/FPC 서버 모듈이에요. TsgcWebSocketHTTPServer 또는 TsgcWebSocketServer와 통합되며, 등록과 인증을 위한 REST 형태의 엔드포인트를 제공해요.
엔드포인트 동작 방식
기본적으로 컴포넌트는 /sgcWebAuthn 아래에 라우트를 등록해요.
| 용도 | 기본 엔드포인트 | 설명 |
|---|---|---|
| 등록 옵션 | /Registration/Options | 클라이언트가 navigator.credentials.create를 호출하기 전에 challenge와 relying-party 정보를 요청해요 |
| 등록 확인 | /Registration/Verify | 브라우저가 서버 검증을 위해 새 자격 증명, attestation 객체, 클라이언트 데이터를 전송해요 |
| 인증 옵션 | /Authentication/Options | 서버가 허용된 자격 증명 ID 목록과 challenge를 제공해요 |
| 인증 확인 | /Authentication/Verify | 브라우저가 검증을 위해 어설션(authenticatorData + 서명)을 전송해요 |
| JavaScript 헬퍼 | /Webauthn | 표준 WebAuthn 브라우저 호출을 감싸는 헬퍼 스크립트를 제공해요 |
| 테스트 페이지 | /Test | 개발용으로 API를 손쉽게 시험해 볼 수 있는 HTML 페이지예요 |
엔드포인트는 기존 라우팅 체계에 맞추기 위해 EndpointOptions로 재매핑할 수 있어요.
핵심 속성
- RelyingParty (RPID / RPName) – 자격 증명에 대한 논리적 도메인을 식별하는 필수 DNS 이름이에요. 애플리케이션의 유효 도메인과 일치하는지 확인해 주세요.
- Origins & TopOrigins – 세미콜론으로 구분된 유효 origin 목록이에요.
Origins는 기본 도메인을 다루고,TopOrigins는 iframe에 임베드할 때 사용돼요. - AllowCrossOrigins –
True로 설정하면 cross-origin iframe이 인증을 요청할 수 있어요. 이때는TopOrigins를 신중하게 큐레이션하고 서버 측 검증이 필요해요. - Algorithms – 지원하는 COSE 알고리즘 식별자(예:
ES256,RS256,EdDSA)예요. 서버가 어떤 공개키 종류를 받아들일지 제어해요. - TimeoutMS – WebAuthn 작업을 완료하기 위해 클라이언트에 권장되는 타임아웃이에요.
- UserVerification – 사용자 검증 정책이에요(
preferred,required,discouraged). - Attestation – attestation을 none, indirect, direct 중 무엇으로 할지 지정해요. Direct attestation은 attestation 인증서 체인 검증이 필요해요.
- Metadata Service (MDS) – 활성화하면 컴포넌트가 FIDO Metadata Service 파일을 참조해 인증기 모델의 신뢰성을 확인해요. 필드는 다음과 같아요.
MDS_FileName– 로컬에 캐시된 JSON 메타데이터(FIDO에서 다운로드).RootCert_FileName– 메타데이터 서명을 검증하는 루트 인증서.
- ChallengeOptions – 생성되는 challenge의 길이와 난수 소스를 커스터마이징할 수 있어요.
- CredentialStorage – 직접적인 속성은 아니지만, 컴포넌트는 애플리케이션이 자격 증명 공개키, 서명 카운터, 사용자 핸들을 영속화할 것으로 가정해요.
이벤트 생명주기
등록
OnWebAuthnRegistrationOptionsRequest(Sender, Request, Response): 사용자 이름을 검사하고, 유효하지 않으면 중단하거나 사용자 정보를 제공해요.OnWebAuthnRegistrationOptionsResponse(Sender, Request, Response): 클라이언트에 전송하기 전에 challenge를 수정하거나 인증기 선택 기준을 설정해요.OnWebAuthnRegistrationVerify(Sender, Credential, var Success): 커스텀 attestation 검사를 수행하거나 등록을 거부할 수 있어요.OnWebAuthnRegistrationSuccessful(Sender, Credential): 자격 증명 ID, 공개키, 서명 카운터, 사용자 핸들을 데이터베이스에 저장해요.OnWebAuthnRegistrationError(Sender, ErrorCode, ErrorMsg): 더 상세한 오류를 로깅하거나 반환해요.
인증
OnWebAuthnAuthenticationOptionsRequest(Sender, Request, Response): 사용자 이름에 대한 자격 증명 ID를 조회하고, 허용 전송 수단(USB, NFC, BLE, internal)을 결정해요.OnWebAuthnAuthenticationOptionsResponse(Sender, Request, Response):UserVerification을 커스터마이징하고, challenge 길이를 조정하거나 추가 메타데이터를 포함해요.OnWebAuthnAuthenticationVerify(Sender, Credential, var Success): 서명 카운터 진행을 검증하고 계정 상태 검사를 강제해요.OnWebAuthnAuthenticationSuccessful(Sender, Credential): 서명 카운터를 업데이트하고 세션 토큰을 생성해요.OnWebAuthnAuthenticationError(Sender, ErrorCode, ErrorMsg): 속도 제한, 잠금 정책, 감사 기능을 구현해요.
이러한 이벤트로 옵션 생성부터 어설션 처리까지 프로토콜의 모든 단계를 세밀하게 제어할 수 있어요.