Tổng quan FaceAuthen

FaceAuthen là dịch vụ xác thực dựa trên khuôn mặt của CAKE: người dùng đăng ký một hồ sơ (profile) khuôn mặt một lần, sau đó xác thực bằng một tấm selfie cho mỗi thao tác cần xác thực bổ sung tiếp theo. Trang này trình bày vòng đời hồ sơ, mô hình giao dịch, xác thực, và luồng xử lý đầu-cuối.

INFO

Mọi ví dụ trong tài liệu này dùng cùng một danh tính giả định — Nguyễn Văn A, CCCD 001xxxxxxxxx, user_id user_00000001, ref_id ref_00000001. Thông tin xác thực, token và key được ghi dạng <PLACEHOLDER>. Đây không phải dữ liệu thật; hãy thay toàn bộ bằng giá trị của bạn.

Điều kiện tiên quyết

Thông tin	Mô tả
Access ID	Một UUID định danh Tenant của bạn. Được gửi trong header `Authorization`. Do CAKE cung cấp.
Access Key	Secret key dùng để ký các request phía backend. Do CAKE cung cấp.
Base URL	Do CAKE cấp cùng bộ credentials, cho cả môi trường stage và production.
App-Id	Giới hạn phạm vi một giao dịch theo cấu hình riêng của từng app — cấu hình challenge và flash liveness. Mặc định là `default`.
Mobile SDK	Chụp ảnh selfie và tự ký request của nó bằng JWT riêng cho từng giao dịch.

Các ví dụ trong tài liệu này ghi base URL dưới dạng <BASE_URL> — hãy thay bằng giá trị CAKE cấp cho bạn.

Hai khái niệm cần nắm rõ

FaceAuthen có hai đối tượng riêng biệt, và nhầm lẫn giữa chúng là lỗi tích hợp phổ biến nhất.

Trường	Kiểu	Mô tả
Hồ sơ (Profile)	mỗi user	Template khuôn mặt đã đăng ký, khóa theo `user_id`. Được tạo bởi Đăng ký khuôn mặt, chỉnh sửa bởi Cập nhật Face Authen, xóa bởi Xóa Face Authen. Tồn tại lâu dài.
Giao dịch (Transaction)	mỗi lần xác thực	Một lần thử xác thực, khóa theo `ref_id`. Được tạo bởi Tạo giao dịch, đóng bởi Xác minh khóa xác thực giao dịch. Tồn tại ngắn hạn.

Một hồ sơ phải tồn tại trước khi bất kỳ lần xác thực nào có thể thành công. Một giao dịch là tùy chọn đối với một lần kiểm tra khuôn mặt đơn thuần, nhưng bắt buộc bất cứ khi nào bạn cần một kết quả có thể xác minh, kiểm toán được mà backend của bạn có thể tin tưởng.

Xác thực

Thông tin	Mô tả
HMAC — `Authorization: ATV <ACCESS_ID>:<SIGNATURE>`	Được backend của bạn dùng cho mọi endpoint trong phần này. Xem cách suy ra bên dưới.
JWT — `Authorization: Bearer {token}` cộng `X-Signature`	Được Mobile SDK dùng, ký request của nó bằng JWT riêng cho từng giao dịch làm khóa HMAC. Xem Ký request.
Signature của thiết bị — `Device-Id`, `X-Device-Key-Id`, `X-Device-Signature`	Được Mobile SDK thêm vào các request dùng Bearer token trên những tenant đã bật kiểm tra signature của thiết bị, dùng một khóa đã đăng ký cho thiết bị bằng Khởi tạo khóa ký. Xem Ký request.

WARNING

Access Key không bao giờ rời khỏi backend của bạn. SDK được Tạo giao dịch cấp một JWT riêng cho từng giao dịch và ký bằng JWT đó thay thế.

Phương án 1: Xác thực HMAC (backend đến FaceAuthen backend)

Các request server-to-server được xác thực bằng HMAC-SHA256, chứng minh cả tính toàn vẹn lẫn tính xác thực của nội dung request bằng một khóa dùng chung (shared secret) giữa backend của bạn và CAKE.

Header	Mô tả
`X-TV-Timestamp`	Timestamp hiện tại theo định dạng RFC3339. Ví dụ: `2019-04-21T18:00:15+07:00`
`Authorization`	`ATV <ACCESS_ID>:<SIGNATURE>`

