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 (Federated Credential Management), kullanıcıların kişisel bilgilerini kimlik hizmetiyle veya siteyle paylaşmadan sitelere giriş yapabildiği birleşik kimlik hizmetlerine (ör. "...ile oturum aç...") yönelik gizliliği koruyan 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'daki IdP ve RP'de güvenli bir içeriğe (HTTPS veya localhost) ihtiyacınız vardır.

Android'deki Chrome'da hata ayıklama kodu

FedCM kodunuzda hata ayıklamak için yerel olarak bir sunucu kurup çalıştırın. Bağlantı noktası yönlendirme özellikli USB kablosuyla bağlanan bir Android cihazda Chrome'dan bu sunucuya erişebilirsiniz.

Android cihazlarda uzaktan hata ayıklama bölümündeki talimatları uygulayarak Android'de Chrome'daki hataları ayıklamak için masaüstünde Geliştirici Araçları'nı kullanabilirsiniz.

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

Chrome'u bunları engelleyecek şekilde yapılandırarak üçüncü taraf çerezlerini kullanımdan kaldırma simülasyonunu çalıştırın
Chrome'u yapılandırarak üçüncü taraf çerezlerini aşamalı olarak kullanımdan kaldırma sürecini simüle edin

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

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

FedCM API'yi kullanma

Hesap listesi, hak talebi verme ve isteğe bağlı olarak istemci meta verileri için iyi bilinen bir dosya, yapılandırma dosyası ve uç noktalar oluşturarak FedCM ile entegrasyon sağlarsınız.

Burada FedCM, 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 eTLD+1 /.well-known/web-identity bölgesinden bilinen bir dosya yayınlanmalıdır.

Örneğin, IdP uç noktaları https://accounts.idp.example/ altında sunuluyorsa https://idp.example/.well-known/web-identity alanında iyi bilinen bir dosya ve bir 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 bölgesinde configURL yol parçası olarak belirtilebilecek bir IdP yapılandırma dosyası URL'leri dizisine sahip provider_urls özelliğini içermelidir. Dizideki URL dizesi sayısı birle sınırlıdır ancak bu, ileride geri bildiriminizle birlikte 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. IdP'ler 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 yayınlanmalıdır.

Yapılandırma dosyasının URL'si, 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;

IdP yapılandırma dosyasının tam URL'sini configURL olarak belirtin. RP'de navigator.credentials.get() çağrıldığında tarayıcı, yapılandırma dosyasını Origin başlığı veya Referer üst bilgisi olmadan GET isteğiyle getirir. İstekte çerezler yer almaz ve yönlendirmeler takip edilmez. Bu durum, IdP'nin isteği kimin yaptığını ve hangi kısıtlanmışın bağlanmaya çalıştığını öğrenmesini etkili bir şekilde önler. Ö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:

Özellik Açıklama
accounts_endpoint (zorunlu) Hesaplar uç noktasının URL'si.
client_metadata_endpoint (isteğe bağlı) İstemci meta verisi uç noktasının URL'si.
id_assertion_endpoint (zorunlu) Kimlik onayı uç noktası URL'si.
disconnect (isteğe bağlı) Bağlantı kesme uç noktası 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 markalama seçenekleri içeren nesne.
branding.background_color (isteğe bağlı) "Şu kullanıcı olarak devam et..." düğmesinin arka plan rengini belirleyen markalama seçeneği. İlgili CSS söz dizimini (hex-color, hsl(), rgb() veya named-color) kullanın.
branding.color (isteğe bağlı) "Şu kullanıcı olarak devam et..." düğmesinin metin rengini belirleyen markalama seçeneği. İlgili CSS söz dizimini (hex-color, hsl(), rgb() veya named-color) kullanın.
branding.icons (isteğe bağlı) Simge nesnesini ayarlayan ve oturum açma iletişim kutusunda gösterilen markalama seçeneği. Simge nesnesi, iki parametreye sahip bir dizidir:
  • url (gerekli): Simge resminin URL'si. Bu özellik, SVG resimlerini desteklemez.
  • size (isteğe bağlı): Uygulama tarafından kare ve tek çözünürlüklü olduğu varsayılan simge boyutları. Bu sayı en az 25 olmalıdır.

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

