Menerapkan solusi identitas dengan FedCM di sisi Pihak Tergantung

Pihak yang Meyakini (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.
• Berikan metadatanya (seperti URL kebijakan privasi dan persyaratan layanan) ke IdP.
• [opsional] Sesuaikan pengalaman pengguna dengan memilih mode UX, memberikan login atau petunjuk domain, meneruskan parameter kustom, meminta informasi pengguna tertentu, memberikan pesan error kustom, atau memilih cara melakukan autentikasi ulang pengguna.

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
  } 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(), misalnya:

  const credential = await navigator.credentials.get({
    identity: {
      context: 'signin',
      providers: [{
        configURL: 'https://accounts.idp.example/config.json',
        clientId: '********',
        mode: 'active',
        params: {
          nonce: '******'
        }
      }]
    }
  });
  const { token } = credential;

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, misalnya. Properti context dapat memiliki nilai berikut:

• signin (default)
• signup
• use

Misalnya, menetapkan 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'
      }
    });
  }

Ikon kustom dalam mode aktif

Mode aktif memungkinkan IdP menyertakan ikon logo resmi RP secara 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 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.

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

Domain Hint API

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

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

Parameter kustom

Fitur Parameter Kustom memungkinkan RP memberikan parameter nilai kunci tambahan ke endpoint pernyataan ID. Dengan Parameters API, RP dapat meneruskan parameter tambahan ke IdP untuk meminta izin resource di luar 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, 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 serialisasi 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 (kombinasi nama, alamat email, dan foto profil) yang perlu dibagikan IdP kepada mereka. Informasi yang diminta akan disertakan dalam UI pengungkapan dialog FedCM. Pengguna akan melihat pesan yang memberi tahu bahwa idp.example akan membagikan informasi yang diminta kepada rp.example jika pengguna memilih untuk login.

Untuk menggunakan fitur Kolom, RP harus menambahkan array fields dalam panggilan navigator.credentials.get(). Kolom dapat berisi permutasi name, email, dan 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 user email and profile picture
        fields: [ 'email', '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 menyertakan ketiga kolom: 'name', 'email', dan 'picture'.

  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 client ID yang cocok dengan RP di approved_clients.

Dalam hal ini, disclosure_text_shown yang dikirim ke endpoint pernyataan ID adalah salah dalam 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, 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 tersebut 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 serta didukung sebagian oleh PublicKeyCredential juga. 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.

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 dalam 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 hubungan 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.

Langkah berikutnya