Nhảy tới nội dung

Quy trình tích hợp Biometric Authentication trên Zalo

Bắt đầu hỗ trợ ở phiên bản:

  • API: 2.5.3
Lưu ý

Với API version ﹤ 2.23.0, phải gọi api login trước khi gọi api này và cần xin cấp quyền tại trang Quản lý ứng dụng

Mô tả tính năng​

Biometric Authentication (xác thực sinh trắc học) là tính năng dùng vân tay, khuôn mặt… để xác thực thông tin người sử dụng.

Hiện tại API Biometric đang trong quá trình thử nghiệm nên sẽ chỉ mở cho một số đối tác nhất định. Vì vậy để sử dụng tính năng này, vui lòng đăng ký với Mini App Team và gửi kèm các thông tin sau:

  • Zalo App ID
  • Mini App ID
  • Webhook URL: url để nhận event khi xác thực thành công. Yêu cầu domain public và sử dụng HTTPS.

Sequence Diagram​

Biểu đồ mô tả trình tự cơ bản quá trình xác thực với Biometric trên Zalo, với Mini App quy trình sẽ được tối giản và lược bỏ 1 số bước.

Sequence Diagram

Các bước cơ bản để xác thực Biometric trên Mini App như sau:

  • Kiểm tra trạng thái Biometric của thiết bị
  • Sử dụng SDK mở UI xác thực Biometric
  • Server xử lý sự kiện webhook - xác thực thành công
  • Mini App sử dụng secret data xác thực lại với Server

Kiểm tra trạng thái Biometric của thiết bị​

API checkStateBioAuthentication cho phép ứng dụng kiểm tra thông tin xác thực bằng sinh trắc học có bị thay đổi so với lần gần nhất không. Ví du: thêm vân tay, thêm FaceID, reset vân tay,... bạn cũng có thể dựa vào đó để biết thiết bị có hỗ trợ Biometric hay không?

Lưu ý, tính năng Biometric chỉ hỗ trợ các OS chuẩn, không bị Root hoặc Jailbreak.

Sample code​

import api from "zmp-sdk";

api.checkStateBioAuthentication({
  success: (data) => {
    const { bioState } = data;
    //Có hỗ trợ Biometric
  },
  fail: (err) => {
    //Không hỗ trợ Biometric
  },
});

Sử dụng SDK mở UI xác thực Biometric​

Sử dụng function api.openBioAuthentication để mở UI xác thực với Biometric, tham số cần truyền:

Parameters​

Object object​

PropertyTypeDefaultRequiredDescriptionMinimum Version
secretDatastringKhoá bí mật, dùng một lần cho quá trình xác thực. Bạn có thể tạo secretData = hash(accessToken + timestamp)2.5.3
uiobject2.5.3
requireFingerprintbooleanChỉ sử dụng vân tay. Hỗ trợ Android2.5.3
successfunctionCallback function khi gọi api thành công2.5.3
failfunctionCallback function khi gọi api thất bại2.5.3

UI Object​

PropertyTypeDefaultRequiredDescriptionMinimum Version
titlestring"Xác thực"Tiêu đề form xác thực
subTitlestring"Sử dụng sinh trắc học của bạn để xác thực"Nội dung hướng dẫn
negativeButtonTextstring"Đóng"Tiêu đề của Button thoát

Error code​

CodeError
108Xác thực quá nhiều lần => Đã bị khóa Biometic
103Xác thực không thành công (Bấm nhập mật khẩu - iOS)
102Hủy xác thực
101Xác thực thất bại 3 lần (Android)
100Unknown error

Sample code​

import api from "zmp-sdk";

api.openBioAuthentication({
  secretData: "aGkgYmFu",
  ui: {
    title: "Biometric login for my app",
    subTitle: "Log in using your biometric credential",
    negativeButtonText: "Cancel",
  },
  success: (data) => {},
  fail: (error) => {
    const { code } = error;
    //Mô tả code các mã lỗi
    // -108: Xác thực quá nhiều lần => Đã bị khóa Biometic
    // -103: Xác thực không thành công (Bấm nhập mật khẩu - iOS)
    // -102: Hủy xác thực
    // -101: Xác thực thất bại 3 lần (Android)
    // -100: Unknown error
  },
});

Server xử lý sự kiện webhook - xác thực thành công​

Sau khi người dùng xác thực thành công, Zalo Server sẽ gửi event tới url bạn đã đăng ký

  • URL: Webhook URL của ứng dụng
  • Method: POST
  • Headers: X-ZEvent-Signature (xem hướng dẫn verify signature bên dưới)
  • Content-Type: application/json
PropertyTypeDefaultRequiredDescriptionMinimum Version
secretDataString"Xác thực"2.5.3
eventStringbiometric.verify.successTên sự kiện2.5.3
timestampLong"Đóng"Thời gian sự kiện2.5.3

Server của bạn tiến hành verify X-ZEvent-Signature theo hướng dẫn bên dưới. Sau đó lưu lại trạng thái xác thực Bio thành công cho secret_data vừa nhận được.

Hướng Dẫn Verify Signature​

Để xác thực Signature của sự kiện vui lòng làm theo hướng dẫn sau:

  • Lấy tất cả danh sách fields dữ liệu trong data bạn nhận được sắp theo thứ tự Alphabet (A - Z)
  • Build chuỗi content các giá trị theo thứ tự fields vừa sắp xếp được
  • Signature được tính theo hàm hash sha256(content + API Key). Vui lòng tham khảo code mẫu bên dưới. API Key sẽ do Team Mini App cung cấp.

Code mẫu build signature từ data:

var generateSignature = (data, apiKey) => {
  const keys = Object.keys(data).sort();
  let content = "";
  for (let k of keys) {
    let value = data[k];
    if (typeof value == "object") {
      value = JSON.stringify(value);
    }
    content += value;
  }
  const signature = crypto
    .createHash("sha256")
    .update(`${content}${apiKey}`)
    .digest("hex");
  return signature;
};

Mini App sử dụng secret data xác thực lại với Server​

Sau khi có callback từ API openBioAuthentication, nếu thành công, bạn cần dùng secretData ở đã tạo ở bước trước để xác thực/login với Server của bạn.

Ví dụ hiện thực API xác thực tài khoản với Biometric

  • URL: https://yourdomain/biometric/verify
  • Method: POST
  • Content-Type: application/json
PropertyTypeDefaultRequiredDescriptionMinimum Version
secretDataString2.5.3
timestampLongThời gian sự kiện2.5.3
accessTokenStringZalo Access Token để định danh tài khoản Zalo2.5.3

Quy trình tích hợp Biometric Authentication trên Zalo

zi-chevron-up