Birleşik Kimlik Bilgisi Yönetimi API'si geliştirici kılavuzu

Gizliliği korumaya yönelik kimlik federasyonu için FedCM'yi nasıl kullanacağınızı öğrenin.

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

FedCM kullanım alanları, kullanıcı akışları ve API yol haritası hakkında daha fazla bilgi edinmek için FedCM API'ye giriş sayfasına göz atın.

FedCM geliştirme ortamı

FedCM'yi kullanmak için Chrome'da hem kimlik sağlayıcıda hem de RP'de güvenli bir bağlama (HTTPS veya localhost) ihtiyacınız vardır.

Android'de Chrome'da kod hata ayıklama

FedCM kodunuzdaki hataları ayıklamak için yerel olarak bir sunucu oluşturup çalıştırın. Bağlantı noktası yönlendirmeli USB kablosuyla bağlanmış bir Android cihazdan Chrome'da bu sunucuya erişebilirsiniz.

Android cihazlarda uzaktan hata ayıklama başlıklı makaledeki talimatları uygulayarak Android'de Chrome'da hata ayıklama için masaüstünde Geliştirici Araçları'nı kullanabilirsiniz.

Chrome'da üçüncü taraf çerezlerini engelleme

Chrome'u üçüncü taraf çerezlerini engelleyecek şekilde yapılandırarak üçüncü taraf çerezlerinin kullanımdan kaldırılmasını simüle etme
Chrome'u üçüncü taraf çerezlerini engelleyecek şekilde yapılandırarak üçüncü taraf çerezlerinin kullanımdan kaldırılmasını simüle etme

FedCM'nin, Chrome'da üçüncü taraf çerezleri olmadan nasıl çalıştığını gerçekten uygulanmadan önce test edebilirsiniz.

Üçüncü taraf çerezlerini engellemek için Gizli modu kullanın veya chrome://settings/cookies adresindeki masaüstü ayarlarınızdan "Üçüncü taraf çerezlerini engelle"yi seçin ya da mobil cihazınızda Ayarlar > Site ayarları > Çerezler'e giderek bu seçeneği belirleyin.

FedCM API'sini kullanma

Hesap listesi, iddia yayınlama ve isteğe bağlı olarak istemci meta verileri için tanınmış bir dosya, yapılandırma dosyası ve uç noktalar oluşturarak FedCM ile entegrasyon gerçekleştirirsiniz.

FedCM, buradan RP'lerin IdP ile oturum açmak için kullanabileceği JavaScript API'lerini gösterir.

İyi bilinen bir dosya oluşturma

İzleyicilerin API'yi kötüye kullanmasını önlemek için IdP'nin /.well-known/web-identity eTLD+1 kısmından iyi bilinen bir dosya sunulmalıdır.

Örneğin, IdP uç noktaları https://accounts.idp.example/ altında sunuluyorsa https://idp.example/.well-known/web-identity adresinde iyi bilinen bir dosya ve IdP yapılandırma dosyası sunmaları gerekir. İyi bilinen bir dosya içeriği örneği:

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

JSON dosyası, RP'ler tarafından navigator.credentials.get içinde configURL'in bir yol parçası olarak belirtilebilecek IdP yapılandırma dosyası URL'leri dizisi içeren provider_urls mülkünü içermelidir. Dizideki URL dizesi sayısı 1 ile sınırlıdır ancak bu sayı ileride geri bildiriminizle değişebilir.

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 bu yapılandırma dosyasını ve gerekli uç noktaları ile URL'leri barındırı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;

configURL olarak IdP yapılandırma dosyası konumunun tam URL'sini belirtin. RP'de navigator.credentials.get() çağrıldığında tarayıcı, Origin veya Referer başlığı olmadan GET isteğiyle yapılandırma dosyasını getirir. İstek çerez içermiyor ve yönlendirmeleri takip etmiyor. 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

Tarayıcı, IdP'den aşağıdaki özellikleri içeren bir JSON yanıtı bekler:

Mülk Açıklama
accounts_endpoint (zorunlu) Hesaplar uç noktasının URL'si.
client_metadata_endpoint (isteğe bağlı) İstemci meta veri uç noktasının URL'si.
id_assertion_endpoint (zorunlu) Kimlik onayı 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. Alakalı 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ı) Oturum açma iletişim kutusunda görüntülenen simge nesnesini ayarlayan markalaşma seçeneği. Simge nesnesi, iki parametreye sahip bir dizidir:
  • 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üklü olduğu varsayılan simge boyutları. Bu sayı 25'ten büyük veya 25'e eşit olmalıdır.

