Panduan Developer Federated Credential Management API

Pelajari cara menggunakan FedCM untuk federasi identitas yang menjaga privasi.

FedCM (Federated Credential Management) adalah pendekatan yang menjaga privasi untuk layanan identitas gabungan (seperti "Login dengan...") tempat pengguna dapat login ke situs tanpa membagikan informasi pribadi mereka dengan layanan identitas atau situs.

Untuk mempelajari lebih lanjut kasus penggunaan FedCM, alur penggunaan, dan roadmap API, lihat introduksi FedCM API.

Lingkungan pengembangan FedCM

Anda memerlukan konteks aman (HTTPS atau localhost) di IdP dan RP di Chrome untuk menggunakan FedCM.

Men-debug kode di Chrome di 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 Men-debug perangkat Android dari jarak jauh.

Memblokir cookie pihak ketiga di Chrome

Memblokir cookie pihak ketiga dari setelan Chrome
Memblokir cookie pihak ketiga dari setelan Chrome

Anda dapat menguji cara kerja FedCM tanpa cookie pihak ketiga di Chrome sebelum diberlakukan.

Untuk memblokir cookie pihak ketiga, gunakan mode Samaran, atau pilih "Blokir cookie pihak ketiga" di setelan desktop Anda di chrome://settings/cookies atau di perangkat seluler dengan membuka Setelan > Setelan situs > Cookie.

Menggunakan FedCM API

Anda berintegrasi dengan FedCM dengan membuat file yang dikenal, file konfigurasi dan endpoint untuk daftar akun, pemberian pernyataan, dan secara opsional metadata klien.

Dari sana, FedCM mengekspos JavaScript API yang dapat digunakan RP untuk login dengan IdP.

Membuat file well-known

Untuk mencegah pelacak menyalahgunakan API, file yang dikenal baik harus ditayangkan dari /.well-known/web-identity dari eTLD+1 dari IdP.

Misalnya, jika endpoint IdP ditayangkan di https://accounts.idp.example/, endpoint tersebut harus menayangkan file well-known di https://idp.example/.well-known/web-identity serta file konfigurasi IdP. Berikut adalah 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 configURL di navigator.credentials.get oleh RP. Jumlah string URL dalam array dibatasi hingga satu, tetapi hal ini dapat berubah dengan masukan Anda di masa mendatang.

Membuat file konfigurasi dan endpoint 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 di 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 mengetahui 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 (wajib diisi) URL untuk endpoint akun.
client_metadata_endpoint (opsional) URL untuk endpoint metadata klien.
id_assertion_endpoint (wajib diisi) URL untuk endpoint pernyataan ID.
disconnect (opsional) URL untuk endpoint pemutusan hubungan.
login_url (wajib diisi) URL halaman login untuk pengguna 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 di dialog login. Objek ikon adalah array dengan dua parameter:
  • url (wajib): URL gambar ikon. Fitur ini tidak mendukung gambar SVG.
  • size (opsional): dimensi ikon, yang diasumsikan oleh aplikasi sebagai persegi dan resolusi tunggal. Angka ini harus lebih besar dari atau sama dengan 25.

RP dapat mengubah string di UI dialog FedCM menggunakan nilai identity.context untuk navigator.credentials.get() guna mengakomodasi konteks autentikasi yang telah ditentukan sebelumnya. Properti opsional dapat berupa salah satu dari "signin" (default), "signup", "use", atau "continue".

Cara penerapan branding ke dialog FedCM
Cara penerapan branding ke dialog FedCM

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 mengirim permintaan berikutnya ke endpoint IdP:

Endpoint IdP
Endpoint IdP

Endpoint akun

Endpoint akun IdP menampilkan daftar akun yang digunakan pengguna untuk login ke IdP. Jika IdP mendukung beberapa akun, endpoint ini akan menampilkan semua akun yang login.

Browser mengirimkan permintaan GET dengan cookie dengan SameSite=None, tetapi tanpa parameter client_id, header Origin, atau header Referer. Hal ini secara efektif mencegah IdP mengetahui RP mana yang dicoba diakses oleh pengguna. 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:

  1. Pastikan permintaan berisi header HTTP Sec-Fetch-Dest: webidentity.
  2. Cocokkan cookie sesi dengan ID akun yang sudah login.
  3. Respons dengan daftar akun.

