Menerapkan solusi identitas dengan FedCM di sisi Pihak Tergantung

Pihak Tepercaya (RP) harus menyelesaikan langkah-langkah berikut untuk mengaktifkan FedCM di situs mereka:

• Pastikan endpoint FedCM diizinkan di situs RP.
• Gunakan FedCM JavaScript API untuk memulai autentikasi pengguna.
• Memberikan metadatanya (seperti URL kebijakan privasi dan persyaratan layanan) ke IdP (atau beberapa IdP dari Chrome 136).
• [opsional] Sesuaikan pengalaman pengguna dengan memilih mode UX, memberikan petunjuk login atau domain, meneruskan parameter kustom, meminta informasi pengguna tertentu, memberikan pesan error kustom, atau memilih cara mengautentikasi ulang pengguna.

Memanggil FedCM API di Pihak Tepercaya

Setelah konfigurasi IdP dan endpoint tersedia, RP dapat memanggil navigator.credentials.get() untuk meminta izin pengguna login ke RP dengan IdP.

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

  if ('IdentityCredential' in window) {
    // If the feature is available, take action
  } else {
    // FedCM is not supported, use a different identity solution
  }

Untuk mengizinkan pengguna login ke IdP di RP menggunakan FedCM, RP dapat memanggil navigator.credentials.get(). Mulai Chrome 136, RP dapat mendukung beberapa IdP dengan menentukan array dari beberapa penyedia identitas dalam satu panggilan navigator.credentials.get(), misalnya:

  const credential = await navigator.credentials.get({
      identity: {
        // Specify the IdP (or multiple IdPs, supported from Chrome 136) this Relying Party supports
        providers: [
        {
              configURL: 'https://accounts.idp-1.example/config.json',
              clientId: '********'
        },
        {
          configURL: 'https://accounts.idp-2.example/config.json',
          clientId: '********'
        }]
      }
    },
  );
  const { token } = credential;
  
  // Get the current IdP's configURL to identify which provider the user is signed in with
  const currentIdpConfigUrl = credential.configURL;
  if (currentIdpConfigUrl === 'https://idp1.example/foo.json') {
    // handle the case where the user signed in with idp1
  } else if (currentIdpConfigUrl === 'https://idp2.example/bar.json') {
    // handle the case where the user signed in with idp2
    }

Coba fitur beberapa IdP dengan login menggunakan IdP1 dan IdP2.

Properti konteks

Dengan properti context opsional, RP dapat mengubah string di UI dialog FedCM (misalnya, "Login ke rp.example…", "Gunakan idp.example…") untuk mengakomodasi konteks autentikasi yang telah ditentukan sebelumnya, misalnya. Properti context dapat memiliki nilai berikut:

• signin (default)
• signup
• use

Misalnya, menyetel context ke use akan menghasilkan pesan berikut:

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 telah mendaftar ke RP.
Properti providers menggunakan array objek IdentityProvider yang memiliki properti berikut:

Properti penyedia

Properti providers menggunakan array objek IdentityProvider yang memiliki properti berikut:

Mode aktif

FedCM mendukung konfigurasi mode UX yang berbeda. Mode pasif adalah mode default, dan developer tidak perlu mengonfigurasinya.

Untuk menggunakan FedCM dalam mode aktif:

1. Periksa ketersediaan fitur di browser pengguna.
2. Panggil API dengan gestur pengguna sementara, seperti klik tombol.
3. Teruskan parameter mode ke panggilan API:

  let supportsFedCmMode = false;
  try {
    navigator.credentials.get({
      identity: Object.defineProperty(
        // Check if this Chrome version supports the Mode API.
        {}, 'mode', {
          get: function () { supportsFedCmMode = true; }
        }
      )
    });
  } catch(e) {}

  if (supportsFedCmMode) {
    // The button mode is supported. Call the API with mode property:
    return await navigator.credentials.get({
      identity: {
        providers: [{
          configURL: 'https://idp.example/config.json',
          clientId: '123',
        }],
        // The 'mode' value defines the UX mode of FedCM.
        // - 'active': Must be initiated by user interaction (e.g., clicking a button).
        // - 'passive': Can be initiated without direct user interaction.
        mode: 'active'
      }
    });
  }

Coba mode aktif dengan demo ini.

Ikon kustom dalam mode aktif

Mode aktif memungkinkan IdP menyertakan ikon logo resmi RP langsung dalam respons endpoint metadata klien. RP harus memberikan data branding mereka terlebih dahulu.

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 asal yang dapat memanggil FedCM, kirim header Permissions-Policy dengan daftar asal 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.

Login Hint API

Dengan menggunakan Petunjuk Login, RP dapat merekomendasikan akun yang harus digunakan pengguna untuk login. Hal ini dapat membantu mengautentikasi ulang pengguna yang tidak yakin akun mana yang telah mereka gunakan sebelumnya.

