FedCM ile kimlik çözümü uygulama

FedCM (Birleştirilmiş Kimlik Bilgisi Yönetimi), birleşik kimlik hizmetlerinde (ör. "... ile oturum aç") gizliliği korumaya yönelik bir yaklaşımdır. Bu yaklaşım, kullanıcıların kimlik hizmeti veya siteyle kişisel bilgilerini paylaşmadan sitelere giriş yapmasına olanak tanır.

FedCM uygulaması hem IdP (Kimlik Sağlayıcı) hem de RP (Güvenilir Taraf) için birkaç temel adım içerir.

IdPs, FedCM'yi uygulamak için aşağıdaki adımları tamamlamalıdır:

RP'lerin sitelerinde FedCM'yi etkinleştirmek için aşağıdaki adımları tamamlaması gerekir:

FedCM'yi IdP olarak uygulama

FedCM'yi kimlik sağlayıcı tarafında uygulamayla ilgili adımlar hakkında daha fazla bilgi edinin.

Well-known dosyası oluşturma

İzleyicilerin API'yi kötüye kullanmasını önlemek için IdP'nin eTLD+1 alanındaki /.well-known/web-identity adresinden bir .well-known dosyası yayınlanmalıdır.

Bilinen dosya aşağıdaki özellikleri içerebilir:

Mülk Zorunlu Açıklama
provider_urls zorunlu IdP yapılandırma dosyası yolları dizisi. accounts_endpoint ve login_url belirtilirse yoksayılır (ancak yine de gereklidir).
accounts_endpoint önerilir, login_url
gerektirir 		Hesaplar uç noktasının URL'si. Bu, her yapılandırma dosyası aynı login_url ve accounts_endpoint URL'sini kullandığı sürece birden fazla yapılandırma desteğine olanak tanır.

Not: Parametre, Chrome 132'den itibaren desteklenir.
login_url önerilir, accounts_endpoint gerektirir Kullanıcının IdP'de oturum açacağı giriş sayfası URL'si. Bu sayede, her yapılandırma dosyası aynı login_url ve accounts_endpoint değerini kullandığı sürece birden fazla yapılandırma desteği sağlanabilir.

Not: Parametre, Chrome 132 ve sonraki sürümlerde desteklenir.

Örneğin, IdP uç noktaları https://accounts.idp.example/ altında sunuluyorsa https://idp.example/.well-known/web-identity adresinde bir .well-known dosyası ve bir IdP yapılandırma dosyası da sunulmalıdır. Aşağıda, bilinen bir dosya içeriği örneği verilmiştir:

  {
    "provider_urls": ["https://accounts.idp.example/config.json"]
  }

IdP'ler, .well-known dosyasında accounts_endpoint ve login_url parametrelerini belirterek bir IdP için birden fazla yapılandırma dosyası barındırabilir.
Bu özellik aşağıdaki durumlarda yararlı olabilir:

  • Bir kimlik sağlayıcının birden fazla farklı test ve üretim yapılandırmasını desteklemesi gerekir.
  • Bir IdP'nin bölgeye göre farklı yapılandırmaları (örneğin, eu-idp.example ve us-idp.example) desteklemesi gerekir.

Birden fazla yapılandırmayı desteklemek için (ör. test ve üretim ortamını ayırt etmek için) kimlik sağlayıcının accounts_endpoint ve login_url değerlerini belirtmesi gerekir:

  {
    // This property is required, but will be ignored when IdP supports
    // multiple configs (when `accounts_endpoint` and `login_url` are
    // specified), as long as `accounts_endpoint` and `login_url` in
    // that config file match those in the well-known file.
    "provider_urls": [ "https://idp.example/fedcm.json" ],

    // Specify accounts_endpoint and login_url properties to support
    // multiple config files.
    // Note: The accounts_endpoint and login_url must be identical
    // across all config files. Otherwise,
    // the configurations won't be supported.
    "accounts_endpoint": "https://idp.example/accounts",
    "login_url": "https://idp.example/login"
  }

IdP yapılandırma dosyası ve uç noktaları oluşturma

IdP yapılandırma dosyası, tarayıcı için gerekli uç noktaların listesini sağlar. Kimlik sağlayıcılar bir veya daha fazla yapılandırma dosyası ile gerekli uç noktaları ve URL'leri barındırmalıdır. Tüm JSON yanıtları application/json içerik türüyle sunulmalıdır.

Yapılandırma dosyasının URL'si, bir RP'de yürütülen navigator.credentials.get() çağrısına sağlanan değerlere göre belirlenir.

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

