Khái niệm cốt lõi

Sơ đồ quan hệ

Bảng đi từ ngoài vào trong. Một workspace có nhiều ứng dụng; một ứng dụng có nhiều gói license, nhiều license và nhiều biến; một license chạy trên tối đa số máy mà nó cho phép; mỗi máy có thể có phiên đang chạy.

Workspace

Workspace là đơn vị sở hữu cao nhất. Mỗi tài khoản dashboard mới được tạo sẵn một workspace cá nhân trên gói Basic, và bạn là chủ sở hữu (owner). Những thứ sau gắn với workspace chứ không gắn với từng ứng dụng:

• Gói dịch vụ Basic hoặc Premium cùng mọi hạn mức: số ứng dụng, số key tạo mỗi ngày, số máy tối đa mỗi key, số tài khoản người dùng cuối, thời gian lưu nhật ký. Xem ở Tài khoản & tổ chức › Gói & sử dụng.
• Thành viên với ba vai trò: member (xem mọi thứ, quản lý license, người dùng cuối, thiết bị), admin (thêm ứng dụng, gói license, biến, luật truy cập, webhook, khoá API) và owner (thêm xoá ứng dụng, thanh toán, đội ngũ). Xem Workspace, thành viên và vai trò.
• Khoá Seller API và đại lý, nằm trong nhóm Kinh doanh.

Ứng dụng

Mỗi sản phẩm bạn phát hành là một ứng dụng. Vào Không gian làm việc › Ứng dụng, bấm Ứng dụng mới, nhập Tên rồi bấm Tạo. Ngay khi tạo, ứng dụng nhận một App ID dạng app_…, một cặp khoá ký riêng và một gói license mặc định tên "Standard" (30 ngày, 1 máy).

License, người dùng, biến, webhook, bản phát hành, luật truy cập và nhật ký đều thuộc riêng một ứng dụng, không dùng chung. Mỗi ứng dụng cũng chọn một Chế độ đăng nhập ở Phát hành & bản quyền › Đăng nhập & gói license: License key, Tài khoản, hoặc Tài khoản + license key. Tắt Cho phép đăng nhập ở Tích hợp › Cài đặt ứng dụng sẽ khiến mọi yêu cầu từ phần mềm bị từ chối với mã app_paused.

Khoá ký và khoá công khai

Mỗi ứng dụng có một cặp khoá Ed25519. Nửa bí mật nằm trên máy chủ, được mã hoá khi lưu, và dùng để ký mọi phản hồi, token offline và manifest cập nhật. Nửa công khai hiện ở trang Tổng quan trong khối mang tên ứng dụng, mục Khoá công khai, kèm App ID.

Bạn nhúng khoá công khai vào phần mềm. Nó chỉ xác minh được, không ký được gì, nên phát hành kèm build là an toàn; SDK từ chối mọi câu trả lời không được ký bởi một khoá mà build tin tưởng, nên máy chủ giả hay proxy sửa phản hồi đều vô dụng. Mỗi khoá có một mã kid (16 ký tự hex đầu của sha256 khoá công khai). Đổi khoá ở bảng Khoá ký trong Bảo mật ứng dụng › Bảo vệ, tab Phương pháp, khi dùng Bảo vệ Advanced, xem Khoá ký và xoay vòng khoá.

License và license key

License là quyền dùng một ứng dụng; license key là chuỗi người mua nhập vào. Key gồm 25 ký tự ngẫu nhiên chia nhóm 5 ký tự, có thể thêm tiền tố như PRO-. Chữ thường và khoảng trắng thừa được chuẩn hoá trước khi tra cứu.

Máy chủ không bao giờ lưu key, chỉ lưu mã băm HMAC-SHA256. Vì thế key chỉ hiện một lần lúc tạo, sau đó danh sách chỉ còn bản xem trước dạng PRO-XXXXX-…-XXXXX. Tạo key ở Phát hành & bản quyền › License bằng nút Tạo key, rồi sao chép hoặc Tải file .txt trước khi bấm Tôi đã lưu lại.

Trạng thái của license:

