หน้านี้ได้รับการแปลโดย Cloud Translation API

คู่มือนักพัฒนาซอฟต์แวร์สำหรับ API การจัดการข้อมูลเข้าสู่ระบบแบบรวมศูนย์

ดูวิธีใช้ FedCM ในการรวมศูนย์การรักษาความเป็นส่วนตัว

FedCM (Federated Credential Management) คือวิธีการรักษาความเป็นส่วนตัวของบริการระบุตัวตนแบบรวมศูนย์ (เช่น "ลงชื่อเข้าใช้ด้วย...") ซึ่งผู้ใช้สามารถเข้าสู่ระบบเว็บไซต์ได้โดยไม่ต้องแชร์ข้อมูลส่วนบุคคลกับบริการข้อมูลประจำตัวหรือเว็บไซต์

หากต้องการดูข้อมูลเพิ่มเติมเกี่ยวกับกรณีการใช้งาน การไหลเวียนของผู้ใช้ และแผนงานของ API ของ FedCM โปรดดูข้อมูลเบื้องต้นเกี่ยวกับ FedCM API

สภาพแวดล้อมในการพัฒนาซอฟต์แวร์ FedCM

คุณต้องมีบริบทที่ปลอดภัย (HTTPS หรือ localhost) ทั้งบน IdP และ RP ใน Chrome เพื่อใช้ FedCM

โค้ดแก้ไขข้อบกพร่องใน Chrome ใน Android

ตั้งค่าและเรียกใช้เซิร์ฟเวอร์ในเครื่องเพื่อแก้ไขข้อบกพร่องของโค้ด FedCM คุณเข้าถึงเซิร์ฟเวอร์นี้ได้ใน Chrome บนอุปกรณ์ Android ที่เชื่อมต่อโดยใช้สาย USB ที่มีการส่งต่อพอร์ต

คุณใช้เครื่องมือสำหรับนักพัฒนาเว็บบนเดสก์ท็อปเพื่อแก้ไขข้อบกพร่องของ Chrome ใน Android ได้โดยทำตามวิธีการในหัวข้ออุปกรณ์ Android สำหรับการแก้ไขข้อบกพร่องระยะไกล

บล็อกคุกกี้ของบุคคลที่สามใน Chrome

จำลองการยกเลิกการใช้งานคุกกี้ของบุคคลที่สามโดยการกำหนดค่า Chrome เพื่อบล็อกคุกกี้ของบุคคลที่สาม — จำลองการยกเลิกการใช้งานคุกกี้ของบุคคลที่สามโดยการกำหนดค่า Chrome ให้บล็อกบุคคลที่สาม

คุณสามารถทดสอบวิธีการทำงานของ FedCM โดยไม่ต้องใช้คุกกี้ของบุคคลที่สามใน Chrome ก่อนที่จะบังคับใช้จริง

หากต้องการบล็อกคุกกี้ของบุคคลที่สาม ให้ใช้โหมดไม่ระบุตัวตน หรือเลือก "บล็อกคุกกี้ของบุคคลที่สาม" ในการตั้งค่าเดสก์ท็อปที่ chrome://settings/cookies หรือในอุปกรณ์เคลื่อนที่ โดยไปที่การตั้งค่า > การตั้งค่าเว็บไซต์ > คุกกี้

การใช้ FedCM API

คุณผสานรวมกับ FedCM โดยการสร้างไฟล์ซึ่งเป็นที่รู้จัก ไฟล์การกำหนดค่าและปลายทางสำหรับรายการบัญชี การออกเอกสารรับรอง และข้อมูลเมตาของไคลเอ็นต์ด้วยก็ได้

จากนั้น FedCM จะเปิดเผย JavaScript API ที่ RP สามารถใช้เพื่อลงชื่อเข้าใช้ด้วย IdP

สร้างไฟล์ที่รู้จัก

หากต้องการป้องกันไม่ให้เครื่องมือติดตามใช้ API ในทางที่ผิด คุณจะต้องส่งไฟล์ที่รู้จักจาก /.well-known/web-identity ของ eTLD+1 ของ IdP

เช่น หากปลายทาง IdP ให้บริการภายใต้ https://accounts.idp.example/ อุปกรณ์ปลายทางดังกล่าวต้องแสดงไฟล์ซึ่งเป็นที่รู้จักที่ https://idp.example/.well-known/web-identity รวมถึงไฟล์การกำหนดค่า IdP ต่อไปนี้เป็นตัวอย่างเนื้อหาไฟล์ซึ่งเป็นที่รู้จักกันดี

{
  "provider_urls": ["https://accounts.idp.example/config.json"]
}

ไฟล์ JSON ต้องมีพร็อพเพอร์ตี้ provider_urls ที่มีอาร์เรย์ของ URL ไฟล์การกำหนดค่า IdP ที่ระบุเป็นส่วนหนึ่งของเส้นทางของ configURL ใน navigator.credentials.get ตาม RP จำนวนสตริง URL ในอาร์เรย์ถูกจำกัดไว้ที่ 1 รายการ แต่อาจมีการเปลี่ยนแปลงตามความคิดเห็นของคุณในอนาคต

เคล็ดลับ: เมื่อ FedCM พัฒนา ทดสอบ หรือทดลองใช้โดเมนเซิร์ฟเวอร์ RP อาจเป็นโดเมนย่อยของเซิร์ฟเวอร์ IdP เวอร์ชันที่ใช้งานจริง เช่น เซิร์ฟเวอร์ IdP เวอร์ชันที่ใช้งานจริงจะอยู่ที่ idp.example และทั้งเซิร์ฟเวอร์ RP สำหรับทดลองใช้และเซิร์ฟเวอร์ IdP ของการทดลองใช้จะอยู่ที่ staging.idp.example อย่างไรก็ตาม เนื่องจากไฟล์ที่เป็นที่รู้จักดีจะต้องวางไว้ที่รูทของ eTLD+1 ของเซิร์ฟเวอร์ IdP ไฟล์ดังกล่าวจึงต้องเป็น idp.example/.well-known/web-identity และเป็นเซิร์ฟเวอร์เวอร์ชันที่ใช้งานจริง เนื่องจากนักพัฒนาซอฟต์แวร์ไม่ได้วางไฟล์ในสภาพแวดล้อมการใช้งานจริงระหว่างการพัฒนา นักพัฒนาซอฟต์แวร์จึงทดสอบ FedCM ไม่ได้ หากโดเมน RP และโดเมน IdP เหมือนกัน Chrome จะข้ามการตรวจสอบไฟล์ที่รู้จักกันดีได้ตั้งแต่ Chrome 122 เป็นต้นไป คุณยังสามารถข้ามการตรวจสอบ configURL ได้โดยเปิดใช้แฟล็ก chrome://flags#fedcm-without-well-known-enforcement ซึ่งจะเป็นประโยชน์เมื่อสภาพแวดล้อมในการพัฒนาซอฟต์แวร์ของคุณใช้ DNS ที่ไม่สามารถเข้าถึงได้แบบสาธารณะ

สร้างไฟล์การกำหนดค่า IdP และปลายทาง

โดยไฟล์การกำหนดค่า IdP จะแสดงรายการปลายทางที่จำเป็นสำหรับเบราว์เซอร์ IdP จะโฮสต์ไฟล์การกำหนดค่านี้ รวมถึงปลายทางและ URL ที่จำเป็น การตอบสนอง JSON ทั้งหมดต้องแสดงด้วย content-type 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;

