Bu sayfa, Cloud Translation API ile çevrilmiştir.

FedCM güncellemeleri: Continuation API paketi ve Storage Access API otomatik izni için kaynak denemeleri

Eiji Kitamura

Geliştiriciler, Chrome 126'dan itibaren bazı Yetkilendirme kullanım alanlarını mümkün kılan bir masaüstü Federated Credential Management API (FedCM) özelliği paketi için kaynak deneme sürümünü çalıştırmaya başlayabilirler. Paket, Continuation API ve Parameters API'den oluşur. Bu API, kimlik sağlayıcı (IdP) tarafından sağlanan izin iletişim kutusunu içeren OAuth yetkilendirme akışına benzer bir deneyim sunar. Pakette Fields API, Birden çok configURL ve Özel Hesap Etiketleri gibi başka değişiklikler de bulunur. Chrome 126'dan itibaren, kullanıcının FedCM'yi kullanarak başarıyla giriş yapmış olması durumunda SAA isteklerini otomatik olarak veren Storage Access API (SAA) için bir kaynak denemesini de kullanıma sunuyoruz.

Kaynak Deneme: FedCM Continuation API paketi

FedCM Continuation API paketi, birden fazla FedCM uzantısından oluşur:

Continuation API
Parameters API
Fields API
Birden çok configURL
Özel Hesap Etiketleri

Continuation API'si

Bir kullanıcı, kısıtlanmış taraflarda oturum açıp düğme moduyla yetkilendiriyor.

Glitch'te API demosuna göz atabilirsiniz.

Continuation API, kullanıcının çok adımlı oturum açma akışına devam etmesine izin vermek için IdP'nin kimlik onayı uç noktasının isteğe bağlı olarak FedCM'nin oluşturacağı bir URL'yi döndürmesine olanak tanır. Bu, IdP'nin kullanıcıdan bağlı taraf (RP) için mevcut FedCM kullanıcı arayüzünde mümkün olanın ötesinde izinler (ör. kullanıcının sunucu tarafı kaynaklarına erişim) vermesini istemesine olanak tanır.

Genellikle kimlik onayı uç noktası, kimlik doğrulama için gereken jetonu döndürür.

{
  "token": "***********"
}

Bununla birlikte, Continuation API ile ID assertion uç noktası, mutlak yol veya kimlik onayı uç noktasına göreli bir yol içeren continue_on özelliğini döndürebilir.

{
  // In the id_assertion_endpoint, instead of returning a typical
  // "token" response, the IdP decides that it needs the user to
  // continue on a pop-up window:
  "continue_on": "/oauth/authorize?scope=..."
}

Tarayıcı continue_on yanıtını alır almaz yeni bir pop-up pencere açılır ve kullanıcıyı belirtilen yola yönlendirir.

Kullanıcı sayfayla etkileşimde bulunduktan sonra (örneğin, Kısıtlanmış Taraf ile ek bilgi paylaşmak için daha fazla izin verdikten sonra) IdP sayfası, orijinal navigator.credentials.get() çağrısını çözüme kavuşturmak için IdentityProvider.resolve() yöntemini çağırabilir ve bağımsız değişken olarak bir jeton döndürebilir.

document.getElementById('allow_btn').addEventListener('click', async () => {
  let accessToken = await fetch('/generate_access_token.cgi');
  // Closes the window and resolves the promise (that is still hanging
  // in the relying party's renderer) with the value that is passed.
  IdentityProvider.resolve(accessToken);
});

Ardından tarayıcı pop-up'ı kendiliğinden kapatır ve jetonu API arayana geri gönderir.

Kullanıcı isteği reddederse IdentityProvider.close() kodunu çağırarak pencereyi kapatabilirsiniz.

IdentityProvider.close();

Kullanıcı, herhangi bir nedenle pop-up'ta hesabını değiştirdiyse (örneğin, IdP'de "kullanıcı değiştir" işlevi veya yetki durumları söz konusuysa) çözümleme çağrısı, isteğe bağlı ikinci bir bağımsız değişkene tabi tutulur ve bu işleve aşağıdaki gibi bir olanak tanır:

