Güvenen taraf tarafında FedCM ile kimlik çözümü uygulama

Kullanıcı Tarafları'nın (RP'ler) sitelerinde FedCM'yi etkinleştirmek için aşağıdaki adımları tamamlaması gerekir:

• RP'nin sitesinde FedCM uç noktalarına izin verildiğinden emin olun.
• Kullanıcı kimlik doğrulamasını başlatmak için FedCM JavaScript API'sini kullanın.
• Meta verilerini (ör. gizlilik politikası ve hizmet şartları URL'leri) kimlik sağlayıcıya sağlayın.
• [isteğe bağlı] Kullanıcı deneyimi modu seçerek, giriş veya alan ipuçları sağlayarak, özel parametreler ileterek, belirli kullanıcı bilgilerini isteyerek, özel hata mesajı sağlayarak veya kullanıcıları yeniden kimlik doğrulamanın nasıl yapılacağını seçerek kullanıcı deneyimini özelleştirin.

IdP'nin yapılandırması ve uç noktaları kullanıma sunulduktan sonra RP'ler, kullanıcıların IdP ile RP'de oturum açmasına izin verilmesini istemek için navigator.credentials.get() çağrısı yapabilir.

API'yi çağırmadan önce FedCM'nin kullanıcının tarayıcısında kullanılabildiğini onaylamanız gerekir. FedCM'nin kullanılıp kullanılamadığını kontrol etmek için bu kodu FedCM uygulamanızın etrafına sarın:

  if ('IdentityCredential' in window) {
    // If the feature is available, take action
  } else {
    // FedCM is not supported, use a different identity solution
  }

Kullanıcıların FedCM'yi kullanarak bir RP'de IdP'de oturum açmasına izin vermek için RP, navigator.credentials.get() işlevini çağırabilir. Örneğin:

  const credential = await navigator.credentials.get({
    identity: {
      context: 'signin',
      providers: [{
        configURL: 'https://accounts.idp.example/config.json',
        clientId: '********',
        mode: 'active',
        params: {
          nonce: '******'
        }
      }]
    }
  });
  const { token } = credential;

Bağlam mülkü

İsteğe bağlı context mülküyle RP, FedCM iletişim kutusu kullanıcı arayüzündeki dizeyi (ör. "rp.example adresinde oturum açın…", "idp.example adresini kullanın…") önceden tanımlanmış kimlik doğrulama bağlamlarına uyacak şekilde değiştirebilir. context mülkünün değeri aşağıdakilerden biri olabilir:

• signin (varsayılan)
• signup
• use

Örneğin, context değerini use olarak ayarladığınızda aşağıdaki mesaj gösterilir:

Tarayıcı, hesap listesi uç noktasından gelen yanıtta approved_clients değerinin varlığına bağlı olarak kayıt ve oturum açma kullanım alanlarını farklı şekilde işler. Kullanıcı RP'ye zaten kaydolduysa tarayıcı ".... ile devam etmek için" şeklinde bir açıklama metni göstermez.
providers mülkü, aşağıdaki özelliklere sahip bir IdentityProvider nesnesi dizisi alır:

Sağlayıcılar mülkü

providers mülkü, aşağıdaki özelliklere sahip bir IdentityProvider nesnesi dizisi alır:

Etkin mod

FedCM, farklı kullanıcı deneyimi modu yapılandırmalarını destekler. Pasif mod varsayılan moddur ve geliştiricilerin bunu yapılandırması gerekmez.

FedCM'yi etkin modda kullanmak için:

1. Kullanıcının tarayıcısında özelliğin kullanılabilirlik durumunu kontrol edin.
2. API'yi düğme tıklaması gibi geçici bir kullanıcı hareketiyle çağırın.
3. mode parametresini API çağrısına iletin:

  let supportsFedCmMode = false;
  try {
    navigator.credentials.get({
      identity: Object.defineProperty(
        // Check if this Chrome version supports the Mode API.
        {}, 'mode', {
          get: function () { supportsFedCmMode = true; }
        }
      )
    });
  } catch(e) {}

  if (supportsFedCmMode) {
    // The button mode is supported. Call the API with mode property:
    return await navigator.credentials.get({
      identity: {
        providers: [{
          configURL: 'https://idp.example/config.json',
          clientId: '123',
        }],
        // The 'mode' value defines the UX mode of FedCM.
        // - 'active': Must be initiated by user interaction (e.g., clicking a button).
        // - 'passive': Can be initiated without direct user interaction.
        mode: 'active'
      }
    });
  }

Etkin moddaki özel simge

Etkin mod, kimlik sağlayıcıların RP'nin resmi logo simgesini doğrudan istemci meta veri uç noktasına yanıtına eklemesine olanak tanır. RP, markalaşma verilerini önceden sağlamalıdır.

FedCM'yi kaynaklar arası bir iFrame içinden çağırma

FedCM, üst çerçeve izin veriyorsa identity-credentials-get izin politikası kullanılarak kaynakta çapraz bir iframe içinden çağrılabilir. Bunu yapmak için allow="identity-credentials-get" özelliğini iframe etiketine aşağıdaki gibi ekleyin:

  <iframe src="https://fedcm-cross-origin-iframe.glitch.me" allow="identity-credentials-get"></iframe>

Bu özelliğin işleyiş şeklini bir örnekte görebilirsiniz.

İsteğe bağlı olarak, üst çerçeve FedCM'yi çağıracak kaynakları kısıtlamak isterse izin verilen kaynakların listesini içeren bir Permissions-Policy başlığı gönderin.

  Permissions-Policy: identity-credentials-get=(self "https://fedcm-cross-origin-iframe.glitch.me")

İzin Politikası'nın işleyiş şekli hakkında daha fazla bilgiyi İzin Politikası ile tarayıcı özelliklerini kontrol etme başlıklı makalede bulabilirsiniz.

Login Hint API

Giriş İpucu'nu kullanarak RP, kullanıcının hangi hesapta oturum açması gerektiğini önerebilir. Bu, daha önce hangi hesabı kullandıklarından emin olmayan kullanıcıların kimliklerini yeniden doğrulamaları için yararlı olabilir.

RP'ler, aşağıdaki kod örneğinde gösterildiği gibi hesap listesi uç noktasından alınan login_hints değerlerinden biriyle loginHint mülkü için navigator.credentials.get()'ü çağırarak belirli bir hesabı seçerek gösterebilir:

  return await navigator.credentials.get({
    identity: {
      providers: [{
        configURL: 'https://idp.example/manifest.json',
        clientId: '123',
        // Accounts endpoint can specify a 'login_hints' array for an account.
        // When RP specifies a 'exampleHint' value, only those accounts will be
        // shown to the user whose 'login_hints' array contains the 'exampleHint'
        // value
        loginHint : 'exampleHint'
      }]
    }
  });

loginHint ile eşleşen hesap olmadığında FedCM iletişim kutusunda bir giriş istemi gösterilir. Bu istem, kullanıcının RP tarafından istenen ipucu ile eşleşen bir IdP hesabına giriş yapmasına olanak tanır. Kullanıcı istem üzerine dokunduğunda, yapılandırma dosyasında belirtilen giriş URL'sinin yer aldığı bir pop-up pencere açılır. Bağlantıya giriş ipucu ve alan ipucu sorgu parametreleri eklenir.

Domain Hint API

RP'ler yalnızca belirli bir alanla ilişkili hesapları seçerek gösterebilir. Bu, kurumsal alanla kısıtlanmış RP'ler için yararlı olabilir.

Yalnızca belirli alan hesaplarını görüntülemek için RP, aşağıdaki kod örneğinde gösterildiği gibi hesap listesi uç noktasından alınan domain_hints değerlerinden biriyle domainHint mülkü kullanarak navigator.credentials.get()'ü çağırmalıdır:

  return await navigator.credentials.get({
    identity: {
      providers: [{
        configURL: 'https://idp.example/manifest.json',
        clientId: 'abc',
        // Accounts endpoint can specify a 'domain_hints' array for an account.
        // When RP specifies a '@domain.example' value, only those accounts will be
        // shown to the user whose 'domain_hints' array contains the
        // '@domain.example' value
        domainHint : '@domain.example'
      }]
    }
  });

domainHint ile eşleşen hesap olmadığında FedCM iletişim kutusunda bir giriş istemi gösterilir. Bu istem, kullanıcının RP tarafından istenen ipucu ile eşleşen bir IdP hesabına giriş yapmasına olanak tanır. Kullanıcı istem üzerine dokunduğunda, yapılandırma dosyasında belirtilen giriş URL'sinin yer aldığı bir pop-up pencere açılır. Bağlantıya giriş ipucu ve alan ipucu sorgu parametreleri eklenir.

Özel parametreler

Özel Parametreler özelliği, RP'nin kimlik beyanı uç noktasına ek anahtar/değer parametreleri sağlamasına olanak tanır. RP'ler, temel oturum açma dışındaki kaynaklar için izin istemek üzere Parameters API ile kimlik sağlayıcıya ek parametreler iletebilir. Ek parametre göndermek aşağıdaki senaryolarda yararlı olabilir:

• RP'nin, kimlik sağlayıcının sahip olduğu ek izinleri (ör. fatura adresi veya takvim erişimi) dinamik olarak istemesi gerekir. Kullanıcı, Devam et özelliği kullanılarak başlatılan ve IdP tarafından kontrol edilen bir kullanıcı deneyimi akışı aracılığıyla bu izinleri yetkilendirebilir. Ardından IdP bu bilgileri paylaşır.

API'yi kullanmak için RP, navigator.credentials.get() çağrısında params mülküne nesne olarak parametreler ekler:

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

Tarayıcı, bunu otomatik olarak tek bir URL kodlamalı JSON olarak serileştirilmiş nesne olarak parametrelerle birlikte kimlik sağlayıcıya gönderilecek bir POST isteğine dönüştürür:

  // The assertion endpoint is drawn from the config file
  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

  // params are translated into urlencoded version of `{"IDP_SPECIFIC_PARAM":"1","foo":"bar"}`
  account_id=123&client_id=client1234&params=%22%7B%5C%22IDP_SPECIFIC_PARAM%5C%22%3A1%2C%5C%22foo%5C%22%3A%5C%22BAR%5C%22%7D%22.

RP'nin ek izinlere ihtiyacı varsa kimlik sağlayıcı yönlendirme bağlantısı sağlayabilir. Örneğin, node.js'de:

  if (rpRequestsPermissions) {
    // Response with a URL if the RP requests additional permissions
    return res.json({
      continue_on: '/example-redirect',
    });
  }

Alanlar

RP, kimlik sağlayıcının kendisiyle paylaşmasını istediği kullanıcı bilgilerini (ad, e-posta adresi ve profil resminin herhangi bir kombinasyonu) belirtebilir. İstenen bilgiler, FedCM iletişim kutusunun açıklama kullanıcı arayüzüne eklenir. Kullanıcı oturum açmayı seçerse idp.example'ün istenen bilgileri rp.example ile paylaşacağını bildiren bir mesaj görür.

Alanlar özelliğini kullanmak için RP, navigator.credentials.get() çağrısına bir fields dizisi eklemelidir. Alanlar name, email ve picture değerlerinin herhangi bir permütasyonunu içerebilir. Bu liste 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: [{
        // RP requests the IdP to share only user email and profile picture
        fields: [ 'email', 'picture'],
        clientId: '1234',
        configURL: 'https://idp.example/fedcm.json',

      },
    }
  });