ระบุ URL แบบเต็มของตำแหน่งไฟล์การกำหนดค่า IdP เป็น configURL เมื่อมีการเรียก navigator.credentials.get() ใน RP เบราว์เซอร์จะดึงข้อมูลไฟล์การกำหนดค่าที่มีคำขอ GET โดยไม่มีส่วนหัว Origin หรือส่วนหัว Referer คำขอไม่มีคุกกี้และไม่ติดตามการเปลี่ยนเส้นทาง วิธีนี้จะป้องกันไม่ให้ IdP เรียนรู้ว่าใครเป็นผู้ส่งคำขอและ RP ใดกำลังพยายามเชื่อมต่อ เช่น

GET /config.json HTTP/1.1
Host: accounts.idp.example
Accept: application/json
Sec-Fetch-Dest: webidentity

ข้อควรระวัง: คำขอทั้งหมดที่ส่งจากเบราว์เซอร์โดยใช้ FedCM จะมีส่วนหัว Sec-Fetch-Dest: webidentity เพื่อป้องกันการโจมตี CSRF อุปกรณ์ปลายทาง IdP ต่อไปนี้ต้องยืนยันว่ามีส่วนหัวนี้รวมอยู่ด้วย

ปลายทางบัญชี
ปลายทางการยืนยันรหัส
ยกเลิกการเชื่อมต่อปลายทาง

เบราว์เซอร์ต้องการการตอบสนอง JSON จาก IdP ซึ่งมีพร็อพเพอร์ตี้ต่อไปนี้

พร็อพเพอร์ตี้	คำอธิบาย
`accounts_endpoint` (ต้องระบุ)	URL สำหรับปลายทางของบัญชี
`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 รายการ ดังนี้ `url` (ต้องระบุ): URL ของรูปภาพไอคอน ส่วนนี้ไม่รองรับรูปภาพ SVG `size` (ไม่บังคับ): ขนาดไอคอนที่แอปพลิเคชันสันนิษฐานว่าเป็นรูปสี่เหลี่ยมจัตุรัสและความละเอียดเดียว จำนวนนี้ต้องมากกว่าหรือเท่ากับ 25

RP สามารถแก้ไขสตริงใน UI ของกล่องโต้ตอบ FedCM ผ่านค่า identity.context สำหรับ navigator.credentials.get() เพื่อรองรับบริบทการตรวจสอบสิทธิ์ที่กำหนดไว้ล่วงหน้า พร็อพเพอร์ตี้ที่ไม่บังคับอาจเป็น "signin" (ค่าเริ่มต้น), "signup", "use" หรือ "continue"

วิธีใช้การสร้างแบรนด์กับกล่องโต้ตอบของ FedCM

ต่อไปนี้คือตัวอย่างเนื้อหาการตอบสนองจาก IdP

{
  "accounts_endpoint": "/accounts.php",
  "client_metadata_endpoint": "/client_metadata.php",
  "id_assertion_endpoint": "/assertion.php",
  "disconnect_endpoint": "/disconnect.php",
  "login_url": "/login",
  "branding": {
    "background_color": "green",
    "color": "#FFEEAA",
    "icons": [{
      "url": "https://idp.example/icon.ico",
      "size": 25
    }]
  }
}

เมื่อดึงไฟล์การกำหนดค่าแล้ว เบราว์เซอร์จะส่งคำขอถัดไปไปยังปลายทาง IdP ดังต่อไปนี้

ปลายทางบัญชี

ปลายทางของบัญชี IdP จะแสดงรายการบัญชีที่ผู้ใช้ลงชื่อเข้าใช้อยู่ใน IdP หาก IdP รองรับหลายบัญชี ปลายทางนี้จะแสดงบัญชีที่ลงชื่อเข้าใช้ไว้ทั้งหมด

เบราว์เซอร์จะส่งคำขอ GET ที่มีคุกกี้ที่มี SameSite=None แต่ไม่มีพารามิเตอร์ client_id, ส่วนหัว Origin หรือส่วนหัว Referer วิธีนี้จะป้องกันไม่ให้ IdP เรียนรู้ว่าผู้ใช้พยายามลงชื่อเข้าใช้ด้วย RP ใด เช่น

GET /accounts.php HTTP/1.1
Host: accounts.idp.example
Accept: application/json
Cookie: 0x23223
Sec-Fetch-Dest: webidentity

เมื่อได้รับคำขอ เซิร์ฟเวอร์ควรทำดังนี้

ตรวจสอบว่าคำขอมีส่วนหัว HTTP ของ Sec-Fetch-Dest: webidentity
จับคู่คุกกี้เซสชันกับ ID ของบัญชีที่ลงชื่อเข้าใช้อยู่แล้ว
ตอบกลับด้วยรายชื่อบัญชี

เบราว์เซอร์ต้องการการตอบกลับ 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` เพื่อกรองบัญชี

ตัวอย่างเนื้อหาคำตอบ

{
  "accounts": [{
    "id": "1234",
    "given_name": "John",
    "name": "John Doe",
    "email": "john_doe@idp.example",
    "picture": "https://idp.example/profile/123",
    "approved_clients": ["123", "456", "789"],
    "login_hints": ["demo1", "demo1@idp.example"]
  }, {
    "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", "demo2@idp.example"],
    "domain_hints": ["corp.example"]
  }]
}

หากผู้ใช้ไม่ได้ลงชื่อเข้าใช้ ให้ตอบกลับด้วย HTTP 401 (ไม่ได้รับอนุญาต)

เบราว์เซอร์จะใช้รายการบัญชีที่ส่งคืนและจะไม่พร้อมใช้งานสำหรับ RP

ปลายทางข้อมูลเมตาของไคลเอ็นต์

ปลายทางข้อมูลเมตาไคลเอ็นต์ของ IdP จะแสดงข้อมูลเมตาของฝ่ายที่เกี่ยวข้อง เช่น นโยบายความเป็นส่วนตัวและข้อกำหนดในการให้บริการของ RP RP ควรแจ้งลิงก์ไปยังนโยบายความเป็นส่วนตัวและข้อกำหนดในการให้บริการแก่ IdP ล่วงหน้า โดยลิงก์เหล่านี้จะแสดงในกล่องโต้ตอบการลงชื่อเข้าใช้เมื่อผู้ใช้ยังไม่ได้ลงทะเบียนใน RP ด้วย IdP

เบราว์เซอร์จะส่งคำขอ GET โดยใช้ client_id navigator.credentials.get โดยไม่มีคุกกี้ เช่น

GET /client_metadata.php?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

เบราว์เซอร์ต้องการการตอบสนอง JSON จากปลายทาง:

{
  "privacy_policy_url": "https://rp.example/privacy_policy.html",
  "terms_of_service_url": "https://rp.example/terms_of_service.html",
}

เบราว์เซอร์จะใช้ข้อมูลเมตาของไคลเอ็นต์ที่ส่งกลับและ RP จะใช้งานกับ RP ไม่ได้

ปลายทางการยืนยันรหัส

ปลายทางการยืนยันรหัสของ IdP จะแสดงการยืนยันสำหรับผู้ใช้ที่ลงชื่อเข้าใช้ เมื่อผู้ใช้ลงชื่อเข้าใช้เว็บไซต์ RP โดยใช้การเรียกใช้ navigator.credentials.get() เบราว์เซอร์จะส่งคำขอ POST ที่มีคุกกี้ที่มี SameSite=None และประเภทเนื้อหา application/x-www-form-urlencoded ไปยังปลายทางนี้พร้อมด้วยข้อมูลต่อไปนี้