RP, önceden tanımlanmış kimlik doğrulama bağlamlarını karşılamak için navigator.credentials.get() için identity.context değeri aracılığıyla FedCM iletişim kutusu kullanıcı arayüzündeki dizeyi değiştirebilir. İsteğe bağlı özellik şunlardan biri olabilir: "signin" (varsayılan), "signup", "use" veya "continue".

Marka bilinci oluşturma, FedCM iletişim kutusuna nasıl uygulanır?
FedCM iletişim kutusuna marka öğeleri nasıl uygulanır?

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

{
  "accounts_endpoint": "/accounts.php",
  "client_metadata_endpoint": "/client_metadata.php",
  "id_assertion_endpoint": "/assertion.php",
  "disconnect_endpoint": "/disconnect.php",
  "login_url": "/login",
  "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, sonraki istekleri IdP uç noktalarına gönderir:

IdP uç noktaları
IdP uç noktaları

Hesaplar uç noktası

IdP'nin hesap uç noktası, kullanıcının şu anda IdP'de oturum açtığı hesapların listesini döndürür. IdP birden fazla hesabı destekliyorsa bu uç nokta, oturum açılmış 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.php HTTP/1.1
Host: accounts.idp.example
Accept: application/json
Cookie: 0x23223
Sec-Fetch-Dest: webidentity

İsteği aldıktan sonra sunucu şunları yapmalıdır:

  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 dizi hesap bilgisine sahip bir accounts mülkü içeren 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 kaydolduğu bir RP istemci kimliği dizisi.
login_hints (isteğe bağlı) IdP'nin bir hesabı belirtmek için desteklediği tüm filtre türlerinin dizisi. Kısıtlanmış taraf, belirtilen hesabı seçmeli olarak göstermek için loginHint mülküyle navigator.credentials.get() komutunu çağırabilir.
domain_hints (isteğe bağlı) Hesabın ilişkili olduğu tüm alan adlarının bir dizisi. Kısıtlanmış taraf, hesapları filtrelemek için domainHint mülküyle navigator.credentials.get() komutunu çağırabilir.

Ö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",
    "approved_clients": ["123", "456", "789"],
    "login_hints": ["demo1", "demo1@idp.example"]
  }, {
    "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", "demo2@idp.example"],
    "domain_hints": ["corp.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.

İstemci meta verisi uç noktası

IdP'nin istemci meta veri uç noktası, bağlı tarafın meta verilerini (ör. RP'nin gizlilik politikası ve hizmet şartları) 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 Kısıtlanmış Taraf'a kaydolmadığında 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.php?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.

İstemci meta veri 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.

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",
}

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

Kimlik onayı 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.
nonce (isteğe bağlı) Kısıtlanmış taraf tarafından sağlanan tek seferlik istek.
disclosure_text_shown Sonuçlar, "true" veya "false" dizesiyle (boole yerine) elde edilir. Açıklama metni gösterilmediyse sonuç "false" olur. Kısıtlanmış tarafın istemci kimliği, hesap uç noktasından gelen yanıtın approved_clients özellik listesine eklendiğinde veya tarayıcı geçmişte approved_clients yokken bir kayıt anı gözlemlediğinde bu durum gerçekleşir.
is_auto_selected RP'de otomatik yeniden kimlik doğrulama gerçekleştirilirse is_auto_selected, "true" değerini gösterir. Diğer durumlarda "false". Bu, güvenlikle ilgili daha fazla özelliğin desteklenmesine 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 IdP, böyle bir uyumlulaştırma olmadan jeton isteği alırsa isteği farklı şekilde işleyebilir. Örneğin, kısıtlanmış tarafın FedCM API'yi mediation: required ile tekrar çağırabileceği bir hata kodu döndürün.

Örnek HTTP üst bilgisi:

POST /assertion.php HTTP/1.1
Host: accounts.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=Ct60bD&disclosure_text_shown=true&is_auto_selected=true

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şmiyorlarsa reddedin.
  4. account_id öğesini, halihazırda oturum açmış olan hesabın kimliğiyle eşleştirin. Eşleşmiyorlarsa reddedin.
  5. Jeton kullanarak yanıt ver. İstek reddedilirse hata yanıtı ile yanıt verin.

Jetonun nasıl verileceği IdP'ye bağlıdır, ancak genellikle hesap kimliği, istemci kimliği, kartı verenin kaynağı, nonce gibi bilgilerle imzalanır. Böylece, kısıtlanmış taraf, jetonun orijinal olduğunu doğrulayabilir.

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