RP dapat secara selektif menampilkan akun tertentu dengan memanggil navigator.credentials.get() dengan 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',
        // Accounts endpoint can specify a 'login_hints' array for an account.
        // When RP specifies a 'exampleHint' value, only those accounts will be
        // shown to the user whose 'login_hints' array contains the 'exampleHint'
        // value
        loginHint : 'exampleHint'
      }]
    }
  });

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 config. Link tersebut kemudian ditambahkan dengan parameter kueri petunjuk login dan petunjuk domain.

Domain Hint API

RP dapat secara selektif menampilkan hanya akun yang terkait dengan domain tertentu. Hal ini dapat berguna untuk RP yang dibatasi ke domain perusahaan.

Untuk menampilkan hanya akun domain tertentu, RP harus 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',
        // Accounts endpoint can specify a 'domain_hints' array for an account.
        // When RP specifies a '@domain.example' value, only those accounts will be
        // shown to the user whose 'domain_hints' array contains the
        // '@domain.example' value
        domainHint : '@domain.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 config. Link tersebut kemudian ditambahkan dengan parameter kueri petunjuk login dan petunjuk domain.

Lihat demo untuk mengetahui detail selengkapnya.

Parameter kustom

Fitur Parameter Kustom memungkinkan RP memberikan parameter key-value tambahan ke endpoint pernyataan ID. Dengan Parameters API, RP dapat meneruskan parameter tambahan ke IdP untuk meminta izin bagi resource di luar proses login dasar. Meneruskan parameter tambahan dapat berguna dalam skenario berikut:

• RP perlu meminta izin tambahan secara dinamis yang dimiliki IdP, seperti alamat penagihan atau akses kalender. Pengguna dapat memberikan otorisasi izin ini melalui alur UX yang dikontrol IdP yang diluncurkan menggunakan fitur Lanjutkan di, dan IdP kemudian akan membagikan informasi ini.

