WebAuthn Signal API: Cập nhật & Xóa Passkey phía Client

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

Get Cheat Sheet

Cập nhật lần cuối: 4 tháng 11, 2025

Dưới đây là tổng quan nhanh về khả năng hỗ trợ WebAuthn Signal API trên các nền tảng:

⚠️ Vấn đề đã biết: Safari 26+ đang gặp lỗi khiến promise không được giải quyết (resolve) đúng cách (WebKit Bug #298951). Bản sửa lỗi đang chờ được merge.

Hệ sinh thái passkey đang không ngừng phát triển. Để thúc đẩy sự thay đổi này, tiêu chuẩn WebAuthn cơ bản cũng được cập nhật liên tục. Các tính năng mới thường bắt đầu bằng một tài liệu giải thích kỹ thuật (technical explainer) trên GitHub, sau đó phát triển thành một pull request (PR) vào tiêu chuẩn khi đã được thảo luận đầy đủ. Gần đây, pull request này đã được thêm vào bản dự thảo tiêu chuẩn với tên gọi WebAuthn Signal API. Trong bài viết này, chúng ta sẽ cùng tìm hiểu:

• Tại sao cần WebAuthn Signal API: Những trường hợp sử dụng (use case) nào mà WebAuthn Signal API hỗ trợ?
• WebAuthn Signal API hoạt động như thế nào: Cơ chế hoạt động chính xác là gì? Đâu là khuyến nghị cho các Relying Party?

Tại thời điểm viết bài, WebAuthn Signal API được bật mặc định từ phiên bản Chrome 132 và trước đây được gọi là Reporting API trước khi được đổi tên để tránh xung đột với một API khác có cùng tên.

WebAuthn Signal API giải quyết các nhu cầu cụ thể liên quan đến việc quản lý passkey ở phía client (máy khách). Cụ thể, nó giúp đồng bộ hóa thông tin giữa Relying Party (RP) và các Authenticator (trình xác thực) nằm trong hệ điều hành phía client. Dưới đây là các trường hợp sử dụng quan trọng:

Subscribe to our Passkeys Substack for the latest news.

Subscribe

Khi một passkey được tạo, nó bao gồm một vài thông tin: user.id, user.name, và user.displayName. Bản thân passkey được định danh thông qua Credential ID duy nhất.

• user.id: là định danh duy nhất đại diện cho tài khoản mà passkey được liên kết. user.id này cực kỳ quan trọng vì nó được dùng để khớp passkey với tài khoản người dùng.
• user.name và user.displayName: đây là các dữ liệu meta (siêu dữ liệu) chỉ được dùng cho mục đích hiển thị trên giao diện người dùng.

Hình minh họa sau đây cho thấy cấu trúc cơ sở dữ liệu đơn giản, giải thích thông tin nào thường được lưu trữ trong trường nào:

Điều quan trọng cần hiểu là mặc dù user.name (thường là địa chỉ email) và user.displayName (tên hiển thị thân thiện, dễ đọc hơn) giúp người dùng nhận diện tài khoản của họ trong giao diện chọn lựa, nhưng mối liên kết thực sự giữa passkey và tài khoản được duy trì thông qua user.id và Credential ID:

• Một tài khoản có thể có nhiều passkey, nhưng mỗi passkey được định danh duy nhất và khớp với tài khoản bằng user.id.
• Mỗi passkey đều có một Credential ID duy nhất được tạo bởi Authenticator.

Vấn đề nảy sinh khi user.name (ví dụ như địa chỉ email) thay đổi. Hiện tại, không có cơ chế nào để cập nhật sự thay đổi này trực tiếp trên Authenticator phía client. user.name có thể thay đổi vì nhiều lý do, chẳng hạn như khi người dùng cập nhật địa chỉ email của họ. Mặc dù meta-data của tài khoản đã thay đổi ở phía máy chủ (server-side), nhưng user.name cũ vẫn sẽ tiếp tục xuất hiện trong giao diện chọn thông tin xác thực, gây nhầm lẫn cho người dùng.

Cách giải quyết tạm thời cho vấn đề này là tạo một passkey mới với user.name đã cập nhật và cùng user.id, sau đó ghi đè lên passkey hiện có. Tuy nhiên, cách tiếp cận này khá bất tiện vì vài lý do:

1. Sự dư thừa: Một authenticator chỉ có thể lưu một passkey cho mỗi user.id đối với một ID Relying Party cụ thể. Điều này có nghĩa là passkey cũ phải được thay thế bằng passkey mới chỉ để cập nhật metadata, đây là một bước thừa thãi.
2. Trải nghiệm người dùng: Người dùng sẽ không hiểu tại sao họ cần tạo passkey mới. Đó là lý do tại sao giải pháp này không được sử dụng rộng rãi.
3. Sự phức tạp: Việc quản lý quy trình tạo passkey và thay thế chỉ để cập nhật metadata làm tăng thêm sự phức tạp không cần thiết.

Địa chỉ email, số điện thoại và các định danh khác có thể thay đổi thường xuyên. Nếu không có phương pháp đơn giản để cập nhật user.name và user.displayName trực tiếp trên authenticator, người dùng có thể gặp phải vấn đề dai dẳng là nhìn thấy và phải chọn passkey gắn với email cũ. Tình huống này làm giảm trải nghiệm liền mạch mà passkey hướng tới. WebAuthn Signal API giải quyết vấn đề này bằng cách cho phép các Relying Party báo cáo cập nhật meta-data của passkey mà không yêu cầu tạo mới. Trước khi giải thích cách triển khai Signal API, chúng ta sẽ khám phá trường hợp sử dụng quan trọng thứ hai.

Become part of our Passkeys Community for updates & support.

Join

Một trường hợp sử dụng quan trọng khác là xóa passkey trên authenticator phía client. Theo thời gian, người dùng có thể thu hồi thông tin xác thực (credentials) thông qua danh sách quản lý passkey hoặc xóa tài khoản của họ. Khi đó, cần đảm bảo rằng các thông tin xác thực này được xóa khỏi authenticator phía client để ngăn chúng xuất hiện trong các giao diện chọn lựa sau này (Conditional UI / passkey autofill).

Nhu cầu này nảy sinh trong một vài tình huống:

1. Passkey bị xóa qua cài đặt tài khoản: Khi một thông tin xác thực không còn hợp lệ, ví dụ như sau khi người dùng đã chủ động xóa nó qua phần cài đặt tài khoản:

Từ góc độ người dùng, rất khó để hiểu rằng việc xóa trong cài đặt tài khoản (như hộp thoại trên) lại không dẫn đến việc passkey bị xóa trên thiết bị client này.

2. Xóa tài khoản: Khi người dùng xóa tài khoản, tất cả passkey liên quan cũng nên được gỡ bỏ.

3. Chính sách bảo mật: Các Relying Party có thể có chính sách bảo mật yêu cầu thu hồi thông tin xác thực sau một khoảng thời gian không hoạt động hoặc do phát hiện vấn đề bảo mật.

Nếu không có phương pháp trực tiếp để xóa passkey ở phía client, các thông tin xác thực cũ hoặc không hợp lệ này sẽ tiếp tục làm lộn xộn giao diện chọn lựa, dẫn đến nhầm lẫn. Người dùng có thể nhìn thấy và cố gắng sử dụng các passkey không còn hiệu lực, dẫn đến lỗi xác thực và trải nghiệm người dùng kém.

Xem video này để biết cách xóa passkey phía server trong Corbado Connect Management Console:

Việc triển khai WebAuthn Signal API bao gồm một số bước và cân nhắc để đảm bảo chức năng được tích hợp chính xác và bảo mật. Signal API cho phép các Relying Party (RP) cập nhật hoặc xóa passkey trên authenticator phía client. Phần này phác thảo các cân nhắc chính và các bước thực hiện.

Khi triển khai WebAuthn Signal API, điều quan trọng là phải ghi nhớ các yếu tố sau:

• Bảo vệ quyền riêng tư (Privacy Preserving): WebAuthn Signal API được thiết kế để bảo vệ quyền riêng tư của người dùng vì đây là một trong những nền tảng của WebAuthn. Điều này có nghĩa là sẽ không có phản hồi nào được gửi lại cho RP về việc thay đổi yêu cầu có được xử lý hay không. API hoạt động ngầm (silently) để ngăn chặn mọi rò rỉ tiềm ẩn thông tin về trạng thái của các thông tin xác thực.

• Sự sẵn sàng của Authenticator: Hiệu quả của WebAuthn Signal API phụ thuộc vào tính khả dụng của authenticator. Điều này bao gồm cả tính sẵn sàng về vật lý và hỗ trợ phần mềm (ví dụ: trình duyệt và hệ điều hành tương thích). Trình duyệt chỉ có thể thực hiện hành động nếu authenticator có thể truy cập được và hỗ trợ các hoạt động cần thiết mà không cần xác thực sinh trắc học.

• Giới hạn miền (Domain Restrictions): API đảm bảo rằng chỉ Relying Party liên kết với một tên miền cụ thể mới có thể yêu cầu thay đổi thông tin xác thực liên quan đến tên miền đó. Đây là biện pháp bảo mật để ngăn chặn sửa đổi trái phép bởi bên thứ ba.

• Credential ID là Khóa: Khi tham chiếu đến passkey, Credential ID là khóa chính được WebAuthn Signal API sử dụng. ID này định danh duy nhất passkey trên authenticator phía client. API cho phép RP thay đổi meta-data liên quan đến passkey hoặc báo hiệu rằng một số passkey nhất định không nên được truy cập nữa, nhưng chỉ thông qua Credential ID. Trong trường hợp một authenticator không biết một Credential ID cụ thể, nó sẽ âm thầm bỏ qua.

Những cân nhắc này là thiết yếu để hiểu các khía cạnh quan trọng nhất giúp WebAuthn Signal API hoạt động chính xác.

WebAuthn Signal API cung cấp một cơ chế tinh gọn để các Relying Party (RP) cập nhật metadata liên quan đến passkey trên các authenticator phía client. Điều này đặc biệt quan trọng để đảm bảo người dùng nhìn thấy thông tin chính xác và cập nhật trong giao diện chọn thông tin xác thực mà không cần phải tạo passkey mới một cách không cần thiết. Dưới đây là cách API thực hiện điều này:

Cập nhật Metadata với signalCurrentUserDetails(options)

Phương thức signalCurrentUserDetails(options) trong Signal API được thiết kế riêng cho việc cập nhật metadata của passkey. Phương thức này cho phép RP cung cấp các giá trị hiện tại cho user.name và user.displayName.

Dưới đây là quy trình hoạt động (xem thêm tiêu chuẩn WebAuthn Level 3).

1. Cấu trúc phương thức: Phương thức signalCurrentUserDetails(options) bao gồm rp.id, user.id và các giá trị cập nhật cho user.name và user.displayName.

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

2. Cập nhật Metadata cục bộ: Tìm kiếm các thông tin xác thực có sẵn cục bộ (trên authenticator) khớp với rpId và userId. Đối với tất cả các thông tin xác thực khớp, authenticator sẽ cập nhật name và displayName của chúng.

3. Bảo vệ quyền riêng tư: Quy trình được thiết kế để bảo vệ quyền riêng tư. Signal API không cung cấp phản hồi cho RP về việc cập nhật có thành công hay không, ngăn chặn mọi rò rỉ thông tin về trạng thái của thông tin xác thực.

4. Nhất quán trên các thiết bị: Bằng cách thường xuyên chạy phương thức signalCurrentUserDetails(options), RP có thể đảm bảo rằng metadata cho passkey vẫn nhất quán trên các thiết bị và nền tảng khác nhau nơi người dùng xác thực. Cách tiếp cận này giảm khả năng thông tin lỗi thời hoặc không chính xác hiển thị trong giao diện chọn lựa.

Trong ảnh chụp màn hình trên, bạn có thể thấy cách Google Chrome báo hiệu cập nhật này cho người dùng. WebAuthn Signal API là một phần của Chrome và có thể được thử nghiệm với Google Password Manager trên máy tính.

WebAuthn Signal API cung cấp cơ chế để các Relying Party (RP) báo hiệu việc xóa passkey khỏi các authenticator phía client. Điều này rất cần thiết để đảm bảo các thông tin xác thực lỗi thời hoặc không hợp lệ không xuất hiện trong giao diện chọn lựa, từ đó duy trì trải nghiệm người dùng tinh gọn và an toàn. Có hai phương thức để xóa passkey cục bộ: signalUnknownCredential(options) và signalAllAcceptedCredentials(options). Phương thức đầu tiên có thể được sử dụng trong các tình huống người dùng chưa xác thực, trong khi phương thức sau có thể được sử dụng khi người dùng đã xác thực. Do đó, phương thức thứ hai nên được ưu tiên vì lý do quyền riêng tư.

Dưới đây là cách hai phương thức hoạt động:

1. Cấu trúc phương thức: Phương thức signalUnknownCredential(options) bao gồm rpId (ID của Relying Party) và credentialId (định danh duy nhất của thông tin xác thực cần xóa).

PublicKeyCredential.signalUnknownCredential({
    rpId: "example.com",
    credentialId: "aabbcc", // credential id mà người dùng vừa thử, base64url
});

2. Gọi phương thức: RP gọi phương thức này bất cứ khi nào họ phát hiện ra rằng một thông tin xác thực cần bị xóa. Điều này có thể xảy ra ngay sau một lần thử xác thực với thông tin không hợp lệ, trong quá trình xóa tài khoản, hoặc khi người dùng thu hồi thông tin xác thực qua cài đặt tài khoản.

3. Xử lý phương thức: Khi signalUnknownCredential(options) được gọi, authenticator phía client cố gắng tìm các thông tin xác thực khớp với rpId và credentialID được chỉ định để loại bỏ. Tùy thuộc vào khả năng của authenticator, thông tin xác thực sẽ bị xóa hoặc một quy trình riêng của authenticator sẽ được áp dụng để ẩn thông tin xác thực đó trong các quy trình xác thực (ceremonies) tương lai.

1. Cấu trúc phương thức: Phương thức signalAllAcceptedCredentials(options) bao gồm rpId (ID của Relying Party), userId và một danh sách các Credential ID hợp lệ allAcceptedCredentialIds (danh sách các định danh duy nhất của thông tin xác thực nên được giữ lại).

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

2. Gọi phương thức: RP gọi phương thức này bất cứ khi nào họ phát hiện một thông tin xác thực cần bị xóa và muốn báo hiệu một danh sách các thông tin xác thực hợp lệ. Phương thức này nên được ưu tiên hơn signalUnknownCredential(options) để xóa thông tin xác thực.

3. Xử lý phương thức: Khi signalAllAcceptedCredentials(options) được gọi, authenticator phía client sẽ khớp rpId và userId. Authenticator sau đó tra cứu tất cả các thông tin xác thực cục bộ khớp với rpId và userId. Kết quả được so sánh với allAcceptedCredentialIds. Nếu có các thông tin xác thực cục bộ không nằm trong allAcceptedCredentialIds, thì các thông tin xác thực này sẽ bị xóa cục bộ (hoặc bị ẩn tùy thuộc vào authenticator).

4. Bỏ ẩn thông tin xác thực: Nếu một thông tin xác thực chỉ bị ẩn (tùy thuộc vào authenticator) và sau đó lại xuất hiện trong allAcceptedCredentialIds, thì thông tin xác thực này sẽ hiện diện trở lại trong các quy trình xác thực tương lai.

5. Mẹo hữu ích:

   • Khi sử dụng signalAllAcceptedCredentials(options), cần lưu ý rằng authenticator không phải lúc nào cũng được kết nối tại thời điểm phương thức này được thực thi. Do đó, các Relying Party có thể cân nhắc chạy signalAllAcceptedCredentials(options) định kỳ, chẳng hạn như trong mỗi lần đăng nhập, để đảm bảo tất cả thông tin xác thực đều được cập nhật.
   • Relying Party phải thận trọng khi chỉ định danh sách Credential ID (allAcceptedCredentialIds). Các thông tin xác thực không có trong danh sách này có thể bị ẩn hoặc xóa bởi authenticator, có thể là vĩnh viễn. Để ngăn chặn việc vô tình loại bỏ các thông tin xác thực hợp lệ, điều quan trọng là phải đảm bảo danh sách là đầy đủ. Nếu một ID hợp lệ vô tình bị bỏ sót, nó cần được thêm lại vào signalAllAcceptedCredentials(options) càng sớm càng tốt để hiển thị trở lại, giả sử authenticator hỗ trợ việc này.
   • Bất cứ khi nào có thể, các authenticator nên ưu tiên tạm thời ẩn thông tin xác thực thay vì xóa vĩnh viễn. Cách tiếp cận này giúp tạo điều kiện khôi phục nếu một ID hợp lệ vô tình bị RP bỏ sót, cho phép khôi phục mà không bị mất vĩnh viễn.

Trong ảnh chụp màn hình trên, bạn có thể thấy cách Google Chrome báo hiệu việc xóa. WebAuthn Signal API có thể được kiểm tra với Google Password Manager trên máy tính.

Để triển khai hiệu quả WebAuthn Signal API và đảm bảo đồng bộ hóa liền mạch metadata của passkey trên các authenticator phía client, hãy xem xét các khuyến nghị sau:

• Theo dõi các bản cập nhật WebAuthn Signal API và việc triển khai thực tế: Luôn cập nhật thông tin về các phát triển mới nhất liên quan đến Signal API. WebAuthn Signal API đã được kích hoạt trên Google Chrome 132, theo sau là các trình duyệt khác (ví dụ: Safari cũng đã thông báo hỗ trợ). Thường xuyên kiểm tra tiến độ và cập nhật để đảm bảo việc triển khai của bạn phù hợp với các tiêu chuẩn và thực tiễn mới nhất. Chúng tôi sẽ cập nhật bài đăng blog này khi tình hình phát triển.
• Bắt đầu với phương pháp signalAllAcceptedCredentials(options) sau mỗi lần đăng nhập thành công: Cách tiếp cận này đảm bảo rằng tất cả metadata và Credential ID được cập nhật trong một phương thức duy nhất, đơn giản hóa quy trình và duy trì sự nhất quán trên các thiết bị và nền tảng, đồng thời hủy kích hoạt các thông tin xác thực đã xóa hoặc cũ.
• Nhắn tin thời gian thực với signalUnknownCredential(options) cho các triển khai quy mô lớn: Cân nhắc sử dụng nhắn tin thời gian thực với phương thức signalUnknownCredential(options) trong các triển khai quy mô lớn hoặc khi cần cập nhật ngay lập tức. Phương thức này có thể nâng cao hiệu quả và độ chính xác của việc quản lý thông tin xác thực, đảm bảo rằng các thông tin xác thực không hợp lệ hoặc lỗi thời được xóa ngay lập tức khỏi giao diện chọn lựa.

Bằng cách làm theo các khuyến nghị này, bạn có thể triển khai WebAuthn Signal API hiệu quả ngay khi nó được hỗ trợ, đảm bảo rằng metadata của passkey luôn cập nhật và nhất quán trên tất cả các authenticator phía client, từ đó mang lại trải nghiệm người dùng mượt mà và an toàn cho passkey.

Tiêu chuẩn WebAuthn đang liên tục phát triển, trở nên giàu tính năng hơn theo từng tháng. Việc giới thiệu WebAuthn Signal API là một bước tiến quan trọng trong việc quản lý meta-data và xóa passkey trên các authenticator phía client. API này giải quyết các trường hợp sử dụng quan trọng về việc đồng bộ thông tin giữa Relying Party (RP) và authenticator, đồng thời đảm bảo rằng các passkey không hợp lệ hoặc lỗi thời được gỡ bỏ, qua đó cải thiện trải nghiệm người dùng.

• Tại sao cần Signal API? Signal API rất cần thiết để cập nhật metadata của passkey và xóa passkey trên authenticator phía client. Nó giải quyết các vấn đề liên quan đến thông tin user.name và user.displayName lỗi thời, vốn có thể gây nhầm lẫn khi thông tin xác thực được hiển thị trong giao diện chọn lựa. Ngoài ra, nó giúp duy trì giao diện chọn thông tin xác thực sạch sẽ và an toàn bằng cách loại bỏ các passkey đã thu hồi hoặc bị xóa.
• Signal API hoạt động như thế nào? Signal API hoạt động bằng cách cho phép RP gọi các phương thức về trạng thái hiện tại của thông tin xác thực, bao gồm cập nhật metadata và báo hiệu việc xóa passkey. Các báo cáo này được xử lý bởi authenticator phía client, đảm bảo thông tin hiển thị cho người dùng là chính xác và cập nhật. API được thiết kế để bảo vệ quyền riêng tư và hoạt động mà không cung cấp phản hồi cho RP về sự thành công của các cập nhật.

Khi tiêu chuẩn WebAuthn phát triển, nó hưởng lợi từ những mối quan tâm đa dạng của các bên tham gia, những người thúc đẩy các phần khác nhau của tiêu chuẩn đi lên. Việc theo dõi các phát triển này là rất quan trọng để cập nhật các cải tiến mới nhất và đảm bảo rằng việc triển khai vẫn phù hợp với các phương pháp và tiêu chuẩn tốt nhất. Cộng đồng WebAuthn tiếp tục thúc đẩy sự đổi mới, làm cho việc xác thực trở nên an toàn và thân thiện hơn với người dùng.