Markalama, FedCM iletişim kutusuna nasıl uygulanır?
Markalama, FedCM iletişim kutusuna nasıl uygulanır?

IdP'den alınan örnek yanıt gövdesini burada görebilirsiniz:

{
  "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ı getirdikten sonra IdP uç noktalarına sonraki istekleri gönderir:

IdP uç noktaları
IdP uç noktaları

Hesap uç noktası

IdP'nin hesapları uç noktası, kullanıcının IdP'de oturum açmış olduğu 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 çerezlerine sahip bir GET isteği gönderir ancak client_id parametresi olmadan Origin üst bilgisini veya Referer başlığını kullanır. Bu, IdP'nin kullanıcının hangi RP'de oturum açmaya çalıştığını öğrenmesini etkili bir şekilde önler. Örneğin:

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

Sunucu, isteği aldıktan sonra şunları yapmalıdır:

  1. İsteğin Sec-Fetch-Dest: webidentity HTTP üst bilgisi içerdiğini doğrulayın.
  2. Oturum çerezlerini, önceden oturum açmış olduğunuz hesapların kimlikleriyle eşleştirin.
  3. Hesap listesiyle yanıt verin.

Tarayıcı, aşağıdaki özelliklere sahip bir dizi hesap bilgisi içeren accounts özelliğini içeren bir JSON yanıtı bekler:

Özellik 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ının adı.
picture (isteğe bağlı) Kullanıcı avatarı resminin URL'si.
approved_clients (isteğe bağlı) Kullanıcının kaydolduğu RP müşteri kimlikleri dizisi.
login_hints (isteğe bağlı) IdP'nin bir hesabı belirtmek için desteklediği olası tüm filtre türleri dizisi. RP, belirtilen hesabı seçerek göstermek için loginHint özelliğiyle navigator.credentials.get() çağırabilir.
domain_hints (isteğe bağlı) Hesabın ilişkili olduğu tüm alan adlarını içeren bir dizi. RP, hesapları filtrelemek için domainHint mülküyle navigator.credentials.get() ç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çmamışsa HTTP 401 (Yetkisiz) ile yanıt verin.

Döndürülen hesaplar listesi tarayıcı tarafından tüketilir ve RP tarafından kullanılamaz.

İstemci meta veri uç noktası

IdP'nin istemci meta verisi 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ı önceden IdP'ye sağlamalıdır. Bu bağlantılar, kullanıcı henüz IdP'deki RP'ye 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 şunları yapmalıdır:

  1. client_id için kısıtlanmış tarafları belirleyin.
  2. İstemci meta verileriyle yanıt verin.

İstemci meta veri uç noktasının özellikleri şunlardır:

Özellik 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 doğrulaması uç noktası

IdP'nin kimlik onayı uç noktası, oturum açmış olan kullanıcı için bir onay döndürür. Kullanıcı navigator.credentials.get() çağrısını kullanarak bir RP web sitesinde oturum açtığında tarayıcı, SameSite=None içeren çerezler ve application/x-www-form-urlencoded içerik türü içeren bir POST isteği bu uç noktaya aşağıdaki bilgilerle gönderir:

Özellik Açıklama
client_id (zorunlu) Kısıtlanmış tarafın 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 istek tek seferlik rastgele sayısı.
disclosure_text_shown "true" veya "false" dizesiyle sonuçlanır (boole yerine). Açıklama metni gösterilmediyse sonuç "false" olur. Bu durum, RP'nin istemci kimliği hesap uç noktasından gelen yanıtın approved_clients mülkü listesine eklendiğinde veya tarayıcı geçmişte approved_clients olmadığı için bir kaydolma anını gözlemlediğinde ortaya çıkar.
is_auto_selected Kısıtlanmış taraf için otomatik yeniden kimlik doğrulama gerçekleştirilirse is_auto_selected "true" anlamına gelir. Aksi durumda "false". Bu, güvenlikle ilgili daha fazla özelliğin desteklenmesine yardımcı olur. Örneğin, bazı kullanıcılar kimlik doğrulamada açık kullanıcı uyumlulaştırma gerektiren daha yüksek bir güvenlik katmanını tercih edebilir. Bir IdP, bu tür bir uyumlulaştırma olmadan jeton isteği alırsa isteği farklı bir şekilde işleyebilir. Örneğin, kısıtlanmış tarafın mediation: required ile FedCM API'yi tekrar çağırabilmesi için bir hata kodu döndürün.

Örnek HTTP üstbilgisi:

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 şunları yapmalıdır:

  1. İsteği CORS (Ortamlar Arası Kaynak Paylaşımı) ile yanıtlayın.
  2. İsteğin Sec-Fetch-Dest: webidentity HTTP üst bilgisi içerdiğini doğrulayın.
  3. Origin başlığını, client_id tarafından belirlenen kısıtlanmış taraf kaynağıyla eşleştirin. Eşleşmiyorlarsa reddedin.
  4. account_id öğesini, halihazırda oturum açılmış hesabın kimliğiyle eşleştirin. Eşleşmiyorlarsa reddedin.
  5. Jeton göndererek yanıt verin. İstek reddedilirse hata yanıtı ile yanıt verin.

Jetonun nasıl verileceği IdP'ye bağlıdır ancak genel olarak hesap kimliği, istemci kimliği, kartı veren kuruluşun kaynağı ve nonce gibi bilgilerle imzalanır. Böylece RP, jetonun orijinal olduğunu doğrulayabilir.

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

Özellik Açıklama
token (zorunlu) Jeton, kimlik doğrulamayla ilgili iddiaları içeren bir dizedir. 
{
  "token": "***********"
}

Döndürülen jeton, RP'nin kimlik doğrulamasını 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 listesinden (invalid_request, unauthorized_client, access_denied, server_error vetemporarily_unavailable) bilinen hatalardan birini seçebilir veya herhangi bir dizeyi 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 hatayla ilgili ek bilgi sağlamak için hatayla ilgili bilgilerin yer aldığı, kullanıcıların okuyabileceği bir web sayfasını tanımlar. Tarayıcılar, yerel 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. Bir kullanıcı hata ayrıntıları ve hatanın nasıl düzeltileceği hakkında daha fazla bilgi edinmek isterse, daha ayrıntılı bilgi 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ı kes

Tarayıcı IdentityCredential.disconnect() yöntemini çağırarak bu bağlantı kesme uç noktasına SameSite=None içeren çerezler ve application/x-www-form-urlencoded içerik türünü içeren çapraz kaynakPOST isteği gönderir. İstekte aşağıdaki bilgiler yer alır:

Özellik Açıklama
account_hint IdP hesabıyla ilgili ipucu.
client_id Kısıtlanmış tarafın 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 şunları yapmalıdır:

  1. İsteği CORS (Ortamlar Arası Kaynak Paylaşımı) ile yanıtlayın.
  2. İsteğin Sec-Fetch-Dest: webidentity HTTP üst bilgisi içerdiğini doğrulayın.
  3. Origin başlığını, client_id tarafından belirlenen kısıtlanmış taraf kaynağıyla eşleştirin. Eşleşmiyorlarsa reddedin.
  4. account_hint öğesini, halihazırda oturum açmış olduğunuz hesapların kimlikleriyle eşleştirin.
  5. Kullanıcı hesabının kısıtlanmış taraf ile olan bağlantısını kesin.
  6. Tanımlanmış kullanıcı hesabı bilgileriyle tarayıcıya JSON biçiminde yanıt verin.

Örnek yanıt JSON yükü aşağıdaki gibi görünür:

{
  "account_id": "account456"
}

Bunun yerine, IdP, tarayıcının RP ile ilişkilendirilmiş tüm hesapların bağlantısını kesmesini istiyorsa herhangi bir hesap kimliğiyle eşleşmeyen bir dize (örneğin, "*") iletin.

Giriş URL'si

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

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

CEVAP
IdP'de oturum açmanızı öneren bir FedCM iletişim kutusu.

Kullanıcı Devam düğmesini tıkladığında tarayıcı, IdP'nin giriş sayfası için bir pop-up pencere açar.

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

İletişim kutusu, birinci taraf çerezlerinin bulunduğu normal bir tarayıcı penceresidir. İletişim kutusunda olup biten her şey IdP'ye bağlıdır ve RP sayfasına kaynaklar arası iletişim isteğinde bulunmak için hiçbir pencere işleyicisi yoktur. 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 üst bilgisini 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.
CEVAP
Bir 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 kimlik sağlayıcıdaki giriş durumu hakkında bilgi verir

Giriş Durumu API'si, bir web sitesinin (özellikle de IdP'nin) tarayıcıya IdP'deki giriş durumunu bildirdiği bir mekanizmadır. Bu API sayesinde tarayıcı, IdP'ye gönderilen gereksiz istekleri azaltabilir ve olası zamanlama saldırılarını azaltabilir.

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

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

