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
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¶m_foo=BAR¶m_ETC=MOAR¶m_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¶m_IDP_SPECIFIC_PARAM=1¶m_foo=BAR¶m_ETC=MOAR¶m_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, sepertiscope
. - 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 panggilannavigator.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.
![Pesan pengungkapan dalam mode widget.](https://developers-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/assets/images/blog/fedcm-126-with-disclosure-widget.jpg?authuser=2&hl=id)
![Pesan pengungkapan dalam mode tombol.](https://developers-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/assets/images/blog/fedcm-126-with-disclosure-button.jpg?authuser=2&hl=id)
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.](https://developers-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/assets/images/blog/fedcm-126-without-disclosure-widget.jpg?authuser=2&hl=id)
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
danlogin_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.