Tarayıcı, bu isteği otomatik olarak kimlik beyanı uç noktasına gönderilen bir HTTP isteğine dönüştürür. Bu istek, RP tarafından belirtilen fields parametresini ve tarayıcının kullanıcıya disclosure_shown_for parametresinde açıkladığı alanları içerir. Geriye dönük uyumluluk için, açıklama metni gösterildiyse ve istenen alanlar üç alanın tamamını ('name', 'email' ve 'picture') içeriyorsa tarayıcı disclosure_text_shown=true değerini de gönderir.

  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

  // The RP only requested to share email and picture. The browser will send `disclosure_text_shown=false`, as the 'name' field value is missing
  account_id=123&client_id=client1234&disclosure_text_shown=false&fields=email,picture&disclosure_shown_for=email,picture

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

Bu durum, accounts uç noktasından gelen yanıt approved_clients'deki RP ile eşleşen bir müşteri kimliği içermese bile geçerlidir.

Bu durumda, kimlik beyanı uç noktasına gönderilen disclosure_text_shown, HTTP gövdesinde yanlıştı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

Hata mesajı gösterme

Bazen kimlik sağlayıcı, istemci yetkisiz olduğunda veya sunucu geçici olarak kullanılamadığında gibi geçerli nedenlerle jeton yayınlayamayabilir. IdP "error" yanıtı döndürürse RP bunu yakalayabilir ve Chrome, IdP tarafından sağlanan hata bilgilerini içeren tarayıcı kullanıcı arayüzünü göstererek kullanıcıyı bilgilendirebilir.

  try {
    const cred = await navigator.credentials.get({
      identity: {
        providers: [
          {
            configURL: 'https://idp.example/manifest.json',
            clientId: '1234',
          },
        ],
      }
    });
  } catch (e) {
    const code = e.code;
    const url = e.url;
  }