Set-Login: logged-in

Alternatif olarak, üst düzey gezinme menüsünde IdP kaynağından JavaScript API'sini 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 FedCM'yi çağıran RP, IdP'nin hesap uç noktasına istek gönderir ve mevcut hesapları FedCM iletişim kutusunda kullanıcıya gösterir.

Kullanıcının tüm hesaplarındaki oturumunun kapatıldığını belirtmek için üst düzey gezinme bölmesinde Set-Login: logged-out HTTP üstbilgisini veya IdP kaynağında aynı site alt kaynak isteğini gönderin:

Set-Login: logged-out

Alternatif olarak, üst düzey gezinme menüsünde IdP kaynağından JavaScript API'sini 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 giriş durumu logged-out olduğunda, FedCM'nin çağrılması, IdP'nin hesapları uç noktasına istek yapılmadan sessizce başarısız olur.

unknown durumu, IdP, Login Status API'yi kullanarak sinyal göndermeden önce ayarlanır. Bu API gönderilirken bir kullanıcı zaten IdP'de oturum açmış olabileceğinden Unknown, daha iyi bir geçiş için kullanıma sunulmuştur. IdP'nin, FedCM ilk çağrıldığı zamana kadar bunu tarayıcıya işaret etme şansı olmayabilir. Bu durumda Chrome, IdP'nin hesap uç noktasına bir istekte bulunur 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.
  • Uç nokta hiçbir hesap döndürmezse durumu logged-out olarak güncelleyin ve FedCM çağrısı başarısız olur.

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