text

StringToSign = HttpMethod + "\n" + UrlPath + "\n" + Timestamp + "\n" + HashedBody

# HttpMethod: POST, GET, PUT, PATCH hoặc DELETE
# UrlPath:    đường dẫn route tương đối, không gồm domain. Ví dụ: /v1/face_auth
# Timestamp:  thời điểm request theo định dạng RFC3339; phải khớp với header X-TV-Timestamp
# HashedBody: hex_encode(SHA256(raw body))

Signature = Base64(HmacSha256(AccessKeySecret, Utf8EncodingOf(StringToSign)))

javascript

const CryptoJS = require("crypto-js");

function tokenize(method, path, timestamp, body, key) {
  const hashed_body = CryptoJS.SHA256(body).toString(CryptoJS.enc.Hex);
  const formatted = `${method}\n${path}\n${timestamp}\n${hashed_body}`;
  const hmac = CryptoJS.HmacSHA256(formatted, key);
  const hashed = hmac.toString(CryptoJS.enc.Hex);
  return CryptoJS.enc.Base64.stringify(CryptoJS.enc.Hex.parse(hashed));
}

INFO

StringToSign dùng SHA256 của raw body mã hóa dạng hex. Một số tenant của CAKE được cấp phát dùng hash body mã hóa Base64 thay thế — hãy xác nhận với đội CAKE tenant của bạn đang dùng biến thể nào.

Phương án 2: JWT token (Mobile SDK đến FaceAuthen backend)

Tạo giao dịch trả về một JWT token giới hạn trong một giao dịch. Mobile SDK trình nó dưới dạng bearer token và dùng nó để ký body của từng request — một cơ chế khác với header ATV của backend.

Trường	Kiểu	Mô tả
`Authorization`	header	`Bearer {token}`
`X-TV-Timestamp`	header	Timestamp RFC3339 dùng trong signature.
`X-Signature`	header	HMAC-SHA256 mã hóa Base64 trên timestamp và body đã băm, dùng JWT làm khóa.

Cách suy ra đầy đủ có tại Ký request.

Cách hoạt động

sequenceDiagram
    autonumber
    participant App as Mobile App / SDK
    participant BE as Backend của bạn
    participant FA as FaceAuth Backend

    Note over App,FA: Giai đoạn 1 — Đăng ký (một lần cho mỗi user)
    App->>BE: Ảnh selfie
    BE->>FA: POST /v1/face_auth_register
    FA-->>BE: status success, face_auth VERIFIED

    Note over BE,FA: Giai đoạn 2 — Mở một lần xác thực
    BE->>FA: POST /v1/create_transaction (ký HMAC)
    FA-->>BE: id, status NOT_VERIFIED, token, level
    BE-->>App: token

    Note over App,FA: Giai đoạn 3 — Xác thực
    App->>FA: POST /v1/face_auth (Bearer token + X-Signature)
    FA-->>App: auth_check matched + score, authentication_key
    App-->>BE: authentication_key

    Note over BE,FA: Giai đoạn 4 — Redeem và quyết định
    BE->>FA: POST /v1/verify_transaction_key
    FA-->>BE: status VERIFIED
    BE-->>App: Hành động được duyệt

Giai đoạn 1 — Đăng ký

Ứng dụng của bạn chụp một hoặc nhiều ảnh selfie và chuyển chúng cho backend của bạn, nơi tải chúng lên và thu thập image ID.
POST /v1/face_auth_register tạo hồ sơ cho user_id đó. Việc đăng ký chạy các kiểm tra sanity, liveness và đối chiếu chéo giữa các ảnh; bất kỳ lỗi nào cũng sẽ từ chối việc đăng ký.

Giai đoạn 2 — Mở một lần xác thực

POST /v1/create_transaction mở một giao dịch, chọn level challenge và các sanity_options mà bước xác minh sẽ chạy.
Response mang theo id của giao dịch, status là NOT_VERIFIED, và token. Backend của bạn chuyển token cho ứng dụng.

Giai đoạn 3 — Xác thực

Ứng dụng chụp một ảnh selfie mới và gọi POST /v1/face_auth, xác thực bằng bearer token và ký nội dung theo Ký request.
Response trả về auth_check — matched, unmatched hoặc unsure cùng một điểm số — và, khi có một giao dịch được tham chiếu, một authentication_key.
Ứng dụng trả authentication_key về cho backend của bạn.

