Federated Credential Management API Geliştirici Kılavuzu

Gizliliği koruyan 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ş başlıklı makaleyi inceleyin.

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 kodunuzda hata ayıklama yapmak için yerel olarak bir sunucu kurun ve çalıştırın. Bağlantı noktası yönlendirme özelliğine sahip bir USB kablosuyla bağlı Android cihazdaki Chrome'da bu sunucuya erişebilirsiniz.

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

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

FedCM'nin Chrome'da üçüncü taraf çerezleri olmadan nasıl çalıştığını, henüz zorunlu kılınmadan ö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.

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.

Ö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"]
}

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ı bir ile sınırlıdır ancak bu durum gelecekte geri bildiriminiz doğrultusunda 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ü ile 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;

IdP yapılandırma dosyası konumunun tam URL'sini configURL olarak 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çermez ve yönlendirmeleri takip etmez. Bu, kimlik sağlayıcının isteği kimin yaptığını ve hangi RP'nin bağlantı kurmaya çalıştığını öğrenmesini etkili bir şekilde engeller. Örneğin:

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

Tarayıcı, kimlik sağlayıcıdan 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 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ı)	Oturum açma iletişim kutusunda görüntülenen simge nesnesini ayarlayan markalaşma seçeneği. simge nesnesi, iki parametre içeren 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ükte olduğunu varsaydığı 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ına uyum sağlamak için navigator.credentials.get() için identity.context değerini kullanarak FedCM iletişim kutusu kullanıcı arayüzündeki dizeyi değiştirebilir. İsteğe bağlı özellik "signin" (varsayılan), "signup", "use" veya "continue" değerlerinden biri olabilir.

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 aşağıdaki istekleri kimlik sağlayıcı uç noktalarına gönderir:

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.php HTTP/1.1
Host: accounts.idp.example
Accept: application/json
Cookie: 0x23223
Sec-Fetch-Dest: webidentity

Sunucu, isteği aldıktan sonra:

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

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

Mülk	Açıklama
id (zorunlu)	Kullanıcının benzersiz kimliği.
name (zorunlu)	Kullanıcının adı ve soyadı.
email (zorunlu)	Kullanıcının e-posta adresi.
given_name (isteğe bağlı)	Kullanıcıya verilen ad.
picture (isteğe bağlı)	Kullanıcı avatarı resminin URL'si.
approved_clients (isteğe bağlı)	Kullanıcının kaydettiği RP istemci kimlikleri dizisi.
login_hints (isteğe bağlı)	IdP'nin bir hesabı belirtmek için desteklediği tüm filtre türlerinin dizisi. RP, belirtilen hesabı seçerek göstermek için loginHint mülküyle navigator.credentials.get()'ü çağırabilir.
domain_hints (isteğe bağlı)	Hesabın ilişkili olduğu tüm alanların dizisi. RP, hesapları filtrelemek için domainHint mülkü ile navigator.credentials.get()'ü çağırabilir.

Ö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 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ı 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 RP'ye kaydolmamışsa oturum açma iletişim kutusunda gösterilir.

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

GET /client_metadata.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.

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.

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 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.
nonce (isteğe bağlı)	RP tarafından sağlanan istek tek seferlik kimliği.
disclosure_text_shown	Boole değeri yerine "true" veya "false" dizesi döndürür. Açıklama metni gösterilmediyse sonuç "false" olur. Bu durum, RP'nin müşteri kimliği hesaplar uç noktasından gelen yanıtın approved_clients mülk listesine dahil edildiğinde veya tarayıcı geçmişte approved_clients olmadan bir kayıt anı gözlemlediğinde ortaya çıkar.
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.

Ö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ş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.

Jetonun nasıl yayınlanacağı IdP'ye bağlıdır ancak genel olarak, RP'nin jetonun orijinal olduğunu doğrulayabilmesi için hesap kimliği, istemci kimliği, veren kaynağı gibi bilgilerle imzalanır.nonce

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 iddiaları içeren bir dizedir.

{
  "token": "***********"
}

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

Hata yanıtı döndürme

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