พร็อพเพอร์ตี้	คำอธิบาย
`client_id` (ต้องระบุ)	ตัวระบุลูกค้าของ RP
`account_id` (ต้องระบุ)	รหัสที่ไม่ซ้ำกันของผู้ใช้ที่ลงชื่อเข้าใช้
`nonce` (ไม่บังคับ)	ค่า Nonce ของคำขอมาจาก RP
`disclosure_text_shown`	ผลลัพธ์ในสตริง `"true"` หรือ `"false"` (แทนที่จะเป็นบูลีน) ผลลัพธ์จะเป็น `"false"` หากไม่มีการแสดงข้อความการเปิดเผย กรณีนี้จะเกิดขึ้นเมื่อมีการรวมรหัสไคลเอ็นต์ของ RP ไว้ในรายการพร็อพเพอร์ตี้ `approved_clients` ของการตอบกลับจากอุปกรณ์ปลายทางของบัญชี หรือหากเบราว์เซอร์สังเกตเห็นช่วงเวลาลงชื่อสมัครใช้ในอดีตโดยที่ไม่มี `approved_clients`
`is_auto_selected`	ถ้ามีการตรวจสอบสิทธิ์ซ้ำอัตโนมัติใน RP นั้น `is_auto_selected` จะระบุเป็น `"true"` หรือ`"false"` ซึ่งจะช่วยให้รองรับฟีเจอร์ที่เกี่ยวข้องกับความปลอดภัยได้มากขึ้น เช่น ผู้ใช้บางรายอาจต้องการระดับความปลอดภัยที่สูงขึ้น ซึ่งต้องใช้สื่อกลางผู้ใช้ที่ชัดเจนในการตรวจสอบสิทธิ์ หาก IdP ได้รับคำขอโทเค็นโดยไม่มีสื่อกลางดังกล่าว IdP อาจจัดการคำขอในแบบที่ต่างออกไป เช่น แสดงผลรหัสข้อผิดพลาดเพื่อให้ RP สามารถเรียก FedCM API อีกครั้งด้วย `mediation: required`

ตัวอย่างส่วนหัว HTTP

POST /assertion.php HTTP/1.1
Host: accounts.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=Ct60bD&disclosure_text_shown=true&is_auto_selected=true

เมื่อได้รับคำขอ เซิร์ฟเวอร์ควรทำดังนี้

ตอบกลับคำขอด้วย CORS (กลไกการแชร์ทรัพยากรข้ามโดเมน)
ตรวจสอบว่าคำขอมีส่วนหัว HTTP ของ Sec-Fetch-Dest: webidentity
จับคู่ส่วนหัว Origin กับต้นทาง RP ที่ client_id กำหนด ให้ปฏิเสธหากข้อมูลไม่ตรงกัน
จับคู่ account_id กับรหัสของบัญชีที่ลงชื่อเข้าใช้แล้ว ให้ปฏิเสธหากข้อมูลไม่ตรงกัน
ตอบกลับด้วยโทเค็น หากคำขอถูกปฏิเสธ ให้ตอบกลับด้วยการตอบกลับข้อผิดพลาด

คำเตือน: คำขอ CORS ต้องเป็นข้อมูลเข้าสู่ระบบ ซึ่งหมายความว่าส่วนหัวการตอบกลับ Access-Control-Allow-Origin ต้อง ระบุต้นทางที่ชัดเจน แทนการใช้ไวลด์การ์ดโดยใช้ "*"

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

วิธีออกโทเค็นจะขึ้นอยู่กับ IdP แต่โดยทั่วไปโทเค็นจะลงนามด้วยข้อมูล เช่น รหัสบัญชี รหัสไคลเอ็นต์ ต้นทางของผู้ออก nonce เพื่อให้ RP ยืนยันได้ว่าโทเค็นนั้นเป็นของแท้

เบราว์เซอร์ต้องการการตอบสนอง JSON ที่มีพร็อพเพอร์ตี้ต่อไปนี้

พร็อพเพอร์ตี้	คำอธิบาย
`token` (ต้องระบุ)	โทเค็นเป็นสตริงที่มีการอ้างสิทธิ์เกี่ยวกับการตรวจสอบสิทธิ์

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

เบราว์เซอร์จะส่งโทเค็นที่ส่งกลับไปให้ RP เพื่อให้ RP ตรวจสอบการตรวจสอบสิทธิ์ได้

แสดงการตอบกลับข้อผิดพลาด

id_assertion_endpoint ยังแสดงผลการตอบกลับ "ข้อผิดพลาด" ได้ด้วย ซึ่งมีช่องที่ไม่บังคับ 2 ช่องดังนี้

code: IdP สามารถเลือกข้อผิดพลาดที่ทราบแล้วรายการใดรายการหนึ่งจากรายการข้อผิดพลาดที่ระบุของ OAuth 2.0 (invalid_request, unauthorized_client, access_denied, server_error และtemporarily_unavailable) หรือใช้สตริงที่กำหนดเอง หากเป็นกรณีหลัง Chrome จะแสดงผล UI ข้อผิดพลาดพร้อมข้อความแสดงข้อผิดพลาดทั่วไปและส่งรหัสไปยัง RP
url: ระบุหน้าเว็บที่มนุษย์อ่านได้ซึ่งมีข้อมูลเกี่ยวกับข้อผิดพลาดเพื่อให้ข้อมูลเพิ่มเติมเกี่ยวกับข้อผิดพลาดแก่ผู้ใช้ ช่องนี้มีประโยชน์ต่อผู้ใช้เนื่องจากเบราว์เซอร์แสดงข้อความแสดงข้อผิดพลาดที่สมบูรณ์ใน UI เนทีฟไม่ได้ เช่น ลิงก์สำหรับขั้นตอนถัดไป ข้อมูลติดต่อ ของฝ่ายบริการลูกค้า และอื่นๆ หากผู้ใช้ต้องการดูข้อมูลเพิ่มเติมเกี่ยวกับรายละเอียดข้อผิดพลาดและวิธีแก้ไข ก็สามารถดูรายละเอียดเพิ่มเติมได้ที่หน้าที่ระบุจาก UI ของเบราว์เซอร์ URL ต้องเป็นของเว็บไซต์เดียวกับ IdP configURL

// id_assertion_endpoint response
{
  "error" : {
     "code": "access_denied",
     "url" : "https://idp.example/error?type=access_denied"
  }
}

ยกเลิกการเชื่อมต่อปลายทาง

เมื่อเรียกใช้ IdentityCredential.disconnect() เบราว์เซอร์จะส่งคำขอ POST แบบข้ามต้นทางพร้อมคุกกี้ที่มี SameSite=None และประเภทเนื้อหาของ application/x-www-form-urlencoded ไปยังปลายทางการยกเลิกการเชื่อมต่อนี้พร้อมด้วยข้อมูลต่อไปนี้

พร็อพเพอร์ตี้	คำอธิบาย
`account_hint`	คำแนะนำสำหรับบัญชี IdP
`client_id`	ตัวระบุลูกค้าของ RP

POST /disconnect.php 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 (กลไกการแชร์ทรัพยากรข้ามโดเมน)
ตรวจสอบว่าคำขอมีส่วนหัว HTTP ของ Sec-Fetch-Dest: webidentity
จับคู่ส่วนหัว Origin กับต้นทาง RP ที่ client_id กำหนด ให้ปฏิเสธหากข้อมูลไม่ตรงกัน
จับคู่ account_hint กับรหัสของบัญชีที่ลงชื่อเข้าใช้อยู่แล้ว
ยกเลิกการเชื่อมต่อบัญชีผู้ใช้จาก RP
ตอบกลับเบราว์เซอร์ด้วยข้อมูลบัญชีผู้ใช้ที่ระบุในรูปแบบ JSON

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

ตัวอย่างเพย์โหลด JSON ของการตอบกลับจะมีลักษณะดังนี้

{
  "account_id": "account456"
}

แต่หาก IdP ต้องการให้เบราว์เซอร์ยกเลิกการเชื่อมต่อบัญชีทั้งหมดที่เชื่อมโยงกับ RP แทน ให้ส่งสตริงที่ไม่ตรงกับรหัสบัญชีใดๆ เช่น "*"

