Panduan developer Token Status Pribadi

Sebelumnya, cookie pihak ketiga telah digunakan untuk menyimpan dan menyampaikan informasi tentang status pengguna, seperti status login, informasi tentang perangkat yang mereka gunakan, atau apakah mereka dikenal dan dipercaya. Misalnya, apakah pengguna telah login dengan SSO, apakah pengguna memiliki jenis perangkat yang kompatibel tertentu, atau apakah pengguna dikenal dan tepercaya. Dengan dukungan cookie pihak ketiga yang dihentikan, banyak kasus penggunaan ini harus didukung dengan cara lain.

Token Status Pribadi menawarkan cara untuk membagikan informasi di seluruh web, tetapi dengan cara yang menjaga privasi melalui kontrol pada jumlah data yang benar-benar dapat dibagikan.

Private State Tokens (sebelumnya dikenal sebagai Trust Tokens) memungkinkan kepercayaan pada keaslian pengguna disampaikan dari satu konteks ke konteks lain sekaligus membantu situs memberantas penipuan dan membedakan bot dengan manusia sungguhan—tanpa pelacakan pasif.

Dokumen ini menguraikan detail teknis untuk menerapkan Token Status Pribadi (PST). Untuk ringkasan yang lebih umum, lihat Ringkasan PST.

Bagaimana cara kerja Token Status Pribadi?

Hubungan utama yang perlu dipahami dalam PST adalah antara penerbit dan penukaran. Penerbit dan penukar dapat berada dalam perusahaan yang sama.

• Penerbit - Entitas ini memiliki beberapa sinyal tentang pengguna (misalnya, apakah pengguna tersebut adalah bot atau bukan) dan menyematkan sinyal tersebut ke dalam token yang disimpan di perangkat pengguna (detail selengkapnya di bagian berikutnya).
• Penukaran - Entitas ini mungkin tidak memiliki sinyal tentang pengguna, tetapi perlu mengetahui sesuatu tentang pengguna tersebut (misalnya, apakah pengguna tersebut adalah bot atau bukan) dan meminta untuk menukarkan token dari penerbit untuk memahami kredibilitas pengguna tersebut.

Setiap interaksi PST mengharuskan penerbit dan penukaran bekerja sama untuk membagikan sinyal di seluruh web. Sinyal tersebut adalah nilai kasar yang tidak cukup detail untuk mengidentifikasi individu.

Apakah Token Status Pribadi cocok untuk saya?

Perusahaan yang membuat keputusan terkait kepercayaan dan ingin informasi tersebut tersedia di berbagai konteks dapat memperoleh manfaat dari PST. Untuk mengetahui informasi selengkapnya tentang potensi kasus penggunaan PST, lihat dokumentasi kami tentang kasus penggunaan PST.

Menerbitkan dan menukarkan token

Penerapan PST dilakukan dalam tiga fase:

1. Menerbitkan token
2. Menukarkan token
3. Penerusan data penukaran

Pada fase pertama, token dikeluarkan ke browser (biasanya setelah beberapa jenis validasi). Pada fase kedua, entitas lain akan membuat permintaan untuk menukarkan token yang telah dikeluarkan untuk membaca nilai dalam token tersebut. Pada tahap akhir, pihak yang menukarkan menerima catatan penukaran (RR) dengan nilai yang terdapat dalam token. Pihak yang menukarkan kemudian dapat menggunakan catatan tersebut sebagai pengesahan pengguna tersebut untuk berbagai tujuan.

Tentukan strategi token Anda

Untuk menentukan strategi token, Anda perlu memahami konsep utama PST (token dan catatan penukaran), variabel, perilaku, dan batasan agar dapat memikirkan potensi penggunaannya untuk kasus penggunaan Anda.

Token dan catatan penukaran: apa hubungan di antara keduanya?

Setiap perangkat dapat menyimpan hingga 500 token per situs dan penerbit tingkat teratas. Selain itu, setiap token memiliki metadata yang memberi tahu kunci mana yang digunakan penerbit untuk menerbitkannya. Informasi tersebut dapat digunakan untuk memutuskan apakah akan menukarkan token atau tidak selama proses penukaran. Data PST disimpan secara internal oleh browser di perangkat pengguna dan hanya dapat diakses oleh PST API.

