getClientCapabilities()를 사용한 간단한 WebAuthn 기능 감지

Eiji Kitamura

게시일: 2025년 1월 15일

WebAuthn은 하이브리드 프로토콜을 위한 블루투스와의 상호작용, 패스키 제공업체와의 통신, 자동 완성에서 패스키 제안과 같은 고유한 기능을 제공합니다. 하지만 클라이언트와 인증자에 따라 WebAuthn 기능에 대한 지원 수준이 다릅니다. 이러한 불일치는 일부 사용자에게 오류가 발생하거나 특정 인증 옵션을 활용할 수 없는 등 사용자 경험이 분열될 수 있습니다. 개발자가 클라이언트 기능을 결정할 수 있는 방법을 제공하면 이러한 변형에 적응하는 더 강력한 인증 흐름을 만들 수 있습니다.

PublicKeyCredential.getClientCapabilities() 메서드를 사용하면 신뢰 당사자가 브라우저에서 지원되는 WebAuthn 기능을 확인할 수 있습니다. 이 메서드는 지원되는 기능 목록으로 확인되는 프로미스를 반환하므로 개발자는 클라이언트의 특정 기능에 따라 인증 환경과 워크플로를 조정할 수 있습니다.

호환성

Browser Support

  • Chrome: not supported.
  • Edge: not supported.
  • Firefox: not supported.
  • Safari: 17.4.

getClientCapabilities()

getClientCapabilities()는 신뢰 당사자가 사용 가능한 기능을 결정할 수 있는 WebAuthn API입니다. API를 사용하려면 PublicKeyCredential.getClientCapabilities()를 호출해야 합니다. 반환된 프로미스는 기능이 포함된 객체로 확인되며, 각 기능은 true 또는 false의 사용 가능 여부를 나타냅니다. 기능이 undefined인 경우 사용 가능 여부가 알려지지 않은 것으로 간주합니다.

if (window.PublicKeyCredential &&
  if (PublicKeyCredential.getClientCapabilities) {
    const capabilities = await PublicKeyCredential.getClientCapabilities();
    if (capabilities.conditionalGet === true &&
        capabilities.passkeyPlatformAuthenticator === true) {
      // The browser supports passkeys and the conditional mediation.
    }
  }
}

conditionalCreate

사용자가 이미 사용자 인증 정보 생성에 동의한 경우 브라우저는 눈에 띄는 모달 UI 없이 사용자 인증 정보를 만들 수 있습니다.

conditionalGet

브라우저는 눈에 띄는 모달 UI 대신 자동 완성 대화상자의 일부로 패스키를 표시하여 인증할 수 있습니다. 기존 등가 항목은 PublicKeyCredential.isConditionalMediationAvailable()입니다.

hybridTransport

기기는 블루투스를 사용하여 브라우저가 사용자 인증 정보를 만들고 하이브리드 프로토콜을 사용하여 교차 기기 인증을 할 수 있도록 할 수 있습니다. 일반적으로 이는 브라우저가 QR 코드를 표시하여 사용자가 이를 스캔하고 사용자 인증 정보가 있는 휴대전화로 로그인할 수 있음을 의미합니다.

passkeyPlatformAuthenticator

브라우저는 사용자 인증 플랫폼 인증자 또는 하이브리드 프로토콜을 통해 이를 지원하는 다른 기기를 통해 사용자 인증 정보를 만들고 이를 사용하여 인증할 수 있습니다. hybridTransport || userVerifyingPlatformAuthenticator와 같습니다.

relatedOrigins

브라우저는 관련 출처 파일에 지정된 경우 RP ID와 일치하지 않는 사용자 인증 정보를 만들고 이를 사용하여 인증할 수 있습니다.

signalAllAcceptedCredentials

브라우저는 서버의 사용 가능한 사용자 인증 정보를 패스키 제공업체에 전달하여 패스키 제공업체가 패스키 목록을 서버와 일관되게 유지할 수 있도록 할 수 있습니다.

signalCurrentUserDetails

브라우저는 서버의 사용자 이름 및 표시 이름과 같은 사용자 정보를 패스키 제공업체에 신호하여 패스키 제공업체가 패스키 정보를 서버와 일관되게 유지할 수 있도록 할 수 있습니다.

signalUnknownCredential

브라우저는 서버에서 삭제된 사용자 인증 정보를 패스키 제공업체에 전달하여 패스키 제공업체가 패스키 목록을 서버와 일관되게 유지할 수 있도록 할 수 있습니다.

userVerifyingPlatformAuthenticator

브라우저는 플랫폼 인증자에 사용자 인증 정보를 만들고 이를 사용하여 인증할 수 있습니다. 그렇다고 해서 브라우저가 하이브리드 프로토콜을 지원하는 것은 아닙니다. 기존 등가 항목은 PublicKeyCredential.isUserVerifyingPlatformAuthenticatorAvailable()입니다.

extensions

RP는 getClientCapabilities()를 사용하여 사용 가능한 확장 프로그램을 확인할 수도 있습니다.

if (capabilities['extension:appid'] === true) {
  // appId extension is supported
}

식별자 앞에는 extension:가, 그 뒤에 확장자 이름이 붙습니다. 확장 프로그램 이름은 IANA에 정의된 WebAuthn 확장 프로그램 식별자를 참고하세요.

자세히 알아보기

패스키에 대해 자세히 알아보려면 패스키를 사용한 비밀번호 없는 로그인부터 시작하세요.