Hướng dẫn dành cho nhà phát triển về Mã thông báo trạng thái riêng tư

Trước đây, cookie của bên thứ ba được dùng để lưu trữ và truyền tải thông tin về trạng thái của người dùng, chẳng hạn như trạng thái đăng nhập, thông tin về thiết bị mà họ đang sử dụng hoặc liệu họ có phải là người dùng đã biết và đáng tin cậy hay không. Ví dụ: người dùng đã đăng nhập bằng tính năng SSO hay chưa, người dùng có một loại thiết bị tương thích nhất định hay không, hoặc người dùng có phải là người dùng đã biết và đáng tin cậy hay không. Khi tính năng hỗ trợ cookie của bên thứ ba bị ngừng sử dụng, nhiều trường hợp sử dụng này sẽ cần được hỗ trợ bằng các phương tiện khác.

Private State Tokens cung cấp một cách để chia sẻ thông tin trên web, nhưng theo cách bảo vệ quyền riêng tư thông qua các chế độ kiểm soát đối với lượng dữ liệu thực sự có thể được chia sẻ.

Private State Tokens (trước đây gọi là Trust Tokens) cho phép truyền tải độ tin cậy về tính xác thực của người dùng từ ngữ cảnh này sang ngữ cảnh khác, đồng thời giúp các trang web chống lại hành vi gian lận và phân biệt bot với người dùng thực mà không cần theo dõi thụ động.

Tài liệu này trình bày chi tiết về kỹ thuật để triển khai Mã thông báo trạng thái riêng tư (PST). Để biết thông tin tổng quan ở cấp độ cao hơn, hãy xem thông tin tổng quan về PST.

Private State Tokens hoạt động như thế nào?

Mối quan hệ chính cần nắm rõ trong PST là giữa bên phát hành và bên sử dụng. Bên phát hành và bên sử dụng có thể thuộc cùng một công ty.

• Bên phát hành – Những thực thể này có một số tín hiệu về người dùng (ví dụ: người dùng đó có phải là bot hay không) và nhúng tín hiệu đó vào một mã thông báo được lưu trữ trên thiết bị của người dùng (xem thêm thông tin chi tiết trong các phần tiếp theo).
• Bên xác thực – Những thực thể này có thể không có tín hiệu về người dùng nhưng cần biết một số thông tin về họ (ví dụ: người dùng đó có phải là bot hay không) và yêu cầu xác thực mã thông báo từ bên phát hành để hiểu được độ tin cậy của người dùng đó.

Mọi hoạt động tương tác PST đều yêu cầu bên phát hành và bên sử dụng cùng nhau chia sẻ tín hiệu trên web. Những tín hiệu đó là các giá trị thô không đủ chi tiết để xác định cá nhân.

Private State Tokens có phù hợp với tôi không?

Những công ty đang đưa ra quyết định về mức độ tin cậy và muốn thông tin đó có sẵn trong nhiều bối cảnh có thể hưởng lợi từ PST. Để biết thêm thông tin về các trường hợp sử dụng có thể có của PST, hãy xem tài liệu của chúng tôi về các trường hợp sử dụng PST.

Phát hành và đổi mã thông báo

Việc triển khai PST diễn ra theo 3 giai đoạn:

1. Phát hành mã thông báo
2. Đổi mã thông báo
3. Chuyển tiếp bản ghi về việc sử dụng

Trong giai đoạn đầu tiên, mã thông báo được phát hành cho một trình duyệt (thường là sau một số loại xác thực). Trong giai đoạn thứ hai, một thực thể khác sẽ yêu cầu đổi mã thông báo đã được phát hành để đọc giá trị trong mã thông báo đó. Trong giai đoạn cuối cùng, bên nhận sẽ nhận được một bản ghi sử dụng (RR) có giá trị nằm trong mã thông báo. Sau đó, bên nhận có thể sử dụng bản ghi đó làm chứng thực cho người dùng đó cho nhiều mục đích.

Xác định chiến lược mã thông báo

Để xác định chiến lược mã thông báo, bạn cần hiểu các khái niệm chính về PST (mã thông báo và bản ghi đổi mã thông báo), các biến, hành vi và giới hạn để có thể nghĩ đến khả năng sử dụng chúng cho trường hợp sử dụng của bạn.

Mã thông báo và bản ghi sử dụng: mối quan hệ giữa chúng là gì?