Giai đoạn 4 — Redeem và quyết định

POST /v1/verify_transaction_key redeem key và chuyển giao dịch sang VERIFIED. Hãy quyết định dựa trên kết quả phía server này, không phải những gì ứng dụng báo cáo.

WARNING

Các lần thất bại liên tiếp sẽ khóa hồ sơ — 2002206 User profile is locked, sau khi vượt face_auth_brute_force_limit_exceeded. Một hồ sơ bị khóa sẽ từ chối mọi lần thử tiếp theo cho đến khi Mở khóa hồ sơ được gọi. Hãy xây dựng một quy trình vận hành cho việc này trước khi ra mắt, nếu không người dùng bị khóa sẽ không có cách nào quay lại.

Cấu trúc response dùng chung

json

{
  "data": {
    "status": "success",
    "request_id": "cfc7b8d5-f2e2-437b-80e5-d600dfad26e2"
  },
  "errors": [],
  "success": true,
  "code": 0,
  "message": "Success"
}

Trường	Kiểu	Mô tả
`data.status`	string	`success` hoặc `failure`.
`data.request_id`	string	Request ID; cung cấp cho CAKE Support khi cần kiểm tra log.
`errors`	array	Chi tiết từng lỗi. Rỗng khi thành công.
`errors[].code`	string	Mã lỗi dạng máy đọc được.
`errors[].message`	string	Mô tả dạng người đọc được.
`errors[].detail`	object	Ngữ cảnh tùy chọn, ví dụ `field` nêu tên tham số không hợp lệ.
`success`	bool	Cuộc gọi có thành công hay không.
`code`	int	status code dạng số — `0` khi thành công.
`message`	string	Thông báo trạng thái.

Một HTTP 200 không có nghĩa là kiểm tra đã thành công. Hãy đọc success, rồi data.status, rồi đến kết quả cuối cùng.

Mã lỗi

FaceAuthen dùng chung dải mã số với các dịch vụ định danh khác của CAKE. Hai mã bạn sẽ rẽ nhánh nhiều nhất:

Mã	Thông báo
`2002201` · `2002205`	Xác thực khuôn mặt không khớp — xem cảnh báo về verdict trong Mã lỗi.
`2002206`	Hồ sơ người dùng đã bị khóa. Gỡ khóa bằng Mở khóa hồ sơ.
`4041002`	Không tìm thấy hồ sơ của người dùng — hãy đăng ký trước.

Bảng đầy đủ các mã dạng số và dạng chuỗi nằm ở Mã lỗi.

Bước tiếp theo

Tạo giao dịch — mở một lần xác thực và cấp token cho SDK
Ký request — cách SDK ký các request của nó
Đăng ký khuôn mặt — đăng ký hồ sơ khuôn mặt của một người dùng
Xác minh Face Authen — xác thực dựa trên hồ sơ
Lấy thông tin Face Authen — đọc trạng thái của một hồ sơ
Cập nhật Face Authen — thay thế các khuôn mặt đã đăng ký
Xóa Face Authen — hủy đăng ký một hồ sơ
Mở khóa hồ sơ — gỡ một lần khóa sau các lần thất bại do brute-force
Tải ảnh lên — biến dữ liệu ảnh selfie thành image ID mà các API này dùng
Khuyến nghị sử dụng — nhãn ảnh và quy ước metadata
Lấy giao dịch — đọc trạng thái hiện tại của một giao dịch
Xác minh khóa xác thực giao dịch — redeem key và đóng giao dịch
Mã lỗi — bảng lỗi đầy đủ dạng số và dạng chuỗi

Tổng quan FaceAuthen ​

Điều kiện tiên quyết ​

Hai khái niệm cần nắm rõ ​

Xác thực ​

Phương án 1: Xác thực HMAC (backend đến FaceAuthen backend) ​

Phương án 2: JWT token (Mobile SDK đến FaceAuthen backend) ​

Cách hoạt động ​

Giai đoạn 1 — Đăng ký ​

Giai đoạn 2 — Mở một lần xác thực ​

Giai đoạn 3 — Xác thực ​

Giai đoạn 4 — Redeem và quyết định ​

Cấu trúc response dùng chung ​

Mã lỗi ​

Bước tiếp theo ​