เมื่อใช้ API สถานะการเข้าสู่ระบบ IdP ต้องแจ้งสถานะการเข้าสู่ระบบของผู้ใช้ให้เบราว์เซอร์ทราบ แต่สถานะอาจไม่ซิงค์กัน เช่น เมื่อเซสชันหมดอายุ ในสถานการณ์เช่นนี้ เบราว์เซอร์จะอนุญาตให้ผู้ใช้ลงชื่อเข้าใช้ IdP ในแบบไดนามิกผ่าน URL ของหน้าเข้าสู่ระบบที่ระบุด้วย login_url ของ idp config

กล่องโต้ตอบ FedCM จะแสดงข้อความที่แนะนำการลงชื่อเข้าใช้ตามที่แสดงในภาพต่อไปนี้

กล่องโต้ตอบของ FedCM ที่แนะนำให้ลงชื่อเข้าใช้ IdP

เมื่อผู้ใช้คลิกปุ่มดำเนินการต่อ เบราว์เซอร์จะเปิดหน้าต่างป๊อปอัปสำหรับหน้าการเข้าสู่ระบบของ IdP

ตัวอย่างกล่องโต้ตอบที่แสดงหลังจากคลิกลงชื่อเข้าใช้ปุ่ม IdP

กล่องโต้ตอบคือหน้าต่างเบราว์เซอร์ปกติที่มีคุกกี้ของบุคคลที่หนึ่ง สิ่งที่เกิดขึ้นภายในกล่องโต้ตอบจะขึ้นอยู่กับ IdP และไม่มีแฮนเดิลหน้าต่างสำหรับส่งคำขอการสื่อสารแบบข้ามต้นทางไปยังหน้า RP หลังจากที่ผู้ใช้ลงชื่อเข้าใช้แล้ว IdP ควรทำดังนี้

ส่งส่วนหัว Set-Login: logged-in หรือเรียกใช้ navigator.login.setStatus("logged-in") API เพื่อแจ้งให้เบราว์เซอร์ทราบว่าผู้ใช้ลงชื่อเข้าใช้แล้ว
โทรหา IdentityProvider.close() เพื่อปิดกล่องโต้ตอบ

ผู้ใช้ลงชื่อเข้าใช้ RP หลังจากลงชื่อเข้าใช้ IdP โดยใช้ FedCM

API สถานะการเข้าสู่ระบบเป็นกลไกที่เว็บไซต์ โดยเฉพาะ IdP จะแจ้งสถานะการเข้าสู่ระบบของผู้ใช้บน IdP ให้กับเบราว์เซอร์ เมื่อใช้ API นี้ เบราว์เซอร์จะลดคำขอที่ไม่จำเป็นที่ส่งไปยัง IdP และลดการโจมตีในเวลาที่อาจเกิดขึ้น

หมายเหตุ: FedCM แนะนำคำขอข้อมูลเข้าสู่ระบบไปยังปลายทางรายการบัญชี คําขอนี้ไม่ได้ส่งข้อมูลที่ระบุตัวผู้ขอและไม่อนุญาตให้ส่งผ่านข้อมูลที่ได้จาก RP เบราว์เซอร์จะดำเนินการตามคำขอที่ไม่มีข้อมูลเข้าสู่ระบบซึ่งมีข้อมูล RP ไปยัง client_metadata_endpoint ดังนั้นเซิร์ฟเวอร์ IdP จะเชื่อมโยงคำขอที่ไม่มีข้อมูลเข้าสู่ระบบกับคำขอข้อมูลเข้าสู่ระบบ (ตามลำดับ) โดยใช้การประทับเวลาหรือข้อมูลลายนิ้วมืออื่นๆ ได้ อ่านรายละเอียดเพิ่มเติมได้ที่ GitHub

IdP จะส่งสัญญาณสถานะการเข้าสู่ระบบของผู้ใช้ไปยังเบราว์เซอร์ได้โดยการส่งส่วนหัว HTTP หรือเรียกใช้ JavaScript API เมื่อผู้ใช้ลงชื่อเข้าใช้ใน IdP หรือเมื่อผู้ใช้ออกจากระบบบัญชี IdP ทั้งหมด สำหรับ IdP แต่ละรายการ (ระบุโดย URL การกำหนดค่า) เบราว์เซอร์จะเก็บตัวแปร Tri-state ที่แสดงสถานะการเข้าสู่ระบบซึ่งมีค่าที่เป็นไปได้ logged-in, logged-out และ unknown สถานะเริ่มต้นคือ unknown

หากต้องการส่งสัญญาณว่าผู้ใช้ลงชื่อเข้าใช้อยู่ ให้ส่งส่วนหัว HTTP ของ Set-Login: logged-in ในการนำทางระดับบนสุดหรือคำขอทรัพยากรย่อยในเว็บไซต์เดียวกันที่ต้นทาง IdP โดยดำเนินการดังนี้

Set-Login: logged-in

หรือเรียกใช้ JavaScript API navigator.login.setStatus("logged-in") จากต้นทาง IdP ในการนําทางระดับบนสุด ดังนี้

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

การโทรเหล่านี้จะบันทึกสถานะการเข้าสู่ระบบของผู้ใช้เป็น logged-in เมื่อตั้งค่าสถานะการเข้าสู่ระบบของผู้ใช้เป็น logged-in ทาง RP ที่โทรหา FedCM จะส่งคำขอไปยังปลายทางบัญชีของ IdP และแสดงบัญชีที่พร้อมใช้งานแก่ผู้ใช้ในกล่องโต้ตอบของ FedCM

หากต้องการส่งสัญญาณว่าผู้ใช้ออกจากระบบทุกบัญชีแล้ว ให้ส่งส่วนหัว HTTP ของ Set-Login: logged-out ในการนำทางระดับบนสุดหรือคำขอทรัพยากรย่อยในเว็บไซต์เดียวกันที่ต้นทาง IdP โดยดำเนินการดังนี้

Set-Login: logged-out

หรือเรียกใช้ JavaScript API navigator.login.setStatus("logged-out") จากต้นทาง IdP ในการนําทางระดับบนสุด ดังนี้

navigator.login.setStatus("logged-out")

การโทรเหล่านี้จะบันทึกสถานะการเข้าสู่ระบบของผู้ใช้เป็น logged-out เมื่อสถานะการเข้าสู่ระบบของผู้ใช้คือ logged-out การเรียกใช้ FedCM จะล้มเหลวโดยไม่ส่งคำขอไปยังปลายทางบัญชีของ IdP

ระบบจะตั้งค่าสถานะ unknown ก่อนที่ IdP จะส่งสัญญาณโดยใช้ API สถานะการเข้าสู่ระบบ เราแนะนำ Unknown เพื่อการเปลี่ยนรุ่นที่ดียิ่งขึ้น เนื่องจากผู้ใช้อาจลงชื่อเข้าใช้ IdP อยู่แล้วในตอนที่จัดส่ง API นี้ IdP อาจไม่มีโอกาสส่งสัญญาณนี้ไปยังเบราว์เซอร์เมื่อมีการเรียกใช้ FedCM เป็นครั้งแรก ในกรณีนี้ Chrome จะส่งคำขอไปยังปลายทางบัญชีของ IdP และอัปเดตสถานะตามการตอบสนองจากปลายทางบัญชี ดังนี้

หากปลายทางแสดงรายการบัญชีที่ใช้งานอยู่ ให้อัปเดตสถานะเป็น logged-in แล้วเปิดกล่องโต้ตอบ FedCM เพื่อแสดงบัญชีเหล่านั้น
หากปลายทางไม่พบบัญชี ให้อัปเดตสถานะเป็น logged-out ทำให้การเรียก FedCM ไม่สำเร็จ

