Gizlilik Jetonları geliştirici kılavuzu

Geçmişte üçüncü taraf çerezleri, kullanıcının durumuyla ilgili bilgileri (ör. oturum açma durumu, kullandığı cihazla ilgili bilgiler veya bilinen ve güvenilir olup olmadığı) depolamak ve iletmek için kullanılıyordu. Örneğin, kullanıcının TOA ile giriş yapıp yapmadığı, belirli bir uyumlu cihaz türüne sahip olup olmadığı veya bilinen ve güvenilir bir kullanıcı olup olmadığı. Üçüncü taraf çerez desteğinin kullanımdan kaldırılmasıyla bu kullanım alanlarının çoğunun başka yöntemlerle desteklenmesi gerekecek.

Gizli durum jetonları, web'de bilgi paylaşmanın bir yolunu sunar ancak paylaşılabilen gerçek veri miktarıyla ilgili denetimler sayesinde gizliliği korur.

Gizli Durum Jetonları (eski adıyla Güven Jetonları), kullanıcının kimliğine duyulan güvenin bir bağlamdan diğerine aktarılmasına olanak tanır. Ayrıca, sitelerin pasif izleme olmadan sahtekarlıkla mücadele etmesine ve botları gerçek kullanıcılardan ayırt etmesine yardımcı olur.

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

Gizlilik Jetonları nasıl çalışır?

PST'de anlaşılması gereken en önemli ilişki, kart verenler ile kart kullananlar arasındaki ilişkidir. Kartı veren ve kullanan aynı şirkette olabilir.

• Kullanıcı kimliği verenler: Bu varlıklar, bir kullanıcıyla ilgili bir sinyale (ör. kullanıcının bot olup olmadığı) sahiptir ve bu sinyali kullanıcı cihazında depolanan bir jetona yerleştirir (daha fazla bilgi için sonraki bölümlere bakın).
• Kullanıcı kimliğini doğrulayanlar: Bu tüzel kişiler bir kullanıcıyla ilgili sinyal almamış olabilir ancak kullanıcı hakkında bilgi edinmesi (ör. kullanıcının bot olup olmadığını öğrenmesi) ve kullanıcının güvenilirliğini anlamak için sağlayıcıdan jeton kullanması gerekir.

Her PST etkileşimi, sağlayıcıların ve kullanıcıların web'de sinyal paylaşmak için birlikte çalışmasını gerektirir. Bu sinyaller, kullanıcıları tanımlayacak kadar ayrıntılı olmayan kaba değerlerdir.

Gizlilik jetonları benim için uygun mu?

Güven kararları alan ve bu bilgilerin farklı bağlamlarda kullanılmasını 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.

Jeton kullanma ve kullanma

PST'nin uygulanması üç aşamada gerçekleşir:

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

İlk aşamada, jetonlar bir tarayıcıya verilir (genellikle bir tür doğrulama işleminden sonra). İkinci aşamada, başka bir öğe, bu öğedeki değeri okumak için verilen jetonu kullanma isteği gönderir. Son aşamada, jetonu kullanan taraf, jetonda bulunan değeri içeren bir kullanım kaydı (RR) alır. Bu kullanıcı, bu kaydı çeşitli amaçlarla kullanıcının onay belgesi olarak kullanabilir.

Jeton 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ızdaki 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 ihraççı başına en fazla 500 jeton saklayabilir. Ayrıca her jetonda, jetonu veren tarafın jetonu vermek için hangi anahtarı kullandığını bildiren meta veriler bulunur. Bu bilgiler, jeton kullanma işlemi sırasında jetonu kullanıp kullanmayacağınıza 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 depolanır. Bu depolama alanı, gelecekteki teklifler için önbelleğe alınmış olarak kullanılır. Cihaz, sayfa ve ihraç eden başına 48 saatte iki jeton kullanma sınırı vardır. Yeni kullanım çağrıları, mümkün olduğunda yayıncıdan istek yerine önbelleğe alınmış RR'leri kullanır.

1. Yeni jetonlar verilir (her sağlayıcı, site ve cihaz için en fazla 500).
2. Tüm jetonlar cihaz üzerinde jeton deposunda (çerez deposuna benzer) depolanır.
3. Etkin RR bulunamazsa yayından sonra yeni RR'ler oluşturulabilir (48 saatte en fazla 2).
4. RR'ler, geçerlilik süreleri dolana kadar etkin olarak kabul edilir ve yerel önbellek olarak kullanılır.
5. Yeni teklif kullanma çağrıları yerel önbelleğe ulaşır (yeni RR oluşturulmaz).

Kullanım alanınızı tanımladıktan sonra, RR'lerinizin kullanım süresini dikkatlice belirlemeniz gerekir. Bu, kullanım alanınızda bunları kaç kez kullanabileceğinizi belirler.

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

Örnek senaryolar

1. senaryo: RR ömrü 24 saatten kısa (t=t) ve teklifin kullanılması 48 saatlik süre içinde birden fazla kez gerçekleştirilir.