Mülk Açıklama
token (zorunlu) Jeton, kimlik doğrulamayla ilgili hak taleplerini içeren bir dizedir. 
{
  "token": "***********"
}

Döndürülen jeton, RP'nin kimlik doğrulamayı doğrulayabilmesi için tarayıcı tarafından RP'ye iletilir.

Hata yanıtı döndürme

id_assertion_endpoint, iki isteğe bağlı alanı olan bir "hata" yanıtı da döndürebilir:

  • code: IdP, OAuth 2.0 belirtilen hata listesindeki (invalid_request, unauthorized_client, access_denied, server_error ve temporarily_unavailable) bilinen hatalardan birini seçebilir veya rastgele 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ıların okuyabileceği bir web sayfasını tanımlar. Tarayıcılar yerel bir 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ımlar için bağlantılar, müşteri hizmetleri iletişim bilgileri vb. Kullanıcılar 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, IdP configURL ile aynı siteye ait olmalıdır.
// id_assertion_endpoint response
{
  "error" : {
     "code": "access_denied",
     "url" : "https://idp.example/error?type=access_denied"
  }
}

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

IdentityCredential.disconnect() çağrıldığında tarayıcı, bu bağlantı kaldırma uç noktasına aşağıdaki bilgileri içeren SameSite=None ve application/x-www-form-urlencoded türünde içerik türü çerezleri içeren bir çapraz kaynak POST isteği gönderir:

Mülk Açıklama
account_hint IdP hesabıyla ilgili ipucu.
client_id RP'nin istemci tanımlayıcısı. 
POST /disconnect.php 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 öğesini, halihazırda oturum açmış durumdaki 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 kullanarak tarayıcıya yanıt verin.

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

{
  "account_id": "account456"
}

Bunun yerine, IdP, 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. "*") iletin.

Giriş URL'si

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ı, kullanıcının idp config dosyası login_url ile belirtilen giriş sayfası URL'si üzerinden IdP'de dinamik bir şekilde oturum açmasına izin verebilir.

FedCM iletişim kutusunda, aşağıdaki resimde gösterildiği gibi oturum açmayı ö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.

Örnek bir FedCM iletişim kutusu.
IdP'de oturum açma düğmesini tıkladıktan sonra gösterilen örnek iletişim kutusu.

İletişim kutusu, birinci taraf çerezlerine sahip 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 kimlik sağlayıcıdaki giriş durumu hakkında bilgilendirin

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. Bu API ile tarayıcı, IdP'ye gönderilen gereksiz istekleri azaltabilir ve olası zamanlama saldırılarını hafifletebilir.

IdP'ler, bir HTTP üst bilgisi göndererek veya kullanıcı IdP'de oturum açtığında ya da kullanıcı tüm IdP hesaplarındaki oturumlarını kapattığında bir JavaScript API ç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 logged-in, logged-out ve unknown olası değerleriyle giriş durumunu temsil eden üç durumlu bir değişken tutar. Varsayılan durum unknown şeklindedir.

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

Set-Login: logged-in

Alternatif olarak, üst düzey gezinme menüsündeki IdP kaynağından JavaScript API'yi navigator.login.setStatus("logged-in") çağırın:

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

Bu aramalar, kullanıcının giriş durumunu logged-in olarak kaydeder. Kullanıcının giriş durumu logged-in olarak ayarlandığında, RP çağrısı FedCM, IdP'nin hesap uç noktasına istek yapar ve kullanılabilir hesapları FedCM iletişim kutusunda kullanıcıya gösterir.

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

Set-Login: logged-out

Alternatif olarak, üst düzey gezinme menüsündeki IdP kaynağından JavaScript API'yi navigator.login.setStatus("logged-out") çağırın:

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

Bu aramalar, kullanıcının giriş durumunu logged-out olarak kaydeder. Kullanıcının oturum açma 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 durumu, IdP Giriş Durumu API'sini kullanarak bir sinyal göndermeden önce ayarlanır. Bu API gönderildiğinde kullanıcı zaten IdP'de oturum açmış olabileceğinden daha iyi bir geçiş için Unknown kullanıma sunuldu. IdP'nin, FedCM ilk kez çağrıldığında bunu tarayıcıya bildirme fırsatı olmayabilir. Bu durumda Chrome, IdP'nin 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 FedCM iletişim kutusunu açarak bu hesapları görüntüleyin.
  • 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 sürekli olarak bildirse de, oturumun süresinin sona ermesi gibi durumlarda senkronize olmayabilir. 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.