Saat token ditukarkan, Catatan Penukaran (RR) akan disimpan di perangkat. Penyimpanan ini berfungsi sebagai cache untuk penukaran di masa mendatang. Ada batas dua penukaran token setiap 48 jam, per perangkat, halaman, dan penerbit. Panggilan penukaran baru akan menggunakan RR yang di-cache jika memungkinkan, bukan menyebabkan permintaan ke penerbit.

1. Token baru dikeluarkan (maks. 500 per penerbit, situs, dan perangkat).
2. Semua token disimpan di penyimpanan token dalam perangkat (mirip dengan penyimpanan cookie).
3. Jika tidak ada RR aktif, RR baru dapat dibuat setelah penerbitan (maksimum 2 setiap 48 jam).
4. RR dianggap aktif hingga masa berlakunya berakhir dan akan digunakan sebagai cache lokal.
5. Panggilan penukaran baru akan mencapai cache lokal (tidak ada RR baru yang dihasilkan).

Setelah menentukan kasus penggunaan, Anda harus menentukan masa aktif RR dengan cermat karena hal ini akan menentukan berapa kali Anda dapat menggunakannya dalam kasus Anda.

Pastikan Anda memahami perilaku dan variabel penting berikut sebelum menentukan strategi:

Contoh skenario

Skenario #1: Masa berlaku RR kurang dari 24 jam (t=t) dan penukaran dilakukan beberapa kali selama periode 48 jam.

Skenario #2: Masa berlaku RR adalah 24 jam dan penukaran dilakukan beberapa kali selama periode 48 jam.

Skenario #3: Masa berlaku RR adalah 48 jam dan penukaran dilakukan beberapa kali selama periode 48 jam.

Jalankan demo

Sebelum mengadopsi PST, sebaiknya siapkan demo.

Dengan menjalankan demo ini, browser Anda menggunakan server penerbit dan penukar demo untuk menyediakan dan menggunakan token.

Pertimbangan teknis

Demo akan berjalan paling baik jika Anda menerapkan langkah-langkah berikut:

• Pastikan Anda menghentikan semua instance Chrome sebelum menjalankan Chrome dengan tanda.
• Jika Anda menjalankan di mesin Windows, lihat panduan ini tentang cara meneruskan parameter ke biner yang dapat dieksekusi Chrome.
• Buka Chrome DevTools di bagian Applications > Storage > Private State Tokens saat menggunakan aplikasi demo untuk melihat token yang dikeluarkan atau ditukarkan oleh penerbit demo.

Menyiapkan penggunaan

Bagian ini menjelaskan persyaratan untuk menjadi penerbit atau penukar PST.

Menjadi penerbit

Penerbit memainkan peran penting dalam PST. Mereka menetapkan nilai ke token untuk menentukan apakah pengguna adalah bot atau bukan. Jika ingin mulai menggunakan PST sebagai penerbit, Anda harus mendaftar dengan menyelesaikan Proses pendaftaran penerbit.

Untuk mengajukan permohonan menjadi penerbit, operator situs penerbit harus membuka masalah baru di repositori GitHub menggunakan template "Penerbit PST Baru". Ikuti panduan di repositori untuk mengisi masalah. Setelah endpoint diverifikasi, endpoint tersebut akan digabungkan ke repositori ini dan infrastruktur sisi server Chrome akan mulai mengambil kunci tersebut.

Server penerbit

Penerbit dan penukar adalah aktor utama untuk PST; server dan token adalah alat utama untuk PST. Meskipun kami telah memberikan beberapa detail tentang token dan di dokumentasi GitHub, kami ingin menawarkan detail selengkapnya tentang server PST. Untuk menyiapkan diri sebagai penerbit PST, Anda harus menyiapkan server penerbitan terlebih dahulu.

Men-deploy lingkungan Anda: server penerbit

Untuk menerapkan server penerbit token, Anda harus membuat aplikasi sisi server sendiri yang mengekspos endpoint HTTP.

Komponen penerbit terdiri dari dua modul utama: (1) server penerbit dan (2) penerbit token.

Seperti semua aplikasi yang menghadap web, sebaiknya tambahkan lapisan perlindungan ke server penerbit Anda.

1. Server penerbit: Dalam penerapan contoh kami, server penerbit kami adalah server Node.js yang menggunakan framework Express untuk menghosting endpoint HTTP Penerbit. Anda dapat melihat contoh kode di GitHub.