หมายเหตุ: ส่วนหัวสถานะการเข้าสู่ระบบสามารถส่งจากแหล่งข้อมูลย่อยของเว็บไซต์เดียวกันได้เช่นกัน โดยเริ่มจาก Chrome 122 ซึ่งจะเป็นประโยชน์ เช่น เมื่อเว็บไซต์ที่อนุญาตให้ผู้ใช้ป้อนชื่อผู้ใช้และรหัสผ่านใน idp.example แต่โพสต์ข้อมูลเข้าสู่ระบบไปยัง login.idp.example ด้วย fetch() การตอบกลับการดึงข้อมูลจาก login.idp.example ยังตั้งค่าสถานะการเข้าสู่ระบบสำหรับ idp.example ได้โดยการส่งส่วนหัว HTTP Set-Login: logged-in

อนุญาตให้ผู้ใช้ลงชื่อเข้าใช้ผ่านขั้นตอนการเข้าสู่ระบบแบบไดนามิก

แม้ว่า IdP จะให้ข้อมูลสถานะการเข้าสู่ระบบของผู้ใช้แก่เบราว์เซอร์อยู่เสมอ แต่ระบบอาจไม่ซิงค์กัน เช่น เมื่อเซสชันหมดอายุ เบราว์เซอร์จะพยายามส่งคำขอที่มีข้อมูลเข้าสู่ระบบไปยังปลายทางบัญชีเมื่อสถานะการเข้าสู่ระบบคือ logged-in แต่เซิร์ฟเวอร์ไม่ส่งกลับบัญชีเนื่องจากเซสชันไม่พร้อมใช้งานอีกต่อไป ในสถานการณ์เช่นนี้ เบราว์เซอร์จะอนุญาตให้ผู้ใช้ลงชื่อเข้าใช้ IdP ได้แบบไดนามิกผ่านหน้าต่างป๊อปอัป

ประสบการณ์การเข้าสู่ระบบแบบไดนามิกนี้มีไว้สำหรับตอนที่เซสชัน IdP หมดอายุลงโดยไม่มีการออกจากระบบอย่างชัดแจ้ง ซึ่งทำให้สถานะการเข้าสู่ระบบของเบราว์เซอร์ขัดแย้งกับสถานะจริงของผู้ใช้ แต่จะไม่ทริกเกอร์สําหรับผู้ใช้ที่ยังไม่ได้ลงชื่อเข้าใช้ IdP ขั้นตอนนี้ออกแบบมาเพื่อครอบคลุมกรณีที่สถานะการเข้าสู่ระบบ IdP ของผู้ใช้ในเบราว์เซอร์คือ logged-in แต่ accounts destination ของ IdP จะไม่แสดงบัญชี สมมติว่า API สถานะการเข้าสู่ระบบถูกเรียกใช้ทันทีเมื่อมีการเรียกใช้ FedCM สถานการณ์ใดกรณีหนึ่งต่อไปนี้อาจเกิดขึ้น

หากตั้งค่าสถานะการเข้าสู่ระบบของผู้ใช้เป็น "ไม่ทราบ" ระบบจะอัปเดตสถานะ (logged-in หรือ logged-out) ตามการตอบสนองของ IdP จากปลายทางของบัญชี ระบบจะไม่ทริกเกอร์ขั้นตอนการเข้าสู่ระบบแบบไดนามิก
หากผู้ใช้ลงชื่อเข้าใช้ IdP ในเบราว์เซอร์แล้วออกจากระบบ IdP ด้วยตนเอง ระบบจะไม่ทริกเกอร์ขั้นตอนการเข้าสู่ระบบแบบไดนามิก
หากผู้ใช้ลงชื่อเข้าใช้ IdP ในเบราว์เซอร์ แต่เซสชันหมดอายุโดยไม่มีการอัปเดต logged-out อย่างชัดเจน ระบบจะเรียกใช้ขั้นตอนการเข้าสู่ระบบแบบไดนามิก

API สถานะการเข้าสู่ระบบไม่ได้ช่วยให้ RP แสดงกล่องโต้ตอบ "ลงชื่อเข้าใช้ IdP" แก่ผู้ใช้ที่ไม่ได้ลงชื่อเข้าใช้ IdP ได้ ซึ่งเป็นฟีเจอร์แยกต่างหากซึ่งอาจเพิ่มเข้ามาในอนาคต

ลงชื่อเข้าใช้บุคคลที่ต้องพึ่งพาผู้ให้บริการข้อมูลประจำตัว

เมื่อการกำหนดค่าและปลายทางของ IdP พร้อมใช้งานแล้ว RP จะเรียกใช้ navigator.credentials.get() เพื่อขออนุญาตให้ผู้ใช้ลงชื่อเข้าใช้ RP ด้วย IdP ได้

ก่อนเรียก API คุณต้องยืนยันว่า [FedCM พร้อมใช้งานบนเบราว์เซอร์ของผู้ใช้] หากต้องการตรวจสอบว่า FedCM พร้อมให้บริการหรือไม่ ให้ใส่โค้ดต่อไปนี้ไว้กับการใช้งาน FedCM

if ('IdentityCredential' in window) {
  // If the feature is available, take action
}

หากต้องการอนุญาตให้ผู้ใช้ลงชื่อเข้าใช้ IdP จาก RP ให้ดำเนินการดังนี้

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

พร็อพเพอร์ตี้ providers ใช้อาร์เรย์ของออบเจ็กต์ IdentityProvider ที่มีพร็อพเพอร์ตี้ต่อไปนี้

พร็อพเพอร์ตี้	คำอธิบาย
`configURL` (ต้องระบุ)	เส้นทางแบบเต็มของไฟล์การกำหนดค่า IdP
`clientId` (ต้องระบุ)	ตัวระบุไคลเอ็นต์ของ RP ที่ออกโดย IdP
`nonce` (ไม่บังคับ)	สตริงแบบสุ่มเพื่อให้แน่ใจว่าจะมีการตอบสนองคำขอที่เจาะจงนี้ ป้องกันการโจมตีจากการเล่นซ้ำ
`loginHint` (ไม่บังคับ)	การระบุค่าใดค่าหนึ่งจาก `login_hints` ที่ได้จากปลายทางของบัญชีจะทำให้กล่องโต้ตอบ FedCM เลือกแสดงบัญชีที่ระบุ
`domainHint` (ไม่บังคับ)	การระบุค่าใดค่าหนึ่งจาก `domain_hints` ที่ได้จากปลายทางของบัญชีจะทำให้กล่องโต้ตอบของ FedCM เลือกแสดงบัญชีที่ระบุ

เบราว์เซอร์จะจัดการกับกรณีการใช้งานการลงชื่อสมัครใช้และการลงชื่อเข้าใช้แตกต่างกันไปตามการมีอยู่ของ approved_clients ในการตอบกลับจากปลายทางของรายการบัญชี เบราว์เซอร์จะไม่แสดงข้อความเปิดเผย "ใช้ ...." ต่อหากผู้ใช้ลงชื่อสมัครใช้ RP แล้ว

ขั้นตอนการลงชื่อสมัครใช้จะพิจารณาจากเงื่อนไขต่อไปนี้ว่าเป็นไปตามเงื่อนไขต่อไปนี้หรือไม่

หาก approved_clients มี clientId ของ RP
หากเบราว์เซอร์จำได้ว่าผู้ใช้ได้ลงชื่อสมัครใช้ RP ไว้แล้ว

ผู้ใช้ลงชื่อเข้าใช้ RP โดยใช้ FedCM

เมื่อ RP เรียกใช้ navigator.credentials.get() ระบบจะทำกิจกรรมต่อไปนี้