• Chưa dùng: chưa kích hoạt. Thời hạn chỉ bắt đầu tính từ lần kích hoạt đầu tiên.
• Đang dùng: đã kích hoạt, có thể có ngày hết hạn hoặc vĩnh viễn.
• Hết hạn: đã qua ngày hết hạn. Nếu gói có ân hạn, phần mềm vẫn chạy thêm số ngày đó và nhận trạng thái grace để cảnh báo người dùng.
• Tạm khoá: dừng tạm thời, Mở khoá để dùng lại.
• Thu hồi: dừng vĩnh viễn, không khôi phục được.

Tạm khoá và thu hồi đều kết thúc ngay các phiên đang chạy của license đó. Chi tiết ở Tạo và quản lý license.

Gói license (policy)

Gói license là khuôn mẫu cho license, trong mã nguồn gọi là policy, và trong form tạo key là trường Gói. Tạo ở Phát hành & bản quyền › Đăng nhập & gói license, mục Gói license, bấm Thêm gói. Một gói quy định thời hạn, số máy, quyền tính năng, dùng thử, luật chuyển máy, ân hạn, số ngày báo trước khi hết, thời gian máy im lặng thì trả suất và số phiên cùng lúc.

Mỗi ứng dụng có tối đa một gói được đánh dấu Gói mặc định cho key mới và tài khoản miễn phí; đánh dấu gói khác sẽ bỏ dấu ở gói cũ. Gói này được dùng khi bạn tạo key mà không chọn gói, và khi người dùng đăng ký tài khoản không kèm key.

Thời hạn và số máy được chép vào license ngay lúc tạo, nên sửa gói sau đó không đổi hai giá trị này ở license cũ. Các luật còn lại, như quyền tính năng, ân hạn hay chuyển máy, được đọc trực tiếp từ gói nên thay đổi áp dụng cho cả license đã phát hành.

Quyền tính năng (entitlement)

Quyền tính năng là cờ bật tắt một tính năng trong phần mềm, ví dụ bản Pro được xuất PDF còn bản thường thì không. Bạn khai báo chúng ở cấp ứng dụng trong ô Quyền tính năng (entitlement) của trang Đăng nhập & gói license, gồm Tên hiển thị và một khoá viết thường, số, dấu gạch dưới như export_pdf. Sau đó mỗi gói license chọn một phần trong danh sách đó.

Danh sách quyền nằm trong câu trả lời có chữ ký, nên không ai sửa được nó trên đường truyền. Trong phần mềm, bạn kiểm tra bằng clavis.has("export_pdf"); danh sách được làm mới sau mỗi heartbeat. Xem Gói license và quyền tính năng.

Thiết bị

Thiết bị là một máy đã kích hoạt license. Máy chủ nhận diện nó bằng ba thứ:

• Khoá thiết bị: cặp khoá Ed25519 do SDK sinh ở lần chạy đầu. Hãy lưu nó trong keychain của hệ điều hành để máy giữ nguyên danh tính.
• Fingerprint: mã băm ổn định của máy.
• Components: mã băm từng linh kiện (CPU, bo mạch, ổ đĩa...). Nếu ít nhất 3 linh kiện trùng khớp (mức mặc định), máy chủ coi đó vẫn là máy cũ. Hãy gửi nhiều hơn số đó để cài lại hệ điều hành hay thay một linh kiện không tốn thêm suất.

Khi license đã đủ số máy, máy mới bị từ chối với device_limit. Máy im lặng quá lâu theo cài đặt của gói (để trống là 72 giờ) sẽ tự trả suất. Một máy bị chặn thì bị chặn trên toàn ứng dụng, dù mang key nào. Xem Thiết bị, HWID và chuyển máy.

Phiên

Mỗi lần đăng nhập thành công tạo một phiên ses_…. Phiên gắn với khoá thiết bị đã tạo ra nó, nên ID phiên bị đánh cắp sang máy khác là vô dụng (session_device_mismatch). Phiên sống 60 phút và được gia hạn bởi mỗi heartbeat, nên phần mềm nên gọi heartbeat() khoảng 30 phút một lần. Khi bật Session lease ngắn hạn ở Bảo vệ Advanced, phiên chỉ sống bằng ba lần chu kỳ heartbeat đã đặt.

Trường Phiên cùng lúc của gói giới hạn số nơi chạy song song; đăng nhập lại trên cùng máy sẽ thay phiên cũ của máy đó. Phiên kết thúc khi phần mềm gọi logout(), khi bạn bấm Kết thúc phiên ở Người dùng cuối › Thiết bị & phiên, hoặc khi license bị tạm khoá, thu hồi hay đặt lại thiết bị.

