WebAuthn 클라이언트 기능

Passkeys Cheat Sheet — dev-focused WebAuthn reference. Trusted by Ally, Stanford CS & more.

Get Cheat Sheet

WebAuthn은 패스키를 뒷받침하는 최신 표준입니다. 기존 비밀번호에 의존하는 대신 공개 키 암호화를 활용하여 생체 인식(지문이나 안면 인식) 또는 물리적 보안 키를 포함할 수 있는 패스키로 인증할 수 있게 해줍니다. 이러한 변화는 보안을 강화할 뿐만 아니라 비밀번호 관리의 필요성을 없애 사용자 경험을 크게 개선합니다.

WebAuthn 레벨 3 표준은 개발자와 플랫폼이 패스키를 구현할 때 더 많은 제어권과 유연성을 가질 수 있도록 새로운 클라이언트 기능(브라우저 API getClientCapabilities()를 통해 확인 가능)을 도입했습니다. 이 업데이트는 기기, 브라우저, 플랫폼 전반에서 패스키를 통합하는 과정을 간소화하여 더 매끄럽고 일관된 사용자 경험을 보장합니다.

이 블로그 포스트에서는 다음 질문들에 대해 알아보겠습니다.

1. WebAuthn 클라이언트 기능이란 무엇인가요?
2. 어떤 WebAuthn 클라이언트 기능이 있나요?
3. WebAuthn 클라이언트 기능이 패스키 구현을 어떻게 개선하나요?
4. 개발자와 프로덕트 매니저에게 WebAuthn 클라이언트 기능이 중요한 이유는 무엇인가요?

이 글을 끝까지 읽으시면 이러한 기능들이 현대적인 사용자의 기대에 부응하는 매끄럽고 안전한 인증 흐름을 만드는 데 어떻게 도움이 되는지 이해할 수 있을 것입니다.

WebAuthn 클라이언트 기능은 브라우저와 플랫폼이 어떤 WebAuthn 기능을 지원하는지 알려주는 기능 세트입니다. 간단히 말해, 사용자의 기기에서 사용 가능한 인증 방식과 설정이 무엇인지 웹사이트에 알려주는 '기능 체크리스트' 역할을 합니다. 이를 통해 개발자는 클라이언트의 기능에 맞춰 인증 흐름을 조정하고 더 매끄럽고 안전한 사용자 경험을 보장할 수 있습니다.

예를 들어, 브라우저가 생체 인증(예: Touch ID)을 지원한다고 알려오면, 개발자는 사용자가 지문으로 로그인할 수 있는 옵션을 제공하도록 로그인 흐름을 설계할 수 있습니다. 반대로 브라우저가 특정 기능을 지원하지 않는다면 비밀번호나 SMS OTP와 같은 대체 수단을 제공할 수 있습니다. 실제로 지원되지 않거나 중단된 기능 경로도 일반적인 브라우저 오류로 나타날 수 있으므로, 팀에서는 이러한 결과를 명시적인 WebAuthn 오류 분류에 매핑해 두는 것이 좋습니다.

WebAuthn Level 3 standard는 패스키 구현을 더욱 다재다능하고 사용자 친화적으로 만들어 주는 여러 새로운 클라이언트 기능을 도입했습니다. getClientCapabilities() API 호출에 대한 첫 번째 지원은 Safari 17.4에서 도입되었습니다.

브라우저의 지원 여부를 감지하려면 다음 코드 스니펫이 유용할 수 있습니다.

// 현재 브라우저에서 PublicKeyCredential이 지원되는지 확인합니다.
if (typeof PublicKeyCredential === "undefined") {
    console.log("PublicKeyCredential is not supported in this browser.");
}
 
// PublicKeyCredential에 getClientCapabilities 메서드가 있는지 확인합니다.
if (typeof PublicKeyCredential.getClientCapabilities === "function") {
    try {
        let capabilities = await PublicKeyCredential.getClientCapabilities();
        console.log(capabilities);
    } catch (error) {
        console.error("Error getting client capabilities:", error);
    }
} else {
    console.log("getClientCapabilities is not supported in this browser");
}

getClientCapabilities()를 사용하면 웹사이트와 앱이 클라이언트(예: 브라우저나 기기)에 쿼리하여 지원하는 WebAuthn 기능을 확인할 수 있습니다. 클라이언트의 기능을 이해함으로써 개발자는 생체 인증과 같이 사용 가능한 기능을 최대한 활용하도록 인증 흐름을 최적화하고, 특정 기능이 없는 경우 대체 방법을 제공할 수 있습니다.

Subscribe to our Passkeys Substack for the latest news.

Subscribe

WebAuthn 클라이언트 기능과 이들이 패스키 통합에 미치는 영향에 대해 자세히 알아보겠습니다.