Browser mengharapkan respons JSON yang menyertakan properti accounts dengan array informasi akun dengan properti berikut:

Properti Deskripsi
id (wajib diisi) ID unik pengguna.
name (wajib diisi) Nama depan dan nama keluarga pengguna.
email (wajib diisi) 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 dari 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 dari semua domain yang terkait 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 Diberi Otorisasi).

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 mereka ke IdP terlebih dahulu. Link ini ditampilkan dalam dialog login saat pengguna belum mendaftar 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:

  1. Tentukan RP untuk client_id.
  2. Respons dengan metadata klien.

Properti untuk endpoint metadata klien mencakup:

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 menampilkan pernyataan untuk pengguna yang login. Saat pengguna login ke situs RP menggunakan panggilan navigator.credentials.get(), browser akan mengirim 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 (wajib diisi) ID klien RP.
account_id (wajib diisi) ID unik pengguna yang login.
nonce (opsional) Nonce permintaan, yang diberikan 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 sebelumnya tanpa adanya approved_clients.
is_auto_selected Jika autentikasi ulang otomatis dilakukan di RP, is_auto_selected akan menunjukkan "true". Atau "false". Hal ini berguna untuk mendukung lebih banyak fitur terkait keamanan. Misalnya, beberapa pengguna mungkin lebih memilih tingkat keamanan yang lebih tinggi yang memerlukan mediasi pengguna eksplisit dalam autentikasi. Jika IdP menerima permintaan token tanpa mediasi tersebut, IdP dapat menangani permintaan dengan cara yang 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:

  1. Respons permintaan dengan CORS (Cross-Origin Resource Sharing).
  2. Pastikan permintaan berisi header HTTP Sec-Fetch-Dest: webidentity.
  3. Cocokkan header Origin dengan origin RP yang ditentukan oleh client_id. Tolak jika tidak cocok.
  4. Cocokkan account_id dengan ID akun yang sudah login. Tolak jika tidak cocok.
  5. Respons dengan token. Jika permintaan ditolak, respons dengan respons error.