IdP, kullanıcının giriş durumunu tarayıcıya bildirmeye devam etse de, oturumun sona ermesi gibi senkronize bir durum olabilir. Giriş durumu logged-in olduğunda tarayıcı, hesaplar uç noktasına kimlik bilgileri içeren bir istek göndermeye çalışır ancak oturum artık kullanılamadığı için sunucu hiçbir hesap döndürmez. Böyle bir senaryoda, tarayıcı, kullanıcının bir pop-up pencere üzerinden IdP'de oturum açmasına dinamik olarak izin verebilir.

Kimlik sağlayıcıyla bağlı taraf hesabında oturum açın

IdP'nin yapılandırması ve uç noktaları kullanılabilir olduğunda RP'ler, kullanıcıların IdP ile RP'de oturum açmalarına izin vermek için navigator.credentials.get() yöntemini çağırabilir.

API'yi çağırmadan önce [FedCM'nin kullanıcının tarayıcısında kullanılabilir] olduğunu onaylamanız gerekir. FedCM'nin kullanılabilir olup olmadığını kontrol etmek için bu kodu FedCM uygulamanızın etrafına sarmalayın:

if ('IdentityCredential' in window) {
  // If the feature is available, take action
}

Kullanıcıların RP'den IdP'de oturum açmasına izin vermek 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 bir IdentityProvider nesne dizisi alır:

Özellik Açıklama
configURL (zorunlu) IdP yapılandırma dosyasının tam yolu.
clientId (zorunlu) IdP tarafından verilen kısıtlanmış taraf istemci kimliği.
nonce (isteğe bağlı) Bu spesifik istek için yanıtın verilmesini sağlayan rastgele bir dize. Tekrar oynatma 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.

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ı şekillerde işler. Kullanıcı RP'ye kaydolmuşsa tarayıcı, "... ile devam etmek için" açıklama metnini göstermez.

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

  • approved_clients, kısıtlanmış tarafın clientId bilgilerini içeriyorsa.
  • Tarayıcı, kullanıcının RP'ye zaten kaydolmuş olduğunu hatırlarsa.
Bir kullanıcı FedCM'yi kullanarak bir kısıtlanmış taraf üzerinde oturum açıyor

Kısıtlanmış taraf navigator.credentials.get() çağrısı yaptığında aşağıdaki etkinlikler gerçekleşir:

  1. Tarayıcı istekleri gönderir ve çeşitli dokümanları getirir:
    1. Uç noktaları bildiren iyi bilinen dosya ve bir IdP yapılandırma dosyası.
    2. Hesap listesi.
    3. İsteğe bağlı: RP'nin gizlilik politikası ve hizmet şartları URL'leri (istemci meta veri uç noktasından alınır).
  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örüntüler.
  3. Kullanıcı oturum açmak için bir hesap seçtiğinde, jeton alması için IdP'ye kimlik doğrulaması uç noktasına 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 mevcut, FedCM olmayan bir oturum açma işlemini kullanabilmelidir. Üçüncü taraf çerezleri tamamen kullanımdan kaldırılıncaya kadar herhangi bir sorun yaşanmayacaktır.

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

Giriş İpucu API'sı

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 olamayabilir. RP, hangi hesapla oturum açılacağını belirtebiliyorsa kullanıcının hesap seçmesi daha kolay olur.

RP'ler, aşağıdaki kod örneğinde gösterildiği gibi hesap listesi uç noktasından getirilen login_hints değerlerinden biriyle loginHint mülküyle 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",
      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 ipucuyla 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 yer aldığı bir pop-up pencere açılır. Ardından bağlantı, giriş ipucu ve alan ipucu sorgu parametreleriyle birlikte eklenir.

Alan İpucu API'si

RP'nin, yalnızca belirli bir alan adıyla ilişkili hesapların siteye giriş yapmasına izin verildiğini zaten bildiği durumlar vardır. Bu durum, özellikle erişilen siteye kurumsal bir alan adıyla sınırlı olan kurumsal senaryolarda yaygın olarak görülür. FedCM API, daha iyi bir kullanıcı deneyimi sunmak için RP'nin yalnızca kısıtlanmış tarafa giriş yapmak için kullanılabilecek hesapları göstermesine izin verir. Bu, kullanıcının kurumsal alan dışında bir hesap kullanarak RP'ye giriş yapmaya çalıştığı, ancak doğru hesap türünün kullanılmadığı için daha sonra bir hata mesajıyla (veya girişin çalışmadığı durumlarda sessize alındığı) senaryoları önler.

RP'ler, aşağıdaki kod örneğinde gösterildiği gibi hesap listesi uç noktasından getirilen domain_hints değerlerinden biriyle navigator.credentials.get() yöntemini çağırarak yalnızca eşleşen hesapları seçerek gösterebilir:domainHint

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 ipucuyla 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 yer aldığı bir pop-up pencere açılır. Ardından bağlantı, giriş ipucu ve alan ipucu sorgu parametreleriyle birlikte eklenir.

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