conditionalCreate는 특정 조건에 따라 자동 패스키 생성을 활성화합니다. 애플리케이션은 비밀번호 관리자가 지원하는 경우 비밀번호 자동 완성 중에 이 기능을 사용하여 패스키를 자동으로 생성할 수 있습니다. 이는 사용자를 비밀번호에서 패스키로 자동으로 전환시켜 줌으로써 패스키 도입과 이후의 사용을 촉진하는 데 도움이 됩니다.

conditionalCreate와 유사하게, conditionalGet은 패스키 로그인을 자동으로 트리거합니다. 이는 로그인 과정을 비밀번호가 없을 뿐만 아니라 사용자 이름도 필요 없도록(사용자가 모달/드롭다운에서 선택한 패스키를 클릭하기만 하면 인증됨) 최적의 패스키 UX를 제공해야 하는 시나리오에서 유용합니다. 이 기능을 사용하면 개발자는 적절한 때에만 패스키 인증이 발생하도록 하여 불필요한 프롬프트를 최소화하고 사용자 경험을 향상할 수 있습니다.

hybridTransport는 패스키를 다양한 기기에서 사용할 수 있게 하여 원활한 교차 디바이스 인증(QR 코드 및 Bluetooth 사용)을 가능하게 합니다. 예를 들어, 사용자는 스마트폰에 저장된 패스키를 사용하여 데스크톱의 서비스에 로그인할 수 있습니다. 이 기능을 통해 사용자는 패스키 전송을 수동으로 하거나 각 기기에 대해 기존 로그인 방법에 의존할 필요 없이 안전하게 인증할 수 있어 통합된 인증 경험을 누릴 수 있습니다.

Windows Hello, Face ID, Touch ID와 같은 플랫폼 인증기(Authenticator)는 기기에 내장되어 있으며 사용자가 생체 인식이나 기타 기기 기본 방식(예: PIN 패턴)으로 인증할 수 있게 하여 더 빠르고 부드러우며 안전한 패스키 경험을 제공합니다.

Become part of our Passkeys Community for updates & support.

Join

userVerifyingPlatformAuthenticator는 패스키 인증에 실제 지문 스캔이나 안면 인식과 같은 사용자 검증(User Verification)이 포함되도록 보장하여 추가적인 보안 계층을 제공합니다.

relatedOrigins 기능은 동일한 조직이 소유한 다른 도메인(예: amazon.com 및 amazon.de) 전반에서 원활한 인증을 허용합니다. 예를 들어 회사가 여러 도메인을 관리하거나 여러 하위 도메인이 있는 경우, 사용자는 한 번만 로그인하면 각 도메인에서 다시 인증할 필요 없이 모든 자산에 접근할 수 있습니다. 이 기능은 사용자 경험을 간소화하여 마찰을 줄여주며, 특히 다국적 환경이나 다중 서비스 플랫폼을 갖춘 기업에 매우 유용합니다.

signalAllAcceptedCredentials(options) 메서드는 특정 사용자의 전체 WebAuthn Credential ID 목록을 제공합니다. WebAuthn 신뢰 당사자(Relying Party)는 사용자가 인증되었을 때 개인정보 유출 위험이 없으므로 signalUnknownCredential() 대신 이 메서드를 사용해야 합니다. 이 메서드는 현재 연결된 인증기(Authenticator)에 업데이트되지 않았을 수 있는 최근 변경 사항을 포함하여 사용자의 공개 키 자격 증명에 대한 포괄적인 개요를 제공합니다.

예를 들어 보겠습니다. 사용자(userId: A)가 Base64URL로 인코딩했을 때 X와 Y가 되는 Credential ID를 가진 2개의 패스키를 가지고 있습니다. 그런 다음 사용자가 웹 서비스(example.com)의 계정 설정에서 패스키 X를 삭제합니다(공개 키가 삭제됨). 이제 다음 코드 스니펫을 실행합니다.

PublicKeyCredential.signalAllAcceptedCredentials({
    rpId: "example.com",
    userId: "A", // WebAuthn User Handle, Base64URL.
    allAcceptedCredentialIds: ["Y"],
});

위 코드가 실행될 때 인증기(Authenticator)를 사용할 수 있는 상태라면, 인증기는 이후의 인증 절차에서 패스키 X를 삭제하거나 숨깁니다. 하지만 실행 시점에 인증기가 연결되어 있지 않을 수도 있으므로, 신뢰 당사자는 로그인할 때마다 등 주기적으로 이 코드를 실행하는 것이 권장됩니다.

allAcceptedCredentialIds에 존재하지 않는 패스키는 돌이킬 수 없이 삭제되거나 숨겨질 수 있습니다. 따라서 신뢰 당사자는 유효한 WebAuthn Credential ID가 목록에서 절대 제거되지 않도록 주의해야 합니다. 유효한 Credential ID가 실수로 제거된 경우, 신뢰 당사자는 가능한 한 빨리 다른 signalAllAcceptedCredentials(options) 호출에 이를 포함하여 패스키의 "숨김을 해제"해야 합니다. 패스키가 숨겨진 것이 아니라 삭제된 것이라면 복구하기 매우 어렵습니다.