เบราว์เซอร์จะส่งคำขอและดึงเอกสารหลายรายการ ดังนี้
1. ไฟล์ที่รู้จักกันดีและไฟล์การกำหนดค่า IdP ซึ่งประกาศปลายทาง
2. รายการบัญชี
3. ไม่บังคับ: URL สำหรับนโยบายความเป็นส่วนตัวและข้อกำหนดในการให้บริการของ RP ที่ดึงมาจากปลายทางข้อมูลเมตาของไคลเอ็นต์
เบราว์เซอร์จะแสดงรายการบัญชีที่ผู้ใช้สามารถใช้เพื่อลงชื่อเข้าใช้ รวมถึงข้อกำหนดในการให้บริการและนโยบายความเป็นส่วนตัว หากมี
เมื่อผู้ใช้เลือกบัญชีที่จะลงชื่อเข้าใช้แล้ว ระบบจะส่งคำขอไปยังปลายทางการยืนยันรหัสไปยัง IdP เพื่อเรียกข้อมูลโทเค็น
ซึ่ง RP จะตรวจสอบโทเค็นเพื่อตรวจสอบสิทธิ์ผู้ใช้ได้

ข้อควรระวัง: FedCM ออกแบบมาไม่ให้แจ้ง RP เกี่ยวกับสถานะการลงชื่อเข้าใช้ IdP ของผู้ใช้จนกว่าผู้ใช้จะยืนยันอย่างชัดแจ้งให้ดำเนินการต่อในชื่อและลงชื่อเข้าใช้ ซึ่งหมายความว่า RP จะไม่ได้รับแจ้งเกี่ยวกับการเชื่อมต่อกับ FedCM API หากผู้ใช้ไม่ได้ลงชื่อเข้าใช้ IdP, ปลายทางบัญชีแสดงรายการที่ว่างเปล่า หรือปลายทางแสดงผลข้อผิดพลาด

เราคาดหวังว่า RP จะต้องรองรับเบราว์เซอร์ที่ไม่รองรับ FedCM ผู้ใช้จึงควรใช้กระบวนการลงชื่อเข้าใช้ที่มีอยู่แล้วซึ่งไม่ใช่ FedCM ได้ เรื่องนี้จะไม่เป็นปัญหาจนกว่าคุกกี้ของบุคคลที่สามจะเลิกใช้งานอย่างสมบูรณ์

เมื่อเซิร์ฟเวอร์ RP ตรวจสอบโทเค็นแล้ว RP อาจลงทะเบียนผู้ใช้หรืออนุญาตให้ผู้ใช้ลงชื่อเข้าใช้และเริ่มเซสชันใหม่

หลังจากที่ผู้ใช้ลงชื่อเข้าใช้ บางครั้งฝ่ายที่ต้องพึ่งพา (RP) จะขอให้ผู้ใช้ตรวจสอบสิทธิ์อีกครั้ง แต่ผู้ใช้อาจไม่แน่ใจว่ากำลังใช้บัญชีใดอยู่ หาก RP สามารถระบุบัญชีที่จะลงชื่อเข้าใช้ ผู้ใช้ก็จะเลือกบัญชีได้ง่ายขึ้น

RP สามารถเลือกแสดงบัญชีหนึ่งๆ ได้โดยเรียกใช้ navigator.credentials.get() ด้วยพร็อพเพอร์ตี้ loginHint ที่มีค่าใดค่าหนึ่งจาก login_hints ที่ดึงข้อมูลจากปลายทางของรายการบัญชี ดังที่แสดงในตัวอย่างโค้ดต่อไปนี้

return await navigator.credentials.get({
  identity: {
    providers: [{
      configURL: "https://idp.example/manifest.json",
      clientId: "123",
      nonce: nonce,
      loginHint : "demo1@example.com"
    }]
  }
});

เมื่อไม่มีบัญชีที่ตรงกับ loginHint กล่องโต้ตอบ FedCM จะแสดงข้อความแจ้งให้เข้าสู่ระบบ ซึ่งช่วยให้ผู้ใช้เข้าสู่ระบบบัญชี IdP ที่ตรงกับคำแนะนำที่ RP ขอได้ เมื่อผู้ใช้แตะข้อความแจ้ง หน้าต่างป๊อปอัปจะเปิดขึ้นพร้อม URL การเข้าสู่ระบบที่ระบุไว้ในไฟล์การกำหนดค่า จากนั้นลิงก์จะต่อท้ายด้วยคำแนะนำในการเข้าสู่ระบบและพารามิเตอร์การค้นหาของคำแนะนำโดเมน

API คำแนะนำโดเมน

มีบางกรณีที่ RP ทราบอยู่แล้วว่ามีเพียงบัญชีที่เชื่อมโยงกับบางโดเมนเท่านั้นที่ได้รับอนุญาตให้เข้าสู่ระบบเว็บไซต์ กรณีนี้พบได้บ่อยในสถานการณ์ขององค์กรที่เว็บไซต์ที่เข้าถึงอยู่จะจำกัดเฉพาะโดเมนของบริษัทเท่านั้น เพื่อให้ผู้ใช้ได้รับประสบการณ์ที่ดียิ่งขึ้น FedCM API จึงอนุญาตให้ RP แสดงเฉพาะบัญชีที่อาจใช้เพื่อเข้าสู่ระบบ RP ได้ ซึ่งเป็นการป้องกันสถานการณ์ที่ผู้ใช้พยายามเข้าสู่ระบบ RP โดยใช้บัญชีภายนอกโดเมนของบริษัท เพียงได้รับข้อความแสดงข้อผิดพลาดในภายหลัง (หรือการปิดเสียงในกรณีที่การเข้าสู่ระบบไม่ทำงาน) เนื่องจากไม่ได้ใช้ประเภทบัญชีที่ถูกต้อง

RP สามารถเลือกแสดงเฉพาะบัญชีที่ตรงกันโดยเรียกใช้ navigator.credentials.get() ด้วยพร็อพเพอร์ตี้ domainHint ที่มีค่าใดค่าหนึ่งจาก domain_hints ที่ดึงข้อมูลจากปลายทางของรายการบัญชี ดังที่แสดงในตัวอย่างโค้ดต่อไปนี้

return await navigator.credentials.get({
  identity: {
    providers: [{
      configURL: "https://idp.example/manifest.json",
      clientId: "abc",
      nonce: nonce,
      domainHint : "corp.example"
    }]
  }
});

หมายเหตุ: เมื่อใช้ domainHint: "any" Chrome จะกรองบัญชีที่ไม่มีโดเมนออก (กล่าวคือ ระบบจะไม่ส่ง domain_hints หรือโดเมนว่างเปล่า) เช่น กรณีการใช้งานนี้จะอนุญาตกรณีการใช้งานที่ RP อนุญาตให้ใช้เฉพาะบัญชีที่จัดการในขั้นตอนลงชื่อสมัครใช้

เมื่อไม่มีบัญชีที่ตรงกับ domainHint กล่องโต้ตอบ FedCM จะแสดงข้อความแจ้งให้เข้าสู่ระบบ ซึ่งช่วยให้ผู้ใช้เข้าสู่ระบบบัญชี IdP ที่ตรงกับคำแนะนำที่ RP ขอได้ เมื่อผู้ใช้แตะข้อความแจ้ง หน้าต่างป๊อปอัปจะเปิดขึ้นพร้อม URL การเข้าสู่ระบบที่ระบุไว้ในไฟล์การกำหนดค่า จากนั้นลิงก์จะต่อท้ายด้วยคำแนะนำในการเข้าสู่ระบบและพารามิเตอร์การค้นหาของคำแนะนำโดเมน

ตัวอย่างข้อความแจ้งให้เข้าสู่ระบบเมื่อไม่มีบัญชีที่ตรงกับ domainHint — ตัวอย่างข้อความแจ้งให้เข้าสู่ระบบเมื่อไม่มีบัญชีที่ตรงกับ `domainHint`

แสดงข้อความแสดงข้อผิดพลาด

