อินเทอร์เฟซ SSO ของรายชื่อผู้ติดต่อ

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

ภาพรวม

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

- หากผู้ติดต่อเป็นบัญชีรอง SurveyMars จะเปิด returnUrl หากไม่ได้ระบุ returnUrl ระบบจะเปิดรายการแบบสำรวจ

- หากผู้ติดต่อไม่ใช่บัญชีรอง SurveyMars จะไม่สนใจ returnUrl และเปิดหน้าแรกของผู้ติดต่อ

กรณีการใช้งาน

- ระบบของคุณมีอีเมลของผู้ติดต่อหรือรหัสผู้ใช้ของบุคคลที่สามอยู่แล้ว และคุณต้องการให้เข้าถึง SurveyMars ได้โดยไม่ต้องใช้รหัสผ่าน

- ผู้ติดต่อที่เป็นบัญชีรองจะไปยัง returnUrl ส่วนผู้ติดต่ออื่น ๆ จะข้าม returnUrl และไปยังหน้าแรกของผู้ติดต่อ

ก่อนเริ่มต้น

1. ลงชื่อเข้าใช้ด้วยบัญชีหลักและคัดลอก appId จาก My Account

2. ขอให้ฝ่ายสนับสนุนเปิดใช้งาน Secret Key ใช้คีย์นี้เฉพาะบนเซิร์ฟเวอร์ของคุณเท่านั้น อย่านำไปใส่ใน URL หรือในโค้ดฝั่งหน้าเว็บ

3. สร้างลายเซ็น SHA256 บนเซิร์ฟเวอร์ของคุณ แล้วเปิดลิงก์เข้าสู่ระบบด้วย GET

คำขอ

วิธี: GET

URL: https://surveymars.com/app/login/contact/verify?appId=&email=&thirdUserId=&ts=&language=&returnUrl=&sign=

พารามิเตอร์	จำเป็น	คำอธิบาย
appId	Yes	ID ของบัญชีหลัก ใช้ appId เดียวกับอินเทอร์เฟซ SSO ของบัญชีรอง
email	Conditional	อีเมลของผู้ติดต่อ ระบุ email หรือ thirdUserId หรือทั้งสองอย่าง email จำเป็นเมื่อบัญชีหลักยังไม่ได้อนุญาตให้อีเมลผู้ติดต่อเป็นค่าว่าง
thirdUserId	Conditional	รหัสผู้ใช้ของบุคคลที่สาม ระบุ email หรือ thirdUserId หรือทั้งสองอย่าง หากส่งมาทั้งคู่ การตรวจสอบจะใช้เฉพาะ email เท่านั้น thirdUserId ยังถูกนำไปรวมในลายเซ็นอยู่
language	No	ภาษาของข้อความแจ้งเตือน ไม่ได้นำไปรวมในลายเซ็น
returnUrl	No	หน้าที่จะเปิดหลังจากบัญชีรองลงชื่อเข้าใช้ SurveyMars จะตามค่านี้สำหรับผู้ติดต่อที่เป็นบัญชีรอง และจะไม่สนใจในกรณีอื่น ไม่ได้นำไปรวมในลายเซ็น
ts	Yes	วินาทีตั้งแต่ 1970-01-01 00:00:00 UTC มีผลใช้งาน 60 วินาที ค่า ts ใน URL ต้องตรงกับ ts ที่ใช้ในลายเซ็น สร้างค่านี้เมื่อผู้ใช้กำลังจะเปิดลิงก์
sign	Yes	ลายเซ็น sign คือค่า SHA256 แบบเลขฐานสิบหกตัวพิมพ์เล็กของข้อความที่นำมาต่อกัน: appId + email + thirdUserId + ts + Secret Key ลำดับต้องตรงกันทุกประการ Secret Key จะถูกนำมาต่อเฉพาะบนเซิร์ฟเวอร์ และต้องไม่ปรากฏในแถบที่อยู่ของเบราว์เซอร์ ดูส่วน Build the Signature ด้านล่าง

สร้างลายเซ็น

กฎของลายเซ็น

1. นำฟิลด์สำหรับการลงลายเซ็นมาต่อกันตามลำดับที่กำหนดโดยไม่มีตัวคั่น: appId + email + thirdUserId + ts + Secret Key หากไม่ได้ระบุ email หรือ thirdUserId ให้ใช้สตริงว่างในตำแหน่งนั้น อย่าลบฟิลด์นั้นออก และอย่าแทนที่ด้วยค่า placeholder Secret Key จะถูกนำมาต่อเฉพาะบนเซิร์ฟเวอร์ และต้องไม่ปรากฏในแถบที่อยู่ของเบราว์เซอร์

2. แฮชสตริงนั้นด้วย SHA256 และใช้ค่าเลขฐานสิบหกตัวพิมพ์เล็กเป็น sign

3. language และ returnUrl จะไม่นำไปรวมในลายเซ็น ใช้เฉพาะฟิลด์และลำดับตามขั้นตอนที่ 1

4. ts คือจำนวนวินาทีนับตั้งแต่ 1970-01-01 00:00:00 UTC มีอายุใช้งาน 60 วินาที สร้าง ts และ sign เมื่อผู้ใช้กำลังจะเปิดลิงก์ และใช้ ts ค่าเดียวกันใน URL การเข้ารหัส URL ต้องไม่เปลี่ยนค่าดั้งเดิมที่ใช้ในลายเซ็น

