WebAuthn Signal API: 클라이언트 측에서 패스키 업데이트 및 삭제하기

Looking for a dev-focused passkey reference? Download our Passkeys Cheat Sheet. Trusted by dev teams at Ally, Stanford CS & more.

Get Cheat Sheet

최종 업데이트: 2025년 11월 4일

플랫폼별 WebAuthn Signal API 지원 현황을 빠르게 살펴보겠습니다.

⚠️ 알려진 문제: Safari 26+ 버전에서 promise가 제대로 resolve되지 않는 버그가 있습니다 (WebKit Bug #298951). 현재 수정 사항 병합 대기 중입니다.

패스키(Passkey) 생태계는 계속해서 진화하고 있습니다. 변화를 뒷받침하기 위해 기반이 되는 WebAuthn 표준도 빠르게 발전하고 있죠. 새로운 기능은 보통 GitHub의 기술 설명(explainer)으로 시작해, 충분한 논의를 거친 뒤 표준 초안에 PR(Pull Request)로 추가됩니다. 최근 이 PR을 통해 **WebAuthn Signal API**가 표준 초안에 포함되었습니다. 이번 글에서는 다음 내용을 다룹니다.

• WebAuthn Signal API가 왜 필요한가: WebAuthn Signal API는 어떤 사용 사례를 지원할까요?
• WebAuthn Signal API는 어떻게 작동하는가: 구체적인 작동 원리와 Relying Party를 위한 권장 사항은 무엇일까요?

이 글을 작성하는 시점을 기준으로 WebAuthn Signal API는 Chrome 132부터 기본적으로 활성화되어 있습니다. 이전에는 Reporting API로 불렸으나, 동일한 이름의 다른 API와 충돌을 피하기 위해 이름이 변경되었습니다.

WebAuthn Signal API는 클라이언트 측에서의 패스키 관리와 관련된 구체적인 사용 사례들을 해결해 줍니다. 특히 Relying Party(RP)와 클라이언트 운영체제의 일부인 Authenticator(인증자) 간의 정보 동기화를 돕습니다. 주요 사용 사례는 다음과 같습니다.

Subscribe to our Passkeys Substack for the latest news.

Subscribe

패스키가 생성될 때 user.id, user.name, user.displayName과 같은 정보가 포함됩니다. 패스키 자체는 고유한 Credential ID를 통해 식별됩니다.

• user.id: 패스키가 연결된 계정을 나타내는 고유 식별자입니다. 이 user.id는 패스키를 실제 사용자 계정과 매칭하는 데 사용되므로 매우 중요합니다.
• user.name 및 user.displayName: 사용자 인터페이스에 표시하기 위한 용도로만 사용되는 메타데이터입니다.

아래 그림은 어떤 정보가 어떤 필드에 저장되는지 설명하는 일반적인 데이터베이스 구조입니다.

여기서 중요한 점은 user.name(주로 이메일 주소)과 user.displayName(읽기 편한 이름)이 사용자가 계정을 식별하는 데 도움을 주지만, 패스키와 계정 간의 실제 연결은 user.id와 Credential ID를 통해 유지된다는 것입니다.

• 하나의 계정은 여러 개의 패스키를 가질 수 있지만, 각 패스키는 user.id를 통해 계정과 고유하게 매칭됩니다.
• 모든 패스키는 Authenticator에 의해 생성된 고유한 Credential ID를 가집니다.

문제는 이메일 주소와 같은 user.name이 변경될 때 발생합니다. 현재로서는 클라이언트 측 Authenticator에서 이 변경 사항을 직접 업데이트할 수 있는 메커니즘이 없습니다. 사용자가 이메일 주소를 바꾸는 등 여러 이유로 user.name이 변경될 수 있습니다. 서버 측에서 계정 메타데이터가 변경되었더라도, 자격 증명 선택 UI에는 예전 user.name이 그대로 표시되어 사용자에게 혼란을 줄 수 있습니다.

이 문제의 해결책으로 변경된 user.name과 동일한 user.id를 가진 새 패스키를 생성하여 기존 패스키를 덮어쓰는 방법이 있습니다. 하지만 이 방식은 몇 가지 이유로 불편합니다.

1. 중복성: Authenticator는 특정 Relying Party ID에 대해 user.id당 하나의 패스키만 저장할 수 있습니다. 즉, 메타데이터 업데이트를 위해 기존 패스키를 새것으로 교체하는 추가 단계가 필요합니다.
2. 사용자 경험(UX): 사용자는 왜 새 패스키를 만들어야 하는지 이해하기 어렵습니다. 이것이 이 우회 방법이 널리 쓰이지 않는 이유입니다.
3. 복잡성: 단순한 메타데이터 업데이트를 위해 패스키 생성 및 교체 과정을 관리하는 것은 불필요하게 복잡합니다.

이메일 주소나 전화번호 같은 식별자는 자주 바뀔 수 있습니다. Authenticator에서 user.name과 user.displayName을 직접 업데이트할 방법이 없다면, 사용자는 자신의 예전 이메일 주소가 연결된 패스키를 계속 보게 되고 이를 선택해야 하는 불편을 겪습니다. 이는 패스키가 제공하려는 매끄러운 경험을 저해합니다. WebAuthn Signal API는 Relying Party가 새 패스키를 만들지 않고도 메타데이터 업데이트를 알릴 수 있도록 하여 이 문제를 해결합니다. 구현 방법을 알아보기 전에, 이 API가 해결하는 두 번째 중요한 사용 사례를 살펴보겠습니다.

Become part of our Passkeys Community for updates & support.

Join

또 다른 중요한 사용 사례는 클라이언트 측 Authenticator에서 패스키를 삭제하는 것입니다. 시간이 지나면서 사용자가 패스키 관리 목록에서 자격 증명을 취소하거나 계정을 삭제할 수 있습니다. 이때 향후 자격 증명 선택 UI(Conditional UI / 패스키 자동 완성)에 해당 자격 증명이 나타나지 않도록 클라이언트 측 Authenticator에서도 제거해야 합니다.

이 기능은 다음과 같은 상황에서 필요합니다.

1. 계정 설정에서 패스키 삭제: 사용자가 계정 설정 등을 통해 명시적으로 자격 증명을 삭제하여 더 이상 유효하지 않은 경우:

사용자 입장에서는 위의 대화 상자와 같이 계정 설정에서 삭제한 것이 해당 클라이언트(기기)에서의 패스키 제거로 이어지지 않는다는 사실을 이해하기 어렵습니다.

2. 계정 삭제: 사용자가 계정을 탈퇴할 때, 관련된 모든 패스키도 함께 제거되어야 합니다.
3. 보안 정책: 일정 기간 비활동 상태이거나 보안 문제가 감지된 경우, Relying Party의 보안 정책에 따라 자격 증명을 취소해야 할 수 있습니다.

클라이언트 측에서 패스키를 직접 삭제할 방법이 없다면, 유효하지 않은 자격 증명이 선택 UI에 계속 남아 혼란을 줍니다. 사용자는 이미 만료된 패스키를 보고 사용하려다 인증 실패를 겪게 되며, 이는 나쁜 사용자 경험으로 이어집니다.

Corbado Connect 관리 콘솔에서 서버 측 패스키를 삭제하는 방법은 아래 영상을 참고하세요.

WebAuthn Signal API를 구현하려면 기능이 정확하고 안전하게 통합되도록 몇 가지 단계와 고려 사항을 확인해야 합니다. Signal API를 사용하면 Relying Party(RP)가 클라이언트 측 Authenticator에서 패스키 자격 증명을 업데이트하거나 삭제할 수 있습니다.

WebAuthn Signal API를 구현할 때 다음 사항을 반드시 염두에 두어야 합니다.

• 프라이버시 보호(Privacy Preserving): WebAuthn Signal API는 WebAuthn의 기본 원칙인 사용자 프라이버시를 보호하도록 설계되었습니다. 즉, 요청된 변경 사항이 처리되었는지 여부에 대해 RP에게 피드백을 제공하지 않습니다. 자격 증명의 상태 정보가 유출되는 것을 막기 위해 API는 조용히(silently) 작동합니다.
• Authenticator 가용성: WebAuthn Signal API의 효과는 Authenticator의 가용성에 달려 있습니다. 이는 물리적 가용성과 소프트웨어 지원(브라우저 및 OS 호환성 등)을 모두 포함합니다. 브라우저는 Authenticator가 접근 가능하고, 생체 인증 없이 필요한 작업을 수행할 수 있을 때만 동작을 수행할 수 있습니다.
• 도메인 제한: API는 특정 도메인과 연결된 Relying Party만 해당 도메인 관련 자격 증명을 변경할 수 있도록 제한합니다. 이는 제3자에 의한 무단 수정을 방지하는 보안 조치입니다.
• 식별 키로서의 Credential ID: 패스키를 참조할 때 Credential ID가 WebAuthn Signal API의 기본 키(Primary Key)로 사용됩니다. 이 ID는 클라이언트 측 Authenticator에서 패스키를 고유하게 식별합니다. RP는 Credential ID를 통해서만 패스키 메타데이터를 변경하거나 특정 패스키를 더 이상 사용하지 않도록 신호를 보낼 수 있습니다. 만약 Authenticator가 특정 Credential ID를 모른다면, 해당 요청은 조용히 무시됩니다.

이러한 고려 사항들은 WebAuthn Signal API 기능을 올바르게 이해하는 데 필수적입니다.

WebAuthn Signal API는 RP가 클라이언트 측 Authenticator의 패스키 메타데이터를 업데이트할 수 있는 간소화된 메커니즘을 제공합니다. 불필요하게 새 패스키를 만들지 않고도 자격 증명 선택 UI에 정확한 최신 정보를 표시할 수 있어 매우 중요합니다. API의 작동 방식은 다음과 같습니다.

signalCurrentUserDetails(options)로 메타데이터 업데이트

Signal API의 signalCurrentUserDetails(options) 메서드는 패스키의 메타데이터 업데이트를 위해 설계되었습니다. RP는 이 메서드를 통해 user.name과 user.displayName의 최신 값을 제공할 수 있습니다.

프로세스는 다음과 같이 진행됩니다 (WebAuthn Level 3 표준 참조).

1. 메서드 구조: signalCurrentUserDetails(options) 메서드는 rp.id, user.id, 그리고 업데이트된 user.name 및 user.displayName 값을 포함합니다.

PublicKeyCredential.signalCurrentUserDetails({
    rpId: "example.com",
    userId: "aabbcc", // user handle, base64url.
    name: "New user name",
    displayName: "New display name",
});

2. 로컬 메타데이터 업데이트: Authenticator에 로컬로 저장된 자격 증명 중 rpId와 userId가 일치하는 것을 찾습니다. 일치하는 모든 자격 증명에 대해 name과 displayName을 업데이트합니다.

3. 프라이버시 보호: 이 과정은 프라이버시를 보호하도록 설계되었습니다. Signal API는 업데이트 성공 여부를 RP에게 알려주지 않아 자격 증명 상태 정보 유출을 방지합니다.

4. 기기 간 일관성: RP는 signalCurrentUserDetails(options) 메서드를 주기적으로 실행하여 사용자가 인증하는 다양한 기기와 플랫폼에서 패스키 메타데이터를 일관되게 유지할 수 있습니다. 이를 통해 자격 증명 선택 UI에 오래되거나 잘못된 정보가 표시될 가능성을 줄입니다.

위 스크린샷에서 Google Chrome이 업데이트를 사용자에게 어떻게 알리는지 볼 수 있습니다. WebAuthn Signal API는 Chrome의 일부이며 데스크톱의 Google 비밀번호 관리자를 통해 테스트할 수 있습니다.

WebAuthn Signal API는 RP가 클라이언트 측 Authenticator에서 패스키 삭제 신호를 보낼 수 있는 메커니즘을 제공합니다. 이는 유효하지 않은 자격 증명이 선택 UI에 나타나지 않게 하여 사용자 경험을 개선하는 데 필수적입니다. 로컬 패스키를 삭제하는 데는 signalUnknownCredential(options)과 signalAllAcceptedCredentials(options) 두 가지 메서드가 있습니다. 전자는 사용자가 인증되지 않은 상황에서, 후자는 사용자가 인증된 상황에서 사용할 수 있습니다. 따라서 프라이버시 보호를 위해서는 후자를 권장합니다.

두 메서드의 작동 방식은 다음과 같습니다.

1. 메서드 구조: signalUnknownCredential(options) 메서드는 rpId(Relying Party ID)와 삭제할 자격 증명의 고유 식별자인 credentialId를 포함합니다.

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

2. 메서드 호출: RP는 자격 증명을 삭제해야 한다고 판단될 때 이 메서드를 호출합니다. 유효하지 않은 자격 증명으로 인증을 시도한 직후, 계정 삭제 시, 또는 사용자가 설정을 통해 자격 증명을 취소했을 때 등이 해당됩니다.

3. 처리 과정: signalUnknownCredential(options)이 호출되면 클라이언트 측 Authenticator는 rpId와 credentialID가 일치하는 자격 증명을 찾아 제외 처리를 시도합니다. Authenticator의 기능에 따라 자격 증명을 삭제하거나, 향후 인증 과정(ceremony)에서 숨기는(hide) 절차를 수행합니다.

1. 메서드 구조: signalAllAcceptedCredentials(options) 메서드는 rpId, userId, 그리고 유효한 Credential ID들의 목록인 allAcceptedCredentialIds를 포함합니다.

PublicKeyCredential.signalAllAcceptedCredentials({
    rpId: "example.com",
    userId: "aabbcc", // user handle, base64url.
    allAcceptedCredentialIds: ["bb"],
});

2. 메서드 호출: RP는 자격 증명 삭제가 필요할 때 유효한 자격 증명 목록과 함께 이 메서드를 호출합니다. 자격 증명 삭제 시 signalUnknownCredential(options)보다 이 메서드를 사용하는 것이 좋습니다.

3. 처리 과정: signalAllAcceptedCredentials(options)이 호출되면 클라이언트 측 Authenticator는 rpId와 userId를 매칭합니다. Authenticator는 해당 rpId와 userId에 해당하는 모든 로컬 자격 증명을 조회하고, 이를 allAcceptedCredentialIds와 비교합니다. 로컬 자격 증명 중 allAcceptedCredentialIds 목록에 없는 것은 로컬에서 삭제되거나(또는 Authenticator에 따라 숨겨짐) 처리됩니다.

4. 자격 증명 숨김 해제: 만약 자격 증명이 (Authenticator 기능에 따라) 숨겨져 있었는데 다시 allAcceptedCredentialIds 목록에 포함된다면, 해당 자격 증명은 향후 인증 과정에서 다시 나타나게 됩니다.

5. 유용한 팁:

   • signalAllAcceptedCredentials(options)를 사용할 때, 메서드 실행 시점에 Authenticator가 항상 연결되어 있는 것은 아니라는 점을 유의하세요. 따라서 로그인할 때마다 주기적으로 signalAllAcceptedCredentials(options)를 실행하여 모든 자격 증명을 최신 상태로 유지하는 것이 좋습니다.
   • RP는 allAcceptedCredentialIds 목록을 작성할 때 주의해야 합니다. 이 목록에 포함되지 않은 자격 증명은 Authenticator에 의해 숨겨지거나 영구적으로 삭제될 수 있습니다. 유효한 자격 증명이 실수로 누락되지 않도록 목록의 완전성을 보장해야 합니다. 실수로 누락된 경우, 가능한 한 빨리 다시 목록에 추가하여 호출해야 합니다.
   • 가능하다면 Authenticator는 자격 증명을 영구 삭제하는 대신 일시적으로 숨기는 방식을 선호해야 합니다. 이를 통해 RP가 실수로 유효한 ID를 누락했을 때 영구적인 손실 없이 복구할 수 있습니다.

위 스크린샷에서 Google Chrome이 삭제 신호를 어떻게 처리하는지 볼 수 있습니다. WebAuthn Signal API는 데스크톱의 Google 비밀번호 관리자를 통해 테스트할 수 있습니다.

WebAuthn Signal API를 효과적으로 구현하고 클라이언트 측 Authenticator 간의 패스키 메타데이터 동기화를 원활하게 하려면 다음 사항을 고려해 보세요.

• WebAuthn Signal API 업데이트 및 실제 구현 확인: Signal API 관련 최신 개발 및 업데이트 소식을 확인하세요. WebAuthn Signal API는 Google Chrome 132에서 활성화되었으며, 다른 브라우저들도 뒤따르고 있습니다(Safari도 지원 발표). 정기적으로 진행 상황을 확인하여 구현이 최신 표준과 일치하도록 하세요. 상황이 변하면 이 블로그 글도 업데이트할 예정입니다.
• 로그인 성공 시마다 signalAllAcceptedCredentials(options) 실행: 이 접근 방식은 단일 메서드로 모든 메타데이터와 Credential ID를 업데이트하므로 프로세스가 단순해집니다. 기기와 플랫폼 간의 일관성을 유지하면서 삭제되거나 오래된 자격 증명을 비활성화할 수 있습니다.
• 대규모 배포 시 signalUnknownCredential(options)로 실시간 메시징: 대규모 서비스나 즉각적인 업데이트가 필요한 경우 signalUnknownCredential(options) 메서드를 사용한 실시간 처리를 고려하세요. 이 방법은 자격 증명 관리의 효율성과 정확성을 높여 유효하지 않은 자격 증명을 선택 UI에서 즉시 제거할 수 있게 합니다.

이러한 권장 사항을 따르면 WebAuthn Signal API가 지원될 때 효과적으로 구현하여 패스키 메타데이터를 최신 상태로 유지하고, 모든 클라이언트 측 Authenticator에서 일관성을 확보해 매끄럽고 안전한 사용자 경험을 제공할 수 있습니다.

WebAuthn 표준은 매달 새로운 기능이 추가되며 지속적으로 발전하고 있습니다. WebAuthn Signal API의 도입은 클라이언트 측 Authenticator의 패스키 메타데이터 관리 및 삭제에 있어 중요한 진전입니다. 이 API는 RP와 Authenticator 간의 정보 동기화, 유효하지 않은 패스키 제거와 같은 핵심 사용 사례를 해결하여 사용자 경험을 개선합니다.

• Signal API는 왜 필요한가? Signal API는 패스키 메타데이터 업데이트와 클라이언트 측 삭제에 필수적입니다. 자격 증명 선택 UI에서 혼란을 주는 오래된 user.name 및 user.displayName 문제를 해결하고, 취소되거나 삭제된 패스키를 제거하여 깨끗하고 안전한 인터페이스를 유지합니다.
• Signal API는 어떻게 작동하는가? RP가 메타데이터 업데이트나 패스키 삭제 신호를 보내면, 클라이언트 측 Authenticator가 이를 처리하여 사용자에게 정확한 최신 정보를 보여줍니다. API는 프라이버시를 보호하도록 설계되어 업데이트 성공 여부를 RP에게 알리지 않고 작동합니다.

WebAuthn 표준은 다양한 참여자들의 관심 속에 계속 발전하고 있습니다. 이러한 변화를 주시하는 것은 최신 기능을 파악하고 구현을 최신 모범 사례에 맞추는 데 매우 중요합니다. WebAuthn 커뮤니티는 계속해서 혁신을 주도하며 인증을 더 안전하고 사용자 친화적으로 만들고 있습니다.