• code: IdP, OAuth 2.0'da belirtilen hata listesinden bilinen hatalardan birini (invalid_request, unauthorized_client, access_denied, server_error ve temporarily_unavailable) seçebilir veya herhangi bir dize kullanabilir. İkinci durumda Chrome, hata kullanıcı arayüzünü genel bir hata mesajıyla oluşturur ve kodu RP'ye iletir.
• url: Kullanıcılara hata hakkında ek bilgi sağlamak için hatayla ilgili bilgiler içeren, kullanıcı tarafından okunabilen bir web sayfasını tanımlar. Tarayıcılar yerleşik kullanıcı arayüzünde zengin hata mesajları sağlayamadığından bu alan kullanıcılar için yararlıdır. Örneğin, sonraki adımlara yönlendiren bağlantılar veya müşteri hizmetleri iletişim bilgileri. Kullanıcı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, 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"
  }
}

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.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 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. "*") 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ı, 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.

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.

İ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.

Tarayıcıya, kullanıcının kimlik sağlayıcıdaki 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 olası 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 için (yapılandırma URL'si ile tanımlanır) giriş durumunu temsil eden üç durumlu bir değişken tutar. Bu değişkenin olası değerleri logged-in, logged-out ve unknown'dir. Varsayılan durum unknown'tir.

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

Set-Login: logged-in

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

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

Bu çağrılar, kullanıcının oturum açma 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 FedCM iletişim kutusunda kullanıcıya mevcut hesapları 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 kimlik sağlayıcı kaynağından JavaScript API'yi navigator.login.setStatus("logged-out")çağırabilirsiniz:

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

Bu çağrılar, kullanıcının oturum açma 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'nin Oturum Durumu API'sini kullanarak sinyal göndermesinden önce ayarlanır. Unknown, kullanıcı bu API kullanıma sunulduğunda IdP'de oturum açmış olabileceği için daha iyi bir geçiş sağlamak amacıyla kullanıma sunulmuştur. FedCM ilk kez çağrılana kadar kimlik sağlayıcının bunu tarayıcıya bildirme şansı olmayabilir. Bu durumda Chrome, 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.

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

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

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

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

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 mülkü, aşağıdaki özelliklere sahip bir IdentityProvider nesnesi dizisi alır:

Mülk	Açıklama
configURL (zorunlu)	IdP yapılandırma dosyasının tam yolu.
clientId (zorunlu)	IdP tarafından verilen RP istemci tanımlayıcısı.
nonce (isteğe bağlı)	Yanıtın bu istek için gönderilmesini sağlamak amacıyla rastgele bir dize. Tekrar oynama saldırılarını önler.
loginHint (isteğe bağlı)	FedCM iletişim kutusu, hesap uç noktaları tarafından sağlanan login_hints değerlerinden birini belirterek belirtilen hesabı seçerek gösterir.
domainHint (isteğe bağlı)	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ı, hesap listesi uç noktasından gelen yanıtta approved_clients değerinin varlığına bağlı olarak kayıt ve oturum açma kullanım alanlarını farklı şekilde işler. Kullanıcı RP'ye zaten kaydolduysa tarayıcı ".... ile devam etmek için" bilgilendirme metnini 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 RP'ye zaten kaydolduğunu hatırlıyorsa.

RP, navigator.credentials.get() işlevini çağrdığında aşağıdaki işlemler 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. Hesap 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 bir hesap seçtikten sonra, jeton almak üzere kimlik sağlayıcıya kimlik beyanı uç noktası için bir istek gönderilir.
4. RP, kullanıcının kimliğini doğrulamak için jetonu doğrulayabilir.

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 çerezleri tarayıcılarda kullanılamadığında bu sorun ortadan kalkacaktır.

RP sunucusu tarafından doğrulanan jeton, RP tarafından kullanıcıyı kaydedebilir veya kullanıcının oturum açıp yeni bir oturum başlatmasına izin verebilir.

Login Hint API

Kullanıcı oturum açtıktan sonra, güvenen taraf (RP) bazen kullanıcıdan kimliğini yeniden 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.

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

return await navigator.credentials.get({
  identity: {
    providers: [{
      configURL: "https://idp.example/manifest.json",
      clientId: "123",
      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ı istem üzerine dokunduğunda, yapılandırma dosyasında belirtilen giriş URL'sinin yer aldığı bir pop-up pencere açılır. Bağlantıya giriş ipucu ve alan adı 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ı istem üzerine dokunduğunda, yapılandırma dosyasında belirtilen giriş URL'sinin yer aldığı bir pop-up pencere açılır. Bağlantıya giriş ipucu ve alan adı ipucu sorgu parametreleri eklenir.

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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Bu özelliğin işleyiş şeklini örnek üzerinden inceleyebilirsiniz.

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

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

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