RP, kullanıcının oturum açmasına izin vermek için yapılandırma dosyasının URL'sini FedCM API çağrısına iletir:

  // Executed on RP's side:
  const credential = await navigator.credentials.get({
    identity: {
      context: 'signup',
      providers: [{
        // To allow users to sign in with an IdP using FedCM, RP specifies the IdP's config file URL:
        configURL: 'https://accounts.idp.example/fedcm.json',
        clientId: '********',
  });
  const { token } = credential;

Tarayıcı, yapılandırma dosyasını Origin veya Referer başlığı olmadan bir GET isteğiyle getirir. İstek çerez içermez ve yönlendirmeleri takip etmez. Bu, kimlik sağlayıcının isteği kimin yaptığını ve hangi RP'nin bağlantı kurmaya çalıştığını öğrenmesini etkili bir şekilde engeller. Örneğin:

  GET /config.json HTTP/1.1
  Host: accounts.idp.example
  Accept: application/json
  Sec-Fetch-Dest: webidentity

IdP, JSON ile yanıt veren bir yapılandırma uç noktası uygulamalıdır. JSON aşağıdaki özellikleri içerir:

Mülk Açıklama
accounts_endpoint (zorunlu) Hesaplar uç noktasının URL'si.
accounts.include (isteğe bağlı) Bu yapılandırma dosyası kullanıldığında hangi hesapların döndürülmesi gerektiğini belirleyen özel hesap etiketi dizesi (ör. "accounts": {"include": "developer"}).
IdP'ler özel hesap etiketlemeyi aşağıdaki şekilde uygulayabilir:

Örneğin, bir IdP, "accounts": {"include": "developer"} belirtilmiş "https://idp.example/developer-config.json" yapılandırma dosyasını uygular. Kimlik sağlayıcı, hesaplar uç noktasındaki labels parametresini kullanarak bazı hesapları "developer" etiketiyle de işaretler. Bir RP, "https://idp.example/developer-config.json" yapılandırma dosyası belirtilmiş şekilde navigator.credentials.get()'ü çağrdığında yalnızca "developer" etiketine sahip hesaplar döndürülür.
client_metadata_endpoint (isteğe bağlı) İstemci meta veri uç noktasının URL'si.
id_assertion_endpoint (zorunlu) Kimlik beyanı uç noktasının URL'si.
disconnect (isteğe bağlı) Bağlantıyı kesme uç noktasının URL'si.
login_url (zorunlu) Kullanıcının IdP'de oturum açacağı giriş sayfası URL'si.
branding (isteğe bağlı) Çeşitli markalaşma seçeneklerini içeren nesne.
branding.background_color (isteğe bağlı) "... olarak devam et" düğmesinin arka plan rengini ayarlayan markalaşma seçeneği. İlgili CSS söz dizimini (hex-color, hsl(), rgb() veya named-color) kullanın.
branding.color (isteğe bağlı) "... olarak devam et" düğmesinin metin rengini ayarlayan markalaşma seçeneği. İlgili CSS söz dizimini (hex-color, hsl(), rgb() veya named-color) kullanın.
branding.icons (isteğe bağlı) Simge nesneleri dizisi. Bu simgeler, oturum açma iletişim kutusunda gösterilir. Simge nesnesinin iki parametresi vardır:
  • url (zorunlu): Simge resminin URL'si. Bu yöntem SVG resimlerini desteklemez.
  • size (isteğe bağlı): Uygulamanın kare ve tek çözünürlükte olduğunu varsaydığı simge boyutları. Bu sayı, pasif modda 25 piksel veya daha büyük, etkin modda ise 40 piksel veya daha büyük olmalıdır.
modes FedCM kullanıcı arayüzünün farklı modlarda nasıl gösterileceğine dair spesifikasyonları içeren nesne:
  • active
  • passive
modes.active FedCM davranışının belirli bir modda özelleştirilmesine olanak tanıyan özellikleri içeren nesne. Hem modes.active hem de modes.passive aşağıdaki parametreyi içerebilir:
  • supports_use_other_account: Kullanıcının şu anda giriş yaptığı hesaptan farklı bir hesapla oturum açıp açamayacağını belirten boole değeri (IdP birden fazla hesabı destekliyorsa).

Not: Diğer Hesabı Kullanma özelliği ve etkin mod, Chrome 132'den itibaren desteklenmektedir.
modes.passive

IdP'den gelen örnek bir yanıt gövdesi:

  {
    "accounts_endpoint": "/accounts.example",
    "client_metadata_endpoint": "/client_metadata.example",
    "id_assertion_endpoint": "/assertion.example",
    "disconnect_endpoint": "/disconnect.example",
    "login_url": "/login",
    // When RPs use this config file, only those accounts will be
    //returned that include `developer` label in the accounts endpoint.
    "accounts": {"include": "developer"},
    "modes": {
        "active": {
          "supports_use_other_account": true,
        }
    },
    "branding": {
      "background_color": "green",
      "color": "#FFEEAA",
      "icons": [{
        "url": "https://idp.example/icon.ico",
        "size": 25
      }]
    }
  }

Tarayıcı, yapılandırma dosyasını aldıktan sonra aşağıdaki istekleri kimlik sağlayıcı uç noktalarına gönderir:

IdP uç noktaları
IdP uç noktaları

Başka bir hesap kullanın

Kimlik sağlayıcı birden fazla hesabı destekliyorsa veya mevcut hesabı değiştiriyorsa kullanıcılar şu anda oturum açtıkları hesaptan farklı bir hesaba geçebilir.

Kullanıcının diğer hesapları seçebilmesi için kimlik sağlayıcının bu özelliği yapılandırma dosyasında belirtmesi gerekir:

  {
    "accounts_endpoint" : "/accounts.example",
    "modes": {
      "active": {
        // Allow the user to choose other account (false by default)
        "supports_use_other_account": true
      }
      // "passive" mode can be configured separately
    }
  }

Hesaplar uç noktası

IdP'nin hesap uç noktası, kullanıcının IdP'de oturum açtığı hesapların listesini döndürür. Kimlik sağlayıcı birden fazla hesabı destekliyorsa bu uç nokta, oturum açmış tüm hesapları döndürür.

Tarayıcı, SameSite=None ile çerez içeren bir GET isteği gönderir ancak client_id parametresi, Origin üstbilgisi veya Referer üstbilgisi olmadan gönderir. Bu, IdP'nin kullanıcının hangi RP'de oturum açmaya çalıştığını öğrenmesini etkili bir şekilde engeller. Örneğin:

  GET /accounts.example HTTP/1.1
  Host: accounts.idp.example
  Accept: application/json
  Cookie: 0x23223
  Sec-Fetch-Dest: webidentity

Sunucu, isteği aldıktan sonra:

  1. İsteğin bir Sec-Fetch-Dest: webidentity HTTP başlığı içerdiğini doğrulayın.
  2. Oturum çerezlerini, oturum açmış hesapların kimlikleriyle eşleyin.
  3. Hesap listesini ekleyerek yanıt verin.

Tarayıcı, aşağıdaki özellikleri içeren bir hesap bilgileri dizisiyle birlikte bir accounts mülkü içeren bir JSON yanıtı bekler:

Mülk Açıklama
id (zorunlu) Kullanıcının benzersiz kimliği.
name (zorunlu) Kullanıcının adı ve soyadı.
email (zorunlu) Kullanıcının e-posta adresi.
given_name (isteğe bağlı) Kullanıcıya verilen ad.
picture (isteğe bağlı) Kullanıcı avatarı resminin URL'si.
approved_clients (isteğe bağlı) Kullanıcının kaydettiği RP istemci kimlikleri dizisi.
login_hints (isteğe bağlı) IdP'nin bir hesabı belirtmek için desteklediği tüm filtre türlerinin dizisi. RP, belirtilen hesabı seçerek göstermek için loginHint mülküyle navigator.credentials.get()'ü çağırabilir.
domain_hints (isteğe bağlı) Hesabın ilişkili olduğu tüm alanların dizisi. RP, hesapları filtrelemek için domainHint mülkü ile navigator.credentials.get()'ü çağırabilir.
labels (isteğe bağlı) Bir hesabın ilişkili olduğu özel hesap etiketleri dize dizisi.
IdP'ler özel hesap etiketlemeyi aşağıdaki şekilde uygulayabilir:
  • Hesap etiketlerini accounts uç noktasında belirtin (bu labels parametresini kullanarak).
  • Her etiket için bir yapılandırma dosyası oluşturun.

Örneğin, bir IdP, "accounts": {"include": "developer"} belirtilmiş https://idp.example/developer-config.json yapılandırma dosyasını uygular. Kimlik sağlayıcı, hesaplar uç noktasındaki labels parametresini kullanarak bazı hesapları "developer" etiketiyle de işaretler. Bir RP, https://idp.example/developer-config.json yapılandırma dosyası belirtilmiş şekilde navigator.credentials.get()'ü çağrdığında yalnızca "developer" etiketine sahip hesaplar döndürülür.

Özel hesap etiketleri, oturum açma ipucu ve alan adı ipucu ile farklıdır. Bu etiketler tamamen IdP sunucusu tarafından yönetilir ve RP yalnızca kullanılacak yapılandırma dosyasını belirtir.

Örnek yanıt gövdesi:

  {
    "accounts": [{
      "id": "1234",
      "given_name": "John",
      "name": "John Doe",
      "email": "john_doe@idp.example",
      "picture": "https://idp.example/profile/123",
      // Ids of those RPs where this account can be used
      "approved_clients": ["123", "456", "789"],
      // This account has 'login_hints`. When an RP calls `navigator.credentials.get()`
      // with a `loginHint` value specified, for example, `exampleHint`, only those
      // accounts will be shown to the user whose 'login_hints' array contains the `exampleHint`.
      "login_hints": ["demo1", "exampleHint"],
      // This account is labelled. IdP can implement a specific config file for a
      // label, for example, `https://idp.example/developer-config.json`. Like that
      // RPs can filter out accounts by calling `navigator.credentials.get()` with
      // `https://idp.example/developer-config.json` config file.
      "labels": ["hr", "developer"]
    }, {
      "id": "5678",
      "given_name": "Johnny",
      "name": "Johnny",
      "email": "johnny@idp.example",
      "picture": "https://idp.example/profile/456",
      "approved_clients": ["abc", "def", "ghi"],
      "login_hints": ["demo2"],
      "domain_hints": ["@domain.example"]
    }]
  }

Kullanıcı oturum açmadıysa HTTP 401 (Yetkisiz) ile yanıt verin.

Döndürülen hesap listesi tarayıcı tarafından kullanılır ve RP tarafından kullanılamaz.

Kimlik beyanı uç noktası

Kimlik doğrulama sağlayıcının kimlik beyanı uç noktası, oturum açmış kullanıcısı için bir beyan döndürür. Kullanıcı, navigator.credentials.get() çağrısını kullanarak bir RP web sitesinde oturum açtığında tarayıcı, bu uç noktaya aşağıdaki bilgileri içeren bir POST isteği gönderir: SameSite=None çerezleri ve application/x-www-form-urlencoded içerik türü.

Mülk Açıklama
client_id (zorunlu) RP'nin istemci tanımlayıcısı.
account_id (zorunlu) Oturum açan kullanıcının benzersiz kimliği.
disclosure_text_shown Boole değeri yerine "true" veya "false" dizesi döndürür. Aşağıdaki durumlarda sonuç "false" olur:
  • RP'nin istemci kimliği, hesaplar uç noktasından gelen yanıtın approved_clients mülk listesine dahil edildiği için açıklama metni gösterilmediyse.
  • Tarayıcı, geçmişte approved_clients olmadan bir kayıt anı gözlemlediği için açıklama metni gösterilmediyse.
  • fields parametresi üç alandan ("ad", "e-posta" ve "resim") en az birini içermiyorsa (ör. fields=[ ] veya fields=['name', 'picture']). Bu, bir açıklama dizesinin her zaman üç alanın tümünü içermesini bekleyen eski kimlik sağlayıcı uygulamalarıyla geriye dönük uyumluluk için gereklidir.
is_auto_selected RP'de otomatik yeniden kimlik doğrulama gerçekleştirilirse is_auto_selected, "true" değerini gösterir. Aksi takdirde "false". Bu, güvenlikle ilgili daha fazla özelliği desteklememize yardımcı olur. Örneğin, bazı kullanıcılar kimlik doğrulama sırasında kullanıcının açıkça müdahale etmesini gerektiren daha yüksek bir güvenlik katmanını tercih edebilir. Bir kimlik sağlayıcı, bu tür bir uyumlulaştırma olmadan jeton isteği alırsa isteği farklı şekilde işleyebilir. Örneğin, RP'nin FedCM API'yi mediation: required ile tekrar çağırabilmesi için bir hata kodu döndürün.
fields (isteğe bağlı) RP'nin, kimlik sağlayıcının kendisiyle paylaşmasını istediği kullanıcı bilgilerini ("ad", "e-posta", "resim") belirten dize dizisi.
Tarayıcı, aşağıdaki örnekte gösterildiği gibi POST isteğinde belirtilen alanları listeleyen fields, disclosure_text_shown ve disclosure_shown_for öğelerini gönderir.

Not: Alanlar parametresi Chrome 132'den itibaren desteklenir.
params (isteğe bağlı) Ek özel anahtar/değer parametreleri belirtmenize olanak tanıyan geçerli bir JSON nesnesi. Örneğin:
  • scope: RP'nin istemesi gereken ek izinleri içeren bir dize değeri (ör. "drive.readonly calendar.readonly")
  • nonce: Yanıtın bu istek için gönderilmesini sağlamak amacıyla RP tarafından sağlanan rastgele bir dize. Tekrar oynama saldırılarını önler.
  • Diğer özel anahtar/değer çifti parametreleri.
Tarayıcı bir POST isteği gönderdiğinde params değeri JSON olarak serileştirilir ve ardından yüzde kodlanır.

Not: Parameters API, Chrome 132 ve sonraki sürümlerde desteklenir.

Örnek HTTP üst bilgisi: 

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

  // disclosure_text_shown is set to 'false', as the 'name' field value is missing in 'fields' array
  // params value is serialized to JSON and then percent-encoded.
  account_id=123&client_id=client1234&disclosure_text_shown=false&is_auto_selected=true&params=%22%7B%5C%22nonce%5C%22%3A%5C%22nonce-value%5C%22%7D%22.%0D%0A4&disclosure_text_shown=true&fields=email,picture&disclosure_shown_for=email,picture

Sunucu, isteği aldıktan sonra:

  1. İsteğe CORS (Kaynaklar Arası Kaynak Paylaşımı) ile yanıt verin.
  2. İsteğin bir Sec-Fetch-Dest: webidentity HTTP başlığı içerdiğini doğrulayın.
  3. Origin başlığını, client_id tarafından belirlenen RP kaynağıyla eşleştirin. Eşleşmezlerse reddedin.
  4. account_id değerini, oturumu açık olan hesabın kimliğiyle eşleştirin. Eşleşmezse reddedin.
  5. Jetonla yanıt verin. İstek reddedilirse hata yanıtı ile yanıt verin.

Kimlik sağlayıcı, jetonu nasıl yayınlayacağına karar verebilir. Genellikle, RP'nin jetonun orijinal olduğunu doğrulayabilmesi için hesap kimliği, istemci kimliği, veren kaynağı ve tek seferlik sayı gibi bilgilerle imzalanır.

Tarayıcı, aşağıdaki özelliği içeren bir JSON yanıtı bekler:

Mülk Açıklama
token Jeton, kimlik doğrulamayla ilgili iddiaları içeren bir dizedir.
continue_on Çok adımlı oturum açma akışını etkinleştiren yönlendirme URL'si.

Döndürülen jeton, tarayıcı tarafından RP'ye iletilir. Böylece RP, kimlik doğrulamayı doğrulayabilir.

  {
    // IdP can respond with a token to authenticate the user
    "token": "***********"
  }
Devam et özelliği

IdP, çok adımlı bir oturum açma akışı etkinleştirmek için kimlik beyanı uç noktası yanıtında bir yönlendirme URL'si sağlayabilir. Bu seçenek, kimlik sağlayıcının ek bilgi veya izin istemesi gerektiğinde kullanışlıdır. Örneğin:

  • Kullanıcının sunucu tarafı kaynaklarına erişim izni.
  • İletişim bilgilerinin güncel olduğunun doğrulanması.
  • Ebeveyn denetimleri.

Kimlik beyanı uç noktası, kimlik beyanı uç noktasının mutlak 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 popup window:
    "continue_on": "https://idp.example/continue_on_url"
  }

Yanıt continue_on parametresini içeriyorsa yeni bir pop-up pencere açılır ve kullanıcıyı belirtilen yola yönlendirir. Kullanıcı continue_on sayfasıyla etkileşime geçtikten sonra, IdP, orijinal navigator.credentials.get() çağrısından gelen promise'in çözülebilmesi için jetonu bağımsız değişken olarak ileterek IdentityProvider.resolve()'i çağırmalıdır:

  document.getElementById('example-button').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'ı otomatik olarak kapatır ve jetonu API çağırıcıya döndürür. Üst pencerenin (RP) ve pop-up pencerenin (IdP) iletişim kurmasının tek yolu tek seferlik bir IdentityProvider.resolve() çağrısıdır.
Kullanıcı isteği reddederse kimlik sağlayıcı, IdentityProvider.close() çağrısını yaparak pencereyi kapatabilir.

  IdentityProvider.close();

Continuation API'nin çalışması için kullanıcının açık bir şekilde etkileşimde bulunması (tıklama yapması) gerekir. Devam API'sinin farklı arabuluculuk modlarıyla işleyiş şekli aşağıda açıklanmıştır:

  • Pasif modda:
    • mediation: 'optional' (varsayılan): Devam API'si yalnızca sayfadaki veya FedCM kullanıcı arayüzündeki bir düğmenin tıklanması gibi bir kullanıcı hareketiyle çalışır. Otomatik yeniden kimlik doğrulama, kullanıcı hareketi olmadan tetiklendiğinde pop-up pencere açılmaz ve söz reddedilir.
    • mediation: 'required': Kullanıcıdan her zaman etkileşim kurmasını ister. Bu nedenle, Continuation API her zaman çalışır.
  • Etkin modda:
    • Kullanıcı etkinleştirmesi her zaman gereklidir. Continuation API uyumludur.

Kullanıcı herhangi bir nedenle pop-up'ta hesabını değiştirdiyse (örneğin, kimlik sağlayıcı "başka hesabı kullan" işlevi sunuyorsa veya yetki verme durumlarında) resolve çağrısı, isteğe bağlı ikinci bir bağımsız değişken alır. Bu bağımsız değişken, aşağıdaki gibi bir işleme olanak tanır:

  IdentityProvider.resolve(token, {accountId: '1234');
Hata yanıtı döndürme

id_assertion_endpoint, iki isteğe bağlı alana sahip bir "error" yanıtı da döndürebilir:

  • code: IdP, OAuth 2.0'da belirtilen hata listesinden bilinen hatalardan birini (invalid_request, unauthorized_client, access_denied, server_error ve temporarily_unavailable) seçebilir veya herhangi bir dize kullanabilir. İkinci durumda Chrome, hata kullanıcı arayüzünü genel bir hata mesajıyla oluşturur ve kodu RP'ye iletir.
  • url: Kullanıcılara hata hakkında ek bilgi sağlamak için hatayla ilgili bilgiler içeren, kullanıcı tarafından okunabilen bir web sayfasını tanımlar. Tarayıcılar yerleşik kullanıcı arayüzünde zengin hata mesajları sağlayamadığından bu alan kullanıcılar için yararlıdır. Örneğin, sonraki adımlara yönlendiren bağlantılar veya müşteri hizmetleri iletişim bilgileri. Kullanıcı, hata ayrıntıları ve hatanın nasıl düzeltileceği hakkında daha fazla bilgi edinmek isterse daha fazla ayrıntı için tarayıcı kullanıcı arayüzünden sağlanan sayfayı ziyaret edebilir. URL, configURL kimlik sağlayıcısıyla aynı sitede olmalıdır.
  // id_assertion_endpoint response
  {
    "error" : {
      "code": "access_denied",
      "url" : "https://idp.example/error?type=access_denied"
    }
  }

Özel Hesap Etiketleri

Özel hesap etiketleri sayesinde kimlik sağlayıcı, kullanıcı hesaplarına etiket eklenebilir ve RP, belirli bir etiket için configURL değerini belirterek yalnızca belirli etiketlere sahip hesapları getirmeyi seçebilir. Bu, bir RP'nin hesapları belirli ölçütlere göre filtrelemesi gerektiğinde (ör. yalnızca "developer" veya "hr" gibi role özel hesapları görüntülemek için) yararlı olabilir.

navigator.credentials.get() çağrısında Alan İpucu ve Giriş İpucu özelliklerini kullanarak benzer bir filtreleme yapabilirsiniz. Ancak özel hesap etiketleri, yapılandırma dosyasını belirterek kullanıcıları filtreleyebilir. Bu özellik özellikle birden fazla configURL kullanıldığında kullanışlı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.

"developer" ve "hr" hesapları arasında ayrım yapmak isteyen bir kimlik sağlayıcıyı düşünün. Bunun için IdP'nin sırasıyla "developer" ve "hr" için iki configURL desteklemesi gerekir:

  • Geliştirici yapılandırma dosyası https://idp.example/developer/fedcm.json'te "developer" etiketi, kurumsal yapılandırma dosyası https://idp.example/hr/fedcm.json'de ise aşağıdaki gibi bir "hr" etiketi bulunur:
  // The developer config file at `https://idp.example/developer/fedcm.json`
  {
    "accounts_endpoint": "https://idp.example/accounts",
    "client_metadata_endpoint": "/client_metadata",
    "login_url": "https://idp.example/login",
    "id_assertion_endpoint": "/assertion",
    "accounts": {
      // Account label
      "include": "developer"
    }
  }

  // The hr config file at `https://idp.example/hr/fedcm.json`
  {
    "accounts_endpoint": "https://idp.example/accounts",
    "client_metadata_endpoint": "/client_metadata",
    "login_url": "https://idp.example/login",
    "id_assertion_endpoint": "/assertion",
    "accounts": {
      // Account label
      "include": "hr"
    }
  }
  • Böyle bir kurulumda, birden fazla configURL'ye izin vermek için well-known dosyası accounts_endpoint ve login_url içermelidir:
  {
    "provider_urls": [ "https://idp.example/fedcm.json" ],
    "accounts_endpoint": "https://idp.example/accounts",
    "login_url": "https://idp.example/login"
  }
  • Ortak kimlik sağlayıcı hesaplar uç noktası (bu örnekte https://idp.example/accounts), her hesap için bir dizi içinde atanan etiketlere sahip bir labels mülkünü içeren hesapların listesini döndürür:
  {
  "accounts": [{
    "id": "123",
    "given_name": "John",
    "name": "John Doe",
    "email": "john_doe@idp.example",
    "picture": "https://idp.example/profile/123",
    "labels": ["developer"]
    }], [{
    "id": "4567",
    "given_name": "Jane",
    "name": "Jane Doe",
    "email": "jane_doe@idp.example",
    "picture": "https://idp.example/profile/4567",
    "labels": ["hr"]
    }]
  }

Bir RP, "hr" kullanıcılarının oturum açmasına izin vermek istediğinde navigator.credentials.get() çağrısında configURL https://idp.example/hr/fedcm.json değerini belirtebilir:

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

Sonuç olarak, kullanıcının oturum açması için yalnızca 4567 hesabının kimliği kullanılabilir. Kullanıcıya bu sitedeki IdP tarafından desteklenmeyen bir hesap sunulmaması için 123 kimlikli hesap, tarayıcı tarafından sessizce gizlenir.

  • Etiketler dizedir. labels dizisi veya include alanı dize olmayan bir şey içeriyorsa yoksayılır.
  • configURL parametresinde etiket belirtilmezse FedCM hesap seçicide tüm hesaplar gösterilir.
  • Bir hesap için etiket belirtilmezse bu hesap, yalnızca configURL de etiket belirtmezse hesap seçicide gösterilir.
  • Pasif modda istenen etiketle eşleşen bir hesap yoksa (Alan adı ipucu özelliğine benzer şekilde) FedCM iletişim kutusunda, kullanıcının bir IdP hesabında oturum açmasına olanak tanıyan bir giriş istemi gösterilir. Etkin modda, giriş pop-up penceresi doğrudan açılır.

Uç noktanın bağlantısını kesme

Tarayıcı, IdentityCredential.disconnect() çağrısı yaparak bu bağlantı kesme uç noktasına SameSite=None çerezleri ve application/x-www-form-urlencoded içerik türü içeren bir kaynakta çapraz POST isteği gönderir. Bu istek aşağıdaki bilgileri içerir:

Mülk Açıklama
account_hint IdP hesabıyla ilgili ipucu.
client_id RP'nin istemci tanımlayıcısı. 
  POST /disconnect.example HTTP/1.1
  Host: idp.example
  Origin: rp.example
  Content-Type: application/x-www-form-urlencoded
  Cookie: 0x123
  Sec-Fetch-Dest: webidentity

  account_hint=account456&client_id=rp123

Sunucu, isteği aldıktan sonra:

  1. İsteğe CORS (Kaynaklar Arası Kaynak Paylaşımı) ile yanıt verin.
  2. İsteğin bir Sec-Fetch-Dest: webidentity HTTP başlığı içerdiğini doğrulayın.
  3. Origin başlığını, client_id tarafından belirlenen RP kaynağıyla eşleştirin. Eşleşmezlerse reddedin.
  4. account_hint kimliğini, oturum açmış hesapların kimlikleriyle eşleştirin.
  5. Kullanıcı hesabının RP ile bağlantısını kesin.
  6. Tanımlanmış kullanıcı hesabı bilgilerini JSON biçiminde tarayıcıya yanıt olarak gönderin.

Örnek bir yanıt JSON yükü şöyle görünür:

  {
    "account_id": "account456"
  }

Bunun yerine, kimlik sağlayıcı, tarayıcının RP ile ilişkili tüm hesapların bağlantısını kesmesini istiyorsa herhangi bir hesap kimliğiyle eşleşmeyen bir dize (ör. "*") iletmelidir.

İstemci meta veri uç noktası

Kimlik sağlayıcının istemci meta veri uç noktası, güvenen tarafın meta verilerini (ör. güvenen tarafın gizlilik politikası, hizmet şartları ve logo simgeleri) döndürür. RP'ler, gizlilik politikalarının ve hizmet şartlarının bağlantılarını IdP'ye önceden sağlamalıdır. Bu bağlantılar, kullanıcı henüz IdP ile RP'ye kaydolmamışsa oturum açma iletişim kutusunda gösterilir.

Tarayıcı, çerez olmadan client_id navigator.credentials.get kullanarak bir GET isteği gönderir. Örneğin:

  GET /client_metadata.example?client_id=1234 HTTP/1.1
  Host: accounts.idp.example
  Origin: https://rp.example/
  Accept: application/json
  Sec-Fetch-Dest: webidentity

Sunucu, isteği aldıktan sonra:

  1. client_id için RP'yi belirleyin.
  2. İstemci meta verilerini ekleyerek yanıt verin.

Müşteri meta verisi uç noktasının özellikleri şunlardır:

Mülk Açıklama
privacy_policy_url (isteğe bağlı) RP gizlilik politikası URL'si.
terms_of_service_url (isteğe bağlı) RP hizmet şartları URL'si.
icons (isteğe bağlı) Nesne dizisi (ör. [{ "url": "https://rp.example/rp-icon.ico", "size": 40}])

Tarayıcı, uç noktadan bir JSON yanıtı bekler:

  {
    "privacy_policy_url": "https://rp.example/privacy_policy.html",
    "terms_of_service_url": "https://rp.example/terms_of_service.html",
    "icons": [{
          "url": "https://rp.example/rp-icon.ico",
          "size": 40
      }]
  }

Döndürülen istemci meta verileri tarayıcı tarafından kullanılır ve RP tarafından kullanılamaz.

Giriş URL'si

Bu uç nokta, kullanıcının IdP'de oturum açmasına izin vermek için kullanılır.

Giriş Durumu API'si ile IdP, kullanıcının giriş durumunu tarayıcıya bildirmelidir. Ancak durum, oturumun süresi dolduğunda senkronize olmayabilir. Böyle bir senaryoda tarayıcı, idp yapılandırma dosyasının login_url parametresinde belirtilen giriş sayfası URL'si aracılığıyla kullanıcının IdP'de dinamik olarak oturum açmasına izin verebilir.

FedCM iletişim kutusunda, aşağıdaki resimde gösterildiği gibi oturum açmanızı öneren bir mesaj görüntülenir.

A
IdP'de oturum açmayı öneren bir FedCM iletişim kutusu.

Kullanıcı Devam düğmesini tıkladığında tarayıcı, kimlik sağlayıcının giriş sayfası için bir pop-up pencere açar.

FedCM iletişim kutusu örneği.
IdP'de oturum aç düğmesi tıklandıktan sonra gösterilen örnek iletişim kutusu.

İletişim kutusu, birinci taraf çerezleri içeren normal bir tarayıcı penceresidir. İletişim kutusunda ne olursa olsun IdP'ye bağlıdır ve RP sayfasına kaynaktan bağımsız iletişim isteği göndermek için pencere tutamaçlarına erişilemez. Kullanıcı oturum açtıktan sonra IdP:

  • Tarayıcıya kullanıcının oturum açtığını bildirmek için Set-Login: logged-in üstbilgisini gönderin veya navigator.login.setStatus("logged-in") API'sini çağırın.
  • İletişim kutusunu kapatmak için IdentityProvider.close() numaralı telefonu arayın.
Kullanıcı, FedCM'yi kullanarak IdP'de oturum açtıktan sonra bir RP'de oturum açar.

Tarayıcıyı kullanıcının giriş durumu hakkında bilgilendirme

Giriş Durumu API'si, bir web sitesinin (özellikle de kimlik sağlayıcının) tarayıcıyı kullanıcının kimlik sağlayıcıdaki giriş durumu hakkında bilgilendirdiği bir mekanizmadır. Tarayıcı, bu API ile kimlik sağlayıcıya yapılan gereksiz istekleri azaltabilir ve potansiyel zamanlama saldırılarını azaltabilir.

Kimlik sağlayıcılar, kullanıcı IdP'de oturum açtığında veya tüm IdP hesaplarından oturumu kapattığında bir HTTP başlığı göndererek ya da bir JavaScript API'yi çağırarak kullanıcının giriş durumunu tarayıcıya bildirebilir. Tarayıcı, her IdP (yapılandırma URL'si ile tanımlanır) için giriş durumunu temsil eden üç durumlu bir değişken tutar. Bu değişkenin olası değerleri şunlardır:

  • logged-in
  • logged-out
  • unknown (varsayılan)
Giriş durumu Açıklama
logged-in Kullanıcının giriş durumu logged-in olarak ayarlandığında, FedCM'yi çağıran RP, IdP'nin hesap uç noktasına istek gönderir ve FedCM iletişim kutusunda kullanıcıya mevcut hesapları gösterir.
logged-out Kullanıcının giriş durumu logged-out olduğunda, FedCM çağrısı, kimlik sağlayıcının hesap uç noktasına istek göndermeden sessizce başarısız olur.
unknown (varsayılan) unknown durumu, IdP Login Status API'yi kullanarak sinyal göndermeden önce ayarlanır. Durum unknown olduğunda tarayıcı, kimlik sağlayıcının hesap uç noktasına istek gönderir ve durumu, hesap uç noktasından gelen yanıta göre günceller.

Kullanıcının oturum açtığını belirtmek için üst düzey gezinme bölümünde bir Set-Login: logged-in HTTP başlığı veya IdP kaynağında aynı sitedeki bir alt kaynak isteği gönderin:

  Set-Login: logged-in

Alternatif olarak, üst düzey gezinme menüsündeki IdP kaynağından navigator.login.setStatus('logged-in')JavaScript yöntemini çağırabilirsiniz:

  navigator.login.setStatus('logged-in')

Kullanıcının giriş durumu logged-in olarak ayarlanır.

Kullanıcının tüm hesaplarında oturumunun kapatıldığını belirtmek için üst düzey bir gezinme bölümünde Set-Login: logged-out HTTP başlığı veya IdP kaynağında aynı sitedeki bir alt kaynak isteği gönderin:

  Set-Login: logged-out

Alternatif olarak, üst düzey gezinme menüsündeki kimlik sağlayıcı kaynağından JavaScript API'yi navigator.login.setStatus('logged-out')çağırabilirsiniz:

  navigator.login.setStatus('logged-out')

Kullanıcının giriş durumu logged-out olarak ayarlanır.

unknown durumu, IdP Login Status API'yi kullanarak sinyal göndermeden önce ayarlanır. Tarayıcı, kimlik sağlayıcının hesap uç noktasına bir istek gönderir ve durumu, hesap uç noktasından gelen yanıta göre günceller:

  • Uç nokta, etkin hesapların listesini döndürürse durumu logged-in olarak güncelleyin ve bu hesapları göstermek için FedCM iletişim kutusunu açın.
  • Bitiş noktası hiçbir hesap döndürmezse durumu logged-out olarak güncelleyin ve FedCM çağrısını başarısız kılın.

Kullanıcının dinamik bir giriş akışı üzerinden oturum açmasına izin verme

IdP, kullanıcının giriş durumunu tarayıcıya bildirmeye devam etse de oturum sona erdiğinde olduğu gibi senkronizasyonda sorun olabilir. Giriş durumu logged-in olduğunda tarayıcı, hesap uç noktasına kimlik bilgisi içeren bir istek göndermeye çalışır ancak oturum artık kullanılamadığı için sunucu hiçbir hesap döndürmez. Bu gibi durumlarda tarayıcı, kullanıcının pop-up pencere aracılığıyla IdP'de dinamik olarak oturum açmasına izin verebilir.

FedCM'yi RP olarak uygulama

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
FedCM iletişim kutusunun kullanıcı arayüzü bileşenlerini açıklayan şema: Sol üst tarafta bir simge gösterilir. Simgenin sağ tarafında, "RP'de IdP ile oturum aç" mesajını gösteren bir içerik bileşeni bulunur. En altta, özel metin ve arka plan rengine sahip bir "Devam et" düğmesi bulunur.
FedCM iletişim kutusuna marka öğeleri nasıl uygulanır?

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

Özelleştirilmiş bir bağlam mesajı gösteren FedCM iletişim kutusu: FedCM ile "Oturum aç" yerine "Kullan" FedCM ifadesi gösterilir.
Özelleştirilmiş bir bağlam mesajı gösteren FedCM iletişim kutusu.

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:

Mülk Açıklama
configURL (zorunlu) IdP yapılandırma dosyasının tam yolu.
clientId (zorunlu) IdP tarafından verilen RP istemci tanımlayıcısı.
nonce (isteğe bağlı) Yanıtın bu istek için gönderilmesini sağlamak amacıyla rastgele bir dize. Tekrar oynama saldırılarını önler.
loginHint (isteğe bağlı) FedCM iletişim kutusu, hesap uç noktaları tarafından sağlanan login_hints değerlerinden birini belirterek belirtilen hesabı seçerek gösterir.
domainHint (isteğe bağlı) FedCM iletişim kutusu, hesap uç noktaları tarafından sağlanan domain_hints değerlerinden birini belirterek belirtilen hesabı seçerek gösterir.
mode (isteğe bağlı) FedCM'nin kullanıcı arayüzü modunu belirten dize. Aşağıdaki değerlerden biri olabilir:
  • "active": FedCM istemi, kullanıcı etkileşimi (ör. bir düğmenin tıklanması) ile başlatılmalıdır.
  • "passive": FedCM istemi, doğrudan kullanıcı etkileşimi olmadan başlatılır.
Etkin ve pasif modlar arasındaki fark hakkında daha fazla bilgi edinmek için genel bakış sayfasını inceleyin.

Not: mode parametresi Chrome 132'den itibaren desteklenir.
fields (isteğe bağlı) RP'nin, kimlik sağlayıcının kendisiyle paylaşmasını istediği kullanıcı bilgilerini ("ad", "e-posta", "resim") belirten dize dizisi.
Not: Field API, Chrome 132 ve sonraki sürümlerde desteklenir.
parameters (isteğe bağlı) Ek anahtar/değer parametreleri belirtmenize olanak tanıyan özel nesne:
  • scope: RP'nin istemesi gereken ek izinleri içeren bir dize değeri (ör. "drive.readonly calendar.readonly")
  • nonce: Yanıtın bu istek için gönderilmesini sağlamak amacıyla rastgele bir dize. Tekrar oynama saldırılarını önler.
  • Diğer özel anahtar/değer çifti parametreleri.

Not: parameters, Chrome 132'den itibaren desteklenir.

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ılabilirliğini 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'den ç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 örnek üzerinden inceleyebilirsiniz.

İsteğe bağlı olarak, üst çerçeve FedCM'yi çağıracak kaynakları kısıtlamak istiyorsa 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.

domainHint ile eşleşen hesap olmadığında gösterilen örnek giriş istemi.
domainHint ile eşleşen hesap olmadığında gösterilen örnek giriş istemi.

Ö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 bir nesne olarak params mülküne 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.

Açıklama mesajı gösteren FedCM etkin mod iletişim kutusu. Devam etmek için kimlik sağlayıcı, kullanıcının e-posta adresini ve profil resmini web sitesiyle paylaşır.
Etkin modda açıklama mesajı: RP, kimlik sağlayıcıdan yalnızca kullanıcının e-posta adresini ve profil resmini paylaşmasını ister.

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 'name', 'email' ve 'picture' olmak üzere üç alanın tamamını 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.

Bilgilendirme kullanıcı arayüzü mesajı göstermeyen FedCM pasif mod iletişim kutusu.
Açıklama mesajı, pasif modda gösterilmez. Düğme akışında, açıklama kullanıcı arayüzü tamamen atlanıyor.

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.

A
Kullanıcının oturum açma girişimi başarısız olduktan sonra hata mesajını gösteren FedCM iletişim kutusu. Dize, hata türüyle ilişkilidir.
  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 olanak tanıyabilir. 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.

Belirli bir kullanıcı deneyimi, kullanıcı izlemeyi önlemek için birleşik hesabı oluşturmadan önce (FedCM'nin ana hedeflerinden biri) anlamlı olsa da 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 et" düğmesini tıklama). Kullanıcılarınızın kimlik doğrulamanın gerektiği her seferinde 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 seçenek kullanılamadığında kullanıcıdan mediation: required içeren bir akış olan açık kullanıcı aracılığı ile oturum açması istenebilir.

FedCM üzerinden otomatik olarak kimliğini doğrulayan bir kullanıcı.

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. Bağlantıyı kesme uç noktası hesabı tanımlayabileceği sürece hesap ipucu 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 içinden ç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.