Giao diện SSO cho Danh bạ

Bài viết này giải thích cách đăng nhập một danh bạ bằng địa chỉ email hoặc ID người dùng của bên thứ ba. Nó sử dụng cùng appId và Secret Key như giao diện SSO của tài khoản phụ, nhưng URL, các trường chữ ký và trang đích thì khác. Hãy tạo tài khoản phụ và thiết lập vai trò bằng giao diện SSO của tài khoản phụ.

Tổng quan

Gửi email của danh bạ hoặc ID người dùng của bên thứ ba. SurveyMars kiểm tra chữ ký và đăng nhập danh bạ đó.

- Nếu danh bạ là tài khoản phụ, SurveyMars sẽ mở returnUrl. Nếu không truyền returnUrl, hệ thống sẽ mở danh sách khảo sát.

- Nếu danh bạ không phải là tài khoản phụ, SurveyMars sẽ bỏ qua returnUrl và mở trang chủ của danh bạ.

Trường hợp sử dụng

- Hệ thống của bạn đã có sẵn email danh bạ hoặc ID người dùng của bên thứ ba, và bạn muốn truy cập SurveyMars mà không cần mật khẩu.

- Một danh bạ là tài khoản phụ sẽ đi tới returnUrl. Các danh bạ khác sẽ bỏ qua returnUrl và đi tới trang chủ của danh bạ.

Trước khi bắt đầu

1. Đăng nhập bằng tài khoản chính và sao chép appId từ Tài khoản của tôi.

2. Yêu cầu bộ phận hỗ trợ kích hoạt Secret Key. Chỉ sử dụng khóa này trên máy chủ của bạn. Không đặt nó trong URL hoặc mã front-end.

3. Tạo chữ ký SHA256 trên máy chủ của bạn, sau đó mở liên kết đăng nhập bằng GET.

Yêu cầu

Phương thức: GET

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

Tham số	Bắt buộc	Mô tả
appId	Yes	ID của tài khoản chính. Sử dụng cùng appId như giao diện SSO của tài khoản phụ.
email	Conditional	Email của danh bạ. Cung cấp email hoặc thirdUserId, hoặc cả hai. email là bắt buộc khi tài khoản chính chưa cho phép email danh bạ trống.
thirdUserId	Conditional	ID người dùng của bên thứ ba. Cung cấp email hoặc thirdUserId, hoặc cả hai. Nếu gửi cả hai, xác minh sẽ chỉ dùng email. thirdUserId vẫn tham gia vào chữ ký.
language	No	Ngôn ngữ của các thông báo nhắc. Tham số này không tham gia vào chữ ký.
returnUrl	No	Trang sẽ mở sau khi tài khoản phụ đăng nhập. SurveyMars sẽ theo giá trị này đối với danh bạ là tài khoản phụ và bỏ qua trong các trường hợp khác. Tham số này không tham gia vào chữ ký.
ts	Yes	Số giây tính từ 1970-01-01 00:00:00 UTC. Nó có hiệu lực trong 60 giây. ts trong URL phải khớp với ts dùng trong chữ ký. Hãy tạo nó khi người dùng sắp mở liên kết.
sign	Yes	Chữ ký. sign là SHA256 dạng thập lục phân chữ thường của chuỗi văn bản ghép lại: appId + email + thirdUserId + ts + Secret Key. Thứ tự phải khớp chính xác. Secret Key chỉ được ghép trên máy chủ và không được xuất hiện trên thanh địa chỉ trình duyệt. Xem phần Tạo chữ ký bên dưới.

Tạo chữ ký

Quy tắc chữ ký

1. Ghép các trường ký theo một thứ tự cố định, không có ký tự phân tách: appId + email + thirdUserId + ts + Secret Key. Nếu bỏ qua email hoặc thirdUserId, hãy dùng chuỗi rỗng ở vị trí đó. Không được bỏ qua trường đó và cũng không được thay bằng giá trị giữ chỗ. Secret Key chỉ được ghép trên máy chủ và không được xuất hiện trên thanh địa chỉ trình duyệt.

2. Băm chuỗi đó bằng SHA256 và dùng giá trị thập lục phân chữ thường làm sign.