IdentityProvider.resolve(token, {accountId: '1234');

Parametreler API'si

Parameters API, RP'nin kimlik onayı uç noktasına ek parametreler sağlamasına olanak tanır. Parametreler API'yi kullanarak RP'ler, temel oturum açmanın dışındaki kaynaklar için izin istemek amacıyla IdP'ye ek parametreler iletebilir. Kullanıcı bu izinleri Continuation API aracılığıyla başlatılan IdP tarafından kontrol edilen kullanıcı deneyimi akışı aracılığıyla yetkilendirir.

API'yi kullanmak için parametreleri navigator.credentials.get() çağrısında bir nesne olarak params özelliğine ekleyin.

let {token} = await navigator.credentials.get({
  identity: {
    providers: [{
      clientId: '1234',
      configURL: 'https://idp.example/fedcm.json',
      // Key/value pairs that need to be passed from the
      // RP to the IdP but that don't really play any role with
      // the browser.
      params: {
        IDP_SPECIFIC_PARAM: '1',
        foo: 'BAR',
        ETC: 'MOAR',
        scope: 'calendar.readonly photos.write',
      }
    },
  }
});

params nesnesindeki özellik adlarının başına param_ eklenir. Yukarıdaki örnekte, params özelliği '1' olarak IDP_SPECIFIC_PARAM, 'BAR' olarak foo, 'MOAR' olarak ETC ve 'calendar.readonly photos.write' olarak scope değerini içerir. Bu, isteğin HTTP gövdesinde param_IDP_SPECIFIC_PARAM=1&param_foo=BAR&param_ETC=MOAR&param_scope=calendar.readonly%20photos.write olarak çevrilecektir:

POST /fedcm_assertion_endpoint HTTP/1.1
Host: idp.example
Origin: https://rp.example/
Content-Type: application/x-www-form-urlencoded
Cookie: 0x23223
Sec-Fetch-Dest: webidentity

account_id=123&client_id=client1234&nonce=234234&disclosure_text_shown=false&param_IDP_SPECIFIC_PARAM=1&param_foo=BAR&param_ETC=MOAR&param_scope=calendar.readonly%20photos.write

İzinleri dinamik olarak alma

Genel olarak kullanıcılar için en faydalı yöntem, geliştiricinin uygulamayı en kolay şekilde hissettiği zamanlar yerine ihtiyaç olduğunda izin istemektir. Örneğin, kullanıcı fotoğraf çekmek üzereyken kameraya erişim izni istemek için kullanıcı web sitesine ulaşır ulaşmaz izin isteme tercih edilir. Aynı uygulama sunucu kaynakları için de geçerlidir. Yalnızca kullanıcı için gerekli olduğunda izin isteyin. Buna "dinamik yetkilendirme" adı verilir.

FedCM ile dinamik bir şekilde yetkilendirme istemek için IdP şunları yapabilir:

IdP'nin anlayabileceği gerekli parametreleri (ör. scope) kullanarak navigator.credentials.get() öğesini çağırın.
Kimlik onayı uç noktası, kullanıcının zaten oturum açmış olduğunu onaylar ve continue_on URL'si ile yanıt verir.
Tarayıcıda, istenen kapsamlarla eşleşen ek izin isteyen IdP'nin izin sayfasının bulunduğu bir pop-up pencere açılır.
IdP tarafından IdentityProvider.resolve() aracılığıyla yetkilendirildikten sonra pencere kapatılır ve Kısıtlanmış Taraf'ın orijinal navigator.credentials.get() çağrısına ilgili bir jeton veya yetkilendirme kodu verilir. Böylece RP', bu kodu uygun bir erişim jetonuyla takas edebilir.

Alanlar API'sı

Fields API, tarayıcının FedCM iletişim kutusunda uygun açıklama kullanıcı arayüzü oluşturabilmesi için RP'nin hesap özelliklerinin IdP'den istekte bulunmasını sağlar. İstenen alanların döndürülen jetona dahil edilmesi IdP'nin sorumluluğundadır. RFC Connect'te "temel profil" ve OAuth'taki "kapsamlar" gibi bir istekte bulunmayı düşünebilirsiniz.

Fields API'yi kullanmak için parametreleri navigator.credentials.get() çağrısında bir dizi olarak fields özelliğine ekleyin. Alanlar şimdilik 'name', 'email' ve 'picture' içerebilir ancak gelecekte daha fazla değer içerecek şekilde genişletilebilir.

fields içeren bir istek şöyle görünür:

let { token } = await navigator.credentials.get({
  identity: {
    providers: [{
      fields: ['name', 'email', 'picture'],
      clientId: '1234',
      configURL: 'https://idp.example/fedcm.json',
      params: {
        scope: 'drive.readonly calendar.readonly',
      }
    },
  }
  mediation: 'optional',
});

Kimlik onayı uç noktasına yapılan HTTP isteği, RP tarafından belirtilen fields parametresini içerir. Bu parametre geri gelen kullanıcı değilse disclosure_text_shown parametresi true olarak ayarlanır ve tarayıcının disclosure_shown_for parametresinde kullanıcıya açıkladığı alanları içerir:

POST /id_assertion_endpoint HTTP/1.1
Host: idp.example
Origin: https://rp.example/
Content-Type: application/x-www-form-urlencoded
Cookie: 0x23223
Sec-Fetch-Dest: webidentity

account_id=123&client_id=client1234&nonce=234234&disclosure_text_shown=true&fields=email,name,picture&disclosure_shown_for=email,name,picture

Kısıtlanmış tarafın, IdP'den alınan ek verilere (ör. takvime erişim) erişmesi gerekiyorsa bu işlem, yukarıda belirtildiği şekilde özel bir parametreyle gerçekleştirilmelidir. IdP, izin istemek için bir continue_on URL'si döndürür.

fields boş bir diziyse istek şöyle görünür:

let { token } = await navigator.credentials.get({
  identity: {
    providers: [{
      fields: [],
      clientId: '1234',
      configURL: 'https://idp.example/fedcm.json',
      params: {
        scope: 'drive.readonly calendar.readonly',
      }
    },
  }
  mediation: 'optional',
});

fields boş bir diziyse kullanıcı aracısı, açıklama kullanıcı arayüzünü atlar.

Açıklama mesajı widget modunda gösterilmiyor. Düğme akışında, açıklama kullanıcı arayüzü tamamen atlanır. — Widget modunda açıklama mesajı gösterilmiyor. Düğme akışında, açıklama kullanıcı arayüzü tamamen atlanır.

Bu durum, hesaplar uç noktasından gelen yanıt approved_clients içindeki Kısıtlanmış Taraf ile eşleşen bir istemci kimliği içermese bile geçerlidir.

Bu durumda, Kimlik onayı uç noktasına gönderilen disclosure_text_shown, HTTP gövdesinde "false" değerini alır:

POST /id_assertion_endpoint HTTP/1.1
Host: idp.example
Origin: https://rp.example/
Content-Type: application/x-www-form-urlencoded
Cookie: 0x23223
Sec-Fetch-Dest: webidentity

account_id=123&client_id=client1234&nonce=234234&disclosure_text_shown=false

Birden çok configURL

Birden çok configURL, IdP'lerin bir IdP'ye ait birden fazla yapılandırma dosyasını barındırmasını sağlar. Bunun için tanınan dosyada accounts_endpoint ve login_url değerlerini yapılandırma dosyalarıyla aynı şekilde belirtir.

İyi bilinen dosyaya accounts_endpoint ve login_url eklenirse IdP'nin birden fazla yapılandırma dosyasını destekleyebilmesi için provider_urls yoksayılır. Aynı boyutta olmamaları halinde provider_urls, geriye dönük uyumlu olması için geçerlilik kazanmaya devam eder.

Birden fazla configURL'yi destekleyen iyi bilinen bir dosya şöyle görünebilir:

{
  "provider_urls": [ "https://idp.example/fedcm.json" ],
  "accounts_endpoint": "https://idp.example/accounts",
  "login_url": "https://idp.example/login"
}

Bu sayede:

İyi bilinen mevcut dosyalar ve zaten dağıtılmış olan tarayıcıların önceki sürümleriyle geriye ve ileriye dönük uyumluluğu koruyun.
İsteğe bağlı sayıda yapılandırma dosyasına sahip olun (hepleri aynı accounts_endpoint ve login_url'a işaret ettikleri sürece).
".well-known" düzeyinde belirtilmesi gerektiğinden, accounts_endpoint için yapılan kimlik bilgisi içeren getirme isteğine entropi ekleme fırsatınız olmaz.

Birden fazla configURL'nin desteklenmesi isteğe bağlıdır ve mevcut FedCM uygulamaları aynı kalabilir.

Özel Hesap Etiketleri

Özel Hesap Etiketleri, FedCM IdP'lerinin hesaplara not eklemesine olanak tanır. Böylece, RP'ler bir yapılandırma dosyasında etiketi belirterek hesapları filtreleyebilir. Benzer filtreleme, Alan İpucu API'si ve Login Hint API tarafından navigator.credentials.get() çağrısında belirtilerek kullanılmıştı. Ancak Özel Hesap Etiketleri, yapılandırma dosyasını belirterek kullanıcıları filtreleyebilir. Bu, özellikle birden fazla configURL kullanıldığında yararlı olur. Özel Hesap Etiketleri, giriş veya alan ipuçları gibi RP'nin aksine IdP sunucusundan sağlanmaları bakımından da farklıdır.

Örnek

Bir IdP, sırasıyla tüketici ve kuruluş için iki configURL'yi destekler. Tüketici yapılandırma dosyasında 'consumer' etiketi, kurumsal yapılandırma dosyasında ise 'enterprise' etiketi bulunur.

Böyle bir kurulum yapıldığında, bilinen dosya, birden fazla configURL'ye izin vermek için accounts_endpoint ve login_url öğelerini içerir.

{
  "provider_urls": [ "https://idp.example/fedcm.json" ],
  "accounts_endpoint": "https://idp.example/accounts",
  "login_url": "https://idp.example/login"
}

İyi bilinen dosyada accounts_endpoint sağlandığında provider_urls yoksayılır. Kısıtlanmış taraf, navigator.credentials.get() çağrısındaki ilgili yapılandırma dosyalarını doğrudan işaret edebilir.

Tüketici yapılandırma dosyası https://idp.example/fedcm.json konumunda. Bu dosya, include kullanılarak 'consumer' değerini belirten accounts özelliğini içerir.

{
  "accounts_endpoint": "https://idp.example/accounts",
  "client_metadata_endpoint": "/client_metadata",
  "login_url": "https://idp.example/login",
  "id_assertion_endpoint": "/assertion",
  "accounts": {
    "include": "consumer"
  }
}

Kurumsal yapılandırma dosyası https://idp.example/enterprise/fedcm.json adresinde. Bu dosya, include kullanarak 'enterprise' değerini belirten accounts özelliğini içerir.

{
  "accounts_endpoint": "https://idp.example/accounts",
  "client_metadata_endpoint": "/enterprise/client_metadata",
  "login_url": "https://idp.example/login",
  "id_assertion_endpoint": "/assertion",
  "accounts": {
    "include": "enterprise"
  }
}

Ortak IdP hesap uç noktası (bu örnekte https://idp.example/accounts), her hesap için bir dizide labels atanmış bir etiket mülkü içeren hesapların listesini döndürür. Aşağıda, iki hesabı olan bir kullanıcı için örnek bir yanıt verilmiştir. Biri tüketici, diğeri ise kurumsal amaçlı:

{
 "accounts": [{
   "id": "123",
   "given_name": "John",
   "name": "John Doe",
   "email": "john_doe@idp.example",
   "picture": "https://idp.example/profile/123",
   "labels": ["consumer"]
  }], [{
   "id": "4567",
   "given_name": "Jane",
   "name": "Jane Doe",
   "email": "jane_doe@idp.example",
   "picture": "https://idp.example/profile/4567",
   "labels": ["enterprise"]
  }]
}

Kısıtlanmış taraf, 'enterprise' kullanıcılarının oturum açmasına izin vermek istediğinde navigator.credentials.get() çağrısında 'enterprise' configURL 'https://idp.example/enterprise/fedcm.json' değerini belirtebilir:

let { token } = await navigator.credentials.get({
  identity: {
    providers: [{
      clientId: '1234',
      nonce: '234234',
      configURL: 'https://idp.example/enterprise/fedcm.json',
    },
  }
});

Sonuç olarak kullanıcı oturum açmak için yalnızca '4567' hesap kimliğini kullanabilir. '123' hesap kimliği, tarayıcı tarafından sessizce gizlenir. Böylece kullanıcıya bu sitede IdP tarafından desteklenmeyen bir hesap sunulmaz.

Kaynak denemesi: Storage Access API için güven sinyali olarak FedCM

Chrome 126, Storage Access API'si için güven sinyali olarak FedCM'nin kaynak denemesini başlatıyor. Bu değişiklikle birlikte, daha önce FedCM üzerinden izin verilmiş olması, depolama alanı erişim isteğinin Storage Access API'leri tarafından otomatik olarak onaylanması için geçerli bir neden hâline gelecek.

Bu özellik, yerleştirilmiş bir iframe kişiselleştirilmiş kaynaklara erişmek istediğinde kullanışlıdır. Örneğin, idp.example, rp.example içine yerleştirilmişse ve kişiselleştirilmiş bir kaynak göstermesi gerekiyorsa. Tarayıcı üçüncü taraf çerezlerine erişimi kısıtlarsa kullanıcı, FedCM ile idp.example kullanarak rp.example'da oturum açmış olsa bile, istekler üçüncü taraf çerezleri içermeyeceği için, yerleştirilmiş idp.example iframe kişiselleştirilmiş kaynak isteyemez.

Bunun için idp.example uygulamasının, web sitesine yerleştirilmiş iframe'i aracılığıyla depolama alanı erişim izni alması gerekir. Bu izin yalnızca bir izin istemi aracılığıyla elde edilebilir.

Storage Access API için güven sinyali olarak FedCM kullanıldığında, Storage Access API izin kontrolleri yalnızca depolama erişim istemi tarafından verilen izin vermeyi değil, aynı zamanda bir FedCM istemi tarafından verilen izni de kabul eder.

// In top-level rp.example:

// Ensure FedCM permission has been granted.
const cred = await navigator.credentials.get({
  identity: {
    providers: [{
      configURL: 'https://idp.example/fedcm.json',
      clientId: '123',
    }],
  },
  mediation: 'optional',
});

// In an embedded IdP iframe:

// No user gesture is needed to call this, and the call will be auto-granted.
await document.requestStorageAccess();

// This returns `true`.
const hasAccess = await document.hasStorageAccess();

Kullanıcı FedCM ile oturum açtığında, FedCM kimlik doğrulaması etkin olduğu sürece bu izin otomatik olarak verilir. Bu, kullanıcının bağlantısı kesildiğinde izin isterken bir istem gösterileceği anlamına gelir.

Kaynak denemesine katılın

Chrome 126 veya sonraki sürümlerde Chrome işaretini chrome://flags#fedcm-authz etkinleştirerek FedCM Continuation API paketini yerel olarak deneyebilirsiniz. Chrome 126 veya sonraki sürümlerde #fedcm-with-storage-access-api hizmetini etkinleştirerek Storage Access API için güven sinyali olarak FedCM'yi yerel olarak da deneyebilirsiniz.

Bu özellikler kaynak denemeleri olarak da kullanılabilir. Kaynak denemeleri; yeni özellikleri deneyip kullanılabilirlik, pratik ve etkililik konularında geri bildirimde bulunmanıza olanak tanır. Daha fazla bilgi için Kaynak denemelerini kullanmaya başlama başlıklı makaleye göz atın.

FedCM Continuation API paketi kaynak denemesini denemek için iki kaynak deneme jetonu oluşturun:

Deneme sürümüne kaydolun. Jetonu IdP kaynağına yerleştirin.
Üçüncü taraf eşleştirme onay kutusu işaretli olarak kaynak denemesine kaydolun. Kısıtlanmış taraf için jetonu yerleştirmek üzere Kısıtlanmış taraf için üçüncü taraf kaynak denemesi kaydetme başlıklı makaledeki talimatları uygulayın.

Düğme akışı ile birlikte Continuation API'yi de etkinleştirmek isterseniz Button Mode API kaynak denemesini de etkinleştirin:

Üçüncü taraf olarak kaynak denemesine kaydolmak. Kısıtlanmış tarafın jetonunu yerleştirmek için Kısıtlanmış Taraf için üçüncü taraf kaynak denemesi kaydetme bölümündeki talimatları uygulayın.

FedCM'yi Storage Access API kaynak denemesinde güven sinyali olarak denemek için:

Kaynak deneme sürümüne kaydolun. Jetonu IdP kaynağına yerleştirin.

Storage Access API kaynak denemesi için güven sinyali olarak Continuation API paketi kaynak denemesi ve FedCM, Chrome 126'dan edinilebilir.

Kısıtlanmış taraf için üçüncü taraf kaynak denemesi kaydettirme

Kaynak deneme kaydı sayfasına gidin.
Kaydol düğmesini tıklayın ve jeton istemek için formu doldurun.
IdP'nin kaynağını Web Origin (Web Kaynağı) olarak girin.
Jetonu başka kaynaklara JavaScript ile eklemek için Üçüncü taraf eşleşmesini kontrol edin.
Gönder'i tıklayın.
Verilen jetonu üçüncü taraf bir web sitesine yerleştirin.

Jetonu bir üçüncü taraf web sitesine yerleştirmek için IdP'nin JavaScript kitaplığına veya IdP'nin kaynağından sunulan SDK'ya aşağıdaki kodu ekleyin.

const tokenElement = document.createElement('meta');
tokenElement.httpEquiv = 'origin-trial';
tokenElement.content = 'TOKEN_GOES_HERE';
document.head.appendChild(tokenElement);

TOKEN_GOES_HERE yerine kendi jetonunuzu yazın.