การใช้งาน FedCM ประกอบด้วยขั้นตอนหลักๆ หลายขั้นตอนสําหรับทั้งผู้ให้บริการข้อมูลประจําตัว (IdP) และฝ่ายที่เชื่อถือ (RP) อ่านเอกสารประกอบเพื่อดูวิธีติดตั้งใช้งาน FedCM ฝั่งRP
IdPsต้องทำตามขั้นตอนต่อไปนี้เพื่อติดตั้งใช้งาน FedCM
- สร้างไฟล์ Well-Known
- สร้างไฟล์การกําหนดค่า
- สร้างปลายทางต่อไปนี้
- แจ้งเบราว์เซอร์เกี่ยวกับสถานะการเข้าสู่ระบบของผู้ใช้
สร้างไฟล์ Well-Known
เพื่อป้องกันไม่ให้เครื่องมือติดตามละเมิด API ต้องแสดงไฟล์ .well-known จาก /.well-known/web-identity
ของ eTLD+1 ของ IdP
ไฟล์ที่รู้จักดีอาจมีพร็อพเพอร์ตี้ต่อไปนี้
พร็อพเพอร์ตี้ | ต้องระบุ | คำอธิบาย |
---|---|---|
provider_
|
ต้องระบุ | อาร์เรย์ของเส้นทางไฟล์การกําหนดค่า IdP ระบบจะไม่สนใจ (แต่ยังคงต้องระบุ) หากมีการระบุ accounts_ และ login_ |
accounts_
|
แนะนำ ต้องมี login_ |
URL สำหรับปลายทางบัญชี ซึ่งช่วยให้รองรับการกำหนดค่าได้หลายรายการ ตราบใดที่ไฟล์การกําหนดค่าแต่ละไฟล์ใช้ URL login_ และ accounts_endpoint เดียวกันหมายเหตุ: ระบบรองรับพารามิเตอร์นี้ตั้งแต่ Chrome 132 |
login_url
|
แนะนำ ต้องมี accounts_endpoint |
URL หน้าเข้าสู่ระบบสำหรับให้ผู้ใช้ลงชื่อเข้าใช้ IdP ซึ่งช่วยให้รองรับการกำหนดค่าได้หลายรายการ ตราบใดที่ไฟล์ config แต่ละไฟล์ใช้ login_url และ accounts_endpoint เดียวกันหมายเหตุ: ระบบรองรับพารามิเตอร์นี้ตั้งแต่ Chrome เวอร์ชัน 132 ขึ้นไป |
เช่น หากมีการแสดงปลายทาง IdP ภายใต้ https://accounts.idp.example/
ปลายทางดังกล่าวต้องแสดงไฟล์ .well-known ที่ https://idp.example/.well-known/web-identity
รวมถึงไฟล์การกําหนดค่า IdP ตัวอย่างเนื้อหาไฟล์ที่รู้จักมีดังนี้
{
"provider_urls": ["https://accounts.idp.example/config.json"]
}
IdP สามารถรองรับไฟล์การกําหนดค่าหลายไฟล์สําหรับ IdP ได้โดยระบุ accounts_endpoint
และ login_url
ในไฟล์ .well-known
ฟีเจอร์นี้มีประโยชน์ในกรณีต่อไปนี้
- IdP ต้องรองรับการกําหนดค่าการทดสอบและเวอร์ชันที่ใช้งานจริงหลายรายการ
- IdP ต้องรองรับการกำหนดค่าที่แตกต่างกันในแต่ละภูมิภาค (เช่น
eu-idp.example
และus-idp.example
)
หากต้องการรองรับการกำหนดค่าหลายรายการ (เช่น เพื่อแยกความแตกต่างระหว่างสภาพแวดล้อมการทดสอบและสภาพแวดล้อมที่ใช้งานจริง) IdP ต้องระบุ accounts_endpoint
และ 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"
}
สร้างไฟล์การกําหนดค่าและปลายทาง IdP
ไฟล์การกําหนดค่า IdP มีรายการอุปกรณ์ปลายทางที่จําเป็นสําหรับเบราว์เซอร์ IdP ต้องโฮสต์ไฟล์การกําหนดค่าอย่างน้อย 1 ไฟล์ รวมถึงปลายทางและ URL ที่จําเป็น การตอบกลับ JSON ทั้งหมดต้องแสดงด้วยประเภทเนื้อหา application/json
URL ของไฟล์การกําหนดค่าจะกําหนดโดยค่าที่ระบุในการเรียกใช้ navigator.credentials.get()
ที่ดําเนินการบน RP
const credential = await navigator.credentials.get({
identity: {
context: 'signup',
providers: [{
configURL: 'https://accounts.idp.example/config.json',
clientId: '********',
nonce: '******'
}]
}
});
const { token } = credential;
RP จะส่ง URL ของไฟล์การกําหนดค่าไปยังการเรียกใช้ FedCM API เพื่อให้ผู้ใช้ลงชื่อเข้าใช้
// 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;
เบราว์เซอร์จะดึงข้อมูลไฟล์การกําหนดค่าด้วยคําขอ GET
ที่ไม่มีส่วนหัว Origin
หรือส่วนหัว Referer
คำขอไม่มีคุกกี้และไม่ติดตามการเปลี่ยนเส้นทาง วิธีนี้ช่วยป้องกันไม่ให้ IdP ทราบว่าใครเป็นผู้ส่งคำขอและ RP ใดที่พยายามเชื่อมต่อ เช่น
GET /config.json HTTP/1.1
Host: accounts.idp.example
Accept: application/json
Sec-Fetch-Dest: webidentity
IdP ต้องใช้ปลายทางการกําหนดค่าที่ตอบกลับด้วย JSON JSON ประกอบด้วยพร็อพเพอร์ตี้ต่อไปนี้
พร็อพเพอร์ตี้ | คำอธิบาย |
---|---|
accounts_endpoint (ต้องระบุ) |
URL สำหรับปลายทางบัญชี |
accounts.include (ไม่บังคับ)
|
สตริงป้ายกำกับบัญชีที่กำหนดเอง ซึ่งกำหนดว่าควรแสดงบัญชีใดเมื่อใช้ไฟล์การกําหนดค่านี้ เช่น "accounts": {"include": "developer"}
IdP สามารถใช้การติดป้ายกำกับบัญชีที่กำหนดเองได้ดังนี้
ตัวอย่างเช่น IdP ใช้ "https://idp.example/developer-config.json" ไฟล์การกําหนดค่าที่ระบุ "accounts": {"include": "developer"} นอกจากนี้ IdP ยังทำเครื่องหมายบัญชีบางบัญชีด้วยป้ายกำกับ "developer" โดยใช้พารามิเตอร์ labels ในปลายทางบัญชี เมื่อ RP เรียกใช้ navigator.credentials.get() โดยระบุไฟล์การกําหนดค่า "https://idp.example/developer-config.json" ระบบจะแสดงเฉพาะบัญชีที่มีป้ายกํากับ "developer" หมายเหตุ: Chrome 132 รองรับป้ายกำกับบัญชีที่กำหนดเอง |
client_metadata_endpoint (ไม่บังคับ) |
URL สำหรับปลายทางข้อมูลเมตาไคลเอ็นต์ |
id_assertion_endpoint (ต้องระบุ) |
URL สำหรับปลายทางการยืนยันผ่านบัตรประจำตัว |
disconnect (ไม่บังคับ) |
URL สำหรับยกเลิกการเชื่อมต่อปลายทาง |
login_url (ต้องระบุ) |
URL หน้าเข้าสู่ระบบสำหรับให้ผู้ใช้ลงชื่อเข้าใช้ IdP |
branding (ไม่บังคับ) |
ออบเจ็กต์ที่มีตัวเลือกการสร้างแบรนด์ต่างๆ |
branding.background_color (ไม่บังคับ) |
ตัวเลือกการสร้างแบรนด์ซึ่งกำหนดสีพื้นหลังของปุ่ม "ดำเนินการต่อในฐานะ..." ใช้ไวยากรณ์ CSS ที่เกี่ยวข้อง ดังนี้
hex-color ,
hsl() ,
rgb() หรือ
named-color |
branding.color (ไม่บังคับ) |
ตัวเลือกการสร้างแบรนด์ซึ่งกำหนดสีข้อความของปุ่ม "ดำเนินการต่อในฐานะ..." ใช้ไวยากรณ์ CSS ที่เกี่ยวข้อง ดังนี้
hex-color ,
hsl() ,
rgb() หรือ
named-color |
branding.icons (ไม่บังคับ) |
อาร์เรย์ของออบเจ็กต์ไอคอน ไอคอนเหล่านี้จะแสดงในกล่องโต้ตอบการลงชื่อเข้าใช้ ออบเจ็กต์ไอคอนมีพารามิเตอร์ 2 รายการ ได้แก่
|
modes |
ออบเจ็กต์ที่มีข้อกำหนดเกี่ยวกับวิธีแสดง UI ของ FedCM ในโหมดต่างๆ
|
modes.active
|
ออบเจ็กต์ที่มีพร็อพเพอร์ตี้ที่อนุญาตให้ปรับแต่งลักษณะการทํางานของ FedCM ในโหมดที่เฉพาะเจาะจง ทั้ง modes.active และ modes.passive มีพารามิเตอร์ต่อไปนี้ได้
หมายเหตุ: ฟีเจอร์ใช้บัญชีอื่นและโหมดที่ใช้งานอยู่ใช้ได้ใน Chrome เวอร์ชัน 132 ขึ้นไป |
modes.passive
|
ต่อไปนี้คือตัวอย่างเนื้อหาการตอบกลับจากผู้ให้บริการระบุตัวตน
{
"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
}]
}
}
เมื่อเบราว์เซอร์ดึงข้อมูลไฟล์การกําหนดค่าแล้ว ก็จะส่งคําขอต่อไปยังปลายทางของ IdP ดังนี้
![ปลายทางของ IdP](https://developers.google.com/static/privacy-sandbox/assets/images/fedcm/fedcm-flow-diagram.png?authuser=8&hl=th)
ใช้บัญชีอื่น
ผู้ใช้สามารถเปลี่ยนไปใช้บัญชีอื่นที่ไม่ใช่บัญชีที่ลงชื่อเข้าใช้อยู่ได้ หากผู้ให้บริการระบุตัวตนรองรับหลายบัญชีหรือแทนที่บัญชีที่มีอยู่
หากต้องการให้ผู้ใช้เลือกบัญชีอื่นได้ IdP จะต้องระบุฟีเจอร์นี้ในไฟล์กำหนดค่า
{
"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
}
}
ปลายทางของบัญชี
ปลายทางบัญชีของ IdP จะแสดงรายการบัญชีที่ผู้ใช้ลงชื่อเข้าใช้ใน IdP หากผู้ให้บริการระบุตัวตนรองรับหลายบัญชี ปลายทางนี้จะแสดงบัญชีที่ลงชื่อเข้าใช้ทั้งหมด
เบราว์เซอร์ส่งคำขอ GET
ที่มีคุกกี้ SameSite=None
แต่ไม่มีพารามิเตอร์ client_id
, ส่วนหัว Origin
หรือส่วนหัว Referer
ซึ่งจะช่วยป้องกันไม่ให้ IdP ทราบว่าผู้ใช้พยายามลงชื่อเข้าใช้ RP ใด เช่น
GET /accounts.example HTTP/1.1
Host: accounts.idp.example
Accept: application/json
Cookie: 0x23223
Sec-Fetch-Dest: webidentity
เมื่อได้รับคําขอ เซิร์ฟเวอร์ควรทําดังนี้
- ตรวจสอบว่าคําขอมีส่วนหัว
Sec-Fetch-Dest: webidentity
HTTP - จับคู่คุกกี้เซสชันกับรหัสของบัญชีที่ลงชื่อเข้าใช้แล้ว
- ตอบกลับพร้อมรายการบัญชี
เบราว์เซอร์คาดหวังว่าจะได้รับคำตอบ JSON ที่มีพร็อพเพอร์ตี้ accounts
ที่มีอาร์เรย์ของข้อมูลบัญชีที่มีพร็อพเพอร์ตี้ต่อไปนี้
พร็อพเพอร์ตี้ | คำอธิบาย |
---|---|
id (ต้องระบุ) |
รหัสที่ไม่ซ้ำกันของผู้ใช้ |
name (ต้องระบุ) |
ชื่อและนามสกุลของผู้ใช้ |
email (ต้องระบุ) |
อีเมลของผู้ใช้ |
given_name (ไม่บังคับ) |
ชื่อจริงของผู้ใช้ |
picture (ไม่บังคับ) |
URL ของรูปโปรไฟล์ผู้ใช้ |
approved_clients (ไม่บังคับ) |
อาร์เรย์รหัสไคลเอ็นต์ RP ที่ผู้ใช้ลงทะเบียนไว้ |
login_hints (ไม่บังคับ) |
อาร์เรย์ของประเภทตัวกรองที่เป็นไปได้ทั้งหมดที่ IdP รองรับเพื่อระบุบัญชี RP สามารถเรียกใช้ navigator.credentials.get() ด้วยพร็อพเพอร์ตี้ loginHint เพื่อแสดงบัญชีที่ระบุ |
domain_hints (ไม่บังคับ) |
อาร์เรย์ของโดเมนทั้งหมดที่เชื่อมโยงกับบัญชี RP สามารถเรียกใช้ navigator.credentials.get() ด้วยพร็อพเพอร์ตี้ domainHint เพื่อกรองบัญชี |
labels (ไม่บังคับ)
|
อาร์เรย์ของสตริงป้ายกำกับบัญชีที่กำหนดเองซึ่งเชื่อมโยงกับบัญชี IdP สามารถใช้การติดป้ายกำกับบัญชีที่กำหนดเองได้ดังนี้
ตัวอย่างเช่น IdP ใช้ https://idp.example/developer-config.json ไฟล์การกําหนดค่าที่ระบุ "accounts": {"include": "developer"} นอกจากนี้ IdP ยังทำเครื่องหมายบัญชีบางบัญชีด้วยป้ายกํากับ "developer" โดยใช้พารามิเตอร์ labels ใน ปลายทางของบัญชี เมื่อ RP เรียกใช้ navigator.credentials.get() โดยระบุไฟล์การกําหนดค่า https://idp.example/developer-config.json ระบบจะแสดงเฉพาะบัญชีที่มีป้ายกํากับ "developer" ป้ายกํากับบัญชีที่กําหนดเองแตกต่างจากคำแนะนำในการเข้าสู่ระบบและคำแนะนำโดเมนตรงที่เซิร์ฟเวอร์ IdP จะเป็นผู้ดูแลรักษาป้ายกำกับเหล่านี้โดยสมบูรณ์ และ RP จะระบุเฉพาะไฟล์การกําหนดค่าที่จะใช้เท่านั้น หมายเหตุ: Chrome 132 รองรับป้ายกำกับบัญชีที่กำหนดเอง |
ตัวอย่างเนื้อหาการตอบกลับ
{
"accounts": [{
"id": "1234",
"given_name": "John",
"name": "John Doe",
"email": "john_doe@idp.example",
"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": "johnny@idp.example",
"picture": "https://idp.example/profile/456",
"approved_clients": ["abc", "def", "ghi"],
"login_hints": ["demo2"],
"domain_hints": ["@domain.example"]
}]
}
หากผู้ใช้ไม่ได้ลงชื่อเข้าใช้ ให้ตอบกลับด้วย HTTP 401
(ไม่ได้รับอนุญาต)
เบราว์เซอร์จะใช้รายการบัญชีที่แสดงผลและ RP จะใช้ไม่ได้
ปลายทางการระบุตัวตน
ปลายทางการยืนยันผ่านบัตรประจำตัวของ IdP จะแสดงการยืนยันสําหรับผู้ใช้ที่ลงชื่อเข้าใช้
เมื่อผู้ใช้ลงชื่อเข้าใช้เว็บไซต์ RP โดยใช้ navigator.credentials.get()
call เบราว์เซอร์จะส่งคำขอ POST
พร้อมคุกกี้ที่มี SameSite=None
และประเภทเนื้อหาเป็น application/x-www-form-urlencoded
ไปยังปลายทางนี้พร้อมข้อมูลต่อไปนี้
พร็อพเพอร์ตี้ | คำอธิบาย |
---|---|
client_id (ต้องระบุ) |
ตัวระบุไคลเอ็นต์ของ RP |
account_id (ต้องระบุ) |
รหัสที่ไม่ซ้ำกันของผู้ใช้ที่ลงชื่อเข้าใช้ |
disclosure_text_shown |
แสดงผลเป็นสตริง "true" หรือ "false" (แทนที่จะเป็นบูลีน) ผลลัพธ์คือ "false" ในกรณีต่อไปนี้
|
is_auto_selected |
หากมีการตรวจสอบสิทธิ์อีกครั้งโดยอัตโนมัติใน RP is_auto_selected จะแสดง "true" หรือ "false" ซึ่งจะเป็นประโยชน์ในการสนับสนุนฟีเจอร์ที่เกี่ยวข้องกับการรักษาความปลอดภัยมากขึ้น ตัวอย่างเช่น ผู้ใช้บางรายอาจต้องการระดับการรักษาความปลอดภัยที่สูงขึ้น ซึ่งกำหนดให้ต้องมีการสื่อกลางของผู้ใช้อย่างชัดเจนในการตรวจสอบสิทธิ์ หาก IdP ได้รับคำขอโทเค็นโดยไม่มีสื่อกลางดังกล่าว IdP อาจจัดการคำขอในลักษณะอื่น เช่น แสดงรหัสข้อผิดพลาดเพื่อให้ RP สามารถเรียกใช้ FedCM API อีกครั้งด้วย mediation: required |
fields (ไม่บังคับ)
|
อาร์เรย์สตริงที่ระบุข้อมูลผู้ใช้ ("name", "email", "picture") ที่ RP ต้องการให้ IdP แชร์ เบราว์เซอร์จะส่ง fields , disclosure_text_shown และ disclosure_shown_for ที่แสดงรายการฟิลด์ที่ระบุในคำขอ POST ดังในตัวอย่างต่อไปนี้หมายเหตุ: Chrome 132 รองรับพารามิเตอร์ฟิลด์ |
params (ไม่บังคับ)
|
ออบเจ็กต์ JSON ที่ถูกต้องซึ่งอนุญาตให้ระบุพารามิเตอร์คีย์-ค่าที่กำหนดเองเพิ่มเติม เช่น
params เป็น JSON แล้วเข้ารหัสเป็นเปอร์เซ็นต์หมายเหตุ: Chrome 132 ขึ้นไปรองรับ Parameters API |
ตัวอย่างส่วนหัว 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¶ms=%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
เมื่อได้รับคําขอ เซิร์ฟเวอร์ควรทําดังนี้
- ตอบสนองคําขอด้วย CORS (Cross-Origin Resource Sharing)
- ตรวจสอบว่าคำขอมีส่วนหัว
Sec-Fetch-Dest: webidentity
HTTP - จับคู่ส่วนหัว
Origin
กับต้นทาง RP ที่ระบุโดยclient_id
ปฏิเสธหากไม่ตรงกัน - จับคู่
account_id
กับรหัสของบัญชีที่ลงชื่อเข้าใช้แล้ว ปฏิเสธหากไม่ตรงกัน - ตอบกลับด้วยโทเค็น หากคำขอถูกปฏิเสธ ให้ตอบกลับด้วยคำตอบเกี่ยวกับข้อผิดพลาด
โดยผู้ให้บริการระบุตัวตนจะเลือกวิธีออกโทเค็นได้ โดยทั่วไปแล้ว โทเค็นจะได้รับการรับรองด้วยข้อมูล เช่น รหัสบัญชี รหัสลูกค้า ต้นทางของผู้ออกบัตร และ Nonce เพื่อให้ RP ยืนยันได้ว่าโทเค็นเป็นของจริง
เบราว์เซอร์คาดหวังว่าการตอบกลับ JSON จะมีพร็อพเพอร์ตี้ต่อไปนี้
พร็อพเพอร์ตี้ | คำอธิบาย |
---|---|
token |
โทเค็นคือสตริงที่มีการอ้างสิทธิ์เกี่ยวกับการตรวจสอบสิทธิ์ |
continue_on |
URL เปลี่ยนเส้นทางที่เปิดใช้ขั้นตอนการลงชื่อเข้าใช้แบบหลายขั้นตอน |
เบราว์เซอร์จะส่งโทเค็นที่แสดงผลไปยัง RP เพื่อให้ RP ตรวจสอบการตรวจสอบสิทธิ์ได้
{
// IdP can respond with a token to authenticate the user
"token": "***********"
}
ดำเนินการต่อในฟีเจอร์
IdP สามารถระบุ URL การเปลี่ยนเส้นทางในการตอบกลับปลายทางการยืนยันเพื่อเปิดใช้ขั้นตอนการลงชื่อเข้าใช้แบบหลายขั้นตอน ซึ่งมีประโยชน์เมื่อ IdP จำเป็นต้องขอข้อมูลเพิ่มเติมหรือสิทธิ์เพิ่มเติม เช่น
- สิทธิ์เข้าถึงทรัพยากรฝั่งเซิร์ฟเวอร์ของผู้ใช้
- ยืนยันว่าข้อมูลติดต่อเป็นข้อมูลล่าสุด
- การควบคุมโดยผู้ปกครอง
ปลายทางการยืนยันผ่านบัตรประจำตัวสามารถแสดงผลพร็อพเพอร์ตี้ continue_on
ซึ่งมีเส้นทางสัมพัทธ์หรือสัมบูรณ์ไปยังปลายทางการยืนยันผ่านบัตรประจำตัว
{
// 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"
}
หากการตอบกลับมีพารามิเตอร์ continue_on
ระบบจะเปิดหน้าต่างป๊อปอัปใหม่และนําผู้ใช้ไปยังเส้นทางที่ระบุ หลังจากการโต้ตอบของผู้ใช้กับหน้า continue_on
แล้ว IdP ควรเรียกใช้ IdentityProvider.resolve()
โดยส่งโทเค็นเป็นอาร์กิวเมนต์เพื่อให้ระบบแก้ไขสัญญาจากnavigator.credentials.get()
การเรียกใช้เดิมได้ ดังนี้
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);
});
จากนั้นเบราว์เซอร์จะปิดป๊อปอัปโดยอัตโนมัติและส่งโทเค็นกลับไปยังผู้เรียก API การเรียก IdentityProvider.resolve()
แบบครั้งเดียวเป็นวิธีเดียวที่หน้าต่างหลัก (RP) และหน้าต่างป๊อปอัป (IdP) จะสื่อสารกันได้
หากผู้ใช้ปฏิเสธคําขอ IdP จะปิดหน้าต่างได้โดยเรียกใช้ IdentityProvider.close()
IdentityProvider.close();
Continuation API ต้องมีการโต้ตอบจากผู้ใช้อย่างชัดเจน (การคลิก) จึงจะทํางานได้ Continuation API ทํางานกับโหมดสื่อกลางต่างๆ ดังนี้
- ในโหมดพาสซีฟ
mediation: 'optional'
(ค่าเริ่มต้น): Continuation API จะทํางานกับท่าทางสัมผัสของผู้ใช้เท่านั้น เช่น การคลิกปุ่มในหน้าเว็บหรือใน UI ของ FedCM เมื่อระบบเรียกให้ตรวจสอบสิทธิ์อีกครั้งโดยอัตโนมัติโดยไม่มีท่าทางสัมผัสของผู้ใช้ ระบบจะไม่เปิดหน้าต่างป๊อปอัปและปฏิเสธสัญญาmediation: 'required'
: ขอให้ผู้ใช้โต้ตอบเสมอเพื่อให้ Continuation API ทำงานได้เสมอ
- ในโหมดทำงาน
- ต้องเปิดใช้งานผู้ใช้เสมอ Continuation API ใช้งานร่วมกันได้
หากผู้ใช้เปลี่ยนบัญชีในป๊อปอัปด้วยเหตุผลบางอย่าง (เช่น IdP มีฟังก์ชัน "ใช้บัญชีอื่น" หรือในกรณีที่มีการมอบสิทธิ์) การเรียกใช้การแก้ไขจะใช้อาร์กิวเมนต์ที่ 2 ที่ไม่บังคับ ซึ่งอนุญาตให้ดำเนินการต่อไปนี้ได้
IdentityProvider.resolve(token, {accountId: '1234');
แสดงการตอบกลับที่มีข้อผิดพลาด
id_assertion_endpoint
ยังแสดงผล "ข้อผิดพลาด" ในการตอบกลับได้ด้วย ซึ่งจะมีช่องที่ไม่บังคับ 2 ช่องดังนี้
code
: IdP สามารถเลือกข้อผิดพลาดที่ทราบแล้วรายการใดรายการหนึ่งจากรายการข้อผิดพลาดที่ระบุของ OAuth 2.0 (invalid_request
,unauthorized_client
,access_denied
,server_error
และtemporarily_unavailable
) หรือใช้สตริงใดก็ได้ หากเป็นกรณีหลัง Chrome จะแสดงผล UI ข้อผิดพลาดพร้อมข้อความแสดงข้อผิดพลาดทั่วไปและส่งรหัสไปยัง RPurl
: ระบุหน้าเว็บที่มนุษย์อ่านได้พร้อมข้อมูลเกี่ยวกับข้อผิดพลาดเพื่อให้ข้อมูลเพิ่มเติมเกี่ยวกับข้อผิดพลาดแก่ผู้ใช้ ช่องนี้มีประโยชน์ต่อผู้ใช้เนื่องจากเบราว์เซอร์ไม่สามารถแสดงข้อความแสดงข้อผิดพลาดแบบริชมีเดียใน UI ในตัว เช่น ลิงก์สำหรับขั้นตอนถัดไป หรือข้อมูลติดต่อฝ่ายบริการลูกค้า หากต้องการดูข้อมูลเพิ่มเติมเกี่ยวกับรายละเอียดข้อผิดพลาดและวิธีแก้ไข ผู้ใช้สามารถไปที่หน้าเว็บที่ระบุจาก UI ของเบราว์เซอร์เพื่อดูรายละเอียดเพิ่มเติม URL ต้องเป็นของเว็บไซต์เดียวกับ IdPconfigURL
// id_assertion_endpoint response
{
"error" : {
"code": "access_denied",
"url" : "https://idp.example/error?type=access_denied"
}
}
ป้ายกำกับบัญชีที่กำหนดเอง
เมื่อใช้ป้ายกำกับบัญชีที่กำหนดเอง ผู้ให้บริการระบุตัวตนจะใส่คำอธิบายประกอบบัญชีผู้ใช้ด้วยป้ายกำกับได้ และ RP จะเลือกดึงข้อมูลเฉพาะบัญชีที่มีป้ายกำกับที่เฉพาะเจาะจงได้โดยระบุ configURL
สำหรับป้ายกำกับนั้น ซึ่งจะมีประโยชน์เมื่อ RP ต้องกรองบัญชีตามเกณฑ์ที่เฉพาะเจาะจง เช่น เพื่อแสดงเฉพาะบัญชีที่เจาะจงบทบาท เช่น "developer"
หรือ "hr"
คุณสามารถกรองข้อมูลในลักษณะที่คล้ายกันได้โดยใช้ฟีเจอร์คำแนะนำโดเมนและคำแนะนำการเข้าสู่ระบบ โดยระบุไว้ในการเรียกใช้ navigator.credentials.get()
อย่างไรก็ตาม ป้ายกํากับบัญชีที่กําหนดเองสามารถกรองผู้ใช้ได้โดยระบุไฟล์การกําหนดค่า ซึ่งมีประโยชน์อย่างยิ่งเมื่อใช้ configURL หลายรายการ นอกจากนี้ ป้ายกำกับบัญชีที่กำหนดเองยังแตกต่างจากป้ายกำกับอื่นๆ ตรงที่มาจากเซิร์ฟเวอร์ IdP ไม่ใช่จาก RP เช่น คำแนะนำในการเข้าสู่ระบบหรือโดเมน
พิจารณาผู้ให้บริการระบุตัวตนที่ต้องการแยกความแตกต่างระหว่างบัญชี "developer"
กับ "hr"
โดย IdP ต้องรองรับ configURL 2 รายการสําหรับ "developer"
และ "hr"
ตามลําดับ
- ไฟล์การกําหนดค่าของนักพัฒนาซอฟต์แวร์
https://idp.example/developer/fedcm.json
มีป้ายกํากับ"developer"
และไฟล์การกําหนดค่าขององค์กรhttps://idp.example/hr/fedcm.json
มีป้ายกํากับ"hr"
ดังนี้
// 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"
}
}
- เมื่อใช้การตั้งค่าดังกล่าว ไฟล์ .well-known ควรมี
accounts_endpoint
และlogin_url
เพื่ออนุญาตให้มี configURL หลายรายการ
{
"provider_urls": [ "https://idp.example/fedcm.json" ],
"accounts_endpoint": "https://idp.example/accounts",
"login_url": "https://idp.example/login"
}
- ปลายทางบัญชี IdP ทั่วไป (ในตัวอย่างนี้
https://idp.example/accounts
) จะแสดงรายการบัญชีที่มีพร็อพเพอร์ตี้labels
ที่มีป้ายกำกับที่กำหนดไว้ในอาร์เรย์สำหรับแต่ละบัญชี
{
"accounts": [{
"id": "123",
"given_name": "John",
"name": "John Doe",
"email": "john_doe@idp.example",
"picture": "https://idp.example/profile/123",
"labels": ["developer"]
}], [{
"id": "4567",
"given_name": "Jane",
"name": "Jane Doe",
"email": "jane_doe@idp.example",
"picture": "https://idp.example/profile/4567",
"labels": ["hr"]
}]
}
เมื่อ RP ต้องการอนุญาตให้ผู้ใช้ "hr"
ลงชื่อเข้าใช้ ให้ระบุ
configURL https://idp.example/hr/fedcm.json
ในnavigator.credentials.get()
call ดังนี้
let { token } = await navigator.credentials.get({
identity: {
providers: [{
clientId: '1234',
nonce: '234234',
configURL: 'https://idp.example/hr/fedcm.json',
},
}
});
ด้วยเหตุนี้ ผู้ใช้จึงลงชื่อเข้าใช้ได้โดยใช้รหัสบัญชี 4567
เท่านั้น
เบราว์เซอร์จะซ่อนรหัสบัญชี 123
โดยอัตโนมัติเพื่อไม่ให้ผู้ใช้ได้รับบัญชีที่ IdP ในเว็บไซต์นี้ไม่รองรับ
- ป้ายกำกับคือสตริง หากอาร์เรย์
labels
หรือช่องinclude
มีสิ่งที่ไม่ใช่สตริง ระบบจะละเว้น - หากไม่ได้ระบุป้ายกำกับใน
configURL
ระบบจะแสดงบัญชีทั้งหมดในเครื่องมือเลือกบัญชี FedCM - หากไม่ได้ระบุป้ายกำกับสำหรับบัญชี บัญชีดังกล่าวจะแสดงในเครื่องมือเลือกบัญชีก็ต่อเมื่อ
configURL
ไม่ได้ระบุป้ายกำกับเช่นกัน - หากไม่มีบัญชีที่ตรงกับป้ายกำกับที่ขอในโหมด Passive (คล้ายกับฟีเจอร์คำแนะนำโดเมน) กล่องโต้ตอบ FedCM จะแสดงข้อความแจ้งให้เข้าสู่ระบบ ซึ่งช่วยให้ผู้ใช้ลงชื่อเข้าใช้บัญชี IdP ได้ สำหรับโหมดที่ใช้งานอยู่ ระบบจะเปิดหน้าต่างป๊อปอัปการเข้าสู่ระบบโดยตรง
ยกเลิกการเชื่อมต่อปลายทาง
เมื่อเรียกใช้ IdentityCredential.disconnect()
เบราว์เซอร์จะส่งคำขอ POST
ข้ามแหล่งที่มาพร้อมคุกกี้ที่มี SameSite=None
และประเภทเนื้อหา application/x-www-form-urlencoded
ไปยังปลายทางการยกเลิกการเชื่อมต่อนี้พร้อมข้อมูลต่อไปนี้
พร็อพเพอร์ตี้ | คำอธิบาย |
---|---|
account_hint |
คำแนะนำสำหรับบัญชี IdP |
client_id |
ตัวระบุไคลเอ็นต์ของ 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
เมื่อได้รับคําขอ เซิร์ฟเวอร์ควรทําดังนี้
- ตอบสนองคําขอด้วย CORS (Cross-Origin Resource Sharing)
- ตรวจสอบว่าคําขอมีส่วนหัว
Sec-Fetch-Dest: webidentity
HTTP - จับคู่ส่วนหัว
Origin
กับต้นทาง RP ที่ระบุโดยclient_id
ปฏิเสธหากไม่ตรงกัน - จับคู่
account_hint
กับรหัสของบัญชีที่ลงชื่อเข้าใช้แล้ว - ยกเลิกการเชื่อมต่อบัญชีผู้ใช้กับ RP
- ตอบกลับเบราว์เซอร์ด้วยข้อมูลบัญชีผู้ใช้ที่ระบุในรูปแบบ JSON
ตัวอย่างเพย์โหลด JSON ของคำตอบมีลักษณะดังนี้
{
"account_id": "account456"
}
แต่หาก IdP ต้องการให้เบราว์เซอร์ยกเลิกการเชื่อมต่อบัญชีทั้งหมดที่เชื่อมโยงกับ RP ให้ส่งสตริงที่ไม่ตรงกับรหัสบัญชีใดๆ เช่น "*"
ปลายทางข้อมูลเมตาไคลเอ็นต์
ปลายทางข้อมูลเมตาไคลเอ็นต์ของผู้ให้บริการระบุตัวตนจะแสดงผลข้อมูลเมตาของฝ่ายที่เชื่อถือ เช่น นโยบายความเป็นส่วนตัว ข้อกำหนดในการให้บริการ และไอคอนโลโก้ของฝ่ายที่เชื่อถือ RP ควรระบุลิงก์ไปยังนโยบายความเป็นส่วนตัวและข้อกำหนดในการให้บริการของตนแก่ผู้ให้บริการระบุตัวตนล่วงหน้า ลิงก์เหล่านี้จะแสดงในกล่องโต้ตอบการลงชื่อเข้าใช้เมื่อผู้ใช้ยังไม่ได้ลงทะเบียนใน RP กับ IdP
เบราว์เซอร์ส่งคําขอ GET
โดยใช้ client_id
navigator.credentials.get
โดยไม่มีคุกกี้ เช่น
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
เมื่อได้รับคําขอ เซิร์ฟเวอร์ควรทําดังนี้
- กำหนด RP สำหรับ
client_id
- ตอบกลับพร้อมข้อมูลเมตาของไคลเอ็นต์
พร็อพเพอร์ตี้สําหรับปลายทางข้อมูลเมตาไคลเอ็นต์มีดังนี้
พร็อพเพอร์ตี้ | คำอธิบาย |
---|---|
privacy_policy_url (ไม่บังคับ) |
URL นโยบายความเป็นส่วนตัวของ RP |
terms_of_service_url (ไม่บังคับ) |
URL ของข้อกำหนดในการให้บริการของ RP |
icons (ไม่บังคับ) |
อาร์เรย์ของออบเจ็กต์ เช่น [{ "url": "https://rp.example/rp-icon.ico", "size": 40}] |
เบราว์เซอร์คาดหวังว่าจะได้รับการตอบกลับ JSON จากปลายทาง
{
"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
}]
}
เบราว์เซอร์จะใช้ข้อมูลเมตาของไคลเอ็นต์ที่แสดงผลและ RP จะใช้ไม่ได้
URL เข้าสู่ระบบ
ปลายทางนี้ใช้เพื่อให้ผู้ใช้ลงชื่อเข้าใช้ IdP
เมื่อใช้ Login Status API นั้น IdP จะต้องแจ้งสถานะการเข้าสู่ระบบของผู้ใช้ให้เบราว์เซอร์ทราบ อย่างไรก็ตาม สถานะอาจไม่ตรงกัน เช่น เมื่อเซสชันหมดอายุ ในกรณีเช่นนี้ เบราว์เซอร์จะอนุญาตให้ผู้ใช้ลงชื่อเข้าใช้ IdP ผ่าน URL หน้าเข้าสู่ระบบที่ระบุด้วย login_url
ของไฟล์การกําหนดค่า IdP แบบไดนามิกได้
กล่องโต้ตอบ FedCM จะแสดงข้อความที่แนะนำให้ลงชื่อเข้าใช้ ดังที่แสดงในรูปภาพต่อไปนี้
![A](https://developers.google.com/static/privacy-sandbox/assets/images/blog/fedcm-120-1.png?authuser=8&hl=th)
เมื่อผู้ใช้คลิกปุ่มต่อไป เบราว์เซอร์จะเปิดหน้าต่างป๊อปอัปสำหรับหน้าเข้าสู่ระบบของผู้ให้บริการระบุตัวตน
![ตัวอย่างกล่องโต้ตอบ FedCM](https://developers.google.com/static/privacy-sandbox/assets/images/fedcm-dialog-example.png?authuser=8&hl=th)
กล่องโต้ตอบคือหน้าต่างเบราว์เซอร์ปกติที่มีคุกกี้ของบุคคลที่หนึ่ง ทุกอย่างที่เกิดขึ้นภายในกล่องโต้ตอบขึ้นอยู่กับ IdP และจะไม่มีแฮนเดิลหน้าต่างสำหรับส่งคำขอการสื่อสารข้ามแหล่งที่มาไปยังหน้า RP หลังจากผู้ใช้ลงชื่อเข้าใช้แล้ว IdP ควรทําดังนี้
- ส่งส่วนหัว
Set-Login: logged-in
หรือเรียกใช้navigator.login.setStatus("logged-in")
API เพื่อแจ้งให้เบราว์เซอร์ทราบว่าผู้ใช้ลงชื่อเข้าใช้แล้ว - กด
IdentityProvider.close()
เพื่อปิดกล่องโต้ตอบ
แจ้งให้เบราว์เซอร์ทราบเกี่ยวกับสถานะการเข้าสู่ระบบของผู้ใช้
Login Status API เป็นกลไกที่เว็บไซต์ โดยเฉพาะ IdP จะแจ้งสถานะการเข้าสู่ระบบของผู้ใช้ใน IdP ให้เบราว์เซอร์ทราบ API นี้ช่วยให้เบราว์เซอร์ลดคำขอที่ไม่จำเป็นไปยัง IDP และลดการโจมตีตามช่วงเวลาที่อาจเกิดขึ้น
IdP สามารถส่งสัญญาณสถานะการเข้าสู่ระบบของผู้ใช้ไปยังเบราว์เซอร์โดยการส่งส่วนหัว HTTP หรือโดยการเรียกใช้ JavaScript API เมื่อผู้ใช้ลงชื่อเข้าใช้ IdP หรือเมื่อผู้ใช้ออกจากระบบบัญชี IdP ทั้งหมด สําหรับ IdP แต่ละรายการ (ระบุด้วย URL ของการกำหนดค่า) เบราว์เซอร์จะเก็บตัวแปรแบบ 3 สถานะซึ่งแสดงสถานะการเข้าสู่ระบบไว้โดยมีค่าที่เป็นไปได้ดังนี้
logged-in
logged-out
unknown
(ค่าเริ่มต้น)
สถานะการเข้าสู่ระบบ | คำอธิบาย |
---|---|
logged-in |
เมื่อตั้งค่าสถานะการเข้าสู่ระบบของผู้ใช้เป็น logged-in แล้ว RP ที่เรียกใช้ FedCM จะส่งคำขอไปยังปลายทางบัญชีของ IdP และแสดงบัญชีที่ใช้ได้ต่อผู้ใช้ในกล่องโต้ตอบ FedCM |
logged-out |
เมื่อสถานะการเข้าสู่ระบบของผู้ใช้คือ logged-out การเรียกใช้ FedCM จะดำเนินการไม่สำเร็จโดยไม่มีการส่งคำขอไปยังปลายทางบัญชีของ IdP |
unknown (ค่าเริ่มต้น) |
ระบบจะตั้งค่าสถานะ unknown ก่อนที่ IdP จะส่งสัญญาณโดยใช้ Login Status API เมื่อสถานะเป็น unknown เบราว์เซอร์จะส่งคำขอไปยังปลายทางบัญชีของ IdP และอัปเดตสถานะตามการตอบกลับจากปลายทางบัญชี |
หากต้องการส่งสัญญาณว่าผู้ใช้ลงชื่อเข้าใช้แล้ว ให้ส่งSet-Login: logged-in
ส่วนหัว HTTP
ในการนําทางระดับบนสุดหรือคําขอทรัพยากรย่อยในเว็บไซต์เดียวกันที่ต้นทาง IdP โดยทำดังนี้
Set-Login: logged-in
หรือเรียกใช้เมธอด JavaScript
navigator.login.setStatus('logged-in')
จากต้นทาง IdP ในการนําทางระดับบนสุด ดังนี้
navigator.login.setStatus('logged-in')
ระบบจะตั้งค่าสถานะการเข้าสู่ระบบของผู้ใช้เป็น logged-in
หากต้องการส่งสัญญาณว่าผู้ใช้ออกจากระบบบัญชีทั้งหมดแล้ว ให้ส่งSet-Login: logged-out
ส่วนหัว HTTP ในการนําทางระดับบนสุดหรือคําขอทรัพยากรย่อยในเว็บไซต์เดียวกันที่ต้นทาง IdP โดยทำดังนี้
Set-Login: logged-out
หรือเรียกใช้ JavaScript API navigator.login.setStatus('logged-out')
จากต้นทาง IdP ในการนําทางระดับบนสุดโดยทำดังนี้
navigator.login.setStatus('logged-out')
ระบบจะตั้งค่าสถานะการเข้าสู่ระบบของผู้ใช้เป็น logged-out
ระบบจะตั้งค่าสถานะ unknown
ก่อนที่ IdP จะส่งสัญญาณโดยใช้ Login Status API เบราว์เซอร์ส่งคําขอไปยังปลายทางบัญชีของผู้ให้บริการข้อมูลประจําตัวและอัปเดตสถานะตามคําตอบจากปลายทางบัญชี
- หากปลายทางแสดงรายการบัญชีที่ใช้งานอยู่ ให้อัปเดตสถานะเป็น
logged-in
แล้วเปิดกล่องโต้ตอบ FedCM เพื่อแสดงบัญชีเหล่านั้น - หากปลายทางไม่แสดงบัญชีใดๆ ให้อัปเดตสถานะเป็น
logged-out
และดำเนินการเรียกใช้ FedCM ไม่สำเร็จ
อนุญาตให้ผู้ใช้ลงชื่อเข้าใช้ผ่านขั้นตอนการเข้าสู่ระบบแบบไดนามิก
แม้ว่า IdP จะแจ้งสถานะการเข้าสู่ระบบของผู้ใช้ไปยังเบราว์เซอร์อย่างต่อเนื่อง แต่สถานะดังกล่าวอาจไม่ซิงค์กัน เช่น เมื่อเซสชันหมดอายุ เบราว์เซอร์พยายามส่งคําขอที่มีข้อมูลเข้าสู่ระบบไปยังปลายทางของบัญชีเมื่อสถานะการเข้าสู่ระบบเป็นlogged-in
แต่เซิร์ฟเวอร์ไม่แสดงบัญชีใดๆ เนื่องจากเซสชันไม่พร้อมใช้งานแล้ว ในกรณีเช่นนี้ เบราว์เซอร์จะอนุญาตให้ผู้ใช้ลงชื่อเข้าใช้ IdP ผ่านหน้าต่างป๊อปอัปได้แบบไดนามิก