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

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

ดูวิธีใช้ 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 ให้บล็อกคุกกี้ดังกล่าว

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

หากต้องการบล็อกคุกกี้ของบุคคลที่สาม ให้ใช้ไม่ระบุตัวตน Modeหรือเลือก "บล็อก คุกกี้ของบุคคลที่สาม" ในการตั้งค่าเดสก์ท็อปที่ 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 ที่มีอาร์เรย์ของ IdP URL ของไฟล์การกำหนดค่าที่สามารถระบุเป็นส่วนหนึ่งของเส้นทางของ configURL ใน navigator.credentials.get โดย RP จำนวน สตริง URL ในอาร์เรย์ถูกจำกัดไว้ที่ 1 รายการ แต่อาจมีการเปลี่ยนแปลงตาม ความคิดเห็นของคุณในอนาคต

เคล็ดลับ: ในการพัฒนา การทดสอบ หรือการทดลองใช้โดเมนเซิร์ฟเวอร์ RP ของ FedCM อาจเป็นวิธี โดเมนย่อยของเซิร์ฟเวอร์ 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 จะมีรายการปลายทางที่จำเป็นสำหรับเบราว์เซอร์ IdPs จะโฮสต์ไฟล์การกำหนดค่านี้ รวมถึงปลายทางและ 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;

ระบุ 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 — วิธีใช้การสร้างแบรนด์กับกล่องโต้ตอบ 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
จับคู่คุกกี้ของเซสชันกับรหัสของบัญชีที่ลงชื่อเข้าใช้แล้ว
ตอบกลับด้วยรายการบัญชี

เบราว์เซอร์ต้องการการตอบกลับ 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

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

ปลายทางการยืนยันรหัสของ IdP จะแสดงการยืนยันสำหรับผู้ใช้ที่ลงชื่อเข้าใช้ เมื่อผู้ใช้ลงชื่อเข้าใช้เว็บไซต์ RP โดยใช้ navigator.credentials.get() call เบราว์เซอร์จะส่งคำขอ 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 ได้รับคำขอโทเค็นโดยไม่มีสื่อกลางดังกล่าว ผู้ให้บริการข้อมูลประจำตัวจะจัดการคำขอต่างออกไปได้ เช่น ส่งคืนรหัสข้อผิดพลาดเพื่อให้ 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 แล้วส่งสตริงที่ไม่ตรงกับรหัสบัญชีใดๆ เช่น "*"

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

กล่องโต้ตอบ 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 การกำหนดค่า) เบราว์เซอร์จะเก็บตัวแปร 3 สถานะที่แสดงถึงสถานะการเข้าสู่ระบบไว้ ด้วยค่าที่เป็นไปได้ 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 จะส่งคำขอไปยัง ปลายทางของบัญชีและแสดงบัญชีที่พร้อมใช้งานแก่ผู้ใช้ใน 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 แต่ปลายทางบัญชีของ 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 หรือ ว่างเปล่า) เช่น อนุญาต Use Case ที่ 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 "แท็กเริ่มต้น การตรวจสอบสิทธิ์" หมายความว่าผู้ใช้สร้างบัญชีหรือลงชื่อเข้าใช้ ได้โดยแตะปุ่ม "ดำเนินการต่อในฐานะ..." ในกล่องโต้ตอบการลงชื่อเข้าใช้ของ FedCM เป็นครั้งแรกในอินสแตนซ์ของเบราว์เซอร์เดียวกัน

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

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

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

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

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

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

การตรวจสอบสิทธิ์ผู้ใช้อีกครั้งโดยอัตโนมัติทันทีที่ออกจากระบบไม่ได้เป็นการ ประสบการณ์ที่ดีของผู้ใช้ ด้วยเหตุนี้ FedCM จึงมีเวลาเงียบใน 10 นาทีหลังจาก การตรวจสอบสิทธิ์ซ้ำโดยอัตโนมัติเพื่อป้องกันปัญหานี้ ซึ่งหมายความว่าการตรวจสอบสิทธิ์ซ้ำโดยอัตโนมัติจะเกิดขึ้น ไม่เกิน 1 ครั้งในทุก 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 ที่ RP ใช้ ในส่วน 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()`