บางครั้ง IdP อาจออกโทเค็นไม่ได้ด้วยเหตุผลทางกฎหมาย เช่น เมื่อไคลเอ็นต์ไม่ได้รับอนุญาต เซิร์ฟเวอร์จะใช้งานไม่ได้ชั่วคราว หาก IdP ตอบกลับเป็น "ข้อผิดพลาด" RP จะตรวจจับได้ รวมถึง Chrome จะแจ้งเตือนผู้ใช้โดยแสดง UI ของเบราว์เซอร์พร้อมข้อมูลข้อผิดพลาดที่ IdP ให้ไว้

try {
  const cred = await navigator.credentials.get({
    identity: {
      providers: [
        {
          configURL: "https://idp.example/manifest.json",
          clientId: "1234",
        },
      ],
    }
  });
} catch (e) {
  const code = e.code;
  const url = e.url;
}

ตรวจสอบสิทธิ์ผู้ใช้อีกครั้งโดยอัตโนมัติหลังจากได้รับความยินยอมครั้งแรก

การตรวจสอบสิทธิ์ซ้ำโดยอัตโนมัติของ FedCM (เรียกสั้นๆ ว่า "auto-reauthn") ช่วยให้ผู้ใช้ตรวจสอบสิทธิ์ซ้ำได้โดยอัตโนมัติ เมื่อกลับมาอีกครั้งหลังจากตรวจสอบสิทธิ์ครั้งแรกโดยใช้ FedCM "การตรวจสอบสิทธิ์ครั้งแรก" ในที่นี้หมายความว่าผู้ใช้จะสร้างบัญชีหรือลงชื่อเข้าใช้เว็บไซต์ของ RP โดยการแตะปุ่ม "ดำเนินการต่อในชื่อ..." บนกล่องโต้ตอบการลงชื่อเข้าใช้ของ FedCM เป็นครั้งแรกในอินสแตนซ์ของเบราว์เซอร์เดียวกัน

แม้ว่าประสบการณ์ที่ชัดเจนของผู้ใช้จะสมเหตุสมผลก่อนที่ผู้ใช้จะสร้างบัญชีแบบรวมศูนย์เพื่อป้องกันการติดตาม (ซึ่งเป็นเป้าหมายหลักอย่างหนึ่งของ FedCM) แต่การทำงานของผู้ใช้อาจยุ่งยากอย่างไม่จำเป็นหลังจากได้ดำเนินการไปแล้วครั้งหนึ่ง หลังจากที่ผู้ใช้ให้สิทธิ์ในการสื่อสารระหว่าง RP กับ IdP แล้ว ก็จะไม่ได้รับประโยชน์ด้านความเป็นส่วนตัวหรือความปลอดภัยในการบังคับใช้การยืนยันอื่นของผู้ใช้อย่างชัดแจ้งในสิ่งที่ตนยอมรับไปแล้วก่อนหน้านี้

เมื่อใช้การตรวจสอบสิทธิ์อีกครั้งโดยอัตโนมัติ เบราว์เซอร์จะเปลี่ยนลักษณะการทำงานตามตัวเลือกที่คุณระบุสำหรับ mediation เมื่อเรียกใช้ 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 คือพร็อพเพอร์ตี้ใน API การจัดการข้อมูลเข้าสู่ระบบ ซึ่งทำงานในลักษณะเดียวกันเช่นเดียวกับที่ใช้กับ PasswordCredential และFederatedCredential รวมถึงรองรับบางส่วนจาก PublicKeyCredential ด้วย พร็อพเพอร์ตี้ยอมรับค่า 4 ค่าต่อไปนี้

'optional'(ค่าเริ่มต้น): ตรวจสอบสิทธิ์อีกครั้งโดยอัตโนมัติหากเป็นไปได้ ต้องใช้สื่อกลางหากไม่ใช้ เราขอแนะนำให้เลือกตัวเลือกนี้ในหน้าลงชื่อเข้าใช้
'required': กำหนดให้ใช้สื่อกลางเพื่อดำเนินการต่อไปเสมอ เช่น คลิกปุ่ม "ต่อไป" ใน UI เลือกตัวเลือกนี้หากผู้ใช้ต้องให้สิทธิ์อย่างชัดเจนทุกครั้งที่ต้องตรวจสอบสิทธิ์
'silent': ตรวจสอบสิทธิ์อีกครั้งโดยอัตโนมัติหากเป็นไปได้ และจะดำเนินการไม่สำเร็จโดยไม่มีสื่อกลาง หากไม่มีสิทธิ์ดังกล่าว เราขอแนะนำให้เลือกตัวเลือกนี้ในหน้าอื่นๆ นอกเหนือจากหน้าสำหรับลงชื่อเข้าใช้โดยเฉพาะ แต่ต้องการให้ผู้ใช้ลงชื่อเข้าใช้อยู่เสมอ เช่น หน้าสินค้าในเว็บไซต์การจัดส่งหรือหน้าบทความในเว็บไซต์ข่าว
'conditional': ใช้สำหรับ WebAuthn และใช้งานกับ FedCM ไม่ได้ในขณะนี้

ในการเรียกนี้ การตรวจสอบสิทธิ์ซ้ำอัตโนมัติจะเกิดขึ้นภายใต้เงื่อนไขต่อไปนี้

FedCM ก็พร้อมให้ใช้งาน เช่น ผู้ใช้ไม่ได้ปิดใช้ FedCM ทั่วโลกหรือสำหรับ RP ในการตั้งค่า
ผู้ใช้ลงชื่อเข้าใช้เว็บไซต์ด้วย FedCM API เพียงบัญชีเดียว
ผู้ใช้ลงชื่อเข้าใช้ IdP ด้วยบัญชีนั้น
การตรวจสอบสิทธิ์ซ้ำอัตโนมัติไม่ได้เกิดขึ้นภายใน 10 นาทีที่ผ่านมา
RP ไม่ได้เรียกใช้ navigator.credentials.preventSilentAccess() หลังจากการลงชื่อเข้าใช้ก่อนหน้า

เมื่อตรงตามเงื่อนไขเหล่านี้ ความพยายามในการตรวจสอบสิทธิ์ผู้ใช้อีกครั้งโดยอัตโนมัติจะเริ่มต้นทันทีที่มีการเรียกใช้ FedCM navigator.credentials.get()

เมื่อmediation: optional การตรวจสอบสิทธิ์ซ้ำอัตโนมัติอาจไม่พร้อมใช้งานเนื่องด้วยเหตุผลที่มีเฉพาะเบราว์เซอร์เท่านั้นที่รู้ RP สามารถตรวจสอบได้ว่ามีการตรวจสอบสิทธิ์ซ้ำโดยอัตโนมัติหรือไม่โดยการตรวจสอบพร็อพเพอร์ตี้ isAutoSelected

ซึ่งจะช่วยในการประเมินประสิทธิภาพของ API และปรับปรุง UX ได้ตามความเหมาะสม นอกจากนี้ เมื่อไม่พร้อมใช้งาน ผู้ใช้อาจได้รับแจ้งให้ลงชื่อเข้าใช้ด้วยสื่อกลางผู้ใช้อย่างชัดแจ้ง ซึ่งเป็นขั้นตอนของ mediation: required

ผู้ใช้ตรวจสอบสิทธิ์ซ้ำโดยอัตโนมัติผ่าน FedCM

บังคับใช้สื่อกลางด้วย `preventSilentAccess()`

