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

ดูวิธีใช้ FedCM สําหรับการรวมศูนย์ข้อมูลระบุตัวตนที่รักษาความเป็นส่วนตัว

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

ดูข้อมูลเพิ่มเติมเกี่ยวกับ Use Case, ขั้นตอนของผู้ใช้ และแผนพัฒนา API ของ FedCM ได้ที่ข้อมูลเบื้องต้นเกี่ยวกับ FedCM API

สภาพแวดล้อมในการพัฒนาของ FedCM

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

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

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

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

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

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

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

การใช้ FedCM API

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

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

สร้างไฟล์ Well-Known

ไฟล์ Well-known ต้องแสดงจาก /.well-known/web-identity ของ eTLD+1 ของ IdP เพื่อไม่ให้เครื่องมือติดตามละเมิด API

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

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

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

เบราว์เซอร์จะส่งคำขอ 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. ยืนยันว่าคำขอมีส่วนหัว Sec-Fetch-Dest: webidentity HTTP
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 (Cross-Origin Resource Sharing)
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 (Cross-Origin Resource Sharing)
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 เข้าสู่ระบบ

เมื่อใช้ 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 จะส่งคำขอไปยังปลายทางบัญชีของ IdP และแสดงบัญชีที่ใช้ได้ต่อผู้ใช้ในกล่องโต้ตอบ FedCM

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

Set-Login: logged-out

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

หากผู้ใช้เคยลงชื่อเข้าใช้ RP โดยใช้ IdP ผ่าน FedCM เบราว์เซอร์จะจดจำความสัมพันธ์ดังกล่าวไว้ในเครื่องเป็นรายการบัญชีที่เชื่อมต่อ RP อาจเริ่มยกเลิกการเชื่อมต่อโดยการเรียกใช้ฟังก์ชัน IdentityCredential.disconnect() โดยเรียกใช้ฟังก์ชันนี้จากเฟรม RP ระดับบนสุดได้ โดย RP จะต้องส่ง configURL, clientId ที่ URL ใช้ภายใต้ 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")

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