Pelajari cara menggunakan FedCM untuk penggabungan identitas yang menjaga privasi.
FedCM (Pengelolaan Kredensial Federasi) adalah pendekatan yang menjaga privasi terhadap layanan identitas gabungan (seperti "Login dengan...") yang memungkinkan pengguna login ke situs tanpa membagikan informasi pribadi mereka ke layanan identitas atau situs.
Untuk mempelajari lebih lanjut kasus penggunaan, alur penggunaan, dan roadmap API FedCM, lihat pengantar FedCM API.
Lingkungan pengembangan FedCM
Anda memerlukan konteks yang aman (HTTPS atau localhost) di IdP dan RP di Chrome untuk menggunakan FedCM.
Men-debug kode di Chrome pada Android
Siapkan dan jalankan server secara lokal untuk men-debug kode FedCM Anda. Anda dapat mengakses server ini di Chrome pada perangkat Android yang terhubung menggunakan kabel USB dengan penerusan port.
Anda dapat menggunakan DevTools di desktop untuk men-debug Chrome di Android dengan mengikuti petunjuk di Perangkat Android debug jarak jauh.
Blokir cookie pihak ketiga di Chrome
Anda dapat menguji cara kerja FedCM tanpa cookie pihak ketiga di Chrome sebelum benar-benar diberlakukan.
Untuk memblokir cookie pihak ketiga, gunakan mode
Samaran, atau pilih "Blokir
cookie pihak ketiga" pada setelan desktop di chrome://settings/cookies
atau di
seluler dengan membuka Setelan > Setelan situs > Cookie.
Menggunakan FedCM API
Lakukan integrasi dengan FedCM dengan membuat file populer, file konfigurasi, dan endpoint untuk daftar akun, penerbitan pernyataan, dan metadata klien secara opsional.
Dari sana, FedCM akan mengekspos JavaScript API yang dapat digunakan RP untuk login dengan IdP.
Membuat file yang dikenal luas
Untuk mencegah pelacak menyalahgunakan
API, file populer harus
disalurkan dari /.well-known/web-identity
eTLD+1 dari
IdP.
Misalnya, jika endpoint IdP ditayangkan di
https://accounts.idp.example/
, endpoint IdP tersebut harus menayangkan file populer di
https://idp.example/.well-known/web-identity
serta file konfigurasi
IdP. Berikut ini contoh konten file yang dikenal:
{
"provider_urls": ["https://accounts.idp.example/config.json"]
}
File JSON harus berisi properti provider_urls
dengan array URL file konfigurasi IdP yang dapat ditentukan sebagai bagian jalur dari configURL
di navigator.credentials.get
oleh RP. Jumlah string URL dalam array dibatasi hingga satu, tetapi ini dapat berubah dengan masukan Anda di masa mendatang.
Membuat endpoint dan file konfigurasi IdP
File konfigurasi IdP menyediakan daftar endpoint yang diperlukan untuk browser. IdP
akan menghosting file konfigurasi ini serta endpoint dan URL yang diperlukan. Semua respons
JSON harus ditayangkan dengan jenis konten application/json
.
URL file konfigurasi ditentukan oleh nilai yang diberikan ke
panggilan navigator.credentials.get
yang dijalankan pada RP.
const credential = await navigator.credentials.get({
identity: {
context: 'signup',
providers: [{
configURL: 'https://accounts.idp.example/config.json',
clientId: '********',
nonce: '******'
}]
}
});
const { token } = credential;
Tentukan URL lengkap lokasi file konfigurasi IdP sebagai configURL
. Saat
navigator.credentials.get()
dipanggil di RP, browser
akan mengambil file konfigurasi dengan permintaan GET
tanpa header Origin
atau
header Referer
. Permintaan tidak memiliki cookie dan tidak mengikuti pengalihan.
Hal ini secara efektif mencegah IdP mempelajari siapa yang membuat permintaan dan
RP mana yang mencoba terhubung. Contoh:
GET /config.json HTTP/1.1
Host: accounts.idp.example
Accept: application/json
Sec-Fetch-Dest: webidentity
Browser mengharapkan respons JSON dari IdP yang menyertakan properti berikut:
Properti | Deskripsi |
---|---|
accounts_endpoint (diperlukan) |
URL untuk endpoint akun. |
client_metadata_endpoint (opsional) |
URL untuk endpoint metadata klien. |
id_assertion_endpoint (diperlukan) |
URL untuk endpoint pernyataan ID. |
disconnect (opsional) |
URL untuk endpoint pecah koneksi. |
login_url (diperlukan) |
URL halaman login bagi pengguna untuk login ke IdP. |
branding (opsional) |
Objek yang berisi berbagai opsi branding. |
branding.background_color (opsional) |
Opsi branding yang menetapkan warna latar belakang tombol "Lanjutkan sebagai...". Gunakan sintaksis CSS yang relevan, yaitu
hex-color ,
hsl() ,
rgb() , atau
named-color . |
branding.color (opsional) |
Opsi branding yang menetapkan warna teks tombol "Lanjutkan sebagai...". Gunakan sintaksis CSS yang relevan, yaitu
hex-color ,
hsl() ,
rgb() , atau
named-color . |
branding.icons (opsional) |
Opsi branding yang menetapkan objek ikon, yang ditampilkan dalam dialog login. Objek ikon adalah array dengan dua parameter:
|
RP dapat mengubah string dalam UI dialog FedCM melalui nilai identity.context
untuk navigator.credentials.get()
guna mengakomodasi konteks autentikasi
yang telah ditetapkan. Properti opsional dapat berupa salah satu dari "signin"
(default), "signup"
, "use"
, atau "continue"
.
Berikut adalah contoh isi respons dari IdP:
{
"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
}]
}
}
Setelah mengambil file konfigurasi, browser akan mengirimkan permintaan berikutnya ke endpoint IdP:
Endpoint akun
Endpoint akun IdP menampilkan daftar akun yang saat ini digunakan pengguna untuk login di IdP. Jika IdP mendukung beberapa akun, endpoint ini akan menampilkan semua akun yang digunakan untuk login.
Browser mengirim permintaan GET
dengan cookie dengan SameSite=None
, tetapi tanpa
parameter client_id
, header Origin
, atau header Referer
. Hal ini
secara efektif mencegah IdP mempelajari RP mana yang coba digunakan pengguna
untuk login. Contoh:
GET /accounts.php HTTP/1.1
Host: accounts.idp.example
Accept: application/json
Cookie: 0x23223
Sec-Fetch-Dest: webidentity
Setelah menerima permintaan, server harus:
- Pastikan permintaan berisi header HTTP
Sec-Fetch-Dest: webidentity
. - Cocokkan cookie sesi dengan ID akun yang sudah login.
- Tanggapi dengan daftar akun.
Browser mengharapkan respons JSON yang menyertakan properti accounts
dengan array informasi akun dan properti berikut:
Properti | Deskripsi |
---|---|
id (diperlukan) |
ID unik pengguna. |
name (diperlukan) |
Nama depan dan nama belakang pengguna. |
email (diperlukan) |
Alamat email pengguna. |
given_name (opsional) |
Nama depan pengguna. |
picture (opsional) |
URL gambar avatar pengguna. |
approved_clients (opsional) |
Array client ID RP yang telah didaftarkan pengguna. |
login_hints (opsional) |
Array semua kemungkinan jenis filter yang didukung IdP untuk menentukan
akun. RP dapat memanggil navigator.credentials.get() dengan properti loginHint untuk menampilkan akun yang ditentukan secara selektif. |
domain_hints (opsional) |
Array semua domain yang dikaitkan dengan akun. RP dapat memanggil navigator.credentials.get() dengan properti domainHint untuk memfilter akun. |
Contoh isi respons:
{
"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"]
}]
}
Jika pengguna tidak login, respons dengan HTTP 401 (Tidak sah).
Daftar akun yang ditampilkan digunakan oleh browser dan tidak akan tersedia untuk RP.
Endpoint metadata klien
Endpoint metadata klien IdP menampilkan metadata pihak tepercaya seperti kebijakan privasi dan persyaratan layanan RP. RP harus memberikan link ke kebijakan privasi dan persyaratan layanan ke IdP terlebih dahulu. Link ini ditampilkan dalam dialog login saat pengguna belum terdaftar di RP dengan IdP.
Browser mengirim permintaan GET
menggunakan client_id
navigator.credentials.get
tanpa cookie. Contoh:
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
Setelah menerima permintaan, server harus:
- Tentukan RP untuk
client_id
. - Merespons dengan metadata klien.
Properti untuk endpoint metadata klien meliputi:
Properti | Deskripsi |
---|---|
privacy_policy_url (opsional) |
URL kebijakan privasi RP. |
terms_of_service_url (opsional) |
URL persyaratan layanan RP. |
Browser mengharapkan respons JSON dari endpoint:
{
"privacy_policy_url": "https://rp.example/privacy_policy.html",
"terms_of_service_url": "https://rp.example/terms_of_service.html",
}
Metadata klien yang ditampilkan digunakan oleh browser dan tidak akan tersedia untuk RP.
Endpoint pernyataan ID
Endpoint pernyataan ID IdP akan menampilkan pernyataan untuk pengguna yang login.
Saat pengguna login ke situs RP menggunakan panggilan
navigator.credentials.get()
, browser akan mengirimkan permintaan POST
dengan cookie dengan
SameSite=None
dan jenis konten application/x-www-form-urlencoded
ke
endpoint ini dengan informasi berikut:
Properti | Deskripsi |
---|---|
client_id (diperlukan) |
ID klien RP. |
account_id (diperlukan) |
ID unik pengguna yang login. |
nonce (opsional) |
Nonce permintaan, yang disediakan oleh RP. |
disclosure_text_shown |
Menghasilkan string "true" atau "false" (bukan boolean). Hasilnya adalah "false" jika teks pengungkapan tidak ditampilkan. Hal ini terjadi jika client ID RP disertakan dalam daftar properti approved_clients respons dari endpoint akun atau jika browser telah mengamati momen pendaftaran di masa lalu tanpa adanya approved_clients . |
is_auto_selected |
Jika autentikasi ulang otomatis dilakukan di RP, is_auto_selected akan menunjukkan "true" . Atau "false" . Tindakan ini berguna untuk mendukung fitur terkait keamanan lainnya. Misalnya, beberapa pengguna mungkin lebih memilih tingkat keamanan yang lebih tinggi yang memerlukan mediasi pengguna eksplisit dalam autentikasi. Jika menerima permintaan token tanpa mediasi tersebut, IdP dapat menangani permintaan tersebut secara berbeda. Misalnya, tampilkan kode error sehingga RP dapat memanggil FedCM API lagi dengan mediation: required . |
Contoh header HTTP:
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
Setelah menerima permintaan, server harus:
- Tanggapi permintaan dengan CORS (Cross-Origin Resource Sharing).
- Pastikan permintaan berisi header HTTP
Sec-Fetch-Dest: webidentity
. - Cocokkan header
Origin
dengan asal RP yang ditentukan berdasarkanclient_id
. Tolak jika tidak cocok. - Cocokkan
account_id
dengan ID akun yang sudah digunakan untuk login. Tolak jika tidak cocok. - Berikan respons dengan token. Jika permintaan ditolak, respons dengan respons error.
Cara penerbitan token bergantung pada IdP, tetapi secara umum, token tersebut ditandatangani dengan informasi seperti ID akun, client ID, asal penerbit, nonce
, sehingga RP dapat memverifikasi bahwa token tersebut asli.
Browser mengharapkan respons JSON yang menyertakan properti berikut:
Properti | Deskripsi |
---|---|
token (diperlukan) |
Token adalah string yang berisi klaim tentang otentikasi. |
{
"token": "***********"
}
Token yang ditampilkan diteruskan ke RP oleh browser, sehingga RP dapat memvalidasi autentikasi.
Menampilkan respons error
id_assertion_endpoint
juga dapat menampilkan respons "error", yang memiliki dua kolom opsional:
code
: IdP dapat memilih salah satu error yang diketahui dari daftar error yang ditentukan OAuth 2.0 (invalid_request
,unauthorized_client
,access_denied
,server_error
, dantemporarily_unavailable
) atau menggunakan string arbitrer apa pun. Jika yang kedua, Chrome akan merender UI error dengan pesan error umum dan meneruskan kode ke RP.url
: Atribut ini mengidentifikasi halaman web yang dapat dibaca manusia berisi informasi tentang error untuk memberikan informasi tambahan tentang error tersebut kepada pengguna. Kolom ini berguna bagi pengguna karena browser tidak dapat memberikan pesan error yang kaya dalam UI native. Misalnya, link untuk langkah berikutnya, informasi kontak layanan pelanggan, dan sebagainya. Jika ingin mempelajari detail error dan cara memperbaikinya lebih lanjut, pengguna dapat mengunjungi halaman yang disediakan dari UI browser untuk mengetahui detail selengkapnya. URL harus berupa situs yang sama dengan IdPconfigURL
.
// id_assertion_endpoint response
{
"error" : {
"code": "access_denied",
"url" : "https://idp.example/error?type=access_denied"
}
}
Memutuskan koneksi endpoint
Dengan memanggil IdentityCredential.disconnect()
, browser akan mengirimkan permintaan POST
lintas origin
dengan cookie dengan SameSite=None
dan jenis konten
application/x-www-form-urlencoded
ke endpoint pemutusan koneksi ini dengan
informasi berikut:
Properti | Deskripsi |
---|---|
account_hint |
Petunjuk untuk akun IdP. |
client_id |
ID klien RP. |
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
Setelah menerima permintaan, server harus:
- Tanggapi permintaan dengan CORS (Cross-Origin Resource Sharing).
- Pastikan permintaan berisi header HTTP
Sec-Fetch-Dest: webidentity
. - Cocokkan header
Origin
dengan asal RP yang ditentukan berdasarkanclient_id
. Tolak jika tidak cocok. - Cocokkan
account_hint
dengan ID akun yang sudah login. - Putuskan hubungan akun pengguna dari RP.
- Tampilkan respons ke browser dengan informasi akun pengguna yang diidentifikasi dalam format JSON.
Contoh payload JSON respons terlihat seperti ini:
{
"account_id": "account456"
}
Sebagai gantinya, jika IdP ingin browser memutuskan sambungan semua akun yang terkait dengan
RP, teruskan string yang tidak cocok dengan ID akun mana pun, misalnya "*"
.
URL Login
Dengan Login Status API, IdP harus memberitahukan status login
pengguna ke browser. Namun, statusnya mungkin tidak sinkron, seperti
saat sesi berakhir. Dalam skenario semacam ini, browser dapat secara dinamis mengizinkan pengguna login ke IdP melalui URL halaman
login yang ditentukan dengan login_url
dari file konfigurasi IDp.
Dialog FedCM menampilkan pesan yang menyarankan login, seperti ditunjukkan dalam gambar berikut.
Saat pengguna mengklik tombol Continue, browser akan membuka jendela pop-up untuk halaman login IdP.
Dialog ini adalah jendela browser biasa yang memiliki cookie pihak pertama. Apa pun yang terjadi dalam dialog bergantung pada IdP, dan tidak ada tuas jendela yang tersedia untuk membuat permintaan komunikasi lintas origin ke halaman RP. Setelah pengguna login, IdP akan:
- Kirim header
Set-Login: logged-in
atau panggilnavigator.login.setStatus("logged-in")
API untuk memberi tahu browser bahwa pengguna telah login. - Panggil
IdentityProvider.close()
untuk menutup dialog.
Memberi tahu browser tentang status login pengguna di Penyedia Identitas
Login Status API adalah mekanisme yang digunakan situs, terutama IdP, untuk memberi tahu status login pengguna pada IdP ke browser. Dengan API ini, browser dapat mengurangi permintaan yang tidak perlu ke IdP dan mengurangi potensi serangan pengaturan waktu.
IdP dapat memberikan sinyal status login pengguna ke browser dengan mengirimkan header HTTP
atau dengan memanggil JavaScript API saat pengguna login di IdP atau saat
pengguna logout dari semua akun IdP mereka. Untuk setiap IdP (yang diidentifikasi oleh
URL konfigurasinya), browser menyimpan variabel tri-status yang mewakili status login
dengan kemungkinan nilai logged-in
, logged-out
, dan unknown
. Status default-nya
adalah unknown
.
Untuk menandakan bahwa pengguna sudah login, kirim header HTTP Set-Login: logged-in
di navigasi level atas atau permintaan subresource situs yang sama di origin
IdP:
Set-Login: logged-in
Atau, panggil JavaScript API navigator.login.setStatus("logged-in")
dari origin IdP di navigasi tingkat atas:
navigator.login.setStatus("logged-in")
Panggilan ini mencatat status login pengguna sebagai logged-in
. Jika status login pengguna
ditetapkan ke logged-in
, RP yang memanggil FedCM akan membuat permintaan ke endpoint akun
IdP dan menampilkan akun yang tersedia kepada pengguna dalam dialog
FedCM.
Untuk menandakan bahwa pengguna logout dari semua akunnya, kirim header HTTP Set-Login:
logged-out
di navigasi level atas atau permintaan subresource situs yang sama
di asal IdP:
Set-Login: logged-out
Atau, panggil JavaScript API navigator.login.setStatus("logged-out")
dari origin IdP di navigasi tingkat atas:
navigator.login.setStatus("logged-out")
Panggilan ini mencatat status login pengguna sebagai logged-out
. Jika status login pengguna adalah logged-out
, memanggil FedCM akan otomatis gagal tanpa membuat permintaan ke endpoint akun IdP.
Status unknown
ditetapkan sebelum IdP mengirim sinyal menggunakan Login Status
API. Unknown
diperkenalkan untuk transisi yang lebih baik, karena pengguna mungkin sudah
login ke IdP saat API ini dikirimkan. IdP mungkin tidak
dapat memberikan sinyal ke browser saat FedCM pertama kali dipanggil. Dalam hal
ini, Chrome akan membuat permintaan ke endpoint akun IdP dan memperbarui
status berdasarkan respons dari endpoint akun:
- Jika endpoint menampilkan daftar akun aktif, perbarui statusnya menjadi
logged-in
dan buka dialog FedCM untuk menampilkan akun tersebut. - Jika endpoint tidak menampilkan akun, perbarui status menjadi
logged-out
dan gagalkan panggilan FedCM.
Mengizinkan pengguna login melalui alur login dinamis
Meskipun IdP terus memberi tahu status login pengguna ke browser, IdP mungkin
tidak sinkron, seperti saat sesi berakhir. Browser mencoba
mengirim permintaan berkredensial ke endpoint akun saat status login adalah
logged-in
, tetapi server tidak menampilkan akun karena sesi tidak lagi
tersedia. Dalam skenario semacam ini, browser dapat secara dinamis mengizinkan pengguna login
ke IdP melalui jendela pop-up.
Login ke pihak tepercaya dengan penyedia identitas
Setelah konfigurasi dan endpoint IdP tersedia, RP dapat memanggil
navigator.credentials.get()
untuk meminta izin pengguna login ke RP
dengan IdP.
Sebelum memanggil API, Anda perlu mengonfirmasi bahwa [FedCM tersedia di browser pengguna]. Untuk memeriksa apakah FedCM tersedia, gabungkan kode ini di sekitar implementasi FedCM Anda:
if ('IdentityCredential' in window) {
// If the feature is available, take action
}
Untuk meminta mengizinkan pengguna login ke IdP dari RP, lakukan hal berikut, misalnya:
const credential = await navigator.credentials.get({
identity: {
providers: [{
configURL: 'https://accounts.idp.example/config.json',
clientId: '********',
nonce: '******'
}]
}
});
const { token } = credential;
Properti providers
menggunakan array objek IdentityProvider
yang memiliki properti berikut:
Properti | Deskripsi |
---|---|
configURL (diperlukan) |
Jalur lengkap file konfigurasi IdP. |
clientId (diperlukan) |
ID klien RP, yang dikeluarkan oleh IdP. |
nonce (opsional) |
String acak untuk memastikan respons dikeluarkan untuk permintaan khusus ini. Mencegah serangan replay. |
loginHint (opsional) |
Dengan menentukan salah satu nilai login_hints yang disediakan oleh
endpoint akun, dialog FedCM
secara selektif menampilkan akun yang ditentukan. |
domainHint (opsional) |
Dengan menentukan salah satu nilai domain_hints yang disediakan oleh
endpoint akun, dialog FedCM
secara selektif menampilkan akun yang ditentukan. |
Browser menangani kasus penggunaan pendaftaran dan login secara berbeda, bergantung pada keberadaan approved_clients
dalam respons dari endpoint daftar akun. Browser tidak akan menampilkan teks
pengungkapan "Untuk melanjutkan dengan ...." jika pengguna sudah mendaftar ke RP.
Status pendaftaran ditentukan berdasarkan apakah kondisi berikut terpenuhi atau tidak:
- Jika
approved_clients
menyertakanclientId
RP. - Jika browser mengingat bahwa pengguna telah mendaftar ke RP.
Saat RP memanggil navigator.credentials.get()
, aktivitas berikut akan
terjadi:
- Browser mengirim permintaan dan mengambil beberapa dokumen:
- File terkenal dan file konfigurasi IdP yang mendeklarasikan endpoint.
- Daftar akun.
- Opsional: URL untuk kebijakan privasi dan persyaratan layanan RP, yang diambil dari endpoint metadata klien.
- Browser menampilkan daftar akun yang dapat digunakan pengguna untuk login, serta persyaratan layanan dan kebijakan privasi jika tersedia.
- Setelah pengguna memilih akun yang akan digunakan untuk login, permintaan ke endpoint pernyataan ID akan dikirim ke IdP untuk mengambil token.
- RP dapat melakukan validasi token untuk mengotentikasi pengguna.
RP diharapkan dapat mendukung browser yang tidak mendukung FedCM, sehingga pengguna harus dapat menggunakan proses login non-FedCM yang sudah ada. Hingga cookie pihak ketiga dihentikan sepenuhnya, hal ini seharusnya tetap tidak menjadi masalah.
Setelah token divalidasi oleh server RP, RP dapat mendaftarkan pengguna atau mengizinkan mereka login dan memulai sesi baru.
API Petunjuk Login
Setelah pengguna login, terkadang pihak tepercaya (RP) akan meminta pengguna untuk melakukan autentikasi ulang. Namun pengguna mungkin tidak yakin akun mana yang mereka gunakan. Jika RP dapat menentukan akun yang akan digunakan untuk login, pengguna akan lebih mudah memilih akun.
RP dapat menampilkan akun tertentu secara selektif dengan memanggil
navigator.credentials.get()
menggunakan properti loginHint
dengan salah satu
nilai login_hints
yang diambil dari endpoint daftar
akun, seperti yang ditunjukkan dalam contoh kode berikut:
return await navigator.credentials.get({
identity: {
providers: [{
configURL: "https://idp.example/manifest.json",
clientId: "123",
nonce: nonce,
loginHint : "demo1@example.com"
}]
}
});
Jika tidak ada akun yang cocok dengan loginHint
, dialog FedCM akan menampilkan perintah login,
yang memungkinkan pengguna login ke akun IdP yang cocok dengan petunjuk yang diminta oleh
RP. Saat pengguna mengetuk perintah, jendela pop-up akan terbuka dengan URL login yang ditentukan dalam file konfigurasi. Link tersebut kemudian
ditambahkan dengan petunjuk login dan parameter kueri petunjuk domain.
API Petunjuk Domain
Ada kasus saat RP sudah mengetahui bahwa hanya akun yang terkait dengan domain tertentu yang diizinkan untuk login ke situs. Hal ini sangat umum dalam skenario perusahaan saat situs yang diakses dibatasi untuk domain perusahaan. Untuk memberikan pengalaman pengguna yang lebih baik, FedCM API memungkinkan RP hanya menampilkan akun yang dapat digunakan untuk login ke RP. Tindakan ini mencegah skenario saat pengguna mencoba login ke RP menggunakan akun di luar domain perusahaan, tetapi akan menerima pesan error di kemudian hari (atau senyap saat login tidak berfungsi) karena jenis akun yang tepat tidak digunakan.
RP dapat secara selektif hanya menampilkan akun yang cocok dengan memanggil
navigator.credentials.get()
menggunakan properti domainHint
menggunakan salah satu
nilai domain_hints
yang diambil dari endpoint daftar
akun, seperti yang ditunjukkan dalam contoh kode berikut:
return await navigator.credentials.get({
identity: {
providers: [{
configURL: "https://idp.example/manifest.json",
clientId: "abc",
nonce: nonce,
domainHint : "corp.example"
}]
}
});
Jika tidak ada akun yang cocok dengan domainHint
, dialog FedCM akan menampilkan perintah login,
yang memungkinkan pengguna login ke akun IdP yang cocok dengan petunjuk yang diminta oleh
RP. Saat pengguna mengetuk perintah, jendela pop-up akan terbuka dengan URL login yang ditentukan dalam file konfigurasi. Link tersebut kemudian
ditambahkan dengan petunjuk login dan parameter kueri petunjuk domain.
Menampilkan pesan error
Terkadang, IdP mungkin tidak dapat mengeluarkan token karena alasan yang sah, seperti jika klien tidak diberi otorisasi, server tidak tersedia untuk sementara. Jika IdP menampilkan respons "error", RP dapat menangkapnya, serta Chrome akan memberi tahu pengguna dengan menampilkan UI browser berisi informasi error yang disediakan oleh IdP.
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;
}
Autentikasi ulang otomatis pengguna setelah autentikasi awal
Autentikasi ulang otomatis FedCM (singkatan "auto-reauthn") dapat memungkinkan pengguna melakukan autentikasi ulang secara otomatis saat mereka kembali setelah melakukan autentikasi awal menggunakan FedCM. "Autentikasi awal" di sini berarti pengguna membuat akun atau login ke situs RP dengan mengetuk tombol "Continue as..." pada dialog login FedCM untuk pertama kalinya pada instance browser yang sama.
Meskipun pengalaman pengguna yang eksplisit masuk akal sebelum pengguna membuat akun gabungan untuk mencegah pelacakan (yang merupakan salah satu sasaran utama FedCM), akan cukup rumit setelah pengguna melakukannya sekali: setelah pengguna memberikan izin untuk memungkinkan komunikasi antara RP dan IdP, tidak ada manfaat privasi atau keamanan untuk menerapkan konfirmasi pengguna eksplisit lainnya untuk sesuatu yang telah mereka konfirmasi sebelumnya.
Dengan autentikasi ulang otomatis, browser akan mengubah perilakunya bergantung pada opsi yang Anda
tentukan untuk mediation
saat memanggil navigator.credentials.get()
.
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
adalah properti dalam Credential Management
API,
berperilaku dengan
cara yang sama
seperti yang dilakukan untuk
PasswordCredential
dan
FederatedCredential
dan juga didukung sebagian oleh
PublicKeyCredential. Properti ini menerima empat nilai berikut:
'optional'
(default): Autentikasi ulang otomatis jika memungkinkan, memerlukan mediasi jika tidak. Sebaiknya pilih opsi ini di halaman login.'required'
: Selalu mewajibkan mediasi untuk melanjutkan, misalnya mengklik tombol "Lanjutkan" di UI. Pilih opsi ini jika pengguna Anda diharapkan untuk memberikan izin secara eksplisit setiap kali mereka perlu diautentikasi.'silent'
: Autentikasi ulang otomatis jika memungkinkan, otomatis gagal tanpa memerlukan mediasi jika tidak. Sebaiknya pilih opsi ini di halaman selain halaman login khusus, tetapi tempat Anda ingin pengguna tetap login, misalnya, halaman item di situs pengiriman atau halaman artikel di situs berita.'conditional'
: Digunakan untuk WebAuthn dan tidak tersedia untuk FedCM saat ini.
Dengan panggilan ini, autentikasi ulang otomatis terjadi dalam kondisi berikut:
- FedCM tersedia untuk digunakan. Misalnya, pengguna belum menonaktifkan FedCM baik secara global maupun untuk RP di setelan.
- Pengguna hanya menggunakan satu akun dengan FedCM API untuk login ke situs di browser ini.
- Pengguna login ke IdP dengan akun tersebut.
- Autentikasi ulang otomatis tidak terjadi dalam 10 menit terakhir.
- RP belum memanggil
navigator.credentials.preventSilentAccess()
setelah login sebelumnya.
Saat kondisi ini terpenuhi, upaya untuk mengautentikasi ulang pengguna secara otomatis akan dimulai segera setelah FedCM navigator.credentials.get()
dipanggil.
Saat mediation: optional
, autentikasi ulang otomatis mungkin tidak tersedia karena alasan yang hanya diketahui oleh browser. RP dapat memeriksa apakah autentikasi ulang otomatis dilakukan dengan memeriksa properti isAutoSelected
.
Langkah ini sangat membantu untuk mengevaluasi performa API dan meningkatkan UX yang sesuai.
Selain itu, jika tidak tersedia, pengguna mungkin diminta untuk login dengan mediasi pengguna eksplisit, yang merupakan alur dengan mediation: required
.
Terapkan mediasi dengan preventSilentAccess()
Autentikasi ulang otomatis pengguna segera setelah mereka logout tidak akan memberikan pengalaman pengguna yang sangat baik. Itulah sebabnya FedCM memiliki masa tenang 10 menit setelah autentikasi ulang otomatis untuk mencegah perilaku ini. Artinya, autentikasi ulang otomatis paling sering terjadi setiap 10 menit sekali, kecuali jika pengguna login kembali dalam waktu 10 menit. RP harus memanggil navigator.credentials.preventSilentAccess()
untuk secara eksplisit meminta browser menonaktifkan autentikasi ulang otomatis saat pengguna logout dari RP secara eksplisit, misalnya, dengan mengklik tombol logout.
function signout() {
navigator.credentials.preventSilentAccess();
location.href = '/signout';
}
Pengguna dapat memilih untuk tidak mengaktifkan ulang otomatis di setelan
Pengguna dapat memilih untuk tidak menggunakan autentikasi ulang otomatis dari menu setelan:
- Di Chrome desktop, buka
chrome://password-manager/settings
> Login secara otomatis. - Di Android Chrome, buka Setelan > Pengelola Sandi > Ketuk roda gigi di pojok kanan atas > Login otomatis.
Dengan menonaktifkan tombol tersebut, pengguna dapat memilih untuk tidak ikut perilaku autentikasi ulang otomatis. Setelan ini disimpan dan disinkronkan di seluruh perangkat, jika pengguna login ke Akun Google di instance Chrome dan sinkronisasi diaktifkan.
Memutuskan koneksi IdP dari RP
Jika sebelumnya pengguna telah login ke RP menggunakan IdP melalui FedCM, hubungan tersebut akan diingat oleh browser secara lokal sebagai daftar akun
yang terhubung. RP dapat memulai pemutusan koneksi dengan memanggil
fungsi IdentityCredential.disconnect()
. Fungsi ini dapat dipanggil dari
frame RP level atas. RP harus meneruskan configURL
, clientId
yang digunakannya
di bawah IdP, dan accountHint
untuk memutuskan sambungan IdP. Petunjuk
akun dapat berupa string arbitrer selama endpoint pemutusan koneksi dapat mengidentifikasi
akun, misalnya alamat email atau ID pengguna yang tidak selalu
cocok dengan ID akun yang diberikan endpoint daftar akun:
// 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()
menampilkan Promise
. Promise ini dapat menampilkan pengecualian karena alasan berikut:
- Pengguna belum login ke RP menggunakan IdP melalui FedCM.
- API dipanggil dari dalam iframe tanpa kebijakan izin FedCM.
- configURL tidak valid atau tidak memiliki endpoint pemutusan koneksi.
- Pemeriksaan Kebijakan Keamanan Konten (CSP) gagal.
- Ada permintaan pemutusan hubungan yang tertunda.
- Pengguna telah menonaktifkan FedCM di setelan browser.
Saat endpoint pemutusan koneksi IdP menampilkan respons, RP dan IdP akan terputus sambungannya di browser dan promise akan diselesaikan. ID akun yang terputus ditentukan dalam respons dari endpoint pemutusan.
Memanggil FedCM dari dalam iframe lintas origin
FedCM dapat dipanggil dari dalam iframe lintas origin menggunakan
kebijakan izin identity-credentials-get
, jika frame induk mengizinkannya. Untuk
melakukannya, tambahkan atribut allow="identity-credentials-get"
ke tag iframe
seperti berikut:
<iframe src="https://fedcm-cross-origin-iframe.glitch.me" allow="identity-credentials-get"></iframe>
Anda dapat melihat cara kerjanya dalam contoh.
Secara opsional, jika frame induk ingin membatasi origin untuk memanggil FedCM,
kirim header Permissions-Policy
dengan daftar origin yang diizinkan.
Permissions-Policy: identity-credentials-get=(self "https://fedcm-cross-origin-iframe.glitch.me")
Anda dapat mempelajari lebih lanjut cara kerja Kebijakan Izin di Mengontrol fitur browser dengan Kebijakan Izin.