Przewodnik dla programistów dotyczący tokenów prywatności

W przeszłości pliki cookie innych firm były używane do przechowywania i przekazywania informacji o stanie użytkownika, takich jak stan logowania, informacje o używanym urządzeniu czy to, czy użytkownik jest znany i zaufany. Na przykład czy użytkownik zalogował się za pomocą logowania jednokrotnego, czy ma określony typ zgodnego urządzenia lub czy jest znany i zaufany. W związku z wycofaniem obsługi plików cookie innych firm wiele z tych zastosowań będzie musiało być obsługiwanych w inny sposób.

Prywatne tokeny stanu umożliwiają udostępnianie informacji w internecie, ale w sposób chroniący prywatność dzięki kontroli ilości danych, które mogą być udostępniane.

Tokeny prywatności (wcześniej znane jako tokeny zaufania) umożliwiają przekazywanie zaufania do autentyczności użytkownika z jednego kontekstu do drugiego, a jednocześnie pomagają witrynom zwalczać oszustwa i odróżniać boty od prawdziwych użytkowników bez pasywnego śledzenia.

Ten dokument zawiera szczegóły techniczne dotyczące implementowania tokenów stanu prywatnego (PST). Ogólne informacje znajdziesz w omówieniu PST.

Jak działają tokeny prywatności?

W przypadku PST kluczowa jest relacja między wydawcami a osobami realizującymi płatności. Wydawcy i osoby realizujące mogą być pracownikami tej samej firmy.

• Wystawcy – te podmioty mają sygnał dotyczący użytkownika (np. czy jest on botem) i osadzają go w tokenie przechowywanym na urządzeniu użytkownika (więcej informacji w następnych sekcjach).
• Podmioty odbierające – te podmioty mogą nie mieć sygnału dotyczącego użytkownika, ale potrzebują informacji o nim (np. czy jest on botem) i proszą o odebranie tokena od wystawcy, aby określić wiarygodność użytkownika.

Każda interakcja z PST wymaga współpracy podmiotów wydających i wykorzystujących tokeny w zakresie udostępniania sygnałów w internecie. Są to wartości przybliżone, które nie są wystarczająco szczegółowe, aby identyfikować poszczególne osoby.

Czy tokeny prywatności są dla mnie odpowiednie?

Firmy, które podejmują decyzje dotyczące zaufania i chcą, aby te informacje były dostępne w różnych kontekstach, mogą skorzystać z PST. Więcej informacji o potencjalnych zastosowaniach PST znajdziesz w dokumentacji dotyczącej przypadków użycia PST.

Wydawanie i wykorzystywanie tokenów

Wdrożenie PST odbywa się w 3 fazach:

1. Wydawanie tokenów
2. Wykorzystywanie tokenów
3. Przekazywanie rekordów wykorzystania

W pierwszej fazie tokeny są wydawane przeglądarce (zwykle po pewnego rodzaju weryfikacji). W drugiej fazie inny podmiot wyśle prośbę o wykorzystanie tokena, który został wydany w celu odczytania wartości w tym tokenie. W ostatniej fazie podmiot realizujący otrzymuje rekord realizacji (RR) z wartością, która była zawarta w tokenie. Podmiot odbierający może następnie użyć tego rekordu jako potwierdzenia tożsamości użytkownika do różnych celów.

Określ strategię dotyczącą tokenów

Aby określić strategię dotyczącą tokenów, musisz poznać kluczowe pojęcia związane z PST (tokeny i rekordy wykorzystania), zmienne, zachowania i ograniczenia, aby móc rozważyć ich potencjalne zastosowanie w swoim przypadku użycia.

Tokeny i rekordy wykorzystania: jaki jest między nimi związek?

Każde urządzenie może przechowywać do 500 tokenów na witrynę najwyższego poziomu i wydawcę. Każdy token ma też metadane informujące, którego klucza użył wystawca do jego wydania. Te informacje mogą pomóc w podjęciu decyzji, czy wykorzystać token podczas procesu wykorzystywania. Dane PST są przechowywane wewnętrznie przez przeglądarkę na urządzeniu użytkownika i dostęp do nich można uzyskać tylko za pomocą interfejsu PST API.

Gdy token zostanie wykorzystany, na urządzeniu zostanie zapisany rekord wykorzystania (RR). Ten obszar pamięci służy jako pamięć podręczna na potrzeby przyszłych wykorzystań. Obowiązuje limit 2 wykorzystań tokenów co 48 godzin na urządzenie, stronę i wydawcę. Nowe wywołania wykorzystujące środki będą w miarę możliwości korzystać z zapisanych w pamięci podręcznej RR, zamiast wysyłać żądanie do wystawcy.