Cara token dikeluarkan bergantung pada IdP, tetapi secara umum, token 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 (wajib diisi) Token adalah string yang berisi klaim tentang autentikasi. 
{
  "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, dan temporarily_unavailable) atau menggunakan string arbitrer. Jika yang terakhir, Chrome akan merender UI error dengan pesan error umum dan meneruskan kode ke RP.
  • url: Fungsi ini mengidentifikasi halaman web yang dapat dibaca manusia dengan informasi tentang error untuk memberikan informasi tambahan tentang error kepada pengguna. Kolom ini berguna bagi pengguna karena browser tidak dapat memberikan pesan error yang lengkap dalam UI bawaan. Misalnya: link untuk langkah berikutnya, atau informasi kontak layanan pelanggan. Jika pengguna ingin mempelajari lebih lanjut detail error dan cara memperbaikinya, mereka dapat membuka halaman yang disediakan dari UI browser untuk mengetahui detail selengkapnya. URL harus berasal dari situs yang sama dengan configURL IdP.
// id_assertion_endpoint response
{
  "error" : {
     "code": "access_denied",
     "url" : "https://idp.example/error?type=access_denied"
  }
}

Memutuskan sambungan 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:

  1. Respons permintaan dengan CORS (Cross-Origin Resource Sharing).
  2. Pastikan permintaan berisi header HTTP Sec-Fetch-Dest: webidentity.
  3. Cocokkan header Origin dengan origin RP yang ditentukan oleh client_id. Tolak jika tidak cocok.
  4. Cocokkan account_hint dengan ID akun yang sudah login.
  5. Putuskan sambungan akun pengguna dari RP.
  6. Respons 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 semua akun yang terkait dengan RP, teruskan string yang tidak cocok dengan ID akun apa pun, misalnya "*".

URL Login

Dengan Login Status API, IdP harus menginformasikan status login pengguna ke browser. Namun, statusnya mungkin tidak sinkron, seperti saat sesi berakhir. Dalam skenario tersebut, browser dapat secara dinamis mengizinkan pengguna login ke IdP melalui URL halaman login yang ditentukan dengan login_url file konfigurasi idp.

Dialog FedCM menampilkan pesan yang menyarankan login, seperti yang ditunjukkan pada gambar berikut.

A
Dialog FedCM yang menyarankan untuk login ke IdP.

Saat pengguna mengklik tombol Lanjutkan, browser akan membuka jendela pop-up untuk halaman login IdP.

Contoh dialog FedCM.
Contoh dialog yang ditampilkan setelah mengklik tombol login ke IdP.

Dialog ini adalah jendela browser biasa yang memiliki cookie pihak pertama. Apa pun yang terjadi dalam dialog bergantung pada IdP, dan tidak ada handle jendela yang tersedia untuk membuat permintaan komunikasi lintas-asal ke halaman RP. Setelah pengguna login, IdP harus:

  • Kirim header Set-Login: logged-in atau panggil navigator.login.setStatus("logged-in") API untuk memberi tahu browser bahwa pengguna telah login.
  • Panggil IdentityProvider.close() untuk menutup dialog.
Pengguna login ke RP setelah login ke IdP menggunakan FedCM.

Memberi tahu browser tentang status login pengguna di penyedia identitas

Login Status API adalah mekanisme saat situs, terutama IdP, memberi tahu browser status login pengguna di IdP. 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-nya. Untuk setiap IdP (diidentifikasi oleh URL konfigurasinya), browser menyimpan variabel tiga status yang mewakili status login dengan kemungkinan nilai logged-in, logged-out, dan unknown. Status defaultnya adalah unknown.

Untuk memberi sinyal bahwa pengguna login, kirim header HTTP Set-Login: logged-in dalam navigasi tingkat atas atau permintaan sub-resource situs yang sama di origin IdP:

Set-Login: logged-in

Atau, panggil JavaScript API navigator.login.setStatus("logged-in") dari origin IdP dalam 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 memberi sinyal bahwa pengguna logout dari semua akunnya, kirim header HTTP Set-Login: logged-out dalam navigasi tingkat teratas atau permintaan sub-resource situs yang sama di origin IdP:

Set-Login: logged-out

Atau, panggil JavaScript API navigator.login.setStatus("logged-out") dari origin IdP dalam 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 gagal secara otomatis 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 telah login ke IdP saat API ini dikirim. IdP mungkin tidak memiliki kesempatan untuk memberikan sinyal ini ke browser pada saat FedCM pertama kali dipanggil. Dalam hal ini, Chrome 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 ke logged-out dan gagalkan panggilan FedCM.

Mengizinkan pengguna login melalui alur login dinamis

Meskipun IdP terus memberi tahu status login pengguna ke browser, status tersebut dapat tidak sinkron, seperti saat sesi berakhir. Browser mencoba mengirim permintaan kredensial ke endpoint akun saat status login adalah logged-in, tetapi server tidak menampilkan akun karena sesi tidak lagi tersedia. Dalam skenario tersebut, 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 agar pengguna dapat login ke RP dengan IdP.

Sebelum memanggil API, Anda harus mengonfirmasi bahwa FedCM tersedia di browser pengguna. Untuk memeriksa apakah FedCM tersedia, gabungkan kode ini dengan penerapan FedCM Anda:

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

Untuk meminta izin agar pengguna dapat 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 (wajib diisi) Jalur lengkap file konfigurasi IdP.
clientId (wajib diisi) ID klien RP, yang diterbitkan oleh IdP.
nonce (opsional) String acak untuk memastikan respons dikeluarkan untuk permintaan spesifik ini. Mencegah serangan replay.
loginHint (opsional) Dengan menentukan salah satu nilai login_hints yang disediakan oleh endpoint akun, dialog FedCM akan menampilkan akun yang ditentukan secara selektif.
domainHint (opsional) Dengan menentukan salah satu nilai domain_hints yang disediakan oleh endpoint akun, dialog FedCM akan menampilkan akun yang ditentukan secara selektif.

Browser menangani kasus penggunaan pendaftaran dan login secara berbeda, bergantung pada adanya approved_clients dalam respons dari endpoint daftar akun. Browser tidak akan menampilkan teks pengungkapan "Untuk melanjutkan dengan ...." jika pengguna telah mendaftar ke RP.

Status pendaftaran ditentukan berdasarkan apakah kondisi berikut terpenuhi atau tidak:

  • Jika approved_clients menyertakan clientId RP.
  • Jika browser mengingat bahwa pengguna telah mendaftar ke RP.
Pengguna login ke RP menggunakan FedCM.

Saat RP memanggil navigator.credentials.get(), aktivitas berikut akan terjadi:

  1. Browser mengirimkan permintaan dan mengambil beberapa dokumen:
    1. File well-known dan file konfigurasi IdP yang mendeklarasikan endpoint.
    2. Daftar akun.
    3. Opsional: URL untuk kebijakan privasi dan persyaratan layanan RP, yang diambil dari endpoint metadata klien.
  2. Browser menampilkan daftar akun yang dapat digunakan pengguna untuk login, serta persyaratan layanan dan kebijakan privasi jika tersedia.
  3. Setelah pengguna memilih akun untuk login, permintaan ke endpoint pernyataan ID akan dikirim ke IdP untuk mengambil token.
  4. RP dapat memvalidasi token untuk mengautentikasi pengguna.
panggilan API login
panggilan API login

RP diharapkan mendukung browser yang tidak mendukung FedCM, sehingga pengguna harus dapat menggunakan proses login non-FedCM yang ada. Hingga cookie pihak ketiga tidak lagi tersedia di browser, hal ini seharusnya tidak akan menjadi masalah.

Setelah token divalidasi oleh server RP, RP dapat mendaftarkan pengguna atau memungkinkan mereka login dan memulai sesi baru.

Login Hint API

Setelah pengguna login, terkadang pihak tepercaya (RP) meminta pengguna untuk melakukan autentikasi ulang. Namun, pengguna mungkin tidak yakin akun mana yang telah 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() dengan properti loginHint dengan salah satu nilai login_hints yang diambil dari endpoint daftar akun, seperti 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 parameter kueri petunjuk login dan petunjuk domain.

Domain Hint API

Ada kasus saat RP sudah mengetahui bahwa hanya akun yang terkait dengan domain tertentu yang diizinkan untuk login ke situs. Hal ini terutama umum terjadi 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. Hal ini mencegah skenario saat pengguna mencoba login ke RP menggunakan akun di luar domain perusahaan, hanya untuk ditampilkan pesan error nanti (atau diam 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() dengan properti domainHint dengan 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 parameter kueri petunjuk login dan petunjuk domain.

Contoh perintah login saat tidak ada akun yang cocok dengan domainHint.
Contoh perintah login saat tidak ada akun yang cocok dengan domainHint.

Menampilkan pesan error

Terkadang, IdP mungkin tidak dapat menerbitkan token karena alasan yang sah, seperti saat klien tidak memiliki otorisasi, server tidak tersedia untuk sementara. Jika IdP menampilkan respons "error", RP dapat menangkapnya, begitu juga Chrome memberi tahu pengguna dengan menampilkan UI browser dengan informasi error yang diberikan oleh IdP.

A
Dialog FedCM yang menampilkan pesan error setelah upaya login pengguna gagal. String dikaitkan dengan jenis error.
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;
}

Mengautentikasi ulang pengguna secara otomatis setelah autentikasi awal

Autentikasi ulang otomatis FedCM (singkatnya "autentikasi ulang otomatis") dapat memungkinkan pengguna melakukan autentikasi ulang secara otomatis, saat mereka kembali setelah autentikasi awal menggunakan FedCM. "Autentikasi awal" di sini berarti pengguna membuat akun atau login ke situs RP dengan mengetuk tombol "Lanjutkan sebagai..." pada dialog login FedCM untuk pertama kalinya di instance browser yang sama.

Meskipun pengalaman pengguna eksplisit masuk akal sebelum pengguna membuat akun gabungan untuk mencegah pelacakan (yang merupakan salah satu sasaran utama FedCM), pengalaman ini tidak perlu rumit setelah pengguna melakukannya sekali: setelah pengguna memberikan izin untuk mengizinkan komunikasi antara RP dan IdP, tidak ada manfaat privasi atau keamanan untuk menerapkan konfirmasi pengguna eksplisit lain untuk sesuatu yang telah mereka akui sebelumnya.

Dengan auto-reauthn, 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 di Credential Management API, dan berperilaku dengan cara yang sama seperti untuk PasswordCredential dan FederatedCredential dan juga didukung sebagian oleh PublicKeyCredential. Properti ini menerima empat nilai berikut:

  • 'optional'(default): Otomatis melakukan autentikasi ulang jika memungkinkan, memerlukan mediasi jika tidak. Sebaiknya pilih opsi ini di halaman login.
  • 'required': Selalu memerlukan 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': Otomatis melakukan autentikasi ulang jika memungkinkan, gagal secara diam-diam tanpa memerlukan mediasi jika tidak. Sebaiknya pilih opsi ini di halaman selain halaman login khusus, tetapi di halaman tempat Anda ingin pengguna tetap login—misalnya, halaman item di situs pengiriman atau halaman artikel di situs berita.
  • 'conditional': Digunakan untuk WebAuthn dan saat ini tidak tersedia untuk FedCM.

Dengan panggilan ini, autentikasi ulang otomatis terjadi dalam kondisi berikut:

  • FedCM dapat digunakan. Misalnya, pengguna belum menonaktifkan FedCM secara global atau 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.
  • Otorisasi ulang otomatis tidak terjadi dalam 10 menit terakhir.
  • RP belum memanggil navigator.credentials.preventSilentAccess() setelah login sebelumnya.

Jika kondisi ini terpenuhi, upaya untuk mengautentikasi ulang pengguna secara otomatis akan dimulai segera setelah navigator.credentials.get() FedCM dipanggil.

Jika mediation: optional, autentikasi ulang otomatis mungkin tidak tersedia karena alasan yang hanya diketahui browser; RP dapat memeriksa apakah autentikasi ulang otomatis dilakukan dengan memeriksa properti isAutoSelected.

Hal ini berguna untuk mengevaluasi performa API dan meningkatkan UX. Selain itu, jika tidak tersedia, pengguna mungkin diminta untuk login dengan mediasi pengguna eksplisit, yang merupakan alur dengan mediation: required.

Pengguna melakukan autentikasi ulang otomatis melalui FedCM.

Menerapkan mediasi dengan preventSilentAccess()

Mengautentikasi ulang pengguna secara otomatis segera setelah mereka logout tidak akan memberikan pengalaman pengguna yang sangat baik. Itulah sebabnya FedCM memiliki periode tenang 10 menit setelah autentikasi ulang otomatis untuk mencegah perilaku ini. Artinya, autentikasi ulang otomatis terjadi maksimal sekali setiap 10 menit, kecuali jika pengguna login kembali dalam 10 menit. RP harus memanggil navigator.credentials.preventSilentAccess() untuk meminta browser secara eksplisit untuk 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 autentikasi ulang otomatis di setelan

Pengguna dapat memilih untuk tidak mengaktifkan otorisasi ulang otomatis dari menu setelan:

  • Di Chrome desktop, buka chrome://password-manager/settings > Login secara otomatis.
  • Di Chrome Android, buka Setelan > Pengelola Sandi > Ketuk gear di sudut kanan atas > Login otomatis.

Dengan menonaktifkan tombol, pengguna dapat memilih untuk tidak menggunakan 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 pengguna sebelumnya 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 tingkat teratas. RP harus meneruskan configURL, clientId yang digunakannya di bawah IdP, dan accountHint agar IdP terputus. Petunjuk akun dapat berupa string arbitrer selama endpoint pemutusan dapat mengidentifikasi akun, misalnya alamat email atau ID pengguna yang tidak selalu cocok dengan ID akun yang telah disediakan 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 koneksi yang tertunda.
  • Pengguna telah menonaktifkan FedCM di setelan browser.

Saat endpoint pemutusan koneksi IdP menampilkan respons, RP dan IdP akan terputus di browser dan promise akan di-resolve. ID akun yang terputus ditentukan dalam respons dari endpoint putus.

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