Menerapkan solusi identitas dengan FedCM

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

Implementasi FedCM mencakup beberapa langkah inti untuk IdP (Penyedia Identitas) dan RP (Pihak yang Memercayai).

IdPs harus menyelesaikan langkah-langkah berikut untuk menerapkan FedCM:

• Buat file well-known.
• Buat file konfigurasi.
• Buat endpoint berikut:
  • Endpoint akun
  • Endpoint pernyataan ID
  • [opsional] Putuskan hubungan endpoint
  • [opsional] Endpoint metadata klien
  • Endpoint login
• Memberi tahu browser tentang status login pengguna.

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.

Catatan: Sebaiknya IdP menyediakan library untuk mengakses FedCM JavaScript API saat API tersebut berkembang, dan tidak menganjurkan RP untuk menghosting sendiri SDK. Hal ini akan memastikan IdP dapat melakukan perubahan seiring berkembangnya API, tanpa harus meminta semua pihak tepercaya untuk men-deploy ulang.

Mengimplementasikan FedCM sebagai IdP

Pelajari lebih lanjut langkah-langkah untuk menerapkan FedCM di sisi 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.

File yang dikenal dapat menyertakan properti berikut:

Properti	Wajib	Deskripsi
provider_urls	wajib diisi	Array jalur file konfigurasi IdP. Diabaikan (tetapi tetap diperlukan) jika accounts_endpoint dan login_url ditentukan.
accounts_endpoint	direkomendasikan, memerlukan login_url	URL untuk endpoint akun. Hal ini memungkinkan dukungan beberapa konfigurasi, selama setiap file konfigurasi menggunakan URL login_url dan accounts_endpoint yang sama. Catatan: Parameter ini didukung mulai Chrome 132.
login_url	direkomendasikan, memerlukan accounts_endpoint	URL halaman login untuk pengguna login ke IdP. Hal ini memungkinkan dukungan beberapa konfigurasi, selama setiap file konfigurasi menggunakan login_url dan accounts_endpoint yang sama. Catatan: parameter ini didukung mulai Chrome 132 dan yang lebih baru.

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"]
  }

IdP dapat mengakomodasi beberapa file konfigurasi untuk IdP, dengan menentukan accounts_endpoint dan login_url dalam file well-known.
Fitur ini dapat berguna dalam kasus berikut:

• IdP harus mendukung beberapa konfigurasi pengujian dan produksi yang berbeda.
• IdP harus mendukung konfigurasi yang berbeda per region (misalnya, eu-idp.example dan us-idp.example).

Untuk mendukung beberapa konfigurasi (misalnya, untuk membedakan antara lingkungan pengujian dan produksi), IdP harus menentukan accounts_endpoint dan login_url:

  {
    // This property is required, but will be ignored when IdP supports
    // multiple configs (when `accounts_endpoint` and `login_url` are
    // specified), as long as `accounts_endpoint` and `login_url` in
    // that config file match those in the well-known file.
    "provider_urls": [ "https://idp.example/fedcm.json" ],

    // Specify accounts_endpoint and login_url properties to support
    // multiple config files.
    // Note: The accounts_endpoint and login_url must be identical
    // across all config files. Otherwise,
    // the configurations won't be supported.
    "accounts_endpoint": "https://idp.example/accounts",
    "login_url": "https://idp.example/login"
  }

Tips: Saat menggunakan FedCM, domain server RP pengujian atau staging dapat berupa subdomain server IdP produksi. Misalnya, server IdP produksi berada di idp.example dan server RP staging serta server IdP staging berada di staging.idp.example. Namun, karena file well-known harus berada di root eTLD+1 server IdP, file tersebut harus berada di idp.example/.well-known/web-identity dan merupakan server produksi. Karena developer tidak dapat menempatkan file di lingkungan produksi saat sedang dalam pengembangan, hal ini mencegah mereka menguji FedCM. Jika domain RP dan domain IdP sama, Chrome dapat melewati pemeriksaan file yang dikenal mulai dari Chrome 122. Anda juga dapat mengabaikan pemeriksaan configURL dengan mengaktifkan flag chrome://flags#fedcm-without-well-known-enforcement. Hal ini berguna saat lingkungan pengembangan Anda menggunakan DNS yang tidak dapat diakses secara publik.