1. Wydawane są nowe tokeny (maksymalnie 500 na wydawcę, witrynę i urządzenie).
2. Wszystkie tokeny są przechowywane w magazynie tokenów na urządzeniu (podobnie jak pliki cookie).
3. Jeśli nie znajdziemy aktywnego RR, nowe RR można wygenerować po wydaniu (maksymalnie 2 co 48 godzin).
4. Rekordy zasobów są uznawane za aktywne do momentu wygaśnięcia i będą używane jako pamięć podręczna lokalna.
5. Nowe wywołania wykorzystania będą trafiać do lokalnej pamięci podręcznej (nie będą generowane nowe RR).

Po zdefiniowaniu przypadku użycia musisz dokładnie określić okres ważności RR, ponieważ będzie on decydował o tym, ile razy będziesz mógł ich użyć w swoim przypadku.

Zanim określisz strategię, zapoznaj się z tymi kluczowymi zachowaniami i zmiennymi:

Przykładowe scenariusze

Scenariusz 1. Okres ważności RR jest krótszy niż 24 godziny (t=t), a wykorzystanie następuje wielokrotnie w ciągu 48 godzin.

Scenariusz 2. Okres ważności RR wynosi 24 godziny, a wykorzystanie następuje wielokrotnie w ciągu 48 godzin.

Scenariusz 3. Okres ważności RR wynosi 48 godzin, a wykorzystanie następuje wielokrotnie w ciągu 48 godzin.

Uruchom wersję demonstracyjną

Zanim zaczniesz korzystać z PST, zalecamy zapoznanie się z wersją demonstracyjną.

Podczas przeprowadzania tej prezentacji przeglądarka używa serwerów wydawcy i odbiorcy wersji demonstracyjnej do udostępniania i wykorzystywania tokenów.

Kwestie techniczne

Aby demo działało jak najlepiej, wykonaj te czynności:

• Przed uruchomieniem Chrome z flagami zatrzymaj wszystkie instancje Chrome.
• Jeśli używasz komputera z systemem Windows, zapoznaj się z  tym przewodnikiem, aby dowiedzieć się, jak przekazywać parametry do pliku wykonywalnego Chrome.
• Otwórz Narzędzia deweloperskie w Chrome w sekcji Aplikacje > Pamięć > Tokeny stanu prywatnego podczas korzystania z aplikacji demonstracyjnej, aby zobaczyć tokeny wydane lub wykorzystane przez wydawcę demonstracyjnego.

Konfigurowanie upowszechniania

W tej sekcji znajdziesz wymagania, które musisz spełnić, aby zostać emitentem lub podmiotem realizującym płatności za pomocą PST.

Zostań wydawcą

Wydawcy odgrywają kluczową rolę w PST. Przypisują one wartości do tokenów, aby określić, czy użytkownik jest botem. Jeśli chcesz zacząć korzystać z tokenów prywatności jako wydawca, musisz zarejestrować się, przechodząc proces rejestracji wydawcy.

Aby zgłosić się jako wydawca, operator witryny wydawcy musi otworzyć nowy problem w repozytorium GitHub, korzystając z szablonu „New PST Issuer” (Nowy wydawca PST). Postępuj zgodnie z instrukcjami w repozytorium, aby wypełnić zgłoszenie. Gdy punkt końcowy zostanie zweryfikowany, zostanie scalony z tym repozytorium, a infrastruktura po stronie serwera Chrome zacznie pobierać te klucze.

Serwery wystawcy

Wydawcy i osoby realizujące płatności to kluczowe podmioty w przypadku PST, a serwery i tokeny to kluczowe narzędzia. Podaliśmy już pewne szczegóły dotyczące tokenów i dokumentacji w GitHubie, ale chcieliśmy podać więcej informacji o serwerach PST. Aby zostać wydawcą PST, musisz najpierw skonfigurować serwer wydawania.

Wdrażanie środowiska: serwery wydawcy

Aby zaimplementować serwer wystawcy tokenów, musisz utworzyć własną aplikację po stronie serwera, która udostępnia punkty końcowe HTTP.

Komponent wydawcy składa się z 2 głównych modułów: (1) serwera wydawcy i (2) wydawcy tokenów.

Podobnie jak w przypadku wszystkich aplikacji internetowych zalecamy dodanie dodatkowej warstwy ochrony serwera wydawcy.

1. Serwer wydawcy: w naszej przykładowej implementacji serwer wydawcy to serwer Node.js, który korzysta z platformy Express do hostowania punktów końcowych HTTP wydawcy. Przykładowy kod znajdziesz na GitHubie.