Người dùng cuối

Người dùng cuối là người đăng nhập vào phần mềm của bạn bằng tên đăng nhập và mật khẩu, khác với thành viên dashboard. Họ chỉ xuất hiện ở chế độ Tài khoản và Tài khoản + license key; ở chế độ License key, chính license là danh tính.

Tên đăng nhập là duy nhất trong một ứng dụng, mật khẩu được lưu dạng băm Argon2. Khi đăng ký từ phần mềm, tài khoản luôn được gắn với một license: đăng ký kèm key thì gắn vào key đó, không kèm key thì máy chủ tạo một license nội bộ từ gói mặc định. Một license đã gắn với tài khoản thì không dùng để đăng ký tài khoản khác được (license_already_registered), và tài khoản không có license bị từ chối khi đăng nhập (no_license). Quản lý ở Người dùng cuối › Người dùng với các nút Thêm người dùng, Cấm, Bỏ cấm, Đặt lại mật khẩu. Xem Người dùng cuối.

Biến

Biến là cặp khoá và giá trị mà phần mềm nhận được sau khi đăng nhập, để gửi cấu hình, cờ tính năng hay thông báo mà không cần build mới. Thêm ở Tích hợp › Biến, bấm Thêm biến, chọn Phạm vi: Mọi người dùng, Một license hoặc Một người dùng. Khi trùng tên, giá trị cụ thể hơn thắng: người dùng trước, rồi license, rồi toàn cục.

Giao thức CLV1

Phần mềm nói chuyện với máy chủ qua CLV1. Mỗi yêu cầu được ký bằng khoá thiết bị trên App ID, phương thức, đường dẫn, mã băm body, thời điểm, một nonce dùng một lần và ID phiên. Máy chủ kiểm tra chữ ký, chỉ chấp nhận đồng hồ lệch tối đa 60 giây và từ chối nonce đã dùng (replayed_request). Mọi câu trả lời, kể cả lỗi, được ký bằng khoá ký của ứng dụng và gắn với nonce của yêu cầu, nên không thể phát lại hay giả mạo. SDK JavaScript dùng CLV1.1, bản mở rộng có kid để xoay vòng khoá. Đặc tả đầy đủ ở giao thức CLV1.

Ghép lại: một lần kích hoạt

import { ClavisClient, hashComponent } from "@clavisauh/sdk";

const clavis = new ClavisClient({
  baseUrl: "https://api.example.com",
  appId: "app_…", // ứng dụng
  appPublicKey: "<khoá công khai>", // nửa công khai của khoá ký
  device: { fingerprint: hashComponent(machineId) }, // thiết bị
  deviceKey: await loadDeviceKey(), // khoá thiết bị đã lưu trong keychain
});

const grant = await clavis.activate(licenseKey); // license key
console.log(grant.session.id, grant.license.state); // phiên, trạng thái license
if (clavis.has("export_pdf")) enablePdfExport(); // quyền tính năng từ gói
console.log(grant.variables); // biến

Khi activate() chạy, máy chủ lần lượt:

1. Kiểm tra chữ ký, đồng hồ và nonce của yêu cầu, ứng dụng có đang nhận đăng nhập không, và luật truy cập nếu dùng Bảo vệ Advanced.
2. Kiểm tra chế độ đăng nhập, chế độ bảo trì và phiên bản tối thiểu.
3. Tìm license theo mã băm của key, kiểm tra trạng thái và hạn dùng cộng ân hạn.
4. Kích hoạt license nếu đang Chưa dùng (thời hạn bắt đầu tính từ đây), nhận diện hoặc thêm thiết bị, kiểm tra số máy và số phiên cùng lúc. Nếu một bước bị từ chối, mọi thay đổi của bước này được huỷ.
5. Tạo phiên và trả về câu trả lời có chữ ký: phiên, license, quyền tính năng, thiết bị, biến, nextCheckSeconds, và token offline trừ khi Chế độ chỉ online đang bật.
6. Ghi kết quả, cho phép hay từ chối kèm lý do, vào Bảo mật ứng dụng › Nhật ký hoạt động.

Liên quan

• Bắt đầu nhanh
• Tạo và quản lý license
• Gói license và quyền tính năng
• SDK JavaScript