2. senaryo: RR'nin geçerlilik süresi 24 saat ve teklifin kullanılması 48 saatlik süre içinde birden fazla kez gerçekleştirilir.

Senaryo 3: RR kullanım süresi 48 saat'tir ve teklifin kullanılması 48 saatlik süre içinde birden çok kez gerçekleştirilir.

Demoyu çalıştırma

PST'yi kullanmaya başlamadan önce demoyu ayarlamanızı öneririz. PST demosunu denemek için Chrome'u , demo veren anahtar taahhütlerini etkinleştirmek üzere işaretlerle çalıştırmanız gerekir (demo sayfasında bulunan talimatları uygulayın).

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

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

Demoyu en iyi şekilde çalıştırmak için aşağıdaki adımları uygulayın:

• Chrome'u işaretlerle çalıştırmadan önce tüm Chrome örneklerini durdurduğunuzdan emin olun.
• Windows makine kullanıyorsanız Chrome yürütülebilir ikilisine parametre geçirme hakkındaki bu kılavuzu inceleyin.
• Demo sağlayıcı tarafından verilen/kullanılan jetonları görmek için demo uygulamasını kullanırken Uygulamalar > Depolama > Gizli Durum Jetonları bölümünde Chrome Geliştirici Araçları'nı açın.

Benimseme için ayarlama

Kart veren kuruluş olma

Düzenleyenler, PST'de önemli bir rol oynar. Kullanıcının bot olup olmadığını belirlemek için jetonlara değer atar. PST'yi veren kurum olarak kullanmak istiyorsanız veren kurum kayıt sürecini tamamlayarak kaydolmanız gerekir.

Kart veren olmak için başvuruda bulunmak isteyen kart veren web sitesinin operatörü, "Yeni PST Kart Vereni" şablonunu kullanarak GitHub deposunda yeni bir sorun açmalıdır. Sorunu doldurmak için depoda verilen talimatları uygulayın. Doğrulanan uç noktalar bu depoyla birleştirilir ve Chrome sunucu tarafı altyapısı bu anahtarları getirmeye başlar.

Düzenleyen sunucuları

PST'nin temel aktörleri, verenler ve kullananlar; temel araçları ise sunucular ve jetonlardır. Jetonlar ve GitHub dokümanları hakkında bazı ayrıntıları daha önce paylaşmıştık. Şimdi de PST sunucuları hakkında daha fazla bilgi vermek istiyoruz. PST'nin sağlayıcısı olarak ayarlanabilmek için öncelikle bir sağlayıcı sunucusu oluşturmanız gerekir.

Ortamınızı dağıtma: Issuer sunucuları

Jeton veren sunucuyu uygulamak için HTTP uç noktalarını gösteren kendi sunucu tarafı uygulamanızı oluşturmanız gerekir.

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

Web'e açık tüm uygulamalarda olduğu gibi, sağlayıcı sunucunuza ek bir koruma katmanı eklemenizi öneririz.

1. Yayınlayan sunucusu: Örnek uygulamamızda, yayınlayan sunucumuz, yayınlayan HTTP uç noktalarını barındırmak için Express çerçevesini kullanan bir Node.js sunucusu. GitHub'daki örnek koda göz atabilirsiniz.

2. Jeton veren: Yayıncı şifreleme bileşeni için belirli bir dil gerekmez ancak bu bileşenin performans gereksinimleri nedeniyle, jetonları yönetmek için BoringSSL kitaplığını kullanan bir C uygulaması örneği sunuyoruz. Düzenleyen kodu örneğini ve kurulum hakkında daha fazla bilgiyi GitHub'da bulabilirsiniz.

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

Sertifika veren sunucular için teknik koşullar

Protokole göre, sağlayıcı sunucunuzda en az iki HTTP uç noktası uygulamanız gerekir:

• Anahtar taahhüt (örneğin, /.well-known/private-state-token/key-commitment): Bu uç noktada, şifreleme ortak anahtar ayrıntılarınız tarayıcılar tarafından sunucunuzun meşru olduğunu doğrulamak için kullanılabilir.
  • Örnek kod
• Jeton verme (örneğin, /.well-known/private-state-token/issuance): Tüm jeton isteklerinin işlendiği jeton verme uç noktası. Bu uç nokta, jeton veren bileşeninin entegrasyon noktası olacaktır.
  • Örnek kod

Daha önce de belirtildiği gibi, bu sunucunun olası yüksek trafiği işlemesi nedeniyle arka uç sunucunuzu değişken talebe göre ayarlayabilmek için ölçeklenebilir bir altyapı (ör. bulut ortamında) kullanarak dağıtmanızı öneririz.

Issuer sunucusuna çağrı gönderme

Yeni jetonlar yayınlamak için kart kuruluşu yığınınıza 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, bir sağlayıcının 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üzenleyeni ve kullananı aynı sunucuda (veya sunucu grubunda) çalıştırmayı seçebilirsiniz.

Kodu kullanan sunucular için teknik koşullar

Protokole göre, kod kullanacak kullanıcı sunucunuz için en az iki HTTP uç noktası uygulamanız gerekir:

• /.well-known/private-state-token/redemption: Tüm jetonların kullanılacağı uç nokta. Bu uç nokta, jetonu kullanan bileşenin entegre edileceği yerdir.
  • Örnek kod

Kodu kullanan sunucuya çağrı gönderme

Daha önce verilen jetonları kullanmak için jetonu kullanan 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 göre oluşturulduğunu onaylayın. Arka uçta, aramaların spesifikasyona uygun şekilde yapıldığını doğrulayın. Ardından, kod kullanma aramasının yapıldığı web sayfasına gidin ve mantığınıza göre RR'lerin oluşturulduğunu onaylayın.

Gerçek hayatta dağıtım

Belirli kullanım alanınızda yer alan web sitelerini hedeflemenizi öneririz:

• Aylık ziyaret sayısı az (< 1 milyon ziyaret/ay): API'yi önce küçük bir kitleye dağıtarak başlamanız gerekir.
• Sahipliğiniz ve kontrolünüz altındadır: Gerekirse karmaşık onaylar olmadan uygulamayı hızlıca devre dışı bırakabilirsiniz
• En fazla bir sağlayıcı: Testi basitleştirmek için jeton miktarını sınırlamak amacıyla.
• En fazla iki kullanıcının kullanabileceği kodlar: Sorun olması durumunda sorun giderme işlemini basitleştirmeniz gerekir.

İzin politikası

PST API'nin düzgün çalışması için üst düzey sayfanın ve API'yi kullanan tüm alt kaynakların erişimine açık 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 direktifi tarafından kontrol edilir. Chrome 132 ve sonraki sürümlerde bu yönergelerin izin verilenler listesi varsayılan olarak * (tüm kaynaklar) olarak ayarlanır. Bu, özelliğin üst düzey sayfa, aynı kaynaklı iframe'ler ve açık yetkilendirme olmadan kaynaklar arası iframe'ler tarafından 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 yayınlamayı veya kullanmayı devre dışı bırakabilirsiniz.

PST'ye üçüncü taraf erişimini kontrol etmek için Permissions-Policy üstbilgisini de kullanabilirsiniz. Başlık kaynağı listesi parametreleri olarak self ve API'ye erişmesine izin vermek istediğiniz tüm kaynakları kullanın. Örneğin, kendi kaynağınız ve https://example.com hariç 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 kaynaktan kaynakta kaynakları için etkinleştirmek üzere kaynak listesini * olarak ayarlayın.

Gizlilik korumalı alan özelliklerini izin politikasıyla nasıl kontrol edeceğinizi öğrenin veya izin politikasını daha ayrıntılı bir şekilde inceleyin.

Sorun giderme

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

Ağ sekmesinde:

Başvuru sekmesinde:

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

İstemcilerle ilgili en iyi uygulamalar

Web sitenizin kritik işlevleri belirli jeton sağlayıcılara bağlıysa bu sağlayıcılara öncelik verin. Diğer komut dosyalarını yüklemeden önce bu tercih edilen sağlayıcılar için hasPrivateToken(issuer)'ü arayın. Bu, olası kullanım hatalarını önlemek için çok önemlidir.

Üst düzey başına kart veren sayısı iki ile sınırlıdır. Üçüncü taraf komut dosyaları da kendi tercih ettikleri kart verenlere öncelik vermek için hasPrivateToken(issuer)'yi çağırmayı deneyebilir. Bu nedenle, sitenizin beklendiği gibi çalıştığından emin olmak için temel sağlayıcılarınızın güvenliğini önceden sağlayı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).

Sunucu en iyi uygulamaları ve sorun giderme

Kart veren ve kart kullanan sunucunuzun etkili bir şekilde çalışması için PST ile ilgili erişim, güvenlik, günlük kaydı veya trafik sorunlarına karşılaşmamak üzere aşağıdaki en iyi uygulamaları uygulamanızı öneririz.

• Bitiş noktalarınız, TLS 1.3 veya 1.2'yi kullanarak güçlü kriptografi 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 Denetimi Politikanız, Anahtar Yönetimi Stratejiniz ve İş Sürekliliği Planlarınızla uyumlu şekilde korunduğundan ve güvenli olduğundan emin olun.
• Üretime geçtikten sonra kullanım, darboğazlar ve performans sorunlarını anlamak için görünürlüğe sahip olmanız amacıyla yığını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. Ayrıca, API hakkında daha fazla bilgi edinmek için API açıklamasını da okuyun.
   5. API'nin mevcut spesifikasyonu hakkında daha fazla bilgi edinin.
2. GitHub sorunları veya W3C toplantıları aracılığıyla sohbete katkıda bulunabilirsiniz.
3. Terminolojiyi daha iyi anlamak için Özel Korumalı Alan terimleri sözlüğünü inceleyin.
4. "Kaynak denemesi" veya "Chrome işaretleri" gibi Chrome kavramları hakkında daha fazla bilgi edinmek için goo.gle/cc adresindeki kısa videoları ve makaleleri inceleyin.