คู่มือนักพัฒนาซอฟต์แวร์สำหรับ 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

วันที่

คุณสามารถทดสอบวิธีการทำงานของ 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 รายการ แต่อาจมีการเปลี่ยนแปลงตาม ความคิดเห็นของคุณในอนาคต

สร้างไฟล์การกำหนดค่า 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

เบราว์เซอร์ต้องการการตอบกลับ JSON จาก IdP ซึ่งประกอบด้วยข้อมูลต่อไปนี้ พร็อพเพอร์ตี้:

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

วันที่

ตัวอย่างเนื้อหาการตอบกลับจาก 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

เมื่อได้รับคำขอ เซิร์ฟเวอร์ควร:

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

เบราว์เซอร์ต้องการการตอบกลับ JSON ที่มีพร็อพเพอร์ตี้ accounts ด้วยอาร์เรย์ข้อมูลบัญชีที่มีพร็อพเพอร์ตี้ต่อไปนี้

ตัวอย่างเนื้อหาการตอบกลับ:

{
  "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

เมื่อได้รับคำขอ เซิร์ฟเวอร์ควร:

1. กำหนด RP สำหรับ client_id
2. ตอบกลับด้วยข้อมูลเมตาของไคลเอ็นต์

พร็อพเพอร์ตี้สำหรับปลายทางข้อมูลเมตาของไคลเอ็นต์มีดังนี้

เบราว์เซอร์คาดหวังการตอบสนอง 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 เพื่อ ปลายทางนี้พร้อมด้วยข้อมูลต่อไปนี้

ตัวอย่างส่วนหัว 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

เมื่อได้รับคำขอ เซิร์ฟเวอร์ควร:

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

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

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

{
  "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 ไปยังปลายทางที่ตัดการเชื่อมต่อนี้กับ ข้อมูลต่อไปนี้

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

เมื่อได้รับคำขอ เซิร์ฟเวอร์ควร:

1. ตอบกลับคำขอด้วย CORS (ทรัพยากรข้ามโดเมน) การแชร์)
2. ยืนยันว่าคำขอมีส่วนหัว HTTP Sec-Fetch-Dest: webidentity
3. จับคู่ส่วนหัว Origin กับต้นทางของ RP ที่กำหนดโดย client_id ปฏิเสธหากข้อมูลไม่ตรงกัน
4. จับคู่ account_hint กับรหัสของบัญชีที่ลงชื่อเข้าใช้แล้ว
5. ยกเลิกการเชื่อมต่อบัญชีผู้ใช้กับ RP
6. โต้ตอบกับเบราว์เซอร์ด้วยข้อมูลบัญชีผู้ใช้ที่ระบุใน JSON

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

{
  "account_id": "account456"
}

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

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

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

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

วันที่

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

วันที่

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

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

วันที่

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

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

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 ไม่สำเร็จ

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

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

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

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

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

เมื่อ RP เรียก navigator.credentials.get() กิจกรรมต่อไปนี้จะเกิดขึ้น สถานที่:

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

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

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

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

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

วันที่

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

บางครั้ง 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

บังคับใช้สื่อกลางด้วย 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")

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