2. Wystawca tokena: komponent kryptograficzny wystawcy nie wymaga żadnego konkretnego języka, ale ze względu na wymagania dotyczące wydajności tego komponentu podajemy jako przykład implementację w języku C, która do zarządzania tokenami używa biblioteki BoringSSL. Przykład kodu wydawcy i więcej informacji o instalacji znajdziesz na GitHubie

3. Klucze: komponent wystawcy tokena używa niestandardowych kluczy EC do szyfrowania tokenów. Te klucze muszą być chronione i przechowywane w bezpiecznym miejscu.

Wymagania techniczne dotyczące serwerów wydawcy

Zgodnie z protokołem na serwerze wydawcy musisz zaimplementować co najmniej 2 punkty końcowe HTTP:

• Zobowiązanie klucza (np. /.well-known/private-state-token/key-commitment): w tym punkcie końcowym przeglądarki będą mogły uzyskać szczegóły klucza publicznego szyfrowania, aby potwierdzić, że serwer jest legalny.
  • Przykładowy kod w GitHubie
  • Zobacz prezentację
• Wydawanie tokenów (np. /.well-known/private-state-token/issuance): punkt końcowy wydawania tokenów, w którym będą obsługiwane wszystkie żądania tokenów. Ten punkt końcowy będzie punktem integracji komponentu wystawcy tokena.
  • Przykładowy kod w GitHubie
  • Zobacz prezentację

Jak wspomnieliśmy wcześniej, ze względu na spodziewany duży ruch, który będzie obsługiwać ten serwer, zalecamy wdrożenie go przy użyciu skalowalnej infrastruktury (np. w środowisku chmurowym), aby móc dostosowywać backend do zmiennego popytu.

Wysyłanie połączenia na serwer wydawcy

Zaimplementuj w swoim stosie wydawcy wywołanie pobierania z witryny, aby wydawać nowe tokeny.

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

Zobacz przykładowy kod

Serwery realizujące

Musisz wdrożyć usługę wykorzystywania tokenów, tworząc własną aplikację po stronie serwera. Umożliwi to odczytywanie tokenów wysyłanych przez wydawcę. Z tych instrukcji dowiesz się, jak wykorzystać tokeny i jak odczytać powiązane z nimi zapisy wykorzystania.

Możesz uruchomić wystawcę i odbiorcę na tym samym serwerze (lub grupie serwerów).

Wymagania techniczne dotyczące serwerów realizujących

Zgodnie z protokołem na serwerze realizującym musisz zaimplementować co najmniej 2 punkty końcowe HTTP:

• /.well-known/private-state-token/redemption: punkt końcowy, w którym będzie obsługiwane wykorzystywanie wszystkich tokenów. Ten punkt końcowy będzie miejscem, w którym zostanie zintegrowany komponent do wykorzystywania tokenów.
  • Przykładowy kod na GitHubie
  • Prezentacja

Wysyłanie połączenia do serwera realizującego

Aby wykorzystać tokeny, musisz wdrożyć w swoim stosie narzędzi do wykorzystywania tokenów wywołanie pobierania z witryny, aby wykorzystać wcześniej wydane tokeny.

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

Zobacz przykładowy kod.

Po wykorzystaniu tokena możesz wysłać rekord wykorzystania (RR), wykonując kolejne wywołanie pobierania:

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

Zobacz przykładowy kod.

Wdrażanie implementacji

Aby przetestować wdrożenie, najpierw przejdź na stronę internetową, na której jest wykonywane wywołanie, i upewnij się, że tokeny są tworzone zgodnie z Twoją logiką. Sprawdź na backendzie, czy połączenia zostały wykonane zgodnie ze specyfikacją. Następnie otwórz stronę internetową, na której jest wykonywane wywołanie wykorzystania, i sprawdź, czy zgodnie z Twoją logiką utworzono RR.

Wdrożenie w świecie rzeczywistym

Zalecamy wybieranie witryn docelowych, które są częścią konkretnego przypadku użycia:

• Niewielka liczba wizyt miesięcznie (ok. <1 mln wizyt miesięcznie): zacznij od wdrożenia interfejsu API w przypadku niewielkiej grupy odbiorców.
• Masz nad nim kontrolę: w razie potrzeby możesz szybko wyłączyć wdrożenie bez konieczności uzyskiwania skomplikowanych zgód.
• Nie więcej niż 1 wydawca: aby ograniczyć liczbę tokenów i uprościć testowanie.
• Nie więcej niż 2 osoby korzystające z kodu: musisz uprościć rozwiązywanie problemów w razie ich wystąpienia.

Zasady dotyczące uprawnień

