API Omniscol — mã thông báo xác thực

Khóa và mã thông báo: hai đối tượng khác nhau

Omniscol phân biệt hai đối tượng mà bạn không nên nhầm lẫn.

Khóa là một đối tượng tồn tại lâu dài, được giữ ở phía Omniscol. Khóa gồm:

• một mã định danh ngắn, sinh ngẫu nhiên, công khai: đây chính là thứ danh sách hiển thị, và nó đi kèm trong mỗi mã thông báo để chỉ ra khóa cần dùng khi kiểm tra;
• một nhãn mô tả, sửa được bất cứ lúc nào;
• một ngày hết hạn tùy chọn, sửa được bất cứ lúc nào;
• một bí mật ngẫu nhiên dài, sinh ở phía máy chủ, dùng làm khóa ký mật mã.

Mã định danh, nhãn và ngày hết hạn là những thông tin quản trị: mã định danh chỉ là một tham chiếu công khai, không phải yếu tố bí mật. Còn bí mật mới là vật liệu ký duy nhất: được sinh ngẫu nhiên khi tạo khóa, nó ở lại phía máy chủ, không sửa được, và không bao giờ được hiển thị hay trả về — dù lúc tạo khóa hay trong danh sách khóa. Và ngay cả khi bị lộ, riêng nó cũng không đủ để giả mạo một mã thông báo: chữ ký còn kết hợp nó với một giá trị salt riêng của tài khoản và một bí mật của máy chủ mà hai thứ này cũng không bao giờ rời khỏi Omniscol.

Mã thông báo là một JWT (JSON Web Token) độc lập, được ký bằng bí mật của khóa. Đây chính là thứ bạn chuyển cho hệ thống bên ngoài. Phần nội dung đã ký của nó mang theo tài khoản liên quan, danh sách điểm truy cập được phép, khóa đã sinh ra nó và ngày hết hạn của chính nó.

Nói cách khác: khóa dùng để ký, mã thông báo là thứ được ký. Cùng một khóa có thể ký nhiều mã thông báo — tất cả đều kiểm tra được bằng cùng một bí mật, nên tất cả cũng bị thu hồi cùng lúc nếu khóa biến mất.

Omniscol không lưu mã thông báo: hệ thống sinh ra nó, hiển thị một lần, rồi kiểm tra lại ở mỗi lệnh gọi bằng cách dựng lại chữ ký từ bí mật của khóa (HMAC SHA-256). Vì vậy, không một quyền nào mà mã thông báo mang theo có thể bị sửa đổi nếu thiếu bí mật này.

Tạo một mã thông báo

Màn hình Chung nằm trong Quản trị → Nhập và xuất dữ liệu trên các tài khoản Premium. Việc tạo diễn ra theo hai bước: trước hết tạo một khóa, rồi sinh một mã thông báo từ khóa đó.

1. Tạo khóa — nhập một nhãn dễ hiểu và, nếu quyền truy cập chỉ tạm thời, một ngày hết hạn. Nhãn và ngày hết hạn vẫn sửa được về sau; bí mật ký thì không.
2. Sinh mã thông báo — chọn khóa, tích chọn những điểm truy cập được phép, nếu cần thì chọn thêm một ngày hết hạn riêng cho mã thông báo, rồi sinh JWT.

Khi sinh mã thông báo, Omniscol hiển thị nó đúng một lần. Hãy chép ngay vào một trình quản lý bí mật: nó sẽ không được hiển thị lại nữa. Thời hạn của mã thông báo được ghi thẳng vào phần nội dung đã ký: về sau không sửa được. Muốn đổi ngày này, bạn hãy sinh một mã thông báo mới.

Như vậy có hai mức thời hạn, độc lập với nhau:

• thời hạn của khóa — sửa được từ danh sách khóa; khi đến hạn, mọi mã thông báo sinh ra từ khóa đó đều bị từ chối (lệnh gọi thất bại với mã 401);
• thời hạn của mã thông báo — ấn định lúc sinh, ghi trong JWT, và sau đó không sửa được.

Những điểm truy cập được phép

Một mã thông báo chỉ cho phép gọi những điểm truy cập đã tích chọn lúc sinh ra nó: đừng bao giờ mặc định rằng nó bao phủ toàn bộ API. Danh sách được phép đi kèm trong mã thông báo và được kiểm tra ở mỗi lệnh gọi; lệnh gọi tới một điểm truy cập không được phép sẽ bị từ chối (401).

Ngoài từng điểm truy cập riêng lẻ, danh sách lựa chọn còn cung cấp các lối tắt theo mô-đun:

• chọn riêng mục của một mô-đun là cho phép toàn bộ các điểm truy cập của mô-đun đó;
• các biến thể theo thao tác — Đọc, Chỉnh sửa, Tạo mới, Xóa — giới hạn mô-đun về một loại lệnh gọi duy nhất.

Vì vậy, tích chọn “Thời khóa biểu [Đọc]” là cấp toàn bộ quyền đọc thời khóa biểu mà không mở bất kỳ quyền ghi nào, và cũng không phải tích từng điểm truy cập một. Hãy giữ ở mức vừa đủ: chỉ cấp những mô-đun và những thao tác thật sự cần cho tích hợp.