Membuat file konfigurasi dan endpoint IdP

File konfigurasi IdP menyediakan daftar endpoint yang diperlukan untuk browser. IdP harus menghosting satu atau beberapa file konfigurasi, 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;

RP akan meneruskan URL file konfigurasi ke panggilan FedCM API untuk mengizinkan pengguna login:

  // Executed on RP's side:
  const credential = await navigator.credentials.get({
    identity: {
      context: 'signup',
      providers: [{
        // To allow users to sign in with an IdP using FedCM, RP specifies the IdP's config file URL:
        configURL: 'https://accounts.idp.example/fedcm.json',
        clientId: '********',
  });
  const { token } = credential;

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

Perhatian: Semua permintaan yang dikirim dari browser menggunakan FedCM menyertakan header Sec-Fetch-Dest: webidentity untuk mencegah serangan CSRF. Endpoint IdP berikut harus mengonfirmasi bahwa header ini disertakan:

• Endpoint akun
• Endpoint pernyataan ID
• Memutuskan hubungan endpoint

IdP harus menerapkan endpoint konfigurasi yang merespons dengan JSON. JSON menyertakan properti berikut:

Properti	Deskripsi
accounts_endpoint (wajib diisi)	URL untuk endpoint akun.
accounts.include (opsional)	String label akun kustom, yang menentukan akun mana yang akan ditampilkan saat file konfigurasi ini digunakan, misalnya: "accounts": {"include": "developer"}. IdP dapat menerapkan pemberian label akun kustom sebagai berikut: Buat file konfigurasi yang terkait dengan label tertentu (menggunakan parameter accounts.include ini). Tentukan label di endpoint akun. Misalnya, IdP menerapkan file konfigurasi "https://idp.example/developer-config.json" dengan "accounts": {"include": "developer"} yang ditentukan. IdP juga menandai beberapa akun dengan label "developer" menggunakan parameter labels di endpoint akun. Saat RP memanggil navigator.credentials.get() dengan file konfigurasi "https://idp.example/developer-config.json" yang ditentukan, hanya akun dengan label "developer" yang akan ditampilkan.
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)	Array objek ikon. Ikon ini ditampilkan di dialog login. Objek ikon memiliki 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. Jumlah ini harus lebih besar dari atau sama dengan 25 piksel dalam mode pasif dan lebih besar dari atau sama dengan 40 piksel dalam mode aktif.
modes	Objek yang berisi spesifikasi tentang cara UI FedCM akan ditampilkan dalam berbagai mode: active passive
modes.active	Objek yang berisi properti yang memungkinkan penyesuaian perilaku FedCM dalam mode tertentu. modes.active dan modes.passive dapat berisi parameter berikut: supports_use_other_account: boolean yang menentukan apakah pengguna dapat login dengan akun yang berbeda dari akun yang saat ini digunakan untuk login (jika IdP mendukung beberapa akun). Catatan: Fitur Gunakan Akun Lain dan mode aktif didukung mulai Chrome 132.
modes.passive

Berikut adalah contoh isi respons dari IdP:

  {
    "accounts_endpoint": "/accounts.example",
    "client_metadata_endpoint": "/client_metadata.example",
    "id_assertion_endpoint": "/assertion.example",
    "disconnect_endpoint": "/disconnect.example",
    "login_url": "/login",
    // When RPs use this config file, only those accounts will be
    //returned that include `developer` label in the accounts endpoint.
    "accounts": {"include": "developer"},
    "modes": {
        "active": {
          "supports_use_other_account": true,
        }
    },
    "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

Gunakan akun lain

Pengguna dapat beralih ke akun yang berbeda dengan akun yang saat ini digunakan untuk login, jika IdP mendukung beberapa akun atau mengganti akun yang ada.

Agar pengguna dapat memilih akun lain, IdP harus menentukan fitur ini di file konfigurasi:

  {
    "accounts_endpoint" : "/accounts.example",
    "modes": {
      "active": {
        // Allow the user to choose other account (false by default)
        "supports_use_other_account": true
      }
      // "passive" mode can be configured separately
    }
  }

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.example 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.
labels (opsional)	Array string Label Akun Kustom yang terkait dengan akun. IdP dapat menerapkan pemberian label akun kustom sebagai berikut: Tentukan label akun di endpoint akun (menggunakan parameter labels ini). Buat file konfigurasi untuk setiap label tertentu. Misalnya, IdP menerapkan file konfigurasi https://idp.example/developer-config.json dengan "accounts": {"include": "developer"} yang ditentukan. IdP juga menandai beberapa akun dengan label "developer" menggunakan parameter labels di endpoint akun. Saat RP memanggil navigator.credentials.get() dengan file konfigurasi https://idp.example/developer-config.json yang ditentukan, hanya akun dengan label "developer" yang akan ditampilkan. Label Akun Kustom berbeda dengan Petunjuk login dan petunjuk domain sedemikian rupa sehingga sepenuhnya dikelola oleh server IdP, dan RP hanya menentukan file konfigurasi yang akan digunakan.

Contoh isi respons:

  {
    "accounts": [{
      "id": "1234",
      "given_name": "John",
      "name": "John Doe",
      "email": "[e-mail]",
      "picture": "https://idp.example/profile/123",
      // Ids of those RPs where this account can be used
      "approved_clients": ["123", "456", "789"],
      // This account has 'login_hints`. When an RP calls `navigator.credentials.get()`
      // with a `loginHint` value specified, for example, `exampleHint`, only those
      // accounts will be shown to the user whose 'login_hints' array contains the `exampleHint`.
      "login_hints": ["demo1", "exampleHint"],
      // This account is labelled. IdP can implement a specific config file for a
      // label, for example, `https://idp.example/developer-config.json`. Like that
      // RPs can filter out accounts by calling `navigator.credentials.get()` with
      // `https://idp.example/developer-config.json` config file.
      "labels": ["hr", "developer"]
    }, {
      "id": "5678",
      "given_name": "Johnny",
      "name": "Johnny",
      "email": "[e-mail]",
      "picture": "https://idp.example/profile/456",
      "approved_clients": ["abc", "def", "ghi"],
      "login_hints": ["demo2"],
      "domain_hints": ["@domain.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 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 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 (wajib diisi)	ID klien RP.
account_id (wajib diisi)	ID unik pengguna yang login.
disclosure_text_shown	Menghasilkan string "true" atau "false" (bukan boolean). Hasilnya adalah "false" dalam kasus ini: Jika teks pengungkapan tidak ditampilkan karena client ID RP disertakan dalam daftar properti approved_clients respons dari endpoint akun. Jika teks pengungkapan tidak ditampilkan karena browser telah mengamati momen pendaftaran sebelumnya tanpa adanya approved_clients. Jika parameter fields tidak menyertakan satu atau beberapa dari tiga kolom ("name", "email", dan "picture"), misalnya, fields=[ ], atau fields=['name', 'picture']. Hal ini diperlukan untuk kompatibilitas mundur dengan penerapan IdP lama yang mengharapkan string pengungkapan selalu menyertakan ketiga kolom tersebut.
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, mereka dapat menangani permintaan dengan cara yang berbeda. Misalnya, tampilkan kode error sehingga RP dapat memanggil FedCM API lagi dengan mediation: required.
fields (opsional)	Array string yang menentukan informasi pengguna ("name", " email", "picture") yang perlu dibagikan IdP kepada RP. Browser akan mengirim fields, disclosure_text_shown, dan disclosure_shown_for yang mencantumkan kolom yang ditentukan dalam permintaan POST, seperti dalam contoh berikut. Catatan: Parameter Kolom didukung mulai Chrome 132.
params (opsional)	Setiap objek JSON yang valid yang memungkinkan untuk menentukan parameter nilai kunci kustom tambahan, misalnya: scope: Nilai string yang berisi izin tambahan yang perlu diminta RP, misalnya "drive.readonly calendar.readonly" nonce: String acak yang diberikan oleh RP untuk memastikan respons dikeluarkan untuk permintaan spesifik ini. Mencegah serangan replay. Parameter nilai kunci kustom lainnya. Saat browser mengirim permintaan POST, nilai params akan diserialisasi ke JSON, lalu dienkode persen. Catatan: Parameters API didukung oleh Chrome 132 dan yang lebih baru.

Contoh header HTTP:

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

  // disclosure_text_shown is set to 'false', as the 'name' field value is missing in 'fields' array
  // params value is serialized to JSON and then percent-encoded.
  account_id=123&client_id=client1234&disclosure_text_shown=false&is_auto_selected=true&params=%22%7B%5C%22nonce%5C%22%3A%5C%22nonce-value%5C%22%7D%22.%0D%0A4&disclosure_text_shown=true&fields=email,picture&disclosure_shown_for=email,picture

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, balas dengan respons error.

Peringatan: Permintaan CORS harus memiliki kredensial, yang berarti header respons Access-Control-Allow-Origin harus menunjukkan origin eksplisit, bukan karakter pengganti menggunakan "*".

HTTP/1.1 200 OK
Access-Control-Allow-Origin: https://rp.example
Access-Control-Allow-Credentials: true
  

IdP dapat memutuskan cara menerbitkan token. Secara umum, token ini ditandatangani dengan informasi seperti ID akun, client ID, asal penerbit, dan nonce, sehingga RP dapat memverifikasi bahwa token tersebut asli.

Peringatan: Karena verifikasi domain di OAuth atau OpenID Connect bergantung pada pengalihan browser, sangat penting di FedCM bahwa server IdP memeriksa nilai header Origin yang cocok dengan origin terdaftar RP.

Browser mengharapkan respons JSON yang menyertakan properti berikut:

Properti	Deskripsi
token	Token adalah string yang berisi klaim tentang autentikasi.
continue_on	URL alihan yang memungkinkan alur login multi-langkah.

Token yang ditampilkan diteruskan ke RP oleh browser, sehingga RP dapat memvalidasi autentikasi.

  {
    // IdP can respond with a token to authenticate the user
    "token": "***********"
  }

Fitur Lanjutkan

IdP dapat memberikan URL alihan dalam respons endpoint pernyataan ID untuk mengaktifkan alur login multi-langkah. Hal ini berguna saat IdP perlu meminta informasi atau izin tambahan, misalnya:

• Izin untuk mengakses resource sisi server pengguna.
• Verifikasi bahwa informasi kontak sudah diperbarui.
• Kontrol orang tua.

Endpoint pernyataan ID dapat menampilkan properti continue_on yang menyertakan jalur absolut atau relatif ke endpoint pernyataan ID.

  {
    // In the id_assertion_endpoint, instead of returning a typical
    // "token" response, the IdP decides that it needs the user to
    // continue on a popup window:
    "continue_on": "https://idp.example/continue_on_url"
  }

Jika respons berisi parameter continue_on, jendela pop-up baru akan terbuka dan mengarahkan pengguna ke jalur yang ditentukan. Setelah interaksi pengguna dengan halaman continue_on, IdP harus memanggil IdentityProvider.resolve() dengan token yang diteruskan sebagai argumen sehingga promise dari panggilan navigator.credentials.get() asli dapat di-resolve:

  document.getElementById('example-button').addEventListener('click', async () => {
    let accessToken = await fetch('/generate_access_token.cgi');
    // Closes the window and resolves the promise (that is still hanging
    // in the relying party's renderer) with the value that is passed.
    IdentityProvider.resolve(accessToken);
  });

Browser kemudian akan otomatis menutup pop-up dan menampilkan token ke pemanggil API. Panggilan IdentityProvider.resolve() satu kali adalah satu-satunya cara bagi jendela induk (RP) dan jendela pop-up (IdP) untuk berkomunikasi.
Jika pengguna menolak permintaan, IdP dapat menutup jendela dengan memanggil IdentityProvider.close().

  IdentityProvider.close();

Continuation API memerlukan interaksi pengguna (klik) yang eksplisit agar dapat berfungsi. Berikut cara kerja Continuation API dengan mode mediasi yang berbeda:

• Dalam mode pasif:
  • mediation: 'optional' (default): Continuation API hanya akan berfungsi dengan gestur pengguna, seperti mengklik tombol di halaman atau di UI FedCM. Saat autentikasi ulang otomatis dipicu tanpa gestur pengguna, tidak ada jendela pop-up yang terbuka, dan promise ditolak.
  • mediation: 'required': Selalu meminta pengguna untuk berinteraksi, sehingga Continuation API selalu berfungsi.
• Dalam mode aktif:
  • Aktivasi pengguna selalu diperlukan. Continuation API kompatibel.

Jika karena alasan tertentu pengguna telah mengubah akunnya di pop-up (misalnya, IdP menawarkan fungsi "gunakan akun lain", atau dalam kasus delegasi), panggilan penyelesaian akan menggunakan argumen kedua opsional yang memungkinkan hal seperti:

  IdentityProvider.resolve(token, {accountId: '1234');

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"
    }
  }

Catatan: Menerapkan respons "error" bersifat opsional. Jika IdP tidak memberi tahu browser tentang jenis error saat terjadi, Chrome akan menampilkan UI error dengan pesan umum. Jika kolom url tidak disediakan, Chrome tidak menyertakan tombol Detail selengkapnya.

Label Akun Kustom

Dengan Label Akun Kustom, IdP dapat menganotasi akun pengguna dengan label, dan RP dapat memilih untuk hanya mengambil akun dengan label tertentu dengan menentukan configURL untuk label tertentu tersebut. Hal ini dapat berguna saat RP perlu memfilter akun berdasarkan kriteria tertentu, misalnya, untuk hanya menampilkan akun khusus peran seperti "developer" atau "hr".

Pemfilteran serupa dapat dilakukan menggunakan fitur Domain Hint dan Login Hint, dengan menentukannya dalam panggilan navigator.credentials.get(). Namun, Label Akun Kustom dapat memfilter pengguna dengan menentukan file konfigurasi, yang sangat berguna saat beberapa configURL digunakan. Label Akun Kustom juga berbeda karena disediakan dari server IdP, bukan dari RP, seperti login atau petunjuk domain.

Pertimbangkan IdP yang ingin membedakan antara akun "developer" dan "hr". Untuk mencapai hal ini, IdP harus mendukung dua configURL untuk "developer" dan "hr":

• File konfigurasi developer https://idp.example/developer/fedcm.json memiliki label "developer", dan file konfigurasi perusahaan https://idp.example/hr/fedcm.json memiliki label "hr" sebagai berikut:

  // The developer config file at `https://idp.example/developer/fedcm.json`
  {
    "accounts_endpoint": "https://idp.example/accounts",
    "client_metadata_endpoint": "/client_metadata",
    "login_url": "https://idp.example/login",
    "id_assertion_endpoint": "/assertion",
    "accounts": {
      // Account label
      "include": "developer"
    }
  }

  // The hr config file at `https://idp.example/hr/fedcm.json`
  {
    "accounts_endpoint": "https://idp.example/accounts",
    "client_metadata_endpoint": "/client_metadata",
    "login_url": "https://idp.example/login",
    "id_assertion_endpoint": "/assertion",
    "accounts": {
      // Account label
      "include": "hr"
    }
  }

• Dengan penyiapan tersebut, file well-known harus menyertakan accounts_endpoint dan login_url untuk mengizinkan beberapa configURL:

  {
    "provider_urls": [ "https://idp.example/fedcm.json" ],
    "accounts_endpoint": "https://idp.example/accounts",
    "login_url": "https://idp.example/login"
  }

• Endpoint akun IdP umum (dalam contoh ini https://idp.example/accounts) menampilkan daftar akun yang menyertakan properti labels dengan label yang ditetapkan dalam array untuk setiap akun:

  {
  "accounts": [{
    "id": "123",
    "given_name": "John",
    "name": "John Doe",
    "email": "[e-mail]",
    "picture": "https://idp.example/profile/123",
    "labels": ["developer"]
    }], [{
    "id": "4567",
    "given_name": "Jane",
    "name": "Jane Doe",
    "email": "[e-mail]",
    "picture": "https://idp.example/profile/4567",
    "labels": ["hr"]
    }]
  }

Jika RP ingin mengizinkan pengguna "hr" untuk login, mereka dapat menentukan configURL https://idp.example/hr/fedcm.json dalam panggilan navigator.credentials.get():

  let { token } = await navigator.credentials.get({
    identity: {
      providers: [{
        clientId: '1234',
        nonce: '234234',
        configURL: 'https://idp.example/hr/fedcm.json',
      },
    }
  });

Akibatnya, hanya ID akun 4567 yang tersedia bagi pengguna untuk login. ID akun 123 disembunyikan secara otomatis oleh browser sehingga pengguna tidak akan diberi akun yang tidak didukung oleh IdP di situs ini.

Catatan:

• Label adalah string. Jika array labels atau kolom include berisi sesuatu yang bukan string, array atau kolom tersebut akan diabaikan.
• Jika tidak ada label yang ditentukan di configURL, semua akun akan ditampilkan di pemilih akun FedCM.
• Jika tidak ada label yang ditentukan untuk akun, akun tersebut hanya akan ditampilkan di pemilih akun jika configURL juga tidak menentukan label.
• Jika tidak ada akun yang cocok dengan label yang diminta dalam mode pasif (mirip dengan fitur Domain Hint), dialog FedCM akan menampilkan perintah login, yang memungkinkan pengguna login ke akun IdP. Untuk mode aktif, jendela pop-up login akan langsung terbuka.

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

Peringatan: Permintaan CORS harus memiliki kredensial, yang berarti header respons Access-Control-Allow-Origin harus menunjukkan origin eksplisit, bukan karakter pengganti menggunakan "*".

HTTP/1.1 200 OK
Access-Control-Allow-Origin: https://rp.example
Access-Control-Allow-Credentials: true
  

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 "*".

Endpoint metadata klien

Endpoint metadata klien IdP menampilkan metadata pihak tepercaya seperti kebijakan privasi, persyaratan layanan, dan ikon logo 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.example?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.
icons (opsional)	Array objek, seperti [{ "url": "https://rp.example/rp-icon.ico", "size": 40}]

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",
    "icons": [{
          "url": "https://rp.example/rp-icon.ico",
          "size": 40
      }]
  }

Metadata klien yang ditampilkan digunakan oleh browser dan tidak akan tersedia untuk RP.

URL Login

Endpoint ini digunakan untuk mengizinkan pengguna login ke IdP.

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.

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 yang ditampilkan setelah mengklik tombol login ke IdP.

Catatan: Situs tidak dapat mengontrol ukuran dialog sebelum dibuka. Secara default, ukuran ditetapkan ke lebar 500 piksel dan tinggi 600 piksel.

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.

Catatan: Baca Memberi tahu browser tentang status login pengguna untuk mempelajari header HTTP Set-Login dan fungsi IdentityProvider.close() lebih lanjut.

Pengguna login ke RP setelah login ke IdP menggunakan FedCM.

Memberi tahu browser tentang status login pengguna

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 memitigasi 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
• unknown (default)

Status login	Deskripsi
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 di dialog FedCM.
logged-out	Jika status login pengguna adalah logged-out, memanggil FedCM akan gagal secara otomatis tanpa membuat permintaan ke endpoint akun IdP.
unknown (default)	Status unknown ditetapkan sebelum IdP mengirim sinyal menggunakan Login Status API. Jika statusnya unknown, browser akan membuat permintaan ke endpoint akun IdP dan memperbarui status berdasarkan respons dari endpoint akun.

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 metode JavaScript navigator.login.setStatus('logged-in') dari origin IdP dalam navigasi tingkat atas:

  navigator.login.setStatus('logged-in')

Status login pengguna akan ditetapkan sebagai logged-in.

Untuk memberi sinyal bahwa pengguna logout dari semua akunnya, kirim header HTTP Set-Login: logged-out di 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')

Status login pengguna akan ditetapkan sebagai logged-out.

Status unknown ditetapkan sebelum IdP mengirim sinyal menggunakan Login Status API. Browser 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.

Catatan: Header status login juga dapat dikirim dari sub-resource situs yang sama, mulai dari Chrome 122. Hal ini berguna, misalnya, saat situs mengizinkan pengguna memasukkan nama pengguna dan sandi mereka di idp.example, tetapi kredensial diposting ke login.idp.example dengan fetch(). Respons pengambilan dari login.idp.example masih dapat menetapkan status login untuk idp.example dengan mengirimkan header HTTP Set-Login: logged-in.

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.

Pengalaman login dinamis ini ditujukan untuk saat sesi IdP telah berakhir tanpa logout eksplisit, sehingga menyebabkan status login browser bertentangan dengan status sebenarnya pengguna. Tindakan ini tidak dipicu untuk pengguna yang belum login ke IdP. Alur ini dirancang untuk mencakup kasus saat status login IdP pengguna di browser adalah logged-in, tetapi endpoint akun IdP tidak menampilkan akun. Dengan asumsi Login Status API dipanggil segera, saat FedCM dipanggil, salah satu skenario berikut dapat terjadi:

• Jika status login pengguna ditetapkan ke tidak diketahui, status akan diperbarui (logged-in atau logged-out) bergantung pada respons IdP dari endpoint akun. Alur login dinamis tidak akan dipicu.
• Jika pengguna telah login ke IdP di browser, lalu secara eksplisit logout dari IdP, alur login dinamis tidak akan dipicu.
• Jika pengguna telah login ke IdP di browser, tetapi masa berlaku sesi berakhir tanpa pembaruan eksplisit ke logged-out, alur login dinamis akan dipicu.

Login Status API tidak memberikan kemampuan bagi RP untuk menampilkan dialog "Login ke IdP" kepada pengguna yang tidak login ke IdP. Ini adalah fitur terpisah yang dapat ditambahkan di masa mendatang.

Menerapkan FedCM sebagai RP

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
  }

Perhatian: Jika RP men-deploy Kebijakan Keamanan Konten (CSP) di halaman tempat FedCM dipanggil, dan menerapkan perintah connect-src, RP harus secara eksplisit mengizinkan endpoint yang disediakan dalam file konfigurasi.

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

Cara penerapan branding ke dialog FedCM

Misalnya, menetapkan context ke use akan menghasilkan pesan berikut:

Dialog FedCM yang menampilkan pesan konteks yang disesuaikan.

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:

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.
mode (opsional)	String yang menentukan mode UI FedCM. Nilai ini dapat berupa salah satu dari nilai berikut: "active": Perintah FedCM harus dimulai oleh interaksi pengguna (seperti mengklik tombol). "passive": Perintah FedCM akan dimulai tanpa interaksi pengguna langsung. Lihat halaman ringkasan untuk mempelajari lebih lanjut perbedaan antara mode aktif dan pasif. Catatan: Parameter mode didukung mulai Chrome 132.
fields (opsional)	Array string yang menentukan informasi pengguna ("name", "email", "picture") yang perlu dibagikan IdP kepada RP. Catatan: Field API didukung oleh Chrome 132 dan yang lebih baru.
parameters (opsional)	Objek kustom yang memungkinkan untuk menentukan parameter nilai kunci tambahan: scope: Nilai string yang berisi izin tambahan yang perlu diminta RP, misalnya "drive.readonly calendar.readonly" nonce: String acak untuk memastikan respons dikeluarkan untuk permintaan spesifik ini. Mencegah serangan replay. Parameter nilai kunci kustom lainnya. Catatan: parameters didukung mulai Chrome 132.

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.

Catatan: Meneruskan ikon logo RP ke browser bersifat opsional. Jika ikon RP tidak ada, Chrome hanya akan menampilkan logo IdP di UI pengungkapan tempat pengguna diminta untuk memberikan izin berbagi.

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 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 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'
      }]
    }
  });

Catatan: Saat domainHint: 'any' digunakan, Chrome akan memfilter akun yang tidak memiliki domain (yaitu, domain_hints tidak diteruskan atau kosong). Misalnya, hal ini memungkinkan kasus penggunaan saat RP hanya mengizinkan akun terkelola dalam proses pendaftarannya.

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.

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

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.

Catatan: Secara default, pesan UI pengungkapan menyertakan semua kolom yang saat ini diterapkan: "Untuk melanjutkan, idp.example akan membagikan nama, alamat email, dan foto profil Anda ke situs ini". Pengguna yang kembali tidak akan melihat UI pengungkapan.

Pesan pengungkapan dalam mode aktif: RP meminta IdP untuk hanya membagikan email dan foto profil pengguna.

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

Pesan pengungkapan tidak ditampilkan dalam mode pasif. Dalam alur tombol, UI pengungkapan dilewati sepenuhnya.

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.

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

Catatan: Pengguna juga dapat memilih untuk tidak menggunakan FedCM per domain.

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.

Catatan: Jika tidak ada respons yang valid dari endpoint pemutusan koneksi yang diterima atau ID akun yang diterima tidak cocok dengan akun apa pun dalam daftar akun yang terhubung, agen pengguna akan menghapus semua akun yang cocok dengan RP dan IdP dari daftar akun yang terhubung.