Aby interfejs PST API działał prawidłowo, musi być dostępny na stronie najwyższego poziomu i we wszystkich zasobach podrzędnych, które go używają.

Operacja żądania tokena jest kontrolowana przez dyrektywę private-state-token-issuance. Operacje token-redemption i send-redemption-record są kontrolowane przez dyrektywę private-state-token-redemption. W Chrome 132 i nowszych wersjach lista dozwolonych dla tych dyrektyw jest domyślnie ustawiona na * (wszystkie źródła). Oznacza to, że funkcja jest dostępna na stronie najwyższego poziomu, w elementach iframe z tej samej domeny i w elementach iframe z różnych domen bez wyraźnego przekazywania uprawnień.

Możesz zrezygnować z wydawania lub wykorzystywania tokenów PST na określonych stronach witryny, umieszczając private-state-token-issuance=() i private-state-token-redemption=() w nagłówku Permissions-Policy na każdej stronie.

Możesz też użyć nagłówka Permissions-Policy, aby kontrolować dostęp innych firm do PST. Jako parametry listy źródeł nagłówka użyj znaku self i wszystkich źródeł, którym chcesz zezwolić na dostęp do interfejsu API. Aby na przykład całkowicie wyłączyć korzystanie z PST we wszystkich kontekstach przeglądania z wyjątkiem własnego źródła i https://example.com, ustaw te nagłówki odpowiedzi HTTP:

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

Aby włączyć interfejs API dla wszystkich zasobów z innych domen, ustaw listę domen na *.

Dowiedz się, jak kontrolować funkcje Privacy Sandbox za pomocą zasady uprawnień, lub poznaj zasadę uprawnień.

Rozwiązywanie problemów

Możesz sprawdzać PST na kartach Sieć i Aplikacja w Narzędziach deweloperskich w Chrome.

Na karcie Sieć:

Na karcie Aplikacja:

Dowiedz się więcej o tej integracji z Narzędziami deweloperskimi.

Sprawdzone metody dotyczące klientów

Jeśli krytyczne funkcje Twojej witryny zależą od określonych wystawców tokenów, nadaj im priorytet. Zanim załadujesz inne skrypty, wywołaj funkcję hasPrivateToken(issuer) dla tych preferowanych wydawców. Jest to kluczowe, aby zapobiec potencjalnym problemom z wykorzystaniem.

Liczba wydawców na najwyższym poziomie jest ograniczona do 2, a skrypty innych firm mogą też próbować wywoływać funkcję hasPrivateToken(issuer), aby nadać priorytet preferowanym przez siebie wydawcom. Zabezpiecz więc z wyprzedzeniem najważniejszych wystawców, aby mieć pewność, że Twoja witryna działa zgodnie z oczekiwaniami.

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

Sprawdzone metody dotyczące serwera i rozwiązywanie problemów

Aby serwer wydawcy i serwer odbiorcy działały efektywnie, zalecamy wdrożenie tych sprawdzonych metod, które pozwolą uniknąć problemów z dostępem, bezpieczeństwem, rejestrowaniem i ruchem w przypadku PST.

• Punkty końcowe muszą stosować silne szyfrowanie przy użyciu protokołu TLS w wersji 1.3 lub 1.2.
• Infrastruktura musi być gotowa na obsługę zmiennych ilości ruchu (w tym nagłych wzrostów).
• Zadbaj o ochronę i bezpieczeństwo kluczy zgodnie z zasadami kontroli dostępu, strategią zarządzania kluczami i planami ciągłości działania.
• Dodaj do swojego stosu wskaźniki dostrzegalności, aby po wdrożeniu na środowisko produkcyjne mieć wgląd w użytkowanie, wąskie gardła i problemy z wydajnością.

Więcej informacji

1. Zapoznaj się z dokumentacją dla deweloperów:
   1. Zacznij od przeczytania omówienia, aby zapoznać się z PST i jego możliwościami.
   2. Obejrzyj film wprowadzający do PST.
   3. Wypróbuj wersję demonstracyjną PST.
   4. Przeczytaj też wyjaśnienie interfejsu API, aby dowiedzieć się więcej szczegółów na jego temat.
   5. Dowiedz się więcej o obecnej specyfikacji interfejsu API.
2. Dołącz do dyskusji, korzystając z problemów w GitHubie lub połączeń W3C.
3. Aby lepiej zrozumieć terminologię, zapoznaj się z słowniczkiem Piaskownicy prywatności.
4. Aby dowiedzieć się więcej o koncepcjach związanych z Chrome, takich jak „testowanie origin” czy „flagi Chrome”, obejrzyj krótkie filmy i przeczytaj artykuły dostępne na stronie goo.gle/cc.