Experiment with passkey flows in the Passkeys Debugger.

Try for Free

signalCurrentUserDetails(options) 메서드는 사용자의 현재 이름과 WebAuthn Display Name을 알립니다. signalCurrentUserDetails(options)가 호출되면, 클라이언트는 이 작업을 실행하기 위해 정의된 단계 세트를 따릅니다.

예를 들어 보겠습니다. WebAuthn User ID가 A인 사용자가 웹사이트(example.com)의 계정 설정에서 이름을 업데이트합니다. 그러면 신뢰 당사자(Relying Party)는 다음 코드를 실행할 수 있습니다.

PublicKeyCredential.signalCurrentUserDetails({
    rpId: "example.com",
    userId: "A", // user ID, Base64URL.
    name: "New user name",
    displayName: "New display name",
});

인증기는 로컬에 저장된 패스키의 메타데이터를 업데이트합니다. 가장 큰 장점은 향후 조건부 UI(Conditional UI) / 패스키 자동 완성 요청 시 선택 및 드롭다운 메뉴에 업데이트된 이름과 WebAuthn Display Name이 표시된다는 것입니다.

signalUnknownCredential(options) 메서드는 사용자가 패스키를 삭제한 경우 등 WebAuthn 신뢰 당사자(Relying Party)가 WebAuthn Credential ID를 인식하지 못함을 알립니다. signalAllAcceptedCredentials(options)와 달리 이 메서드는 수락된 Credential ID의 전체 목록과 WebAuthn User Handle을 제공할 필요가 없으므로 인증되지 않은 호출자에게 발생할 수 있는 잠재적인 개인정보 유출을 방지합니다.

예를 들어 보겠습니다. 사용자가 웹사이트(example.com)의 계정 설정에서 Credential ID가 X인 패스키를 삭제합니다(공개 키가 삭제됨). 하지만 개인 키는 사용자의 기기에 여전히 남아있습니다. 이는 향후 조건부 UI(Conditional UI) / 패스키 자동 완성 로그인 요청(allowCredentials 목록이 비어 있는 경우)에서 해당 패스키가 여전히 선택될 수 있음을 의미합니다. 하지만 공개 키가 이미 삭제되었기 때문에 로그인 시도는 실패할 것이므로 신뢰 당사자는 다음을 실행해야 합니다.

PublicKeyCredential.signalUnknownCredential({
    rpId: "example.com",
    credentialId: "X", // 사용자가 방금 시도한 credential ID, Base64URL
});

그러면 인증기는 이후의 인증 절차에서 Credential ID가 X인 패스키를 삭제하거나 숨깁니다.

WebAuthn 레벨 3 표준이 아직 초안 상태이기 때문에, 이러한 새로운 클라이언트 기능의 채택이 아직 널리 퍼져 있지는 않습니다. 다양한 브라우저가 점진적으로 이 기능들을 구현하고 있지만 지원 여부는 상이합니다. 위에서 언급한 주요 브라우저의 사용 가능성에 대한 최신 개요는 다음과 같습니다.

레벨 3이 성숙해지고 더 많은 브라우저가 이러한 기능을 출시함에 따라 도입 속도는 빨라질 것입니다. 현재 getClientCapabilities()를 활용할 수 있는 사용자가 얼마나 되는지 확인하려면 무료인 State of Passkeys를 사용하여 실제 데이터를 확인할 수 있습니다. 향후 더 광범위한 호환성을 계획하기 위해 브라우저 릴리스 노트와 관련 문서를 주시해 주세요.

See how many people actually use passkeys.

View Adoption Data

개발자로서 이러한 새로운 WebAuthn 클라이언트 기능 감지가 여러분에게 어떤 의미가 있으며 앱에서 어떻게 사용해야 할지 궁금할 수 있습니다. 다음에서 이를 활용하는 권장 사항을 확인해 보세요.

하지만 아직 모든 브라우저가 getClientCapabilities() API 호출을 지원하는 것은 아닙니다(2024년 11월 기준). 모든 브라우저가 이를 지원할 때까지 사용할 수 있는 폴리필이 여기에 제공되어 있습니다.

페이지 로드나 인증 흐름의 시작 부분에서 코드의 앞부분에 getClientCapabilities()를 사용하여 클라이언트가 지원하는 기능을 감지하세요. 이를 통해 경험을 동적으로 커스터마이즈할 수 있으며, 기기나 브라우저에서 작동하는 패스키 기능을 제공할 수 있습니다. 예를 들어 플랫폼 인증이 지원되는 경우 이를 적극 권장하거나, 지원되지 않는 경우 대체 방법(예: SMS OTP 또는 하드웨어 보안 키)을 제공할 수 있습니다.

