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 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 sayfasındaki 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 adresine giderek ya da mobil cihazdan Ayarlar > Site ayarları > Çerezler'e giderek masaüstü ayarlarınızda "Üçüncü taraf çerezlerini engelleyin"i seçin.

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.

Ardından FedCM, RP'lerin IdP ile oturum açmak için kullanabileceği JavaScript API'lerini sunar.

Well-known dosyası 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 bir .well-known dosyası ve bir IdP yapılandırma dosyası da sunulmalıdır. Aşağıda, bilinen bir dosya içeriği örneği verilmiştir:

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

JSON dosyası, RP'ler tarafından navigator.credentials.get içindeki configURL öğesinin 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ı 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üyle sunulmalı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ı 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çmak için kullanacağı 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 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ı en az 25 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".

Aşağıda, IdP'den alınan örnek bir yanıt gövdesi verilmiştir:

{
  "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 şu anda 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 halihazırda oturum açmış hesapların kimlikleriyle eşleştirin.
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ı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 bir RP istemci kimliği dizisi.
login_hints (isteğe bağlı)	IdP'nin hesap belirtmek için desteklediği tüm olası 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 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 sunmalı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.

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

İade edilen istemci meta verileri tarayıcı tarafından kullanılır ve RP'nin erişimine açık olmaz.

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ı kullanarak bir Kısıtlanmış Taraf web sitesinde oturum açtığında tarayıcı, SameSite=None ile birlikte çerezleri ve application/x-www-form-urlencoded içerik türünü içeren bir POST isteği gönderir. Bu istekte aşağıdaki bilgiler bulunur:

Mülk	Açıklama
client_id (zorunlu)	Kısıtlanmış tarafın müşteri 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	Sonuçlar, "true" veya "false" dizesiyle (boole yerine) elde edilir. Açıklama metni gösterilmemişse 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. Diğer durumlarda "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 öğesini, halihazırda oturum açmış 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, 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'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 yerel kullanıcı arayüzünde zengin hata mesajları sağlayamadığından bu alan kullanıcılar için faydalıdır. Örneğin, sonraki adı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, 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 şunları yapmalıdır:

• 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'yi çağırın.
• İletişim kutusunu kapatmak için IdentityProvider.close() öğesini çağırın.

Tarayıcıya, kullanıcının kimlik sağlayıcıdaki giriş durumu hakkında bilgi verme

Login Status API, bir web sitesinin (özellikle IdP'nin) tarayıcıya kullanıcının IdP'deki 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 JavaScript API'yi çağırarak kullanıcının giriş durumunu tarayıcıya bildirebilir. Tarayıcı, her IdP (yapılandırma URL'si ile tanımlanır) için giriş durumunu temsil eden logged-in, logged-out ve unknown olası değerleriyle üç durumlu bir değişken tutar. 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ındaki oturumunun kapatıldığını bildirmek için üst düzey gezinme bölümünde Set-Login: logged-out HTTP üst bilgisi veya IdP kaynağında aynı site alt kaynak isteği 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 çağrılar, kullanıcının oturum açma durumunu logged-out olarak kaydeder. Kullanıcının giriş durumu logged-out olduğunda, FedCM'nin çağrılması, IdP'nin hesap uç noktasına herhangi bir istekte bulunulmadan sessizce başarısız olur.

unknown durumu, IdP, Oturum Durumu API'sini kullanarak sinyal göndermeden ö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, 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 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 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 IdP'de Kısıtlanmış Taraf'tan oturum açmasına izin verme isteğinde bulunmak 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, kısıtlanmış tarafın clientId değerini içeriyorsa.
• Tarayıcı, kullanıcının RP'ye daha önce kaydolduğunu hatırlarsa.

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. Hesap listesi.
   3. İsteğe bağlı: İstemci meta veri uç noktasından alınan, kısıtlanmış taraf 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. Kısıtlanmış taraf, 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 tamamen kullanımdan kaldırılana kadar bu sorun yaşanmayacaktı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.

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 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 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 bir alanla kısıtlı olduğu 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 ipucuyla eşleşen bir IdP hesabına giriş yapmasına olanak tanır. Kullanıcı istem üzerine dokunduğunda, yapılandırma dosyasında belirtilen giriş URL'sinin yer aldığı bir pop-up pencere açılır. Bağlantıya giriş ipucu ve alan ipucu sorgu parametreleri eklenir.

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 "hata" 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ğrulamasından sonra kullanıcıların kimliğini otomatik olarak yeniden doğrula

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 "... olarak devam et" düğmesine dokunarak hesap oluşturması veya RP'nin web sitesinde oturum açması anlamına gelir.

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

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

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

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

mediation, Kimlik Bilgisi Yönetimi API'sinde yer alan bir özelliktir, PasswordCredential ve FederatedCredential'ta olduğu gibi aynı şekilde davranır ve PublicKeyCredential tarafından da kısmen desteklenir. Özellik aşağıdaki dört değeri kabul eder:

• 'optional'(varsayılan): Mümkünse otomatik yeniden yetkilendirme, mümkün değilse arabuluculuk gerekir. Oturum açma sayfasında bu seçeneği belirlemenizi öneririz.
• 'required': Devam etmek için her zaman bir arabuluculuk gerekir (ör. kullanıcı arayüzündeki "Devam" 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, yoksa uyumlulaştırma gerekmeden sessizce başarısız olur. Bu seçeneği özel oturum açma sayfası dışındaki ancak kullanıcıların oturumlarını açık tutmak istediğiniz sayfalarda (örneğin, bir kargo web sitesindeki ürün sayfası veya bir haber web sitesindeki makale sayfası) belirlemenizi ö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ıdan web sitesinde oturum açmak için FedCM API ile yalnızca bir hesap kullanmıştır.
• 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 açısından faydalıdır. Ayrıca, bu özellik kullanılamadığında kullanıcıdan mediation: required içeren bir akış olan açık kullanıcı aracılığı ile oturum açması istenebilir.

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

Kullanıcılar oturum kapatıldıktan hemen sonra otomatik olarak yeniden kimlik doğrulaması yapmak çok iyi bir kullanıcı deneyimi sağlamaz. 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 her 10 dakikada bir gerçekleştiği anlamına gelir. Bir kullanıcı RP'den açıkça çıkış yaptığında (ör. bir oturumu kapatma düğmesini tıklayarak), tarayıcının otomatik yeniden kimlik doğrulamayı devre dışı bırakmasını açıkça istemek için RP navigator.credentials.preventSilentAccess()'yi ç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çmışsa 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. 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 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ı 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ış.

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

Kaynaklar arası iframe içinden FedCM'yi ç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 görebilirsiniz.

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