ข้ามไปยังเนื้อหา
KeuralDocs
นักพัฒนา

ข้อกำหนดการเชื่อมต่อ SSO·SCIM

ข้อกำหนดค่าและการทำงานที่ต้องใช้ในการเชื่อมต่อ OIDC·SAML 2.0·SCIM 2.0

เอกสารนี้เป็นข้อกำหนดทางเทคนิคสำหรับผู้ดูแล IdP และนักพัฒนา ขั้นตอนการตั้งค่าบนหน้าจอดูได้ที่ SSO และ SCIM

{API} ในตารางคือที่อยู่ API ของ Keural ในสภาพแวดล้อมที่คุณใช้ (เช่น https://api.keural.ai) ให้ใช้ที่อยู่ที่แสดงในหน้า การจัดการองค์กร → การตั้งค่า SSO ตามที่ปรากฏ

สรุปค่าที่ต้องลงทะเบียน

รายการค่า
OIDC redirect URI{API}/api/sso/callback
เริ่มการเข้าสู่ระบบ OIDC·SAML{API}/api/sso/{orgId}/login
SAML SP EntityID{API}/api/sso/saml/metadata
SAML ACS URL{API}/api/sso/saml/callback
SCIM Base URL{API}/scim/v2

การเข้าสู่ระบบจะเริ่มจาก Keural เสมอ (SP-initiated) เมื่อกรอกอีเมลที่มีโดเมนที่ลงทะเบียนไว้ในหน้าเข้าสู่ระบบ ระบบจะพาไปยังที่อยู่เริ่มการเข้าสู่ระบบ เมื่อสำเร็จจะไปยังหน้าแรกของ Keural เมื่อล้มเหลวจะไปยัง /login?error=sso

OIDC

รายการการทำงาน
โฟลว์Authorization Code
คำขอ authorizeresponse_type=code, client_id, redirect_uri, scope=openid email profile, state, nonce
state · nonceใช้ได้ครั้งเดียวและมีอายุ 10 นาที หากเปิดหน้าต่างเข้าสู่ระบบค้างไว้เกิน 10 นาที ให้เข้าสู่ระบบใหม่ตั้งแต่ต้น
แลกเปลี่ยนโทเคนPOST ไปยัง token endpoint, application/x-www-form-urlencoded, การยืนยันตัวตนของไคลเอนต์เป็น client_secret_post (ส่ง client_id และ client_secret ในเนื้อหาคำขอ)
การลงนาม ID tokenรับเฉพาะ RS256 โดยค้นหาคีย์จาก jwks_uri ด้วย kid
การตรวจสอบ ID tokenลายเซ็น, exp, aud มี client_id, nonce ตรงกัน, iss ตรงกับ Issuer URL (ไม่นับ / ท้ายสุด)
อีเมลclaim email ใน ID token หากไม่มี จะเรียก userinfo endpoint ด้วย Authorization: Bearer <access_token> แล้วอ่าน email
ชื่อclaim name ใน ID token
endpointค้นหาจาก /.well-known/openid-configuration ของ Issuer URL หาก IdP ค้นหาไม่พบ ให้กรอกที่อยู่ authorization · token · JWKS · userinfo ด้วยตนเองที่ เปิดการตั้งค่าขั้นสูง
เวลาจำกัด15 วินาทีต่อการเรียก IdP หนึ่งครั้ง

แอปพลิเคชัน IdP ต้องอนุญาต client_secret_post หากการตั้งค่าอนุญาตเฉพาะ client_secret_basic หรือ private_key_jwt การแลกเปลี่ยนโทเคนจะล้มเหลว

SAML 2.0

รายการการทำงาน
คำขอส่ง AuthnRequest ด้วยไบนดิง HTTP-Redirect คำขอไม่มีการลงนาม
เนื้อหาคำขอDestination=IdP SSO URL, AssertionConsumerServiceURL=ACS URL, ProtocolBinding=HTTP-POST, Issuer=SP EntityID, NameIDPolicy Format=…:nameid-format:unspecified, AllowCreate=true
การตอบกลับไบนดิง HTTP-POST มี SAMLResponse และ RelayState ต้องส่ง RelayState กลับมาตามค่าที่ Keural ส่งไป
ลายเซ็นResponse หรือ Assertion อย่างใดอย่างหนึ่งต้องมีลายเซ็นที่ถูกต้อง คีย์สำหรับตรวจสอบใช้เฉพาะใบรับรองที่ลงทะเบียนไว้ในหน้าจอ
Assertionในการตอบกลับต้องมี assertion เพียงหนึ่งรายการ ไม่รับ assertion ที่เข้ารหัส (EncryptedAssertion)
สถานะStatusCode คือ urn:oasis:names:tc:SAML:2.0:status:Success
Issuerหากกรอก IdP EntityID ต้องตรงกับ Issuer ใน assertion
เงื่อนไขNotBefore และ NotOnOrAfter (ค่าคลาดเคลื่อนที่ยอมรับได้ 300 วินาที), Audience=SP EntityID
SubjectConfirmationDataRecipient=ACS URL, NotOnOrAfter (ค่าคลาดเคลื่อนที่ยอมรับได้ 300 วินาที), InResponseTo=ID คำขอที่ Keural ส่งไป
อีเมลแอตทริบิวต์ Name หรือ FriendlyName ต้องเป็นหนึ่งในค่าต่อไปนี้ (ไม่สนตัวพิมพ์ใหญ่/เล็ก): email, mail, emailAddress, E-Mail-Addresses, http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress หากไม่มี จะใช้ NameID ที่มี @
ชื่อdisplayName, name, cn, http://schemas.microsoft.com/identity/claims/displayname
ใบรับรองX.509 หนึ่งฉบับ เป็น PEM หรือ Base64(DER) เมื่อเปลี่ยนใบรับรอง ให้กรอกใบรับรองใหม่แล้วบันทึก
เมทาดาทาแทนการอัปโหลด XML เมทาดาทาของ IdP ให้กรอกค่าสามอย่าง ได้แก่ IdP EntityID · IdP SSO URL · ใบรับรอง

การตัดสินผู้ใช้

รายการการทำงาน
เกณฑ์ส่งไปยัง SSOส่วนหลัง @ ของอีเมลตรงทุกตัวอักษรกับรายการหนึ่งในรายการ โดเมนอีเมล (ไม่สนตัวพิมพ์ใหญ่/เล็ก) ซับโดเมนต้องลงทะเบียนแยก
การค้นหาบัญชีค้นหาบัญชี Keural ด้วยอีเมล (ตัวพิมพ์เล็ก) ที่ IdP ส่งมา
เมื่อไม่มีบัญชีหาก การสร้างผู้ใช้อัตโนมัติเมื่อเข้าสู่ระบบครั้งแรก (JIT) เปิดอยู่ ระบบจะสร้างบัญชีให้ ถ้าปิดอยู่ จะปฏิเสธการเข้าสู่ระบบ
เข้าร่วมองค์กรหากไม่ใช่สมาชิกขององค์กร จะเข้าร่วมในฐานะ สมาชิก บัญชีที่ที่นั่งเต็มหรืออยู่ในองค์กรอื่นจะไม่เข้าร่วม และเข้าสู่ระบบได้เท่านั้น
เงื่อนไขการบันทึกโดเมนอีเมลโดเมนที่ยืนยันด้วย DNS TXT แล้ว ยกเว้นโดเมนอีเมลสาธารณะ

การยืนยันโดเมน

รายการค่า
ชนิดเรคคอร์ดTXT
โฮสต์โดเมนที่ลงทะเบียนตามที่เป็น (เช่น acme.com) ไม่ต้องใส่ซับโดเมนนำหน้า
ค่าkeural-verify=<UUID> ตามค่าที่แสดงบนหน้าจอทุกประการ
เวลาตรวจสอบตรวจสอบครั้งเดียวเมื่อกด ยืนยันการตรวจสอบ

SCIM 2.0

รายการค่า
Base URL{API}/scim/v2
การยืนยันตัวตนAuthorization: Bearer <SCIM token> โทเคนขึ้นต้นด้วย scim_ และแสดงเพียงครั้งเดียวตอนออก
Content-Typeคำขอ application/scim+json หรือ application/json การตอบกลับ application/scim+json
รหัสสถานะส่งกลับเป็นรหัสสถานะ HTTP จริง ข้อผิดพลาดอยู่ในรูปแบบ SCIM Error (schemas, status, detail, scimType)

เอนด์พอยต์

เมธอดพาธการทำงาน
GET/Usersรายการ filter=userName eq "…", startIndex (ค่าเริ่มต้น 1), count (ค่าเริ่มต้น 100, สูงสุด 200)
GET/Users/{id}ดูผู้ใช้หนึ่งคน
POST/Usersสร้าง (201) หากมีอีเมลเดียวกันอยู่แล้วจะได้ 409
PATCH/Users/{id}เปลี่ยน active, displayName, name.formatted, name.givenName
PUT/Users/{id}นำ displayName·name·active ไปใช้ หากไม่ใส่ active จะถือว่าใช้งานอยู่
DELETE/Users/{id}ระงับบัญชี (204) ไม่ลบข้อมูล
GET/Groups, /Groups/{id}ดูกลุ่มคงที่สองกลุ่ม filter=displayName eq "…"
PATCH/Groups/{id}เพิ่ม ลบ หรือแทนที่สมาชิก
GET/ServiceProviderConfig, /ResourceTypes, /Schemasดูฟีเจอร์ที่รองรับ

แอตทริบิวต์ผู้ใช้

แอตทริบิวต์การใช้งาน
userNameอีเมล หากไม่มีจะใช้ emails[0].value
displayName · name.formatted · name.givenName+name.familyNameชื่อที่แสดง
activefalse ระงับ (บล็อกการเข้าสู่ระบบ) true คืนสถานะ
idID ผู้ใช้ Keural แสดงอยู่ในการตอบกลับ

ไม่มีการบันทึก externalId เมื่อต้องค้นหาผู้ใช้จาก IdP ให้ใช้ตัวกรอง userName

กลุ่ม

iddisplayNameเมื่อเพิ่มสมาชิกเมื่อลบสมาชิก
keural-adminsKeural Adminsผู้ดูแลระบบสมาชิก
keural-membersKeural Membersสมาชิกไม่เปลี่ยนแปลง

บทบาทเจ้าขององค์กรไม่เปลี่ยนผ่าน SCIM การสร้างหรือลบกลุ่ม (POST·DELETE /Groups) จะได้ 501 กลับมา value ของสมาชิกในกลุ่มคือ ID ผู้ใช้ Keural (id จาก /Users)

ขอบเขตที่รองรับ

ฟีเจอร์รองรับ
PATCHใช่
ตัวกรองuserName eq, displayName eq
Bulk · การเรียงลำดับ · ETag · การเปลี่ยนรหัสผ่านไม่

ข้อผิดพลาด

สถานะscimTypeสาเหตุ
400invalidValueไม่มีทั้ง userName และ emails
401—ไม่มีโทเคนหรือโทเคนไม่ถูกต้อง หรือปิดการจัดสรร SCIM อยู่
404—ไม่ใช่ผู้ใช้หรือกลุ่มขององค์กรนี้
409uniquenessมีบัญชีที่อีเมลเดียวกันอยู่แล้ว หรือที่นั่งเกินจำนวน
501—การสร้างหรือลบกลุ่ม

การเชื่อมต่อปลั๊กอิน·MCP เซิร์ฟเวอร์

วิธีเชื่อม MCP เซิร์ฟเวอร์ที่คุณสร้างเองเข้ากับ Keural และสร้างแพ็กเกจปลั๊กอินสำหรับแอปเดสก์ท็อป

คำถามที่พบบ่อย

คำถามเกี่ยวกับการเข้าสู่ระบบ ขีดจำกัดการใช้งาน ไฟล์ คำตอบ แอป องค์กร และการเรียกเก็บเงิน

ในหน้านี้

สรุปค่าที่ต้องลงทะเบียนOIDCSAML 2.0การตัดสินผู้ใช้การยืนยันโดเมนSCIM 2.0เอนด์พอยต์แอตทริบิวต์ผู้ใช้กลุ่มขอบเขตที่รองรับข้อผิดพลาด