Halaman ini diterjemahkan oleh Cloud Translation API.

Update FedCM: Uji coba origin untuk paket Continuation API dan pemberian otomatis Storage Access API

Eiji Kitamura

Mulai Chrome 126, developer dapat mulai menjalankan uji coba origin untuk paket fitur Federated Credential Management API (FedCM) desktop yang memungkinkan Kasus penggunaan Otorisasi. Paket ini terdiri dari Continuation API dan Parameters API, yang mengaktifkan pengalaman seperti alur otorisasi OAuth yang melibatkan dialog izin yang disediakan penyedia identitas (IdP). Paket tersebut juga mencakup perubahan lain seperti Fields API, Multiple configURLs, dan Custom Label Akun. Mulai Chrome 126, kami juga memperkenalkan uji coba origin untuk Storage Access API (SAA) yang otomatis memberikan permintaan SAA jika pengguna berhasil {i>login<i} menggunakan FedCM sebelumnya.

Uji Coba Origin: Paket FedCM Continuation API

Paket FedCM Continuation API terdiri dari beberapa ekstensi FedCM:

API Lanjutan
Parameters API
API Kolom
Beberapa configURL
Label Akun Kustom

API Lanjutan

Seorang pengguna login ke RP lalu memberi otorisasi melalui mode tombol.

Anda dapat melihat demo API di Glitch.

Continuation API memungkinkan Pernyataan ID IdP endpoint ke secara opsional, tampilkan URL yang akan dirender oleh FedCM agar pengguna dapat melanjutkan alur login multi-langkah. Tindakan ini memungkinkan IdP meminta pengguna memberikan izin izin pihak tepercaya (RP) di luar apa yang mungkin dilakukan di UI FedCM yang ada, seperti akses ke sumber daya sisi server pengguna.

Biasanya, endpoint pernyataan ID mengembalikan token yang diperlukan untuk autentikasi.

{
  "token": "***********"
}

Namun, dengan Continuation API, pernyataan ID endpoint tersebut 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 pop-up window:
  "continue_on": "/oauth/authorize?scope=..."
}

Segera setelah browser menerima respons continue_on, jendela pop-up baru dibuka dan mengarahkan pengguna ke jalur yang ditentukan.

Setelah pengguna berinteraksi dengan halaman, misalnya memberikan izin lebih lanjut untuk membagikan informasi tambahan kepada RP, halaman IdP dapat memanggil IdentityProvider.resolve() untuk me-resolve yang asli navigator.credentials.get() dan menampilkan token sebagai argumen.

document.getElementById('allow_btn').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 menutup pop-up itu sendiri dan mengembalikan token ke API penelepon.

Jika pengguna menolak permintaan, Anda dapat menutup jendela dengan memanggil IdentityProvider.close().

IdentityProvider.close();

Jika karena alasan tertentu pengguna telah mengubah akunnya di pop-up (misalnya IdP menawarkan "beralih pengguna" fungsi, atau dalam kasus delegasi), memanggil argumen kedua opsional yang mengizinkan sesuatu seperti:

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

API Parameter

Parameters API memungkinkan RP untuk memberikan parameter tambahan ke pernyataan ID endpoint. Dengan Parameters API, RP dapat meneruskan parameter tambahan ke IdP untuk meminta izin untuk sumber daya di luar login dasar. Pengguna akan mengizinkan izin ini melalui alur UX yang dikontrol IdP yang diluncurkan melalui API Lanjutan.

Untuk menggunakan API, tambahkan parameter ke properti params sebagai objek di navigator.credentials.get() panggilan.

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',
        ETC: 'MOAR',
        scope: 'calendar.readonly photos.write',
      }
    },
  }
});

Nama properti dalam objek params diawali dengan param_. Di kolom contoh di atas, properti params berisi IDP_SPECIFIC_PARAM sebagai '1', foo sebagai 'BAR', ETC sebagai 'MOAR', dan scope sebagai 'calendar.readonly photos.write'. Ini akan diterjemahkan sebagai param_IDP_SPECIFIC_PARAM=1&param_foo=BAR&param_ETC=MOAR&param_scope=calendar.readonly%20photos.write dalam isi HTTP permintaan:

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

account_id=123&client_id=client1234&nonce=234234&disclosure_text_shown=false&param_IDP_SPECIFIC_PARAM=1&param_foo=BAR&param_ETC=MOAR&param_scope=calendar.readonly%20photos.write

