Mã thông báo API

Một mã thông báo API (token) cho phép phần mềm của bên thứ ba gọi các điểm truy cập API của Omniscol thay mặt cho nhà trường, ở chế độ đọc và, nếu có chọn các điểm truy cập API ghi dữ liệu, ở cả chế độ ghi.

Công cụ này rất mạnh — vì vậy phải sử dụng hết sức thận trọng.

Tạo mã thông báo

Mã thông báo được tạo trong Chung (Nhập và xuất dữ liệu > Chung). Bạn cần cung cấp:

• một khóa (được tạo trong Omniscol, kèm nhãn và thời hạn nếu cần; ngày hết hạn của khóa có thể sửa lại sau),
• một phạm vi: danh sách các điểm truy cập API mà mã thông báo này được phép gọi (chỉ cấp đúng những gì thật sự cần thiết),
• tùy chọn thêm thời hạn của mã thông báo. Ngày này được ghi thẳng vào JWT sinh ra và sau đó không thể sửa được nữa.

Xóa khóa, hoặc khi khóa hết hạn, sẽ lập tức thu hồi mọi mã thông báo sinh ra từ khóa đó. Muốn đổi thời hạn của một mã thông báo riêng lẻ, bạn hãy tạo một JWT mới.

Cách sử dụng

Mã thông báo được gửi trong tiêu đề HTTP Authorization: Bearer <token>, hoặc (ít được khuyến nghị cho môi trường vận hành) trong URL qua ?auth=<token>.

Khuyến nghị sử dụng

• Mỗi tích hợp một khóa riêng — giúp việc thu hồi từng khóa trở nên độc lập và dễ dàng hơn.
• Phạm vi tối thiểu — chỉ tích chọn những API cần dùng, chứ không chọn hết theo mặc định.
• Đặt thời hạn đúng chỗ — dùng thời hạn của khóa để quản lý một tích hợp lâu dài; dùng thời hạn của mã thông báo cho một quyền truy cập tạm thời, không sửa đổi được.
• Thay khóa định kỳ — tạo lại khóa sau mỗi 6-12 tháng.
• Không đưa vào Git — mã thông báo không được nằm trong một kho mã nguồn công khai. Hãy dùng biến môi trường của máy chủ.

Khác biệt so với OIDC / SSO

Để cho người dùng thật đăng nhập bằng danh tính do nhà trường cấp, hãy dùng OIDC / SSO. Mã thông báo API dành cho các tích hợp kỹ thuật giữa máy chủ với máy chủ, không dành cho việc đăng nhập hằng ngày của người dùng.