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
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:
|
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.
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:
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:
- İsteğin
Sec-Fetch-Dest: webidentity
HTTP üst bilgisi içerdiğini doğrulayın. - Oturum çerezlerini, önceden oturum açmış olduğunuz hesapların kimlikleriyle eşleştirin.
- 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:
client_id
için kısıtlanmış tarafları belirleyin.- İ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:
- İsteği CORS (Ortamlar Arası Kaynak Paylaşımı) ile yanıtlayın.
- İsteğin
Sec-Fetch-Dest: webidentity
HTTP üst bilgisi içerdiğini doğrulayın. Origin
başlığını,client_id
tarafından belirlenen kısıtlanmış taraf kaynağıyla eşleştirin. Eşleşmiyorlarsa reddedin.account_id
öğesini, halihazırda oturum açılmış hesabın kimliğiyle eşleştirin. Eşleşmiyorlarsa reddedin.- 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, IdPconfigURL
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:
- İsteği CORS (Ortamlar Arası Kaynak Paylaşımı) ile yanıtlayın.
- İsteğin
Sec-Fetch-Dest: webidentity
HTTP üst bilgisi içerdiğini doğrulayın. Origin
başlığını,client_id
tarafından belirlenen kısıtlanmış taraf kaynağıyla eşleştirin. Eşleşmiyorlarsa reddedin.account_hint
öğesini, halihazırda oturum açmış olduğunuz hesapların kimlikleriyle eşleştirin.- Kullanıcı hesabının kısıtlanmış taraf ile olan bağlantısını kesin.
- 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.
Kullanıcı Devam düğmesini tıkladığında tarayıcı, IdP'nin giriş sayfası için bir pop-up pencere açar.
İ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 veyanavigator.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 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ınclientId
bilgilerini içeriyorsa.- Tarayıcı, kullanıcının RP'ye zaten kaydolmuş olduğunu hatırlarsa.
Kısıtlanmış taraf navigator.credentials.get()
çağrısı yaptığında aşağıdaki etkinlikler gerçekleşir:
- Tarayıcı istekleri gönderir ve çeşitli dokümanları getirir:
- Uç noktaları bildiren iyi bilinen dosya ve bir IdP yapılandırma dosyası.
- Hesap listesi.
- İsteğe bağlı: RP'nin gizlilik politikası ve hizmet şartları URL'leri (istemci meta veri uç noktasından alınır).
- 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.
- 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.
- 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 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.
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.
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ğrulama işleminden 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.
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.