การตรวจสอบสิทธิ์ผู้ใช้อีกครั้งโดยอัตโนมัติทันทีหลังจากที่ออกจากระบบไม่ได้ทำให้ผู้ใช้ได้รับประสบการณ์การใช้งานที่ดีนัก นั่นจึงเป็นเหตุผลที่ FedCM มีเวลาเงียบๆ 10 นาทีหลังจากการตรวจสอบสิทธิ์ซ้ำโดยอัตโนมัติเพื่อป้องกันการทำงานลักษณะนี้ ซึ่งหมายความว่าการตรวจสอบสิทธิ์ซ้ำโดยอัตโนมัติจะเกิดขึ้นทุกๆ 10 นาทีทุกๆ 10 นาที เว้นแต่ว่าผู้ใช้จะกลับมาลงชื่อเข้าใช้ในอีก 10 นาที RP ควรเรียกใช้ navigator.credentials.preventSilentAccess() เพื่อขอเบราว์เซอร์ให้ปิดใช้การตรวจสอบสิทธิ์อีกครั้งโดยอัตโนมัติอย่างชัดแจ้งเมื่อผู้ใช้ออกจากระบบของ RP อย่างชัดแจ้ง เช่น โดยคลิกปุ่มออกจากระบบ

function signout() {
  navigator.credentials.preventSilentAccess();
  location.href = '/signout';
}

ผู้ใช้เลือกไม่ใช้การตรวจสอบสิทธิ์ซ้ำอัตโนมัติได้ในการตั้งค่า

ผู้ใช้สามารถเลือกไม่ใช้การตรวจสอบสิทธิ์ซ้ำอัตโนมัติได้จากเมนูการตั้งค่า ดังนี้

ใน Chrome บนเดสก์ท็อป ให้ไปที่ chrome://password-manager/settings > ลงชื่อเข้าใช้โดยอัตโนมัติ
บน Android Chrome ให้เปิดการตั้งค่า > เครื่องมือจัดการรหัสผ่าน > แตะเฟืองที่มุมบนขวา > การลงชื่อเข้าใช้อัตโนมัติ

การปิดใช้ปุ่มเปิด/ปิดจะทำให้ผู้ใช้เลือกไม่ใช้การทำงานการตรวจสอบสิทธิ์ซ้ำอัตโนมัติทั้งหมดได้ ระบบจะจัดเก็บและซิงค์ข้อมูลการตั้งค่านี้ในอุปกรณ์ต่างๆ หากผู้ใช้ลงชื่อเข้าใช้บัญชี Google ในอินสแตนซ์ของ Chrome และเปิดใช้การซิงค์ข้อมูลอยู่

ยกเลิกการเชื่อมต่อ IdP จาก RP

หากผู้ใช้เคยลงชื่อเข้าใช้ RP โดยใช้ IdP ผ่าน FedCM เบราว์เซอร์จะจดจำความสัมพันธ์ดังกล่าวไว้ในเครื่องเป็นรายการบัญชีที่เชื่อมโยงกัน RP อาจเริ่มยกเลิกการเชื่อมต่อโดยเรียกใช้ฟังก์ชัน IdentityCredential.disconnect() สามารถเรียกฟังก์ชันนี้จากเฟรม RP ระดับบนสุด โดย RP จะต้องผ่าน configURL, clientId ที่ใช้ภายใต้ IdP และ accountHint เพื่อให้ยกเลิกการเชื่อมต่อ IdP คำแนะนำบัญชีสามารถเป็นสตริงที่กำหนดเองได้ตราบใดที่ปลายทางการยกเลิกการเชื่อมต่อสามารถระบุบัญชีได้ เช่น อีเมลหรือรหัสผู้ใช้ ซึ่งไม่จำเป็นต้องตรงกับรหัสบัญชีที่ปลายทางรายการบัญชีระบุไว้

// 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() แสดงผล Promise สัญญานี้อาจมีข้อยกเว้น เนื่องจากสาเหตุต่อไปนี้

ผู้ใช้ไม่ได้ลงชื่อเข้าใช้ RP โดยใช้ IdP ผ่าน FedCM
มีการเรียกใช้ API จากภายใน iframe โดยไม่มีนโยบายสิทธิ์ของ FedCM
configURL ไม่ถูกต้องหรือไม่มีปลายทางการยกเลิกการเชื่อมต่อ
การตรวจสอบนโยบายรักษาความปลอดภัยเนื้อหา (CSP) ไม่สำเร็จ
มีคำขอยกเลิกการเชื่อมต่อที่รอดำเนินการ
ผู้ใช้ปิดใช้ FedCM ในการตั้งค่าเบราว์เซอร์

เมื่อปลายทางการยกเลิกการเชื่อมต่อของ IdP แสดงผลการตอบกลับ RP และ IdP จะเลิกเชื่อมต่อในเบราว์เซอร์และคำมั่นสัญญาจะได้รับการแก้ไข รหัสของบัญชีที่ยกเลิกการเชื่อมต่อจะระบุอยู่ในการตอบกลับจากปลายทางที่ยกเลิกการเชื่อมต่อ

โทรหา FedCM จากภายใน iframe แบบข้ามต้นทาง

คุณเรียกใช้ FedCM ได้จากใน iframe แบบข้ามต้นทางโดยใช้นโยบายสิทธิ์ identity-credentials-get หากเฟรมหลักอนุญาต ในการดำเนินการดังกล่าว ให้เพิ่มแอตทริบิวต์ allow="identity-credentials-get" ต่อท้ายแท็ก iframe ดังนี้

<iframe src="https://fedcm-cross-origin-iframe.glitch.me" allow="identity-credentials-get"></iframe>

ดูการใช้งานจริงได้ในตัวอย่าง

หรือถ้าเฟรมหลักต้องการจำกัดต้นทางที่เรียกใช้ FedCM ให้ส่งส่วนหัว Permissions-Policy พร้อมรายการต้นทางที่อนุญาต

Permissions-Policy: identity-credentials-get=(self "https://fedcm-cross-origin-iframe.glitch.me")

ดูข้อมูลเพิ่มเติมเกี่ยวกับวิธีการทำงานของนโยบายสิทธิ์ได้ที่การควบคุมฟีเจอร์ของเบราว์เซอร์ด้วยนโยบายสิทธิ์

คู่มือนักพัฒนาซอฟต์แวร์สำหรับ API การจัดการข้อมูลเข้าสู่ระบบแบบรวมศูนย์

สภาพแวดล้อมในการพัฒนาซอฟต์แวร์ FedCM

โค้ดแก้ไขข้อบกพร่องใน Chrome ใน Android

บล็อกคุกกี้ของบุคคลที่สามใน Chrome

การใช้ FedCM API

สร้างไฟล์ที่รู้จัก

สร้างไฟล์การกำหนดค่า IdP และปลายทาง

ปลายทางบัญชี

ปลายทางข้อมูลเมตาของไคลเอ็นต์

ปลายทางการยืนยันรหัส

แสดงการตอบกลับข้อผิดพลาด

ยกเลิกการเชื่อมต่อปลายทาง

URL เข้าสู่ระบบ

แจ้งสถานะการเข้าสู่ระบบของผู้ใช้กับผู้ให้บริการข้อมูลประจำตัวแก่เบราว์เซอร์

อนุญาตให้ผู้ใช้ลงชื่อเข้าใช้ผ่านขั้นตอนการเข้าสู่ระบบแบบไดนามิก

ลงชื่อเข้าใช้บุคคลที่ต้องพึ่งพาผู้ให้บริการข้อมูลประจำตัว

API คำแนะนำการเข้าสู่ระบบ

API คำแนะนำโดเมน

แสดงข้อความแสดงข้อผิดพลาด

ตรวจสอบสิทธิ์ผู้ใช้อีกครั้งโดยอัตโนมัติหลังจากได้รับความยินยอมครั้งแรก

บังคับใช้สื่อกลางด้วย preventSilentAccess()

ผู้ใช้เลือกไม่ใช้การตรวจสอบสิทธิ์ซ้ำอัตโนมัติได้ในการตั้งค่า

ยกเลิกการเชื่อมต่อ IdP จาก RP

โทรหา FedCM จากภายใน iframe แบบข้ามต้นทาง

บังคับใช้สื่อกลางด้วย `preventSilentAccess()`