Kimlik sağlayıcıyla güvenen tarafta oturum açma

IdP'nin yapılandırması ve uç noktaları kullanılabilir olduğunda, RP'ler kullanıcıların IdP ile Kısıtlanmış Taraf'ta oturum açmasına izin vermek için navigator.credentials.get() numarasını arayabilir.

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
}

Kullanıcıların RP'den kimlik sağlayıcıda oturum açmasına izin verilmesini istemek için aşağıdakileri yapın. Örneğin:

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

providers özelliği, aşağıdaki özelliklere sahip IdentityProvider nesne dizisini 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. Tekrarlanan saldırılarını engeller.
loginHint (isteğe bağlı) Hesap uç noktaları tarafından sağlanan login_hints değerlerinden birini belirterek FedCM iletişim kutusu, belirtilen hesabı seçerek gösterir.
domainHint (isteğe bağlı) Hesap uç noktaları tarafından sağlanan domain_hints değerlerinden birini belirterek FedCM iletişim kutusunda belirtilen hesabı seçerek gösterebilirsiniz.

Tarayıcı, kayıt ve oturum açma kullanım alanlarını, hesap listesi uç noktasından gelen yanıtta approved_clients varlığına bağlı olarak farklı şekilde ele alır. Kullanıcı Kısıtlanmış Taraf'a zaten kaydolmuşsa tarayıcı, "Şununla devam etmek için:..." ifadesini içeren bir açıklama metni göstermez.

Kaydolma durumu, aşağıdaki koşulların karşılanıp karşılanmadığına göre belirlenir:

  • approved_clients, RP'nin clientId değerini içeriyorsa.
  • Tarayıcı, kullanıcının Kısıtlanmış Taraf'a zaten kaydolduğunu hatırlarsa.
Bir kullanıcı, FedCM'yi kullanarak bir Kısıtlanmış Taraf'ta oturum açıyor.

RP, navigator.credentials.get() işlevini çağrdığında aşağıdaki etkinlikler gerçekleşir:

  1. Tarayıcı, istek gönderir ve çeşitli dokümanları getirir:
    1. Well-known dosyası ve uç noktaları açıklayan bir IdP yapılandırma dosyası.
    2. Hesaplar listesi.
    3. İsteğe bağlı: İstemci meta veri uç noktasından alınan RP'nin gizlilik politikası ve hizmet şartlarının URL'leri.
  2. Tarayıcı, kullanıcının oturum açmak için kullanabileceği hesapların listesini ve varsa hizmet şartlarını ve gizlilik politikasını gösterir.
  3. Kullanıcı oturum açmak için kullanılacak hesabı seçtiğinde, jeton almak üzere IdP'ye kimlik doğrulama uç noktasına yönelik bir istek gönderilir.
  4. RP, kullanıcının kimliğini doğrulamak için jetonu doğrulayabilir.
giriş API çağrısı
login API çağrısı

RP'lerin FedCM'yi desteklemeyen tarayıcıları desteklemesi beklenir. Bu nedenle, kullanıcılar FedCM dışındaki mevcut bir oturum açma işlemini kullanabilir. Üçüncü taraf çerezler tamamen kullanımdan kaldırılana kadar bu durum bir sorun yaratmayacaktır.

Jeton, RP sunucusu tarafından doğrulandıktan sonra, kısıtlanmış taraf kullanıcıyı kaydedebilir veya oturum açıp yeni bir oturum başlatmasına izin verebilir.

Login Hint API

Kullanıcı oturum açtıktan sonra, bazen bağlı taraf (RP) kullanıcıdan yeniden kimlik doğrulamasını ister. Ancak kullanıcı hangi hesabı kullandığından emin olmayabilir. RP, hangi hesapla oturum açılacağını belirtebilirse kullanıcının hesap seçmesi daha kolay olur.

Kısıtlanmış hesaplar, aşağıdaki kod örneğinde gösterildiği gibi, hesap listesi uç noktasından getirilen login_hints değerlerden biriyle loginHint mülküyle navigator.credentials.get() yöntemini çağırarak belirli bir hesabı seçmeli olarak gösterebilir:

return await navigator.credentials.get({
  identity: {
    providers: [{
      configURL: "https://idp.example/manifest.json",
      clientId: "123",
      nonce: nonce,
      loginHint : "demo1@example.com"
    }]
  }
});

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ı isteme dokunduğunda, yapılandırma dosyasında belirtilen giriş URL'sinin bulunduğu bir pop-up pencere açılır. Bağlantıya giriş ipucu ve alan ipucu sorgu parametreleri eklenir.