Sử dụng một mã thông báo

Hai cách thông dụng để gửi mã thông báo tới API:

• Tiêu đề HTTP: Authorization: Bearer <token> (khuyến nghị).
• Query string: ?auth=<token> (tiện khi gỡ lỗi, nhưng xuất hiện trong nhật ký HTTP — nên tránh trong môi trường vận hành).

Ví dụ với curl, cần thay bằng một điểm truy cập thật lấy từ OpenAPI:

curl -H "Authorization: Bearer $TOKEN" \
  https://ten-truong-cua-ban.omniscol.com/api/<mo-dun>/<diem-truy-cap>

Tài liệu OpenAPI

Màn hình Nhập và xuất dữ liệu hiển thị một liên kết OpenAPI 3.1, mở trong Swagger Editor bản đặc tả hiện có của tài khoản. Ở đó bạn tìm thấy:

• danh sách các điểm truy cập API được mở,
• lược đồ của dữ liệu trao đổi,
• các phương thức và tham số,
• các phản hồi mong đợi.

Bản đặc tả cũng được chính tài khoản của bạn cung cấp trực tiếp, không cần xác thực:

• /api/guest/openapi.json — bản đặc tả ở định dạng JSON;
• /api/guest/openapi.yaml (hoặc /api/guest/openapi?yaml=true) — cùng nội dung ở định dạng YAML;
• /api/guest/school_schema.json — lược đồ JSON của dữ liệu tài khoản.

Toàn bộ phần trợ giúp cho trợ lý AI của bạn

Cổng thông tin còn công bố toàn bộ phần trợ giúp của Omniscol trong một tệp văn bản duy nhất, sẵn sàng làm cơ sở tri thức cho một trợ lý AI (dự án Claude, GPT tùy chỉnh…):

• omniscol.com/vi/llms-full.txt — toàn bộ hướng dẫn ở dạng Markdown, có trong mọi ngôn ngữ của phần trợ giúp (/en/llms-full.txt, /fr/llms-full.txt…);
• omniscol.com/llms.txt — mục lục theo chuẩn llms.txt, được các công cụ AI tự động phát hiện.

Thu hồi một quyền truy cập

Việc thu hồi diễn ra ở cấp khóa, chứ không phải từng mã thông báo riêng lẻ.

Màn hình liệt kê các khóa đã dùng để sinh mã thông báo. Xóa một khóa sẽ xóa bí mật ký của khóa đó ở phía Omniscol: từ lúc ấy, không chữ ký nào phái sinh từ bí mật này còn kiểm tra được nữa, và mọi lệnh gọi mang mã thông báo sinh ra từ khóa đó đều thất bại với mã 401. Chính sự vắng mặt của bí mật làm mã thông báo mất hiệu lực, chứ không phải một danh sách thu hồi.

Với bộ phận công nghệ thông tin, có hai hệ quả:

• Không có cơ chế thu hồi từng mã thông báo. Omniscol không lưu các JWT đã phát hành và không thể vô hiệu hóa riêng một cái: một mã thông báo đã sinh ra vẫn còn hiệu lực cho đến khi chính nó hết hạn, hoặc cho đến khi khóa của nó bị xóa hay hết hạn.
• Sửa thời hạn của một khóa có tác dụng ngay lập tức lên mọi mã thông báo của khóa đó: rút ngắn ngày này sẽ cắt quyền truy cập của toàn bộ mã thông báo sinh ra từ khóa.

Thực hành tốt: hãy xóa ngay khóa nào bạn nghi là đã bị lộ, rồi tạo lại một khóa thay thế với nhãn rõ ràng.

Mỗi đích đến và mỗi mục đích một khóa riêng

Vì việc thu hồi diễn ra theo khóa, hãy dành riêng một khóa cho mỗi tích hợp (một phần mềm bên ngoài = một khóa). Bí mật của một khóa chỉ ký những mã thông báo của chính nó: xóa khóa đó chỉ làm mất hiệu lực các quyền truy cập của tích hợp liên quan, không đụng tới những tích hợp khác.

Ngược lại, một khóa duy nhất dùng chung cho nhiều hệ thống khiến mọi lần thu hồi đều không thể chọn lọc: xóa khóa bị lộ sẽ cắt cùng lúc tất cả các hệ thống đang dùng nó.

Dành cho những tích hợp nào

API thường được dùng cho:

• hệ thống hiển thị (signage) riêng (ngoài các bảng thông tin có sẵn của Omniscol; xem Tùy chỉnh bảng thông tin),
• trang tổng quan bên ngoài tổng hợp Omniscol cùng các nguồn khác,
• bộ kết nối hoặc đồng bộ với một ERP hay một hệ thống thông tin nghiệp vụ,
• tác nhân AI tương thích MCP khai thác Omniscol qua máy chủ MCP; xem MCP — kết nối một tác nhân AI bên ngoài.

Để cấp quyền ủy nhiệm cho một dịch vụ bên thứ ba đã xác định (mã thông báo có phạm vi giới hạn, có sự đồng ý của người dùng, thu hồi được bằng cách tắt ứng dụng khách), bạn hãy ưu tiên máy chủ OAuth2 của Omniscol: xem OAuth2 / OIDC (nhà cung cấp).