Untuk menggunakan API, RP menambahkan parameter ke properti params sebagai objek dalam panggilan navigator.credentials.get():

  let {token} = await navigator.credentials.get({
    identity: {
      providers: [{
        clientId: '1234',
        configURL: 'https://idp.example/fedcm.json',
        // Key/value pairs that need to be passed from the
        // RP to the IdP but that don't really play any role with
        // the browser.
        params: {
          IDP_SPECIFIC_PARAM: '1',
          foo: 'BAR'
        }
      },
    }
  });

Browser akan otomatis menerjemahkannya menjadi permintaan POST ke IdP dengan parameter sebagai satu objek yang diserialisasi JSON yang dienkode URL:

  // The assertion endpoint is drawn from the config file
  POST /fedcm_assertion_endpoint HTTP/1.1
  Host: idp.example
  Origin: https://rp.example/
  Content-Type: application/x-www-form-urlencoded
  Cookie: 0x23223
  Sec-Fetch-Dest: webidentity

  // params are translated into urlencoded version of `{"IDP_SPECIFIC_PARAM":"1","foo":"bar"}`
  account_id=123&client_id=client1234&params=%22%7B%5C%22IDP_SPECIFIC_PARAM%5C%22%3A1%2C%5C%22foo%5C%22%3A%5C%22BAR%5C%22%7D%22.

Jika RP memerlukan izin tambahan, IdP dapat memberikan link pengalihan. Misalnya, di node.js:

  if (rpRequestsPermissions) {
    // Response with a URL if the RP requests additional permissions
    return res.json({
      continue_on: '/example-redirect',
    });
  }

Kolom

RP dapat menentukan informasi pengguna yang mereka perlukan untuk dibagikan oleh IdP kepada mereka. Hal ini dapat mencakup kombinasi nama, alamat email, nama pengguna, nomor telepon, dan foto profil. Informasi yang diminta akan disertakan dalam UI pengungkapan dialog FedCM.

Pengguna yang mendaftar akan melihat pesan yang memberi tahu mereka bahwa idp.example akan membagikan informasi yang diminta kepada rp.example jika pengguna memilih untuk mendaftar. Jika respons dari endpoint akun tidak menyertakan kolom yang diminta RP, teks pengungkapan tidak akan menyertakan kolom ini. IdP akan mempelajari semua kolom yang diminta dari endpoint pernyataan ID dan memutuskan apakah mereka harus mengumpulkan izin pengguna lebih lanjut untuk melanjutkan.

Untuk menggunakan fitur Fields, RP harus menambahkan array fields dalam panggilan navigator.credentials.get(). Kolom dapat berisi properti seperti name, email, tel, username, atau picture. Hal ini dapat diperluas untuk menyertakan lebih banyak nilai pada masa mendatang. Permintaan dengan fields akan terlihat seperti ini:

   let { token } = await navigator.credentials.get({
    identity: {
      providers: [{
        // RP requests the IdP to share only username and profile picture
        fields: [ 'username', 'picture'],
        clientId: '1234',
        configURL: 'https://idp.example/fedcm.json',
      },
    }
  });

Browser akan otomatis menerjemahkannya menjadi permintaan HTTP ke endpoint pernyataan ID yang menyertakan parameter fields yang ditentukan RP, dengan kolom yang diungkapkan browser kepada pengguna dalam parameter disclosure_shown_for. Untuk kompatibilitas mundur, browser juga akan mengirim disclosure_text_shown=true jika teks pengungkapan ditampilkan dan kolom yang diminta mencakup ketiga kolom: 'name', 'email', dan 'picture'. Mulai Chrome 141, nilai disclosure_text_shown tidak menunjukkan apakah teks pengungkapan benar-benar ditampilkan kepada pengguna.

  POST /id_assertion_endpoint HTTP/1.1
  Host: idp.example
  Origin: https://rp.example/
  Content-Type: application/x-www-form-urlencoded
  Cookie: 0x23223
  Sec-Fetch-Dest: webidentity

  // The RP only requested to share email and picture. The browser will send `disclosure_text_shown=false`, as the 'name' field value is missing
  account_id=123&client_id=client1234&disclosure_text_shown=false&fields=email,picture&disclosure_shown_for=email,picture

Jika fields adalah array kosong, agen pengguna akan melewati UI pengungkapan.

Hal ini terjadi meskipun respons dari endpoint akun tidak berisi ID klien yang cocok dengan RP di approved_clients.

Dalam hal ini, disclosure_text_shown yang dikirim ke endpoint pernyataan ID adalah salah di isi HTTP:

  POST /id_assertion_endpoint HTTP/1.1
  Host: 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=234234&disclosure_text_shown=false

Menampilkan pesan error

Terkadang, IdP mungkin tidak dapat menerbitkan token karena alasan yang sah, seperti saat klien tidak diberi otorisasi, atau server tidak tersedia untuk sementara. Jika IdP menampilkan respons "error", RP dapat menangkapnya, dan Chrome dapat memberi tahu pengguna dengan menampilkan UI browser dengan informasi error yang diberikan 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;
  }

Mengautentikasi ulang pengguna secara otomatis setelah autentikasi awal

Autentikasi ulang otomatis FedCM (singkatnya "auto-reauthn") dapat memungkinkan pengguna melakukan autentikasi ulang secara otomatis. Kondisi berikut harus dipenuhi untuk mengautentikasi ulang pengguna secara otomatis:

• Pengguna sebelumnya telah melakukan autentikasi awal menggunakan FedCM. "Autentikasi awal" di sini berarti pengguna membuat akun atau login ke situs RP dengan mengetuk tombol "Lanjutkan sebagai..." di dialog login FedCM untuk pertama kalinya di instance browser yang sama.
• Pengguna hanya memiliki satu akun yang kembali. Jika akun yang kembali ada untuk beberapa IdP, pengguna tidak akan diautentikasi ulang secara otomatis.

Meskipun pengalaman pengguna yang eksplisit masuk akal sebelum pengguna membuat akun gabungan untuk mencegah pelacakan (yang merupakan salah satu tujuan utama FedCM), pengalaman ini menjadi 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 konfirmasi sebelumnya.

Dengan autentikasi ulang otomatis, browser 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, perilakunya sama seperti untuk PasswordCredential dan FederatedCredential dan juga didukung sebagian oleh PublicKeyCredential. Properti ini menerima empat nilai berikut:

• 'optional'(default): Otentikasi ulang otomatis 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 memberikan izin secara eksplisit setiap kali mereka perlu diautentikasi.
• 'silent': Otentikasi ulang otomatis 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 tersedia untuk 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.
• Autentikasi 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.

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.

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

Terapkan 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 senyap 10 menit setelah re-autentikasi otomatis untuk mencegah perilaku ini. Artinya, autentikasi ulang otomatis terjadi paling banyak sekali setiap 10 menit, 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 keluar dari RP secara eksplisit, misalnya, dengan mengklik tombol keluar.

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

Pengguna dapat menonaktifkan autentikasi ulang otomatis di setelan

Pengguna dapat menonaktifkan autentikasi ulang otomatis dari menu setelan:

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

Dengan menonaktifkan tombol, pengguna dapat memilih untuk tidak menggunakan perilaku autentikasi ulang otomatis sama sekali. Setelan ini disimpan dan disinkronkan di seluruh perangkat, jika pengguna login ke Akun Google di instance Chrome dan sinkronisasi diaktifkan.

Putuskan 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 IdP, dan accountHint agar IdP terputus. Petunjuk akun dapat berupa string arbitrer selama endpoint pemutusan hubungan dapat mengidentifikasi akun, misalnya alamat email atau ID pengguna yang tidak harus cocok dengan ID akun yang telah diberikan oleh 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 memunculkan 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 pelepasan koneksi IdP menampilkan respons, RP dan IdP akan dilepaskan koneksinya di browser dan promise akan diselesaikan. ID akun yang tidak terhubung ditentukan dalam respons dari endpoint pemutusan hubungan.

Langkah berikutnya

Implementasikan FedCM di sisi IdP

Tinjau cara menerapkan solusi identitas Anda dengan FedCM di sisi Penyedia Identitas.

Penyesuaian dan pilihan tidak ikut

Pelajari cara pengguna dan developer dapat mengelola partisipasi FedCM, termasuk memilih ikut serta atau tidak, di seluruh platform dan situs.