Mỗi thiết bị có thể lưu trữ tối đa 500 mã thông báo cho mỗi trang web và tổ chức phát hành cấp cao nhất. Ngoài ra, mỗi mã thông báo đều có siêu dữ liệu cho biết khoá mà tổ chức phát hành đã dùng để phát hành mã thông báo đó. Thông tin đó có thể được dùng để quyết định có đổi mã thông báo hay không trong quá trình đổi. Dữ liệu PST được trình duyệt lưu trữ nội bộ trên thiết bị của người dùng và chỉ có thể truy cập bằng PST API.

Khi một mã thông báo được đổi, Bản ghi đổi (RR) sẽ được lưu trữ trên thiết bị. Bộ nhớ này đóng vai trò là bộ nhớ đệm cho các lần sử dụng sau này. Mỗi thiết bị, trang và nhà phát hành chỉ được phép đổi hai mã thông báo sau mỗi 48 giờ. Các lệnh gọi yêu cầu sử dụng mới sẽ sử dụng RR được lưu vào bộ nhớ đệm nếu có thể, thay vì gây ra yêu cầu cho tổ chức phát hành.

1. Mã thông báo mới sẽ được phát hành (tối đa 500 mã thông báo cho mỗi tổ chức phát hành, trang web và thiết bị).
2. Tất cả mã thông báo đều được lưu trữ trong kho mã thông báo trên thiết bị (tương tự như kho cookie).
3. Nếu không tìm thấy RR đang hoạt động, thì bạn có thể tạo RR mới sau khi phát hành (tối đa 2 RR sau mỗi 48 giờ).
4. RR được coi là đang hoạt động cho đến khi hết hạn và sẽ được dùng làm bộ nhớ đệm cục bộ.
5. Các lệnh gọi đổi quà mới sẽ truy cập vào bộ nhớ đệm cục bộ (không có RR mới nào được tạo).

Sau khi xác định trường hợp sử dụng, bạn phải xác định cẩn thận thời gian tồn tại của RR vì điều này sẽ xác định số lần bạn có thể sử dụng chúng trong trường hợp của mình.

Hãy đảm bảo bạn hiểu rõ những hành vi và biến số quan trọng sau đây trước khi xác định chiến lược:

Các trường hợp ví dụ

Trường hợp 1: Thời hạn sử dụng RR dưới 24 giờ (t=t) và việc sử dụng được thực hiện nhiều lần trong khoảng thời gian 48 giờ.

Trường hợp 2: Tuổi thọ của RR là 24 giờ và việc sử dụng được thực hiện nhiều lần trong khoảng thời gian 48 giờ.

Tình huống 3: Thời hạn sử dụng RR là 48 giờ và việc sử dụng được thực hiện nhiều lần trong khoảng thời gian 48 giờ.

Chạy bản minh hoạ

Trước khi áp dụng PST, bạn nên thiết lập bản minh hoạ.

Khi chạy bản minh hoạ này, trình duyệt của bạn đang sử dụng các máy chủ phát hành và đổi mã thông báo minh hoạ để cung cấp và sử dụng mã thông báo.

Những điểm cần lưu ý về mặt kỹ thuật

Bản minh hoạ sẽ chạy hiệu quả nhất nếu bạn triển khai các bước sau:

• Hãy nhớ dừng tất cả các phiên bản Chrome trước khi chạy Chrome bằng cờ.
• Nếu bạn đang chạy trên máy Windows, hãy xem hướng dẫn này về cách truyền các tham số đến tệp thực thi nhị phân của Chrome.
• Mở Công cụ cho nhà phát triển của Chrome trong mục Ứng dụng > Bộ nhớ > Mã thông báo trạng thái riêng tư khi sử dụng ứng dụng minh hoạ để xem các mã thông báo do nhà phát hành minh hoạ phát hành hoặc đổi.

Thiết lập để áp dụng

Phần này giải thích các yêu cầu để trở thành bên phát hành hoặc bên sử dụng PST.

Trở thành nhà phát hành

Bên phát hành đóng vai trò quan trọng trong PST. Chúng chỉ định giá trị cho mã thông báo để xác định xem người dùng có phải là bot hay không. Nếu muốn bắt đầu sử dụng PST với tư cách là bên phát hành, bạn cần đăng ký bằng cách hoàn tất Quy trình đăng ký phát hành.

