Kimlik sağlayıcı tarafında FedCM ile kimlik çözümü uygulama

FedCM uygulaması hem Kimlik Sağlayıcı (IdP) hem de Bağımlı Taraf (RP) için çeşitli temel adımlar içerir. FedCM'yi RP tarafında nasıl uygulayacağınızı öğrenmek için dokümanlara bakın.

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

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 sayede, her yapılandırma dosyası aynı login_url ve accounts_endpoint URL'sini kullandığı sürece birden fazla yapılandırma desteği sağlanabilir.

Not: Parametre, Chrome 132'den itibaren desteklenmektedir.
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 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 IdP'nin birden fazla farklı test ve üretim yapılandırmasını desteklemesi gerekir.
  • Bir IdP'nin bölgeye göre farklı yapılandırmaları (ör. 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) IdP'nin accounts_endpoint ve login_url parametrelerini 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. IDP'ler 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ü ile sunulmalıdır.

Yapılandırma dosyasının URL'si, bir RP üzerinde 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 sayede, kimlerin istek gönderdiğini ve hangi RP'nin bağlantı kurmaya çalıştığını öğrenmesi engellenir. Ö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.

Not: Özel hesap etiketleri Chrome 132'den itibaren desteklenir.
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 başka hesaplar seçebilmesi için IdP'nin 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 özelliklere sahip bir hesap bilgileri dizisi içeren 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.

Not: Özel hesap etiketleri, Chrome 132'den itibaren desteklenir.

Ö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 şekilde 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 belirli 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

Kimlik sağlayıcı, çok adımlı bir oturum açma akışı etkinleştirmek için kimlik beyanı uç noktasındaki yanıtta bir yönlendirme URL'si sağlayabilir. Bu, 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()'u ç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. Ana 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, IdP "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 okunabilir 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 faydalıdır. Örneğin: sonraki adımlara yönlendiren bağlantılar veya müşteri hizmetleri iletişim bilgileri. Kullanıcılar, hata ayrıntıları ve hatanın nasıl düzeltileceği hakkında daha fazla bilgi edinmek 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 etiketlerle ek açıklama ekleyebilir 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, özellikle birden fazla yapılandırma URL'si 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 içinde etiket belirtilmezse tüm hesaplar FedCM hesap seçicide gösterilir.
  • Bir hesap için etiket belirtilmezse hesap seçicide yalnızca configURL de etiket belirtmezse gösterilir.
  • Pasif modda istenen etiketle eşleşen bir hesap yoksa (Domain Hint ö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ı önceden kimlik sağlayıcıya 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_idnavigator.credentials.get 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çma 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ıya kullanıcının giriş durumu hakkında bilgi verme

Giriş Durumu API'si, bir web sitesinin (özellikle de kimlik sağlayıcının) tarayıcıya kullanıcının kimlik sağlayıcıdaki giriş durumunu bildirdiğ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 oturum 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 IdP kaynağında üst düzey gezinme veya aynı sitedeki alt kaynak isteğinde Set-Login: logged-in HTTP başlığı gönderin:

  Set-Login: logged-in

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

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

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

unknown durumu, IdP'nin Oturum Durumu API'sini kullanarak sinyal göndermesinden önce ayarlanır. Tarayıcı, kimlik sağlayıcının hesap uç noktasına bir istek gönderir ve hesap uç noktasından gelen yanıta göre durumu 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.

Next steps

Implement FedCM for your RPs and distribute the JavaScript SDK. Keep RPs up-to-date by eliminating the need for self-implementation.
Learn how to setup your enviromnemt and debug your implementation.