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

Chrome 126'dan itibaren geliştiriciler, bazı yetkilendirme kullanım alanlarını etkinleştiren masaüstü Federated Credential Management API (FedCM) özelliklerinin bir paketi için kaynak denemesi çalıştırmaya başlayabilir. Paket, kimlik sağlayıcı (IdP) tarafından sağlanan izin iletişim kutusunu içeren OAuth yetkilendirme akışı benzeri bir deneyim sunan Continuation API ve Parameters API'den oluşur. Pakette Fields API, birden fazla configURL ve özel hesap etiketleri gibi diğer değişiklikler de yer alır. 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'si

Kullanıcı, RP'de oturum açtıktan sonra düğme modu üzerinden yetki veriyor.

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ı tarafa (RP) 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": "***********"
}

Ancak Continuation API ile kimlik beyanı uç noktası, kimlik beyanı uç noktasının mutlak yolunu veya göreli yolunu içeren bir continue_on mülkü 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şime geçtikten sonra (ör. RP ile ek bilgi paylaşmak için daha fazla izin verdikten sonra) IdP sayfası, orijinal navigator.credentials.get() çağrısını çözmek ve bağımsız değişken olarak bir jeton döndürmek için IdentityProvider.resolve() çağrısı yapabilir.

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

Tarayıcı daha sonra pop-up'ı kendi kendine kapatır ve jetonu API çağırıcıya döndürür.

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şken alır ve aşağıdaki gibi bir şeylere izin verir:

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 navigator.credentials.get() çağrısında params mülküne nesne olarak parametreler 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 nesnesinde param_ önek olarak eklenir. Yukarıdaki örnekte, params mülkü '1' olarak IDP_SPECIFIC_PARAM, 'BAR' olarak foo, 'MOAR' olarak ETC ve 'calendar.readonly photos.write' olarak scope içeriyor. Bu, isteğin HTTP gövdesinde param_IDP_SPECIFIC_PARAM=1&param_foo=BAR&param_ETC=MOAR&param_scope=calendar.readonly%20photos.write olarak çevrilir:

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 izinlerin geliştiricinin uygulamanın en kolay olduğunu düşündüğü zamandan ziyade ihtiyaç duyulduğunda istenmesi en yararlı olanıdır. Ö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 olarak yetkilendirme isteğinde bulunmak için kimlik sağlayıcı şunları yapabilir:

  1. navigator.credentials.get() işlevini, IdP'nin anlayabileceği gerekli parametrelerle (ör. scope) çağırın.
  2. Kimlik beyanı uç noktası, kullanıcının zaten oturum açtığını onaylar ve continue_on URL'si ile yanıt verir.
  3. 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.
  4. IdP tarafından IdentityProvider.resolve() üzerinden yetkilendirildikten sonra pencere kapatılır ve RP'nin orijinal navigator.credentials.get() çağrısı, RP'nin uygun bir erişim jetonuyla değiştirebilmesi için alakalı bir jeton veya yetkilendirme kodu alır.

Fields API

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.

Widget modunda açıklama mesajı.
Widget modunda açıklama mesajı.
Düğme modunda açıklama mesajı.
Düğme modunda açıklama mesajı.

Fields API'yi kullanmak için parametreleri navigator.credentials.get() çağrısında bir dizi olarak fields özelliğine ekleyin. Alanlar şu anda '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österilmez. Düğme akışında, açıklama kullanıcı arayüzü tamamen atlanır.
Açıklama mesajı widget modunda gösterilmiyor. Düğme akışında, açıklama kullanıcı arayüzü tamamen atlanıyor.

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 fazla 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.

accounts_endpoint ve login_url, well-known dosyasına 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:

  1. Mevcut bilinen dosyalarla ve kullanıma sunulmuş tarayıcıların önceki sürümleriyle geriye ve ileriye dönük uyumluluğu koruma
  2. İstediğiniz sayıda yapılandırma dosyası olabilir. Ancak tüm bu dosyalar aynı accounts_endpoint ve login_url adresine işaret etmelidir.
  3. ".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 desteklemek 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 bir filtreleme, navigator.credentials.get() çağrısında Domain Hint API ve Login Hint API'yi belirterek mümkün olmuştur. Ancak özel hesap etiketleri, yapılandırma dosyasını belirterek kullanıcıları filtreleyebilir. Bu özellikle birden fazla configURL kullanıldığında faydalıdır. Özel hesap etiketleri, giriş veya alan adı ipuçları gibi RP'den değil, IdP sunucusundan sağlandığı için de 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.

Bu tür bir kurulumda, .well-known dosyası birden fazla configURL'ye izin vermek için accounts_endpoint ve login_url içerir.

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

accounts_endpoint, well-known dosyasında 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 adresindedir ve include kullanarak '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"
  }
}

Kuruluş yapılandırma dosyası https://idp.example/enterprise/fedcm.json adresindedir. 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 kimlik sağlayıcı hesaplar uç noktası (bu örnekte https://idp.example/accounts), her hesap için bir dizi içinde atanan labels içeren bir etiketler 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"]
  }]
}

Bir RP, '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, kullanıcıya bu sitede IdP tarafından desteklenmeyen bir hesap verilmemesi için tarayıcı tarafından sessizce gizlenir.

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

Chrome 126'ta Depolama Aksesuarı API'si için güven sinyali olarak FedCM kaynak denemesi başlatılıyor. Bu değişiklikle birlikte, depolama alanı erişim isteğinin Storage Access API'leri tarafından otomatik olarak onaylanması için FedCM aracılığıyla önceden verilmiş bir izin 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.

Bunu yapmak için idp.example'in web sitesine yerleştirilmiş iframe'i aracılığıyla depolama erişimi izni alması gerekir. Bu izin yalnızca bir izin istemi aracılığıyla alınabilir.

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 bir 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 denemenize ve kullanılabilirlikleri, pratiklikleri ve etkililikleri hakkında geri bildirim vermenize 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:

Düğme akışıyla birlikte Devam API'yi etkinleştirmek istiyorsanız Düğme Modu API kaynağı deneme sürümünü de etkinleştirin:

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

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

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

  1. Kaynak deneme sürümü kayıt sayfasına gidin.
  2. Kaydol düğmesini tıklayın ve jeton istemek için formu doldurun.
  3. IdP'nin kaynağını Web Origin (Web Kaynağı) olarak girin.
  4. Diğer kaynaklarda jetonu JavaScript ile eklemek için üçüncü taraf eşlemeyi kontrol edin.
  5. Gönder'i tıklayın.
  6. 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.