Mendapatkan izin secara dinamis

Secara umum, bagi pengguna, akan sangat membantu untuk meminta izin ketika mereka dibutuhkan, bukan ketika pengembang merasa mereka paling mudah untuk menerapkannya. Sebagai misalnya, meminta izin untuk mengakses kamera ketika pengguna akan mengambil foto lebih disarankan untuk meminta izin segera setelah pengguna membuka situs Anda. Praktik yang sama berlaku untuk sumber daya server. Meminta izin saja saat dibutuhkan untuk pengguna. Tindakan ini disebut "otorisasi dinamis".

Untuk meminta otorisasi secara dinamis dengan FedCM, IdP dapat:

Panggil navigator.credentials.get() dengan parameter yang diperlukan yang dapat digunakan IdP dipahami, seperti scope.
Pernyataan ID endpoint mengonfirmasi bahwa pengguna sudah login dan merespons dengan URL continue_on.
Browser akan membuka jendela pop-up dengan halaman izin IdP yang meminta izin tambahan yang sesuai dengan cakupan yang diminta.
Setelah diizinkan melalui IdentityProvider.resolve() oleh IdP, jendela akan ditutup dan panggilan navigator.credentials.get() asli RP mendapatkan token yang relevan atau kode otorisasi sehingga RP dapat menukarnya dengan token akses yang tepat.

API Kolom

Fields API memungkinkan RP untuk mendeklarasikan atribut akun untuk diminta dari IdP sehingga browser dapat merender UI pengungkapan yang sesuai dalam dialog FedCM; merupakan tanggung jawab IdP untuk menyertakan kolom yang diminta dalam token yang ditampilkan. Pertimbangkan permintaan ini "profil dasar" OpenID Connect versus "scopes" (cakupan) di OAuth.

Untuk menggunakan Fields API, tambahkan parameter ke properti fields sebagai array di navigator.credentials.get() panggilan. Kolom dapat berisi 'name', 'email' dan 'picture' untuk saat ini, tetapi dapat diperluas untuk menyertakan lebih banyak nilai dalam masa depan.

Permintaan dengan fields akan terlihat seperti ini:

let { token } = await navigator.credentials.get({
  identity: {
    providers: [{
      fields: ['name', 'email', 'picture'],
      clientId: '1234',
      configURL: 'https://idp.example/fedcm.json',
      params: {
        scope: 'drive.readonly calendar.readonly',
      }
    },
  }
  mediation: 'optional',
});

Permintaan HTTP ke pernyataan ID endpoint menyertakan parameter fields yang ditentukan RP, dengan disclosure_text_shown ditetapkan sebagai true jika ini bukan pengguna yang kembali, dan kolom yang browser yang diungkapkan kepada pengguna dalam parameter disclosure_shown_for:

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=true&fields=email,name,picture&disclosure_shown_for=email,name,picture

Jika RP memerlukan akses ke data tambahan apa pun dari IdP, seperti akses ke ini harus ditangani dengan parameter khusus seperti yang disebutkan di atas. Tujuan IdP menampilkan URL continue_on untuk meminta izin.

Jika fields adalah array kosong, permintaan akan terlihat seperti ini:

let { token } = await navigator.credentials.get({
  identity: {
    providers: [{
      fields: [],
      clientId: '1234',
      configURL: 'https://idp.example/fedcm.json',
      params: {
        scope: 'drive.readonly calendar.readonly',
      }
    },
  }
  mediation: 'optional',
});

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

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

Hal ini tetap perlu dilakukan, meskipun respons dari akun endpoint tidak berisi client ID yang cocok dengan RP di approved_clients.

Dalam hal ini, disclosure_text_shown dikirim ke pernyataan ID endpoint adalah false 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

Beberapa configURL

Beberapa configURL mengizinkan IdP guna mengakomodasi beberapa file konfigurasi untuk IdP, accounts_endpoint dan login_url di toko terkenal file sama sebagai file konfigurasi.

Jika accounts_endpoint dan login_url ditambahkan ke file yang dikenal, provider_urls diabaikan sehingga IdP dapat mendukung beberapa file konfigurasi. Jika tidak, provider_urls akan terus berlaku sehingga menjadi mundur yang kompatibel.

File terkenal yang mendukung beberapa configURL dapat terlihat seperti ini:

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

Hal ini memungkinkan kita untuk:

Mempertahankan kompatibilitas mundur dan maju dengan file terkenal yang sudah ada dan versi {i>browser<i} sebelumnya yang sudah di-deploy di luar sana.
Memiliki jumlah file konfigurasi arbitrer—asalkan semuanya mengarah ke accounts_endpoint dan login_url yang sama.
Tidak memiliki peluang agar entropi ditambahkan ke permintaan pengambilan berkredensial dibuat ke accounts_endpoint, karena harus ditentukan di ".well-known" level organisasi.

Mendukung beberapa configURL bersifat opsional dan FedCM yang ada implementasinya bisa tetap sama.

Label Akun Khusus

Label Akun Kustom mengizinkan FedCM IdP untuk memberikan anotasi pada akun sehingga RP dapat memfilternya dengan menentukan label di file konfigurasi. Pemfilteran serupa dapat digunakan menggunakan Domain Hint API dan Login Hint API dengan menentukan di panggilan navigator.credentials.get(), namun Label Akun Khusus dapat memfilter pengguna dengan menentukan file konfigurasi, yang sangat berguna ketika beberapa configURL digunakan. Label Akun Khusus adalah juga berbeda karena mereka disediakan dari server IdP, bukan dari RP, seperti petunjuk {i>login<i} atau domain.

Contoh

IdP mendukung dua configURL masing-masing untuk konsumen dan perusahaan. Tujuan file konfigurasi konsumen memiliki label 'consumer', dan file konfigurasi perusahaan memiliki label 'enterprise'.

Dengan penyiapan seperti itu, file yang dikenal luas 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"
}

Jika accounts_endpoint disediakan dalam file yang dikenal, provider_urls diabaikan. RP dapat mengarah langsung ke konfigurasi masing-masing dalam panggilan navigator.credentials.get().

File konfigurasi konsumen ada di https://idp.example/fedcm.json yang mencakup Properti accounts yang menentukan 'consumer' menggunakan include.

{
  "accounts_endpoint": "https://idp.example/accounts",
  "client_metadata_endpoint": "/client_metadata",
  "login_url": "https://idp.example/login",
  "id_assertion_endpoint": "/assertion",
  "accounts": {
    "include": "consumer"
  }
}

File konfigurasi perusahaan ada di https://idp.example/enterprise/fedcm.json, yang mencakup properti accounts yang menentukan 'enterprise' menggunakan include.

{
  "accounts_endpoint": "https://idp.example/accounts",
  "client_metadata_endpoint": "/enterprise/client_metadata",
  "login_url": "https://idp.example/login",
  "id_assertion_endpoint": "/assertion",
  "accounts": {
    "include": "enterprise"
  }
}

Akun IdP umum endpoint (dalam contoh ini https://idp.example/accounts) menampilkan daftar akun yang menyertakan properti label dengan labels yang ditetapkan dalam array untuk setiap akun. Berikut adalah contoh respons untuk pengguna yang memiliki dua akun. Satu untuk dan satu lagi untuk perusahaan:

{
 "accounts": [{
   "id": "123",
   "given_name": "John",
   "name": "John Doe",
   "email": "john_doe@idp.example",
   "picture": "https://idp.example/profile/123",
   "labels": ["consumer"]
  }], [{
   "id": "4567",
   "given_name": "Jane",
   "name": "Jane Doe",
   "email": "jane_doe@idp.example",
   "picture": "https://idp.example/profile/4567",
   "labels": ["enterprise"]
  }]
}

Ketika RP ingin mengizinkan pengguna 'enterprise' untuk login, mereka dapat menentukan 'enterprise' configURL 'https://idp.example/enterprise/fedcm.json' di Panggilan navigator.credentials.get():

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

Oleh karena itu, hanya ID akun '4567' yang tersedia untuk ditandatangani pengguna inc. ID akun '123' disembunyikan secara diam-diam oleh browser agar pengguna tidak akan diberikan dengan akun yang tidak didukung oleh IdP di situs ini.

Uji coba origin: FedCM sebagai sinyal kepercayaan untuk Storage Access API

Chrome 126 memulai uji coba origin FedCM sebagai sinyal kepercayaan untuk Akses Penyimpanan Google Cloud Platform. Dengan perubahan ini, pemberian izin sebelumnya melalui FedCM menjadi alasan yang valid untuk menyetujui permintaan akses penyimpanan melalui Akses Penyimpanan Google Cloud API.

Hal ini berguna saat iframe tersemat ingin mengakses resource yang dipersonalisasi: misalnya, jika idp.example disematkan dalam rp.example dan perlu menampilkan resource yang dipersonalisasi. Jika browser membatasi akses ke cookie pihak ketiga, meskipun pengguna login ke rp.example menggunakan idp.example dengan FedCM, iframe idp.example tersemat tidak akan dapat meminta aset yang dipersonalisasi karena permintaan tidak akan menyertakan cookie pihak ketiga.

Untuk mencapai hal ini, idp.example perlu mendapatkan izin akses penyimpanan melalui iframe yang disematkan di situs, dan ini hanya dapat diperoleh melalui dialog izin akses.

Dengan FedCM sebagai sinyal kepercayaan untuk Akses Penyimpanan API, Pemeriksaan izin Storage Access API tidak hanya menerima pemberian izin disediakan oleh prompt akses penyimpanan, tetapi juga pemberian izin yang diberikan oleh Perintah FedCM.

// In top-level rp.example:

// Ensure FedCM permission has been granted.
const cred = await navigator.credentials.get({
  identity: {
    providers: [{
      configURL: 'https://idp.example/fedcm.json',
      clientId: '123',
    }],
  },
  mediation: 'optional',
});

// In an embedded IdP iframe:

// No user gesture is needed to call this, and the call will be auto-granted.
await document.requestStorageAccess();

// This returns `true`.
const hasAccess = await document.hasStorageAccess();

Setelah pengguna login dengan FedCM, izin akan otomatis diberikan selama maka otentikasi FedCM aktif. Ini berarti setelah pengguna terputus, meminta izin akses akan menampilkan sebuah {i>prompt<i}.

Berpartisipasi dalam uji coba origin

Anda dapat mencoba paket FedCM Continuation API secara lokal dengan mengaktifkan Chrome laporkan chrome://flags#fedcm-authz di Chrome 126 atau yang lebih baru. Anda juga dapat mencoba FedCM sebagai sinyal kepercayaan untuk Storage Access API secara lokal dengan mengaktifkan #fedcm-with-storage-access-api di Chrome 126 atau yang lebih baru.

Fitur ini juga tersedia sebagai uji coba origin. Uji coba origin memungkinkan Anda mencoba fitur baru dan memberikan masukan terkait kegunaan, kepraktisan, dan efektivitasnya. Untuk mengetahui informasi selengkapnya, lihat Memulai uji coba origin.

Untuk mencoba asal paket FedCM Continuation API uji coba, membuat dua token uji coba origin:

Daftar uji coba. Menyematkan token ke IdP asal.
Daftar ke uji coba origin dengan mencentang kotak pencocokan pihak ketiga. Ikuti petunjuk di Mendaftarkan uji coba origin pihak ketiga untuk RP untuk menyematkan token untuk RP.

Jika Anda tertarik untuk mengaktifkan Continuation API beserta tombolnya alur, aktifkan Mode Tombol Asal API uji coba juga:

Mendaftar ke uji coba origin sebagai pihak ketiga. Ikuti petunjuk di Daftarkan uji coba origin pihak ketiga untuk RP yang akan disematkan token untuk RP.

Untuk mencoba FedCM sebagai sinyal kepercayaan untuk origin Storage Access API uji coba:

Daftar untuk uji coba origin. Menyematkan token ke IdP asal.

Uji coba origin paket Continuation API dan FedCM sebagai sinyal kepercayaan untuk Uji coba origin Storage Access API tersedia mulai Chrome 126.

Mendaftarkan uji coba origin pihak ketiga untuk RP

Buka halaman pendaftaran uji coba origin.
Klik tombol Register, lalu isi formulir untuk meminta token.
Masukkan asal IdP sebagai Asal Web.
Periksa pencocokan Pihak ketiga untuk memasukkan token dengan JavaScript di origin lain.
Klik Kirim.
Sematkan token yang diterbitkan di situs pihak ketiga.

Untuk menyematkan token di situs pihak ketiga, tambahkan kode berikut ke IdP Library JavaScript atau SDK yang disalurkan dari asal IdP.

const tokenElement = document.createElement('meta');
tokenElement.httpEquiv = 'origin-trial';
tokenElement.content = 'TOKEN_GOES_HERE';
document.head.appendChild(tokenElement);

Ganti TOKEN_GOES_HERE dengan token Anda sendiri.