3. language và returnUrl không tham gia vào chữ ký. Chỉ sử dụng các trường và thứ tự ở bước 1.

4. ts là số giây tính từ 1970-01-01 00:00:00 UTC. Nó có hiệu lực trong 60 giây. Hãy tạo ts và sign khi người dùng sắp mở liên kết, và dùng cùng ts trong URL. Việc mã hóa URL không được làm thay đổi các giá trị gốc dùng trong chữ ký.

5. Để kiểm tra chuỗi đã ghép, hãy dán nó vào công cụ SHA256 như LZL online SHA256. Trong môi trường sản xuất, hãy tạo sign trên máy chủ của bạn. Không được tiết lộ Secret Key cho trình duyệt.

6. Không dùng lại chữ ký SSO của tài khoản phụ. Chuỗi đó dùng appId, email, userName, roleId và ts. Giao diện này không dùng userName hoặc roleId.

Ví dụ：

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

Email và ID người dùng của bên thứ ba

1. Gửi ít nhất một trong hai: email và thirdUserId.

2. Nếu gửi cả hai, quá trình xác minh sẽ dùng email và bỏ qua thirdUserId. Giữ thirdUserId gốc trong chữ ký, và bạn có thể giữ nó trong URL.

3. Nếu tài khoản chính chưa cho phép email danh bạ trống, thì email là bắt buộc.

4. Nếu cài đặt này đang tắt, hãy liên hệ bộ phận hỗ trợ để bật "Allow empty contact email." Sau khi bật, bạn có thể thêm danh bạ mà không cần email.

Danh bạ sẽ đến đâu

1. Danh bạ là tài khoản phụ: SurveyMars mở returnUrl. Nếu không truyền returnUrl, hệ thống sẽ mở danh sách khảo sát.

2. Các danh bạ khác: SurveyMars bỏ qua returnUrl và mở trang chủ của danh bạ.

Lưu ý quan trọng

- Giữ Secret Key trên máy chủ của bạn. Không đặt nó trong thanh địa chỉ của trình duyệt.

- Giao diện này dùng để đăng nhập một danh bạ. Nó không tạo tài khoản phụ hoặc thiết lập vai trò tài khoản phụ.

- Mã hóa URL các ký tự như @ trong email. Hãy ký trên giá trị gốc, không phải giá trị đã mã hóa.

Câu hỏi thường gặp

Khác gì so với SSO của tài khoản phụ?
SSO của tài khoản phụ dùng /app/login/sso/verify để tạo hoặc đăng nhập một tài khoản phụ. Đăng nhập danh bạ dùng /app/login/contact/verify với email hoặc ID người dùng của bên thứ ba. Các trường chữ ký khác nhau. Không được dùng lại sign.

Tôi có thể chỉ gửi thirdUserId không?
Có, nếu tài khoản chính cho phép email danh bạ trống. Nếu không, email là bắt buộc. Dùng chuỗi rỗng cho trường bị bỏ qua trong chữ ký.

Tôi đã gửi cả email và thirdUserId. Vì sao đăng nhập lại dùng email?
Khi cả hai cùng có mặt, quá trình xác minh sẽ bỏ qua thirdUserId và đối sánh danh bạ theo email. thirdUserId vẫn tham gia vào chữ ký.

Tại sao danh bạ không phải tài khoản phụ lại bỏ qua returnUrl?
returnUrl chỉ áp dụng khi danh bạ là tài khoản phụ. Nếu không, SurveyMars sẽ bỏ qua nó và mở trang chủ của danh bạ.

Tại sao xác minh chữ ký thất bại?
Kiểm tra Secret Key. Ghép appId, email, thirdUserId, ts và Secret Key theo đúng thứ tự đó. Dùng chuỗi rỗng cho email hoặc thirdUserId bị bỏ qua. Xác nhận rằng ts vẫn nằm trong 60 giây và việc mã hóa URL không làm thay đổi các giá trị gốc. Không bao gồm language hoặc returnUrl.

Tại sao ts hết hạn nhanh như vậy?
Trong môi trường sản xuất, ts phải nằm trong vòng 60 giây so với thời gian máy chủ. Hãy tạo ts và sign khi người dùng sắp mở liên kết.