2. Penerbit token: Komponen kriptografi penerbit tidak memerlukan bahasa tertentu, tetapi karena persyaratan performa komponen ini, kami memberikan contoh implementasi C yang menggunakan library BoringSSL untuk mengelola token. Anda dapat menemukan contoh kode penerbit dan informasi selengkapnya tentang penginstalan di GitHub

3. Kunci: Komponen penerbit token menggunakan kunci EC kustom untuk mengenkripsi token. Kunci ini harus dilindungi dan disimpan di penyimpanan yang aman.

Persyaratan teknis untuk server penerbit

Sesuai dengan protokolnya, Anda harus menerapkan minimal dua endpoint HTTP di server penerbit:

• Pengikatan kunci (misalnya, /.well-known/private-state-token/key-commitment): Endpoint ini adalah tempat detail kunci publik enkripsi Anda akan tersedia bagi browser untuk mengonfirmasi bahwa server Anda sah.
  • Contoh kode di GitHub
  • Lihat demo
• Penerbitan token (misalnya, /.well-known/private-state-token/issuance): Endpoint penerbitan token tempat semua permintaan token akan ditangani. Endpoint ini akan menjadi titik integrasi untuk komponen penerbit token.
  • Contoh kode di GitHub
  • Lihat demo

Seperti yang disebutkan sebelumnya, karena server ini diperkirakan akan menangani traffic yang tinggi, sebaiknya deploy server ini menggunakan infrastruktur yang skalabel (misalnya, di lingkungan cloud) agar dapat menyesuaikan backend berdasarkan permintaan yang bervariasi.

Mengirim panggilan ke server penerbit

Terapkan panggilan pengambilan situs ke stack penerbit Anda untuk menerbitkan token baru.

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

Lihat contoh kode.

Server penukaran

Anda harus menerapkan layanan penukaran token dengan membuat aplikasi sisi server Anda sendiri. Hal ini akan memungkinkan Anda membaca token yang dikirim oleh penerbit. Langkah-langkah berikut menguraikan cara menukarkan token serta cara membaca catatan penukaran yang terkait dengan token tersebut.

Anda dapat memilih untuk menjalankan penerbit dan penukaran di server yang sama (atau grup server).

Persyaratan teknis untuk server penukaran

Sesuai dengan protokolnya, Anda harus menerapkan minimal dua endpoint HTTP untuk server penukaran Anda:

• /.well-known/private-state-token/redemption: endpoint tempat semua penukaran token akan ditangani. Endpoint ini akan menjadi tempat komponen penukaran token diintegrasikan
  • Contoh kode di GitHub
  • Demo

Mengirim panggilan ke server penukaran

Untuk menukarkan token, Anda harus menerapkan panggilan pengambilan situs ke stack penukar untuk menukarkan token yang dikeluarkan sebelumnya.

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

Lihat contoh kode.

Setelah menukarkan token, Anda dapat mengirimkan catatan penukaran (RR) dengan melakukan panggilan pengambilan lainnya:

    // 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>]
      }
    });

Lihat contoh kode.

Men-deploy implementasi Anda

Untuk menguji penerapan, buka terlebih dahulu halaman web tempat panggilan penerbitan dilakukan dan pastikan token dibuat sesuai dengan logika Anda. Verifikasi di backend Anda bahwa panggilan dilakukan sesuai dengan spesifikasi. Kemudian, buka halaman web tempat panggilan penukaran dilakukan dan konfirmasi bahwa RR dibuat, mengikuti logika Anda.

Deployment dunia nyata

Sebaiknya pilih situs target yang merupakan bagian dari kasus penggunaan spesifik Anda:

• Jumlah kunjungan bulanan yang kecil (~ <1 juta kunjungan/bulan): Anda harus memulai dengan men-deploy API ke audiens kecil terlebih dahulu
• Anda memiliki dan mengontrolnya: Jika perlu, Anda dapat menonaktifkan penerapan dengan cepat tanpa persetujuan yang rumit
• Tidak lebih dari satu penerbit: Untuk membatasi jumlah token guna menyederhanakan pengujian.
• Tidak lebih dari dua penukar: Anda perlu menyederhanakan pemecahan masalah jika terjadi masalah.

