Gizlilik Jetonları geliştirici kılavuzu

Geçmişte, kullanıcının durumuyla ilgili bilgileri (ör. oturum açma durumu, kullandığı cihazla ilgili bilgiler veya kullanıcının tanınıp tanınmadığı ve güvenilir olup olmadığı) depolamak ve aktarmak için üçüncü taraf çerezleri kullanılıyordu. Örneğin, kullanıcının TOA ile giriş yapıp yapmadığı, belirli bir türde uyumlu cihazının olup olmadığı veya kullanıcının tanınıp güvenilip güvenilmediği. Üçüncü taraf çerez desteği kullanımdan kaldırıldığından, bu kullanım alanlarının çoğu başka yollarla desteklenmelidir.

Private State Tokens, web'de bilgi paylaşmanın bir yolunu sunar ancak gerçekte paylaşılabilecek veri miktarı üzerindeki kontroller aracılığıyla gizliliği koruyacak şekilde bilgi paylaşmanıza olanak tanır.

Özel durum jetonları (eski adıyla güven jetonları), kullanıcının gerçekliğine duyulan güvenin bir bağlamdan diğerine aktarılmasına olanak tanır. Bu sayede siteler, pasif izleme olmadan sahtekarlıkla mücadele edebilir ve botları gerçek kullanıcılardan ayırt edebilir.

Bu belgede, Gizlilik Jetonları'nın (PST) uygulanmasıyla ilgili teknik ayrıntılar açıklanmaktadır. Daha üst düzey bir özet için PST'ye genel bakış başlıklı makaleyi inceleyin.

Private State Tokens'ın işleyiş şekli

PST'de anlaşılması gereken temel ilişki, verenler ve kullananlar arasındadır. Verenler ve kullananlar aynı şirkette olabilir.

• Verenler: Bu tüzel kişiler, bir kullanıcı hakkında bazı sinyallere sahiptir (ör. kullanıcının bot olup olmadığı) ve bu sinyali, kullanıcı cihazında depolanan bir jetona yerleştirir (sonraki bölümlerde daha fazla ayrıntı verilmiştir).
• Kullanıcılar: Bu kuruluşlar, kullanıcı hakkında bir sinyale sahip olmayabilir ancak kullanıcı hakkında bir şeyler bilmesi (ör. kullanıcının bot olup olmadığı) gerekir ve kullanıcının güvenilirliğini anlamak için yayınlayandan bir jeton kullanmasını ister.

Her PST etkileşimi, verenlerin ve kullananların web'deki sinyalleri paylaşmak için birlikte çalışmasını gerektirir. Bu sinyaller, kişileri tanımlayacak kadar ayrıntılı olmayan kaba değerlerdir.

Gizlilik Jetonları benim için doğru tercih mi?

Güvenle ilgili kararlar veren ve bu bilgilerin bağlamlar arasında kullanılabilmesini isteyen şirketler PST'lerden yararlanabilir. PST'lerin olası kullanım alanları hakkında daha fazla bilgi için PST kullanım alanları ile ilgili dokümanlarımıza göz atın.

Jetonları verme ve kullanma

PST uygulaması üç aşamada gerçekleşir:

1. Jeton verme
2. Jeton kullanma
3. Kullanım kaydı yönlendirme

İlk aşamada, tarayıcıya jeton verilir (genellikle bir tür doğrulama işleminden sonra). İkinci aşamada, başka bir tüzel kişi, jetonun değerini okumak için verilmiş olan jetonu kullanma isteğinde bulunur. Son aşamada, kuponu kullanan taraf, jetonda bulunan değeri içeren bir kupon kullanma kaydı (RR) alır. Bu durumda, kuponu kullanan taraf, bu kaydı çeşitli amaçlarla kullanıcının onay belgesi olarak kullanabilir.

Token stratejinizi tanımlama

Jeton stratejinizi tanımlamak için PST'nin temel kavramlarını (jetonlar ve kullanım kayıtları), değişkenlerini, davranışlarını ve sınırlamalarını anlamanız gerekir. Böylece, kullanım alanınızda potansiyel kullanımlarını düşünebilirsiniz.

Jetonlar ve kullanım kayıtları: Aralarındaki ilişki nedir?

Her cihaz, üst düzey web sitesi ve veren başına en fazla 500 jeton saklayabilir. Ayrıca, her jetonun, veren tarafın jetonu vermek için hangi anahtarı kullandığını belirten meta verileri vardır. Bu bilgiler, kullanma işlemi sırasında jetonun kullanılıp kullanılmayacağına karar vermek için kullanılabilir. PST verileri, tarayıcı tarafından kullanıcının cihazında dahili olarak depolanır ve yalnızca PST API'si tarafından erişilebilir.