İlk kimlik doğrulamadan sonra kullanıcıların kimliğini otomatik olarak yeniden doğrulama

FedCM otomatik yeniden kimlik doğrulaması ("auto-reauthn" kısaca) kullanıcıların, FedCM'yi kullanarak ilk kimlik doğrulamalarını yaptıktan sonra geri geldiklerinde otomatik olarak yeniden kimlik doğrulamasına izin verebilir. Buradaki "ilk kimlik doğrulama", kullanıcının aynı tarayıcı örneğinde FedCM'nin oturum açma iletişim kutusunda ilk kez "Böyle devam et..." düğmesine dokunarak hesap oluşturması veya RP'nin web sitesinde oturum açması anlamına gelir.

Kullanıcı, izlemeyi önlemek için birleşik hesabı oluşturmadan önce açık kullanıcı deneyimi anlamlı olsa da (FedCM'nin ana hedeflerinden biri budur), kullanıcı bu işlemi bir kez yaptıktan sonra gereksiz yere hantal olur: Kullanıcı, RP ile IdP arasında iletişime izin verdikten sonra, daha önce kabul ettiği bir şey için başka bir açık kullanıcı onayı zorunlu kılmak gizlilik veya güvenlik açısından bir avantaj sağlamaz.

Otomatik yeniden yetkilendirme özelliğiyle tarayıcı, navigator.credentials.get() çağrısı sırasında mediation için belirttiğiniz seçeneğe bağlı olarak davranışını değiştirir.

  const cred = await navigator.credentials.get({
    identity: {
      providers: [{
        configURL: 'https://idp.example/fedcm.json',
        clientId: '1234',
      }],
    },
    mediation: 'optional', // this is the default
  });

  // `isAutoSelected` is `true` if auto-reauthn was performed.
  const isAutoSelected = cred.isAutoSelected;

mediation, Kimlik Bilgisi Yönetimi API'sindeki bir mülktür. PasswordCredential ve FederatedCredential için olduğu gibi aynı şekilde çalışır ve PublicKeyCredential tarafından da kısmen desteklenir. Özellik aşağıdaki dört değeri kabul eder:

• 'optional'(varsayılan): Mümkünse otomatik yeniden yetkilendirme, mümkün değilse arabuluculuk gerekir. Oturum açma sayfasında bu seçeneği belirlemenizi öneririz.
• 'required': Devam etmek için her zaman bir arabuluculuk gerekir (ör. kullanıcı arayüzündeki "Devam" düğmesini tıklama). Kullanıcılarınızın kimlik doğrulamanın gerekli olduğu her durumda açıkça izin vermesi gerekiyorsa bu seçeneği belirleyin.
• 'silent': Mümkünse otomatik olarak yeniden kimlik doğrulama, mümkün değilse uyumlulaştırma gerektirmeden sessizce başarısız olur. Özel oturum açma sayfası dışındaki ancak kullanıcıların oturumunu açık tutmak istediğiniz sayfalarda (ör. bir kargo web sitesindeki ürün sayfası veya bir haber web sitesindeki makale sayfası) bu seçeneği tercih etmenizi öneririz.
• 'conditional': WebAuthn için kullanılır ve şu anda FedCM için kullanılamaz.

Bu çağrıyla, otomatik yeniden yetkilendirme aşağıdaki koşullarda gerçekleşir:

• FedCM kullanılabilir. Örneğin, kullanıcı FedCM'yi genel olarak veya ayarlarda RP için devre dışı bırakmamıştır.
• Kullanıcı, bu tarayıcıda web sitesinde oturum açmak için FedCM API ile yalnızca bir hesap kullandı.
• Kullanıcı, IdP'de bu hesapla oturum açmıştır.
• Otomatik yeniden yetkilendirme son 10 dakika içinde gerçekleşmedi.
• RP, önceki oturum açmadan sonra navigator.credentials.preventSilentAccess() çağrısı yapmadı.

Bu koşullar karşılandığında, FedCM navigator.credentials.get() çağrıldığı anda kullanıcının kimliğini otomatik olarak yeniden doğrulama girişimi başlar.

mediation: optional olduğunda, yalnızca tarayıcının bildiği nedenlerle otomatik yeniden kimlik doğrulama kullanılamıyor olabilir. RP, isAutoSelected mülkünü inceleyerek otomatik yeniden kimlik doğrulamanın yapılıp yapılmadığını kontrol edebilir.

Bu, API performansını değerlendirmek ve kullanıcı deneyimini buna göre iyileştirmek için yararlıdır. Ayrıca, bu özellik kullanılamadığında kullanıcıdan mediation: required içeren bir akış olan açık kullanıcı arabuluculuğu ile oturum açması istenebilir.

preventSilentAccess() ile uyumlulaştırmayı zorunlu kılma

Kullanıcıların oturumu kapattıktan hemen sonra otomatik olarak kimlik doğrulamasını yapmak çok iyi bir kullanıcı deneyimi sunmaz. Bu nedenle FedCM, bu davranışı önlemek için otomatik yeniden yetkilendirmeden sonra 10 dakikalık bir bekleme süresi uygular. Bu, kullanıcı 10 dakika içinde tekrar oturum açmadığı sürece otomatik yeniden kimlik doğrulamanın en fazla 10 dakikada bir gerçekleşeceği anlamına gelir. RP, kullanıcı RP'den açıkça çıkış yaptığında (ör. çıkış düğmesini tıklayarak) tarayıcıdan otomatik yeniden kimlik doğrulamayı devre dışı bırakmasını açıkça istemek için navigator.credentials.preventSilentAccess() işlevini çağırmalıdır.

  function signout() {
    navigator.credentials.preventSilentAccess();
    location.href = '/signout';
  }

Kullanıcılar, otomatik yeniden yetkilendirmeyi ayarlardan devre dışı bırakabilir.

Kullanıcılar, ayarlar menüsünden otomatik yeniden yetkilendirmeyi devre dışı bırakabilir:

• Masaüstünde Chrome'da chrome://password-manager/settings > Oturumu otomatik olarak aç'a gidin.
• Android Chrome'da Ayarlar > Şifre Yöneticisi'ni açın > Sağ üst köşedeki dişli simgesine dokunun > Otomatik oturum açma'yı seçin.

Kullanıcı, açma/kapatma düğmesini devre dışı bırakarak otomatik yeniden kimlik doğrulama davranışını tamamen devre dışı bırakabilir. Kullanıcı Chrome örneğinde bir Google Hesabı'nda oturum açtıysa ve senkronizasyon etkinse bu ayar cihazlar arasında depolanır ve senkronize edilir.

IdP'nin RP ile bağlantısını kesme

Bir kullanıcı daha önce FedCM üzerinden IdP'yi kullanarak RP'de oturum açtıysa ilişki, tarayıcı tarafından bağlı hesapların listesi olarak yerel olarak ezberlenir. RP, IdentityCredential.disconnect() işlevini çağırarak bağlantıyı kesebilir. Bu işlev, üst düzey bir RP çerçevesinden çağrılabilir. RP'nin, IdP altında kullandığı clientId ve IdP'nin bağlantısının kesilmesi için bir accountHint ile bir configURL iletmesi gerekir. Hesap ipucu, bağlantıyı kesme uç noktası hesabı tanımlayabileceği sürece herhangi bir dize olabilir. Örneğin, hesap listesi uç noktasının sağladığı hesap kimliğiyle eşleşmesi gerekmeyen bir e-posta adresi veya kullanıcı kimliği:

  // Disconnect an IdP account 'account456' from the RP 'https://idp.com/'. This is invoked on the RP domain.
  IdentityCredential.disconnect({
    configURL: 'https://idp.com/config.json',
    clientId: 'rp123',
    accountHint: 'account456'
  });

IdentityCredential.disconnect(), Promise döndürür. Bu söz aşağıdaki nedenlerle istisna atabilir:

• Kullanıcı, FedCM üzerinden IdP'yi kullanarak RP'de oturum açmamıştır.
• API, FedCM izin politikası olmadan bir iFrame'den çağrılıyor.
• configURL geçersiz veya bağlantı kesme uç noktası eksik.
• İçerik Güvenliği Politikası (İGP) kontrolü başarısız olur.
• Bekleyen bir bağlantı kesme isteği var.
• Kullanıcı, tarayıcı ayarlarında FedCM'yi devre dışı bırakmış olabilir.

IdP'nin bağlantı kesme uç noktası bir yanıt döndürdüğünde RP ile IdP'nin tarayıcıdaki bağlantısı kesilir ve söz çözülür. Bağlantısı kesilen hesapların kimliği, bağlantıyı kesme uç noktasından gelen yanıtta belirtilir.

Sonraki adımlar