Để đăng ký trở thành đơn vị phát hành, người vận hành trang web của đơn vị phát hành phải mở một vấn đề mới trên kho lưu trữ GitHub bằng mẫu "Đơn vị phát hành PST mới". Làm theo hướng dẫn trên kho lưu trữ để điền thông tin về vấn đề. Sau khi được xác minh, một điểm cuối sẽ được hợp nhất vào kho lưu trữ này và cơ sở hạ tầng phía máy chủ của Chrome sẽ bắt đầu tìm nạp các khoá đó.

Máy chủ của tổ chức phát hành

Nhà phát hành và người sử dụng là những tác nhân chính của PST; máy chủ và mã thông báo là những công cụ chính của PST. Mặc dù chúng tôi đã cung cấp một số thông tin về mã thông báo và trong tài liệu trên GitHub, nhưng chúng tôi vẫn muốn cung cấp thêm thông tin về các máy chủ PST. Để thiết lập làm đơn vị phát hành PST, trước tiên, bạn cần thiết lập một máy chủ phát hành.

Triển khai môi trường của bạn: máy chủ của tổ chức phát hành

Để triển khai máy chủ phát hành mã thông báo, bạn cần tạo ứng dụng phía máy chủ của riêng mình để hiển thị các điểm cuối HTTP.

Thành phần tổ chức phát hành bao gồm 2 mô-đun chính: (1) máy chủ tổ chức phát hành và (2) tổ chức phát hành mã thông báo.

Giống như tất cả các ứng dụng hướng đến web, bạn nên thêm một lớp bảo vệ bổ sung cho máy chủ của đơn vị phát hành.

1. Máy chủ phát hành: Trong ví dụ triển khai của chúng tôi, máy chủ phát hành là một máy chủ Node.js sử dụng khung Express để lưu trữ các điểm cuối HTTP của Tổ chức phát hành. Bạn có thể xem mã mẫu trên GitHub.

2. Đơn vị phát hành mã thông báo: Thành phần mật mã của đơn vị phát hành không yêu cầu bất kỳ ngôn ngữ cụ thể nào, nhưng do yêu cầu về hiệu suất của thành phần này, chúng tôi sẽ cung cấp một quy trình triển khai C làm ví dụ, trong đó sử dụng thư viện BoringSSL để quản lý mã thông báo. Bạn có thể tìm thấy ví dụ về mã tổ chức phát hành và thông tin khác về quy trình cài đặt trên GitHub

3. Khoá: Thành phần trình phát hành mã thông báo sử dụng các khoá EC tuỳ chỉnh để mã hoá mã thông báo. Bạn phải bảo vệ và lưu trữ các khoá này trong bộ nhớ bảo mật.

Yêu cầu kỹ thuật đối với máy chủ của tổ chức phát hành

Theo giao thức này, bạn sẽ cần triển khai ít nhất 2 điểm cuối HTTP trong máy chủ của đơn vị phát hành:

• Cam kết khoá (ví dụ: /.well-known/private-state-token/key-commitment): Điểm cuối này là nơi trình duyệt có thể truy cập vào thông tin chi tiết về khoá công khai mã hoá của bạn để xác nhận rằng máy chủ của bạn là hợp pháp.
  • Mã mẫu trên GitHub
  • Xem bản minh hoạ
• Phát hành mã thông báo (ví dụ: /.well-known/private-state-token/issuance): Điểm cuối phát hành mã thông báo nơi tất cả các yêu cầu về mã thông báo sẽ được xử lý. Điểm cuối này sẽ là điểm tích hợp cho thành phần trình phát hành mã thông báo.
  • Mã mẫu trên GitHub
  • Xem bản minh hoạ

Như đã đề cập trước đó, do lưu lượng truy cập dự kiến sẽ cao mà máy chủ này có thể xử lý, bạn nên triển khai máy chủ này bằng cách sử dụng cơ sở hạ tầng có khả năng mở rộng (ví dụ: trong môi trường đám mây) để có thể điều chỉnh phần phụ trợ dựa trên nhu cầu thay đổi.

Gửi lệnh gọi đến máy chủ của tổ chức phát hành

Triển khai lệnh tìm nạp trang web vào ngăn xếp của đơn vị phát hành để phát hành mã thông báo mới.

 // issuer request
    await fetch("/.well-known/private-state-token/issuance", {
      method: "POST",
      privateToken: {
        version: 1,
        operation: "token-request"
      }
    });

Xem ví dụ về mã.

Máy chủ của người đổi quà