Hata mesajı göster

Bazen IdP, istemcinin yetkilendirilmemiş olması ve sunucunun geçici olarak kullanılamaması gibi geçerli nedenlerle jeton yayınlayamayabilir. IdP "hata" yanıtı döndürürse RP bunu yakalayabilir ve Chrome, IdP tarafından sağlanan hata bilgilerini tarayıcı kullanıcı arayüzünde göstererek kullanıcıyı bilgilendirir.

CEVAP
Kullanıcının oturum açma girişimi başarısız olduğunda 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 izinden sonra kullanıcıların kimliğini otomatik olarak yeniden doğrula

FedCM otomatik yeniden kimlik doğrulama ("otomatik yeniden kimlik doğrulama"), kullanıcıların FedCM kullanarak ilk kimlik doğrulamasından sonra geri döndüklerinde otomatik olarak yeniden kimlik doğrulaması yapmasını sağlayabilir. Buradaki "ilk kimlik doğrulama", kullanıcının aynı tarayıcı örneğinde ilk kez FedCM'nin oturum açma iletişim kutusundaki "Şu kullanıcı olarak devam et..." düğmesine dokunarak bir hesap oluşturduğu veya kısıtlanmış tarafın web sitesinde oturum açtığı anlamına gelir.

Açık kullanıcı deneyimi, kullanıcı izlemeyi engellemek için birleşik hesabı oluşturmadan önce mantıklı olsa da (bu, FedCM'nin ana hedeflerinden biridir) kullanıcının bir kez geçmesinden sonra gereksiz bir şekilde zahmetli olur: Kullanıcı, RP ve IdP arasında iletişime izin verme izni verdikten sonra, daha önce onayladığı başka bir açık kullanıcı onayını zorunlu kılmanın gizlilik veya güvenlik avantajı olmaz.

Otomatik yeniden kimlik doğrulama ile tarayıcı, navigator.credentials.get() yöntemini çağırırken mediation için belirttiğiniz seçeneğe göre 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, Credential Management API'deki bir özelliktir, PasswordCredential ve FederatedCredential ile 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, aksi takdirde 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. Örneğin, kullanıcı arayüzündeki "Devam" düğmesini tıklamak. Kullanıcılarınızın kimliklerinin her doğrulanması gerektiğinde açıkça izin vermesi bekleniyorsa bu seçeneği belirleyin.
  • 'silent': Mümkünse otomatik olarak yeniden kimlik doğrulama, aksi takdirde herhangi bir aracılık gerektirmeden sessizce başarısız olur. Bu seçeneği, özel oturum açma sayfası dışındaki ancak kullanıcıların oturumlarının açık kalmasını istediğiniz sayfalarda (örneğin, kargoyla ilgili bir web sitesindeki öğe sayfası veya haber web sitesindeki bir makale sayfası) tercih etmenizi öneririz.
  • 'conditional': WebAuthn için kullanılır ve şu anda FedCM tarafından kullanılamaz.

Bu çağrıda, otomatik yeniden kimlik doğrulama aşağıdaki koşullarda gerçekleşir:

  • FedCM kullanılabilir. Örneğin, kullanıcı, FedCM'yi global olarak veya ayarlarda RP için devre dışı bırakmamış olmalıdır.
  • Kullanıcı, bu tarayıcıdan web sitesinde oturum açmak için FedCM API'ye sahip yalnızca bir hesap kullanmıştır.
  • Kullanıcı, IdP'de bu hesapla oturum açmıştır.
  • Son 10 dakika içinde otomatik yeniden kimlik doğrulama işlemi gerçekleşmedi.
  • RP, önceki oturum açma işleminden sonra navigator.credentials.preventSilentAccess() adresini aramadı.

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

mediation: optional olduğunda otomatik yeniden kimlik doğrulama, yalnızca tarayıcının bildiği nedenlerden dolayı kullanılamaz olabilir. RP, 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 açısından faydalıdır. Ayrıca bu seçenek kullanılamadığında kullanıcıdan açık kullanıcı uyumlulaştırmasıyla oturum açması istenebilir. Bu, mediation: required ile bir akıştır.

FedCM üzerinden otomatik olarak yeniden kimlik doğrulaması yapan bir kullanıcı.

preventSilentAccess() ile uyumlulaştırmayı zorunlu kılın

Kullanıcıların oturumlarını kapattıktan hemen sonra otomatik olarak yeniden kimlik doğrulaması yapılması, çok iyi bir kullanıcı deneyimi sunmaz. Bu nedenle, FedCM'nin bu davranışı önlemek için otomatik yeniden kimlik doğrulama işleminden sonra 10 dakikalık sessiz bir süresi vardır. 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ştiği anlamına gelir. RP, bir kullanıcı RP'den açık bir şekilde çıkış yaptığında (ör. oturumu kapat) bir kullanıcı tarafından açık bir şekilde çıkış yaptığında tarayıcının otomatik yeniden kimlik doğrulamayı devre dışı bırakmasını açıkça istemek için navigator.credentials.preventSilentAccess()'i çağırmalıdır.

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

Kullanıcılar, ayarlarda otomatik yeniden kimlik doğrulamayı devre dışı bırakabilir

Kullanıcılar ayarlar menüsünden otomatik yeniden kimlik doğrulamayı devre dışı bırakabilir:

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

Açma/kapatma düğmesini devre dışı bıraktığınızda kullanıcı otomatik yeniden kimlik doğrulama davranışını hep birlikte devre dışı bırakabilir. Bu ayar, kullanıcının Chrome örneğinde bir Google Hesabı'nda oturum açmış olması ve senkronizasyonun etkin olması halinde cihazlar arasında depolanır ve senkronize edilir.

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

Bir kullanıcı daha önce IdP'yi kullanarak FedCM üzerinden RP'de oturum açtıysa bu ilişki, tarayıcı tarafından yerel olarak bağlı hesapların listesi olarak hatırlanır. RP, IdentityCredential.disconnect() işlevini çağırarak bağlantı kesme işlemi başlatabilir. Bu işlev, üst düzey bir RP çerçevesinden çağrılabilir. Kısıtlanmış tarafın bir configURL, IdP altında kullandığı clientId ve IdP'nin bağlantısının kesilebilmesi için bir accountHint iletmesi gerekir. Hesap ipucu, bağlantıyı kesme uç noktası hesabı tanımlayabildiği sürece rastgele bir dize olabilir. Örneğin, hesap listesi uç noktasının sağladığı hesap kimliğiyle eşleşmeyen 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() bir Promise döndürür. Bu vaat aşağıdaki nedenlerle istisnaya yol açabilir:

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

IdP'nin bağlantı kesme uç noktası yanıt döndürdüğünde, tarayıcıda RP ve IdP bağlantısı kesilir ve söz konusu çözüm sonlandırılır. Bağlantısı kesilen hesapların kimliği, bağlantı kesilmesi uç noktasından gelen yanıtta belirtilmiştir.

FedCM'yi çapraz kaynak iframe içinden çağırma

FedCM, üst çerçeve izin veriyorsa bir identity-credentials-get izin politikası kullanılarak çapraz kaynak 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>

Bir örnekte bunu görebilirsiniz.

İsteğe bağlı olarak, üst çerçeve, kaynakları FedCM'yi çağıracak şekilde kısıtlamak isterse izin verilen kaynakların listesini içeren bir Permissions-Policy üstbilgisi 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 İzinler Politikası ile tarayıcı özelliklerini kontrol etme bölümünde bulabilirsiniz.