현재 비밀번호를 사용하는 웹사이트나 앱에 패스키를 추가하는 경우, conditionalCreate 기능은 패스키 도입의 진정한 부스터가 될 수 있습니다. 백그라운드에서 적절한 자격 증명 관리자(2024년 10월 기준 Apple Passwords만 해당)를 사용한 비밀번호 자동 완성 중에 패스키가 자동으로 생성되며 향후 자동 완성 시 우선적으로 사용됩니다.

높은 패스키 도입률뿐만 아니라 높은 패스키 로그인 사용률을 달성하려면 conditionalGet을 확인하여 기기/브라우저가 조건부 UI(Conditional UI) / 패스키 자동 완성을 사용할 수 있는지 확인해 보세요. 이렇게 하면 생성된 패스키가 운영 체제나 브라우저에 의해 선제적으로 제안되며 비밀번호를 자동 완성하는 것보다 적은 노력이 들기 때문에, 사용자가 로그인을 위해 생성된 패스키를 사용하도록 유도할 수 있습니다.

hybridTransport를 활용하여 교차 디바이스 인증(QR 코드 및 Bluetooth 경유)을 활성화하면, 사용자가 데스크톱에서 서비스에 접속하더라도 스마트폰에서 매끄럽게 로그인할 수 있습니다.

WebAuthn 클라이언트 기능은 현재 존재하는 패스키의 격차를 해소하는 데 있어 중요한 발전을 의미합니다. 이 블로그 포스트에서는 WebAuthn 클라이언트 기능에 대한 주요 질문들을 다루었습니다.

1. WebAuthn 클라이언트 기능이란 무엇인가요? 이러한 기능이 어떻게 브라우저와 플랫폼이 특정 기능에 대한 지원 여부를 알릴 수 있게 해주고, 개발자에게 인증 흐름에 대한 더 많은 제어권을 부여하는지 설명했습니다.
2. 어떤 WebAuthn 클라이언트 기능이 있나요? getClientCapabilities, conditionalCreate, hybridTransport 등을 포함하여 레벨 3 표준에 도입된 새로운 기능에 대한 개요를 제공했습니다.
3. WebAuthn 클라이언트 기능이 패스키 구현을 어떻게 개선하나요? 이러한 기능이 어떻게 통합을 간소화하고, 교차 디바이스 사용을 향상하며, 보안을 개선하는지 논의했습니다.
4. 개발자에게 WebAuthn 클라이언트 기능이 중요한 이유는 무엇인가요? 이러한 기능은 최신 사용자의 기대에 부합하는 매끄럽고 안전한 인증 경험을 만들어 구현을 더 쉽고 효과적으로 만듭니다.

새로운 WebAuthn 레벨 3 기능들을 살펴보고 브라우저 전반의 도입 현황을 계속 업데이트하시기 바랍니다. 패스키를 구현하고 이러한 고급 기능을 활용하고 싶으시다면 전문적인 가이드와 지원을 위해 저희에게 연락해 주세요.

페이지 로드나 인증 흐름의 초기 단계에서 getClientCapabilities()를 호출하여 지원되는 기능을 동적으로 감지하세요. 이를 통해 지원되는 경우 플랫폼 인증을 제공하고, 그렇지 않은 경우 SMS OTP나 하드웨어 보안 키와 같은 대체 수단을 제공할 수 있습니다.

signalAllAcceptedCredentials는 유효한 Credential ID의 전체 목록과 WebAuthn User Handle이 필요하므로 개인정보 유출을 피하기 위해 사용자가 인증되었을 때만 호출해야 합니다. 반면 signalUnknownCredential은 전체 목록을 요구하지 않고 인식되지 않은 단일 Credential ID를 알리므로, 로그인 실패 후와 같이 인증되지 않은 상황에서도 안전하게 호출할 수 있습니다.

relatedOrigins 기능은 동일한 조직이 소유한 다른 도메인(예: amazon.com 및 amazon.de) 간의 원활한 인증을 허용합니다. 사용자는 한 번의 로그인으로 각 도메인에서 재인증할 필요 없이 모든 자산에 접근할 수 있어 국제적 환경이나 다중 서비스 환경에서의 마찰을 줄여줍니다.

2024년 11월 기준 모든 브라우저가 getClientCapabilities()를 지원하는 것은 아니므로, github.com/MasterKale/webauthn-polyfills에서 제공하는 폴리필을 임시방편으로 사용할 수 있습니다. WebAuthn 레벨 3 표준이 성숙해지고 이미 Chrome 133, Edge 133, Firefox 135 및 Safari 17.4에서 지원을 제공하고 있으므로 채택 속도는 더 빨라질 것으로 예상됩니다.