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

Eiji Kitamura

게시일: 2025년 1월 15일

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

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

호환성

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()입니다.

확장 프로그램

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

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

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

자세히 알아보기

패스키에 대해 자세히 알아보려면 패스키를 사용한 패스워드리스 로그인을 참고하세요.