Kebijakan izin

Agar berfungsi dengan baik, PST API harus tersedia untuk halaman tingkat teratas dan sub-resource apa pun yang menggunakan API.

Operasi token-request dikontrol oleh direktif private-state-token-issuance. Operasi token-redemption dan send-redemption-record dikontrol oleh perintah private-state-token-redemption. Di Chrome 132 dan yang lebih baru, daftar yang diizinkan untuk direktif ini ditetapkan ke * (semua origin) secara default. Artinya, fitur ini tersedia untuk halaman tingkat teratas, iframe origin yang sama, dan iframe lintas origin tanpa delegasi eksplisit.

Anda dapat memilih untuk tidak menerbitkan atau menukarkan token PST untuk halaman tertentu di situs Anda dengan menyertakan private-state-token-issuance=() dan private-state-token-redemption=() di header Permissions-Policy untuk setiap halaman.

Anda juga dapat menggunakan header Permissions-Policy untuk mengontrol akses pihak ketiga ke PST. Sebagai parameter ke daftar asal header, gunakan self dan asal apa pun yang ingin Anda izinkan akses ke API. Misalnya, untuk menonaktifkan sepenuhnya penggunaan PST dalam semua konteks penjelajahan kecuali untuk origin Anda sendiri dan https://example.com, tetapkan header respons HTTP berikut:

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

Untuk mengaktifkan API bagi semua resource lintas origin, tetapkan daftar origin ke *.

Pelajari cara mengontrol fitur Privacy Sandbox dengan Kebijakan Izin atau pelajari lebih dalam cara memahami Kebijakan Izin.

Pemecahan masalah

Anda dapat memeriksa PST dari tab Jaringan dan Aplikasi Chrome DevTools.

Di tab Jaringan:

Di tab Aplikasi:

Baca selengkapnya tentang integrasi DevTools ini.

Praktik terbaik klien

Jika fungsi penting situs Anda bergantung pada penerbit token tertentu, prioritaskan penerbit tersebut. Panggil hasPrivateToken(issuer) untuk penerbit pilihan ini sebelum memuat skrip lainnya. Hal ini penting untuk mencegah kemungkinan kegagalan penukaran.

Jumlah penerbit per tingkat teratas dibatasi hingga dua, dan skrip pihak ketiga juga dapat mencoba memanggil hasPrivateToken(issuer) untuk memprioritaskan penerbit pilihan mereka sendiri. Jadi, amankan penerbit penting Anda terlebih dahulu untuk memastikan situs Anda beroperasi seperti yang diharapkan.

  // 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).

Praktik terbaik dan pemecahan masalah server

Agar server penerbit dan penukaran Anda beroperasi secara efektif, sebaiknya terapkan praktik terbaik berikut untuk memastikan Anda tidak mengalami masalah akses, keamanan, logging, atau traffic untuk PST.

• Endpoint Anda harus menerapkan kriptografi yang kuat dengan menggunakan TLS 1.3 atau 1.2.
• Infrastruktur Anda harus siap menangani volume traffic yang bervariasi (termasuk lonjakan).
• Pastikan kunci Anda terlindungi dan aman, sesuai dengan Kebijakan Kontrol Akses, Strategi Pengelolaan Kunci, dan Rencana Kelangsungan Bisnis Anda.
• Tambahkan metrik kemampuan pengamatan ke stack Anda untuk memastikan Anda akan memiliki visibilitas untuk memahami penggunaan, hambatan, dan masalah performa setelah beralih ke produksi.

Informasi selengkapnya

1. Tinjau dokumen developer:
   1. Mulailah dengan membaca ringkasan untuk memahami PST dan kemampuannya.
   2. Tonton video pengantar PST.
   3. Coba demo PST.
   4. Baca juga penjelasan API untuk memahami detail selengkapnya tentang API tersebut.
   5. Baca selengkapnya tentang spesifikasi saat ini API.
2. Berpartisipasilah dalam diskusi menggunakan masalah GitHub atau panggilan W3C.
3. Untuk lebih memahami terminologi apa pun, tinjau glosarium Privacy Sandbox.
4. Untuk mempelajari lebih lanjut konsep Chrome, seperti 'uji coba origin' atau 'flag Chrome', tinjau video dan artikel singkat yang tersedia dari goo.gle/cc.