Bir jeton kullanıldığında, Kullanım Kaydı (RR) cihazda saklanır. Bu depolama alanı, gelecekteki kullanımlar için önbellek görevi görür. Cihaz, sayfa ve veren başına 48 saatte iki jeton kullanma sınırı vardır. Yeni ödeme isteği çağrıları, mümkün olduğunda veren kuruluşa istek göndermek yerine önbelleğe alınmış RR'leri kullanır.

1. Yeni jetonlar verilir (düzenleyen kuruluş, site ve cihaz başına en fazla 500).
2. Tüm jetonlar cihaz üzerinde jeton deposunda (çerez deposuna benzer) saklanır.
3. Etkin bir RR bulunamazsa düzenlendikten sonra yeni RR'ler oluşturulabilir (48 saatte en fazla 2 tane).
4. RR'ler geçerlilik süresi dolana kadar etkin olarak kabul edilir ve yerel önbellek olarak kullanılır.
5. Yeni kullanım çağrıları yerel önbelleğe ulaşır (yeni RR'ler oluşturulmaz).

Kullanım alanınızı tanımladıktan sonra, RR'nizin kullanım ömrünü dikkatli bir şekilde tanımlamanız gerekir. Bu, RR'leri kullanım alanınızda kaç kez kullanabileceğinizi belirleyecektir.

Stratejinizi tanımlamadan önce aşağıdaki önemli davranışları ve değişkenleri anladığınızdan emin olun:

Örnek senaryolar

1. Senaryo: RR'nin kullanım süresi 24 saatten kısadır (t=t) ve 48 saatlik süre içinde birden fazla kez kullanılabilir.

2. senaryo: RR'nin kullanım süresi 24 saattir ve 48 saatlik süre içinde birden fazla kez kullanılır.

3. senaryo: RR'nin kullanım süresi 48 saattir ve 48 saatlik süre içinde birden fazla kez kullanılır.

Demoyu çalıştırma

PST'yi kullanmaya başlamadan önce demoyu kullanmanızı öneririz.

Bu demoyu çalıştırdığınızda tarayıcınız, jeton sağlamak ve kullanmak için demo veren ve demo kullanan sunucularını kullanır.

Göz önünde bulundurulması gereken teknik hususlar

Aşağıdaki adımları uyguladığınızda demo en iyi şekilde çalışır:

• Chrome'u flag'lerle çalıştırmadan önce tüm Chrome örneklerini durdurduğunuzdan emin olun.
• Windows makinede çalışıyorsanız Chrome yürütülebilir ikilisine parametreleri nasıl ileteceğinizle ilgili bu kılavuza göz atın.
• Demo yayıncı tarafından verilen veya kullanılan jetonları görmek için demo uygulamasını kullanırken Uygulamalar > Depolama > Özel Durum Jetonları bölümünde Chrome Geliştirici Araçları'nı açın.

Benimsenmeye hazırlama

Bu bölümde, PST ihraç eden veya kullanan kuruluş olmak için gereken şartlar açıklanmaktadır.

Veren kuruluş olma

Kart verenler, PST'de önemli bir rol oynar. Kullanıcının bot olup olmadığını belirlemek için jetonlara değer atarlar. PST'yi sağlayıcı olarak kullanmaya başlamak istiyorsanız Sağlayıcı kayıt sürecini tamamlayarak kaydolmanız gerekir.

Kart veren olmak için başvuruda bulunmak isteyen kart veren web sitesinin operatörü, "New PST Issuer" şablonunu kullanarak GitHub deposunda yeni bir issue açmalıdır. Sorunu doldurmak için depodaki yönergeleri uygulayın. Bir uç nokta doğrulandıktan sonra bu depoya birleştirilir ve Chrome sunucu tarafı altyapısı bu anahtarları getirmeye başlar.

Düzenleyen sunucuları

PST'nin temel aktörleri veren kuruluşlar ve kullanıcılardır. PST'nin temel araçları ise sunucular ve jetonlardır. Jetonlar ve GitHub dokümanları hakkında bazı bilgiler paylaşmış olsak da PST sunucuları hakkında daha fazla bilgi vermek istiyoruz. PST yayıncısı olarak ayarlanmak için öncelikle bir yayın sunucusu ayarlamanız gerekir.

Ortamınızı dağıtma: kart veren sunucuları

Jeton veren sunucuyu uygulamak için HTTP uç noktalarını kullanıma sunan kendi sunucu tarafı uygulamanızı oluşturmanız gerekir.

Yayınlayan bileşeni iki ana modülden oluşur: (1) yayınlayan sunucusu ve (2) jeton yayınlayan.

Web'e yönelik tüm uygulamalarda olduğu gibi, veren sunucunuza ek bir koruma katmanı uygulamanızı öneririz.

1. Düzenleyen sunucu: Örnek uygulamamızda, düzenleyen sunucumuz, Düzenleyen HTTP uç noktalarını barındırmak için Express çerçevesini kullanan bir Node.js sunucusudur. GitHub'daki örnek koda göz atabilirsiniz.

2. Jetonu veren: Jetonu veren şifreleme bileşeni herhangi bir dil gerektirmez ancak bu bileşenin performans gereksinimleri nedeniyle, jetonları yönetmek için BoringSSL kitaplığını kullanan bir C uygulaması örnek olarak verilmektedir. Düzenleyen kodu örneğini ve yükleme hakkında daha fazla bilgiyi GitHub'da bulabilirsiniz.

3. Anahtarlar: Jeton yayınlayan bileşen, jetonları şifrelemek için özel EC anahtarları kullanır. Bu anahtarlar korunmalı ve güvenli depolama alanında saklanmalıdır.

Kartı veren kuruluş sunucularıyla ilgili teknik koşullar

Protokole göre, veren sunucunuzda en az iki HTTP uç noktası uygulamanız gerekir:

• Anahtar taahhüdü (ör. /.well-known/private-state-token/key-commitment): Bu uç nokta, sunucunuzun meşru olduğunu doğrulamak için şifreleme ortak anahtarınızın ayrıntılarının tarayıcılarda kullanılabileceği yerdir.
  • GitHub'da kod örneği
  • Demoyu inceleyin.
• Jeton verme (örneğin, /.well-known/private-state-token/issuance): Tüm jeton isteklerinin işleneceği jeton verme uç noktası. Bu uç nokta, jeton veren bileşeni için entegrasyon noktası olacaktır.
  • GitHub'da kod örneği
  • Demoyu görüntüleyin.

Daha önce de belirtildiği gibi, bu sunucunun potansiyel olarak işleyeceği yüksek trafik nedeniyle, değişken talebe göre arka uç ayarlarınızı yapabilmek için ölçeklenebilir bir altyapı (örneğin, bir bulut ortamında) kullanarak dağıtmanızı öneririz.

Kartı veren kuruluşun sunucusuna çağrı gönderme

Yeni jetonlar yayınlamak için kart veren yığınına bir web sitesi getirme çağrısı uygulayın.

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

Kod örneğine bakın.

Redeemer sunucuları

Kendi sunucu tarafı uygulamanızı oluşturarak jeton kullanma hizmetini uygulamanız gerekir. Bu sayede, veren kuruluşun gönderdiği jetonları okuyabilirsiniz. Aşağıdaki adımlarda jetonların nasıl kullanılacağı ve bu jetonlarla ilişkili kullanım kayıtlarının nasıl okunacağı açıklanmaktadır.

Düzenleyen ve kullanıcının aynı sunucuda (veya sunucu grubunda) çalışmasını tercih edebilirsiniz.

Kullanıcı sunucularıyla ilgili teknik koşullar

Protokole göre, kupon kullanma sunucunuz için en az iki HTTP uç noktası uygulamanız gerekir:

• /.well-known/private-state-token/redemption: Tüm jeton kullanımlarının işleneceği uç nokta. Bu uç nokta, jeton kullanma bileşeninin entegre edileceği yerdir.
  • GitHub'da örnek kod
  • Demo

Kullanıcı sunucusuna bir çağrı gönderin.

Daha önce verilen jetonları kullanmak için, jetonları kullanacak yığınınıza bir web sitesi getirme çağrısı uygulamanız gerekir.

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

Kod örneğine bakın.

Bir jetonu kullandıktan sonra, başka bir getirme çağrısı yaparak kullanım kaydını (RR) gönderebilirsiniz:

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

Kod örneğine bakın.

Uygulamanızı dağıtma

Uygulamanızı test etmek için önce yayınlama çağrısının yapıldığı web sayfasına gidin ve jetonların mantığınıza uygun şekilde oluşturulduğunu onaylayın. Backend'inizde, aramaların spesifikasyona göre yapıldığını doğrulayın. Ardından, kullanma çağrısının yapıldığı web sayfasına gidin ve RR'lerin mantığınıza uygun şekilde oluşturulduğunu onaylayın.

Gerçek dünyada dağıtım

Belirli kullanım alanınızın bir parçası olan hedef web siteleri seçmenizi öneririz:

• Aylık ziyaretçi sayısının az olması (~ <1 milyon ziyaret/ay): API'yi önce küçük bir kitleye dağıtarak başlamalısınız.
• Size aittir ve kontrolü sizdedir: Gerekirse karmaşık onaylar olmadan uygulamayı hızlıca devre dışı bırakabilirsiniz.
• En fazla bir veren: Testi basitleştirmek için jeton miktarını sınırlamak amacıyla.
• İkiden fazla kullanıcının kullanmaması: Sorun olması durumunda sorun giderme sürecini basitleştirmeniz gerekir.

İzin politikası

PST API'nin düzgün çalışması için üst düzey sayfada ve API'yi kullanan tüm alt kaynaklarda kullanılabilir olması gerekir.

Jeton isteği işlemi, private-state-token-issuance yönergesiyle kontrol edilir. token-redemption ve send-redemption-record işlemleri private-state-token-redemption yönergesiyle kontrol edilir. Chrome 132 ve sonraki sürümlerde, bu yönergeler için izin verilenler listesi varsayılan olarak * (tüm kaynaklar) olarak ayarlanır. Bu, özelliğin üst düzey sayfada, aynı kaynaklı iframe'lerde ve açıkça yetki verilmemiş kaynaklar arası iframe'lerde kullanılabileceği anlamına gelir.

Her sayfanın Permissions-Policy başlığına private-state-token-issuance=() ve private-state-token-redemption=() ekleyerek sitenizdeki belirli sayfalar için PST jetonu verilmesini veya kullanılmasını devre dışı bırakabilirsiniz.

PST'ye üçüncü taraf erişimini kontrol etmek için Permissions-Policy üstbilgisini de kullanabilirsiniz. Başlık kaynağı listesinin parametreleri olarak self ve API'ye erişime izin vermek istediğiniz tüm kaynakları kullanın. Örneğin, kendi kaynağınız ve https://example.com dışında tüm tarama bağlamlarında PST kullanımını tamamen devre dışı bırakmak için aşağıdaki HTTP yanıt üst bilgilerini ayarlayın:

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

API'yi tüm kaynaklar arası kaynaklar için etkinleştirmek üzere kaynak listesini * olarak ayarlayın.

İzin politikasıyla Privacy Sandbox özelliklerini nasıl kontrol edeceğinizi öğrenin veya izin politikası hakkında daha fazla bilgi edinin.

Sorun giderme

PST'leri Chrome Geliştirici Araçları'nın Ağ ve Uygulama sekmelerinden inceleyebilirsiniz.

Ağ sekmesinde:

Uygulama sekmesinde:

Bu Geliştirici Araçları entegrasyonu hakkında daha fazla bilgi edinin.

İstemci ile ilgili en iyi uygulamalar

Web sitenizin kritik işlevleri belirli jeton verenlere bağlıysa bunlara öncelik verin. Diğer komut dosyalarını yüklemeden önce bu tercih edilen yayıncılar için hasPrivateToken(issuer) işlevini çağırın. Bu, olası kullanım hatalarını önlemek için çok önemlidir.

Üst düzey alan başına yayıncı sayısı ikiyle sınırlandırılır ve üçüncü taraf komut dosyaları, kendi tercih ettikleri yayıncılara öncelik vermek için hasPrivateToken(issuer) işlevini çağırmayı da deneyebilir. Bu nedenle, sitenizin beklendiği gibi çalıştığından emin olmak için önemli verenlerinizi önceden güvence altına alın.

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

Sunucuyla ilgili en iyi uygulamalar ve sorun giderme

Düzenleyen ve kullanıma sunan sunucunuzun etkili bir şekilde çalışması için PST ile ilgili erişim, güvenlik, günlük kaydı veya trafik sorunları yaşamamak üzere aşağıdaki en iyi uygulamaları uygulamanızı öneririz.

• Uç noktalarınız, TLS 1.3 veya 1.2 kullanarak güçlü şifreleme uygulamalıdır.
• Altyapınız, değişken trafik hacimlerini (ani artışlar dahil) işlemeye hazır olmalıdır.
• Anahtarlarınızın, Erişim Kontrolü Politikanız, Anahtar Yönetimi Stratejiniz ve İş Sürekliliği Planlarınızla uyumlu olacak şekilde korunup güvende olduğundan emin olun.
• Üretime geçtikten sonra kullanımı, darboğazları ve performans sorunlarını anlayabilmek için görünürlüğe sahip olacağınızdan emin olmak üzere yığınıza gözlemlenebilirlik metrikleri ekleyin.

Daha fazla bilgi

1. Geliştirici belgelerini inceleyin:
   1. PST ve özellikleri hakkında bilgi edinmek için genel bakış bölümünü okuyarak başlayın.
   2. PST tanıtım videosunu izleyin.
   3. PST demosunu deneyin.
   4. API hakkında daha fazla bilgi edinmek için API açıklayıcısını da okuyun.
   5. API'nin mevcut özellikleri hakkında daha fazla bilgi edinin.
2. GitHub sorunları veya W3C görüşmeleri ile sohbete katkıda bulunun.
3. Terminolojiyi daha iyi anlamak için Özel Korumalı Alan sözlüğünü inceleyin.
4. "Kaynak denemesi" veya "Chrome flags" gibi Chrome kavramları hakkında daha fazla bilgi edinmek için goo.gle/cc adresindeki kısa videoları ve makaleleri inceleyin.