Domain Hint API

RP'nin, siteye yalnızca belirli bir alanla ilişkili hesapların giriş yapmasına izin verildiğini zaten bildiği durumlar vardır. Bu durum özellikle, erişilen sitenin kurumsal alanla kısıtlandığı kurumsal senaryolarda yaygındır. FedCM API, daha iyi bir kullanıcı deneyimi sunmak için RP'nin yalnızca RP'ye giriş yapmak için kullanılabilecek hesapları göstermesine olanak tanır. Bu, kullanıcının kurumsal alanın dışındaki bir hesap kullanarak RP'ye giriş yapmaya çalıştığı ancak doğru hesap türü kullanılmadığı için daha sonra bir hata mesajı (veya girişin işe yaramadığı durumlarda sessiz kalma) aldığı senaryoları önler.

RP'ler, 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ğırarak yalnızca eşleşen hesapları seçerek gösterebilir:

return await navigator.credentials.get({
  identity: {
    providers: [{
      configURL: "https://idp.example/manifest.json",
      clientId: "abc",
      nonce: nonce,
      domainHint : "corp.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ı isteme dokunduğunda, yapılandırma dosyasında belirtilen giriş URL'sinin bulunduğu bir pop-up pencere açılır. Bu bağlantı, daha sonra giriş ipucu ve alan ipucu sorgu parametreleriyle 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.

Hata mesajı gösterme

Bazen kimlik sağlayıcı, meşru nedenlerle (ör. istemci yetkisiz olduğunda, sunucu geçici olarak kullanılamadığında) jeton yayınlayamayabilir. IdP "error" yanıtı döndürürse RP bunu yakalayabilir. Ayrıca Chrome, IdP tarafından sağlanan hata bilgilerini içeren bir tarayıcı kullanıcı arayüzü göstererek kullanıcıyı bilgilendirir.

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şkilendirilir.
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 FedCM'nin oturum açma iletişim kutusundaki "Şu şekilde devam et..." düğmesine aynı tarayıcı örneğinde ilk kez dokunarak bir hesap oluşturması veya RP'nin web sitesinde oturum açması anlamına gelir.

FedCM'nin ana hedeflerinden biri izlenmeyi önlemek için birleşik hesabı oluşturmadan önce açık kullanıcı deneyimi anlamlı olsa da, kullanıcı bir kez geçtikten sonra gereksiz şekilde kullanışsızdır: Kullanıcı RP ile IdP arasında iletişime izin verme izni verdikten sonra, daha önce kullanıcının onaylamış olduğu başka bir açık kullanıcı onayını zorunlu kılmanın gizlilik veya güvenlik açısından bir faydası olmaz.

Otomatik yeniden kimlik doğrulama ile tarayıcı, navigator.credentials.get() çağrısı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'sinde yer alan bir özelliktir, PasswordCredential ve FederatedCredential'ta olduğu gibi aynı şekilde davranır ve PublicKeyCredential tarafından da kısmen desteklenir. Mülk, aşağıdaki dört değeri kabul eder:

  • 'optional'(varsayılan): Mümkünse otomatik yeniden kimlik doğrulama, değilse uyumlulaştırma gerektirir. Oturum açma sayfasında bu seçeneği belirlemenizi öneririz.
  • 'required': Devam etmek için her zaman uyumlulaştırma gerektirir (ör. kullanıcı arayüzünde "Devam" düğmesini tıklamak). 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, yoksa uyumlulaştırma gerekmeden 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.

Otomatik yeniden kimlik doğrulama, mediation: optional olduğunda yalnızca tarayıcının bildiği nedenlerle kullanılamayabilir. Kısıtlanmış taraf, isAutoSelected özelliğini 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 ile bir akış olan açık kullanıcı uyumlulaştırmasıyla 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 oturumunu 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 kimlik doğrulamayı 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 Kısıtlanmış Taraf ile bağlantısını kesme

Bir kullanıcı daha önce FedCM aracılığıyla IdP'yi kullanarak Kısıtlanmış Taraf'ta oturum açmışsa 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. IdP'nin bağlantısının kaldırılması için RP'nin bir configURL, IdP altında kullandığı clientId ve accountHint geçirmesi 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 Kısıtlanmış Taraf'ta 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ı yok.
  • İç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ış.

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ı kesilen uç noktasından gelen yanıtta belirtilir.

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

Üst çerçeve izin veriyorsa FedCM, identity-credentials-get izin politikası kullanılarak kaynaklar arası 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 yöntemin işleyişini örnekte görebilirsiniz.

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