5. หากต้องการตรวจสอบสตริงที่นำมาต่อกัน ให้วางลงในเครื่องมือ SHA256 เช่น LZL online SHA256 ในสภาพแวดล้อมจริง ให้สร้าง sign บนเซิร์ฟเวอร์ของคุณ อย่าเปิดเผย Secret Key ให้กับเบราว์เซอร์

6. อย่านำลายเซ็น SSO ของบัญชีรองมาใช้ซ้ำ สตริงนั้นใช้ appId, email, userName, roleId และ ts อินเทอร์เฟซนี้ไม่ใช้ userName หรือ roleId

ตัวอย่าง：

http://surveymars.com/app/login/contact/verify?appId=TTeEB8&[email protected]&ts=1790760357&language=2&returnUrl=https://surveymars.com/app/usercenter&sign=26c0c7d9da5e38c61d4aeecb223336d7a259cad0b75c8ff912855421fd832a4e

อีเมลและรหัสผู้ใช้ของบุคคลที่สาม

1. ส่งอย่างน้อยหนึ่งรายการระหว่าง email และ thirdUserId

2. หากส่งทั้งสองค่า การตรวจสอบจะใช้อีเมลและไม่สนใจ thirdUserId ให้คงค่า thirdUserId เดิมไว้ในลายเซ็น และคุณอาจคงไว้ใน URL ด้วย

3. หากบัญชีหลักยังไม่ได้อนุญาตให้อีเมลผู้ติดต่อเป็นค่าว่าง ต้องระบุ email

4. หากการตั้งค่านี้ปิดอยู่ ให้ติดต่อฝ่ายสนับสนุนเพื่อเปิด "Allow empty contact email." เมื่อเปิดแล้ว คุณสามารถเพิ่มผู้ติดต่อโดยไม่ต้องใช้อีเมลได้

ปลายทางที่ผู้ติดต่อจะไป

1. ผู้ติดต่อที่เป็นบัญชีรอง: SurveyMars จะเปิด returnUrl หากไม่ได้ระบุ returnUrl ระบบจะเปิดรายการแบบสำรวจ

2. ผู้ติดต่ออื่น ๆ: SurveyMars จะไม่สนใจ returnUrl และเปิดหน้าแรกของผู้ติดต่อ

หมายเหตุสำคัญ

- เก็บ Secret Key ไว้บนเซิร์ฟเวอร์ของคุณ อย่านำไปวางในแถบที่อยู่ของเบราว์เซอร์

- อินเทอร์เฟซนี้ใช้ลงชื่อเข้าใช้รายชื่อผู้ติดต่อ ไม่ได้สร้างบัญชีรองหรือกำหนดบทบาทให้บัญชีรอง

- เข้ารหัส URL ของอักขระ เช่น @ ในอีเมล ให้ลงลายเซ็นกับค่าดั้งเดิม ไม่ใช่ค่าที่เข้ารหัสแล้ว

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

แตกต่างจาก SSO ของบัญชีรองอย่างไร?
SSO ของบัญชีรองใช้ /app/login/sso/verify เพื่อสร้างหรือลงชื่อเข้าใช้บัญชีรอง ส่วนการลงชื่อเข้าใช้รายชื่อผู้ติดต่อใช้ /app/login/contact/verify พร้อมอีเมลหรือรหัสผู้ใช้ของบุคคลที่สาม ฟิลด์ลายเซ็นต่างกัน อย่านำ sign มาใช้ซ้ำ

ส่งเฉพาะ thirdUserId ได้ไหม?
ได้ หากบัญชีหลักอนุญาตให้อีเมลผู้ติดต่อเป็นค่าว่าง มิฉะนั้นต้องระบุ email ให้ใช้สตริงว่างสำหรับฟิลด์ที่ไม่ได้ใส่ในลายเซ็น

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

ทำไมผู้ติดต่อที่ไม่ใช่บัญชีรองจึงข้าม returnUrl?
returnUrl ใช้ได้เฉพาะเมื่อผู้ติดต่อเป็นบัญชีรองเท่านั้น มิฉะนั้น SurveyMars จะไม่สนใจค่านี้และเปิดหน้าแรกของผู้ติดต่อ

ทำไมการตรวจสอบลายเซ็นจึงล้มเหลว?
ตรวจสอบ Secret Key นำ appId, email, thirdUserId, ts และ Secret Key มาต่อกันตามลำดับนั้น ใช้สตริงว่างสำหรับ email หรือ thirdUserId ที่ไม่ได้ระบุ ยืนยันว่า ts ยังอยู่ภายใน 60 วินาที และการเข้ารหัส URL ไม่ได้เปลี่ยนค่าดั้งเดิม อย่าใส่ language หรือ returnUrl

ทำไม ts หมดอายุเร็วขนาดนี้?
ในสภาพแวดล้อมจริง ts ต้องอยู่ภายใน 60 วินาทีจากเวลาของเซิร์ฟเวอร์ ให้สร้าง ts และ sign เมื่อผู้ใช้กำลังจะเปิดลิงก์