Bạn sẽ cần triển khai dịch vụ đổi mã thông báo bằng cách tạo ứng dụng phía máy chủ của riêng mình. Nhờ đó, bạn có thể đọc các mã thông báo mà một tổ chức phát hành gửi. Các bước sau đây trình bày cách đổi mã thông báo cũng như cách đọc các bản ghi đổi mã thông báo được liên kết với những mã thông báo đó.

Bạn có thể chọn chạy đơn vị phát hành và đơn vị nhận trong cùng một máy chủ (hoặc nhóm máy chủ).

Yêu cầu kỹ thuật đối với máy chủ của người dùng

Theo giao thức này, bạn sẽ cần triển khai ít nhất 2 điểm cuối HTTP cho máy chủ của người dùng:

• /.well-known/private-state-token/redemption: điểm cuối nơi tất cả hoạt động đổi mã thông báo sẽ được xử lý. Điểm cuối này sẽ là nơi tích hợp thành phần đổi mã thông báo
  • Mã ví dụ trên GitHub
  • Bản minh hoạ

Gửi lệnh gọi đến máy chủ người đổi

Để đổi mã thông báo, bạn sẽ cần triển khai một lệnh gọi tìm nạp trang web đến ngăn xếp người đổi để đổi mã thông báo đã phát hành trước đó.

    // redemption request
    await fetch("/.well-known/private-state-token/redemption", {
      method: "POST",
      privateToken: {
        version: 1,
        operation: "token-redemption",
        refreshPolicy: "none"
      }
    });

Hãy xem mã mẫu.

Sau khi đổi mã thông báo, bạn có thể gửi bản ghi việc đổi mã thông báo (RR) bằng cách thực hiện một lệnh tìm nạp khác:

    // attach redemption records from the issuers to the request
    await fetch("<DESTINATION_RESOURCE>", {
      method: "POST",
      privateToken: {
        version: 1,
        operation: "send-redemption-record",
        issuers: [<ISSUER_DOMAIN>]
      }
    });

Hãy xem mã mẫu.

Triển khai

Để kiểm thử việc triển khai, trước tiên, hãy chuyển đến trang web nơi lệnh gọi phát hành được thực hiện và xác nhận rằng(các) mã thông báo được tạo theo logic của bạn. Xác minh trong phần phụ trợ rằng các lệnh gọi được thực hiện theo quy cách. Sau đó, hãy chuyển đến trang web nơi thực hiện lệnh gọi đổi và xác nhận rằng các RR được tạo, theo logic của bạn.

Triển khai trong thế giới thực

Bạn nên chọn những trang web mục tiêu thuộc trường hợp sử dụng cụ thể của mình:

• Số lượt truy cập hằng tháng thấp (khoảng <1 triệu lượt truy cập/tháng): Bạn nên bắt đầu bằng cách triển khai API cho một nhóm nhỏ đối tượng trước
• Bạn sở hữu và kiểm soát: Nếu cần, bạn có thể nhanh chóng tắt chế độ triển khai mà không cần quy trình phê duyệt phức tạp
• Không quá một tổ chức phát hành: Để giới hạn số lượng mã thông báo nhằm đơn giản hoá quy trình kiểm thử.
• Không quá 2 người sử dụng: Bạn cần đơn giản hoá quy trình khắc phục sự cố trong trường hợp có vấn đề.

Chính sách về quyền

Để hoạt động đúng cách, API PST phải có sẵn cho trang cấp cao nhất và mọi tài nguyên phụ sử dụng API này.

Thao tác yêu cầu mã thông báo được kiểm soát bằng chỉ thị private-state-token-issuance. Các thao tác token-redemption và send-redemption-record được kiểm soát bằng chỉ thị private-state-token-redemption. Trong Chrome 132 trở lên, danh sách cho phép của các chỉ thị này được đặt thành * (tất cả các nguồn) theo mặc định. Điều này có nghĩa là tính năng này có sẵn cho trang cấp cao nhất, iframe cùng nguồn gốc và iframe nhiều nguồn gốc mà không cần uỷ quyền rõ ràng.

Bạn có thể chọn không phát hành hoặc đổi mã thông báo PST cho các trang cụ thể trên trang web của mình bằng cách thêm private-state-token-issuance=() và private-state-token-redemption=() vào tiêu đề Permissions-Policy cho từng trang.

Bạn cũng có thể sử dụng tiêu đề Permissions-Policy để kiểm soát quyền truy cập của bên thứ ba vào PST. Khi dùng làm tham số cho danh sách nguồn gốc tiêu đề, hãy sử dụng self và mọi nguồn gốc mà bạn muốn cho phép truy cập vào API. Ví dụ: để hoàn toàn tắt việc sử dụng PST trong tất cả các bối cảnh duyệt web, ngoại trừ nguồn gốc của riêng bạn và https://example.com, hãy đặt các tiêu đề phản hồi HTTP sau:

Permissions-Policy:private-state-token-issuance=(self "https://example.com"),private-state-token-redemption=(self "https://example.com")

Để bật API cho tất cả tài nguyên trên nhiều nguồn, hãy đặt danh sách nguồn thành *.

Tìm hiểu cách kiểm soát các tính năng của Hộp cát về quyền riêng tư bằng Chính sách về quyền hoặc tìm hiểu sâu hơn về Chính sách về quyền.

Khắc phục sự cố

Bạn có thể kiểm tra PST trong thẻ Mạng và Ứng dụng của Công cụ của Chrome cho nhà phát triển.

Trên thẻ Mạng:

Trên thẻ Ứng dụng:

Đọc thêm về chế độ tích hợp Công cụ cho nhà phát triển này.

Các phương pháp hay nhất về ứng dụng

Nếu các chức năng quan trọng của trang web phụ thuộc vào một số đơn vị phát hành mã thông báo nhất định, hãy ưu tiên các đơn vị đó. Gọi hasPrivateToken(issuer) cho những nhà phát hành ưu tiên này trước khi tải bất kỳ tập lệnh nào khác. Điều này rất quan trọng để ngăn chặn các trường hợp không đổi được điểm.

Số lượng tổ chức phát hành cho mỗi cấp cao nhất là tối đa là 2 và các tập lệnh của bên thứ ba cũng có thể cố gắng gọi hasPrivateToken(issuer) để ưu tiên các tổ chức phát hành mà họ muốn. Vì vậy, hãy bảo mật các nhà phát hành thiết yếu ngay từ đầu để đảm bảo trang web của bạn hoạt động như mong đợi.

  // Prioritize your critical token issuer.
  document.hasPrivateToken('https://critical-issuer.example')
    .then(hasToken => {
      if (hasToken) {
        // Use the token or perform actions based on its availability.
      } else {
        // Handle the case where the token is not available.
      }
    });

  // Load third-party scripts or secure another token issuer (up to two in total).

Các phương pháp hay nhất và cách khắc phục sự cố về máy chủ

Để máy chủ của đơn vị phát hành và đơn vị sử dụng hoạt động hiệu quả, bạn nên triển khai các phương pháp hay nhất sau đây để đảm bảo bạn không gặp phải bất kỳ vấn đề nào về quyền truy cập, bảo mật, ghi nhật ký hoặc lưu lượng truy cập đối với PST.

• Các điểm cuối của bạn phải áp dụng phương pháp mã hoá mạnh bằng cách sử dụng TLS 1.3 hoặc 1.2.
• Cơ sở hạ tầng của bạn phải sẵn sàng xử lý lưu lượng truy cập có thể thay đổi (kể cả lưu lượng truy cập tăng đột biến).
• Đảm bảo khoá của bạn được bảo vệ và an toàn, phù hợp với Chính sách kiểm soát quyền truy cập, Chiến lược quản lý khoá và Kế hoạch kinh doanh liên tục.
• Thêm các chỉ số về khả năng quan sát vào ngăn xếp của bạn để đảm bảo bạn có thể quan sát nhằm nắm được mức sử dụng, các điểm tắc nghẽn và vấn đề về hiệu suất sau khi chuyển sang phiên bản phát hành công khai.

Thông tin khác

1. Xem tài liệu dành cho nhà phát triển:
   1. Bắt đầu bằng cách đọc thông tin tổng quan để nắm bắt thông tin về PST và các chức năng của PST.
   2. Xem video giới thiệu về PST.
   3. Dùng thử bản minh hoạ PST.
   4. Bạn cũng nên đọc giải thích về API để hiểu rõ hơn về API này.
   5. Đọc thêm về quy cách hiện tại của API.
2. Đóng góp cho cuộc trò chuyện bằng cách sử dụng vấn đề trên GitHub hoặc cuộc gọi W3C.
3. Để hiểu rõ hơn về bất kỳ thuật ngữ nào, hãy xem bảng chú giải Hộp cát về quyền riêng tư.
4. Để tìm hiểu thêm về các khái niệm của Chrome, chẳng hạn như "bản dùng thử theo nguyên gốc" hoặc "cờ Chrome", hãy xem các video và bài viết ngắn có tại goo.gle/cc.