OAuth2 / OIDC — kết nối một dịch vụ với Omniscol

Omniscol làm gì trong vai trò máy chủ OAuth2

Một dịch vụ bên ngoài — một tác nhân AI, một bộ kết nối, một trang tổng quan — trở thành ứng dụng khách được khai báo trong tài khoản của bạn; một người dùng của trường phê duyệt quyền truy cập đó qua màn hình đồng ý; khi ấy dịch vụ nhận được một mã thông báo truy cập có thời hạn ngắn, chỉ có hiệu lực trong những phạm vi đã cấp và trong quyền hạn của chính người dùng.

Cơ chế này khác với SSO người dùng được mô tả ở OIDC / SSO, nơi Omniscol ngược lại đóng vai ứng dụng khách của nhà cung cấp danh tính của bạn để đăng nhập cho người dùng. Ở đây, Omniscol nằm ở phía máy chủ: chính các dịch vụ mới là bên kết nối tới nó.

Hai tích hợp của Omniscol dùng đến máy chủ này:

• MCP — việc xác thực chuẩn của một tác nhân AI đi qua máy chủ OAuth2 này (xem MCP — kết nối một tác nhân AI bên ngoài);
• OneRoster — bên phát dữ liệu OneRoster xác thực bằng một mã thông báo OAuth2 giữa máy với máy do chính máy chủ này cấp (xem OneRoster).

Mọi dịch vụ khác tuân thủ OAuth2 / OIDC đều có thể kết nối theo đúng cách đó.

Khám phá và các điểm truy cập của giao thức

Omniscol công bố siêu dữ liệu khám phá của mình tại các địa chỉ .well-known chuẩn, đặt ở gốc tên miền của tài khoản bạn (ví dụ https://truong-cua-ban.omniscol.com). Một ứng dụng khách tuân thủ sẽ tự tìm thấy ở đó toàn bộ các điểm truy cập, không cần cấu hình thủ công:

• /.well-known/oauth-authorization-server — siêu dữ liệu của máy chủ ủy quyền (RFC 8414);
• /.well-known/openid-configuration — siêu dữ liệu OpenID Connect (nội dung giống hệt mục trên);
• /.well-known/jwks.json — các khóa công khai dùng để kiểm tra (JWKS), cho phép xác minh chữ ký của id_token;
• /.well-known/oauth-protected-resource — siêu dữ liệu của tài nguyên được bảo vệ (RFC 9728).

Bộ siêu dữ liệu này công bố các điểm truy cập của giao thức:

• /oauth/authorize — yêu cầu ủy quyền (màn hình đăng nhập rồi tới màn hình đồng ý);
• /oauth/token — đổi mã lấy mã thông báo, và làm mới;
• /oauth/register — đăng ký động ứng dụng khách (RFC 7591);
• /oidc/userinfo — thông tin về người dùng đang đăng nhập (OIDC);
• /oauth/revoke — thu hồi một mã thông báo (RFC 7009).

Những điểm truy cập giao thức này là công khai: chúng không dành riêng cho tài khoản Premium và không cần mở thủ công. Chỉ có màn hình quản lý ứng dụng khách mô tả bên dưới mới thuộc gói Premium.

Các luồng ủy quyền

Omniscol hỗ trợ ba luồng OAuth2:

• Mã ủy quyền kèm PKCE — luồng mặc định cho một dịch vụ hoạt động thay mặt một người dùng. Dịch vụ chuyển hướng người dùng tới /oauth/authorize; sau bước đăng nhập và đồng ý, Omniscol trả về một mã ủy quyền (có hiệu lực 5 phút) để dịch vụ đem đổi tại /oauth/token. Phương pháp PKCE được chọn là S256, và response_type duy nhất được chấp nhận là code.
• Làm mới (refresh_token) — để kéo dài một quyền truy cập ủy nhiệm mà không phải qua lại bước đồng ý.
• Client credentials — luồng giữa máy với máy, không có người dùng, đặc biệt được các bên nhận dữ liệu OneRoster sử dụng. Ứng dụng khách tự xác thực trực tiếp và nhận về một mã thông báo truy cập.

Khi đổi mã, máy chủ cấp một mã thông báo truy cập (Bearer, có hiệu lực 1 giờ) và, với các luồng có người dùng, một mã thông báo làm mới (có hiệu lực 30 ngày). Khi phạm vi openid được yêu cầu, một id_token OIDC đã ký cũng được cấp kèm; chữ ký của nó kiểm tra được qua /.well-known/jwks.json. Luồng client_credentials chỉ cấp một mã thông báo truy cập, không kèm làm mới lẫn id_token.

Sau đó mã thông báo truy cập được đưa vào tiêu đề HTTP Authorization: Bearer <token>. Ở mỗi lần gọi, Omniscol kiểm tra chữ ký của nó, kiểm tra ứng dụng khách vẫn còn hoạt động, người dùng vẫn còn tồn tại và vẫn giữ vai trò cần thiết, và các phạm vi của mã thông báo có phủ đúng điểm truy cập đang được gọi hay không — nếu không, lệnh gọi bị từ chối.

Phạm vi và sự đồng ý

Những phạm vi bạn quản lý trên một ứng dụng khách là:

• read:basic — đọc thời khóa biểu, trang tổng quan và các màn hình tra cứu (mô-đun Trang chủ, Thời khóa biểu, Trang tổng quan, Quản lý thời khóa biểu);
• read:user — đọc danh sách người dùng;
• write:data — ghi trên chính những mô-đun tra cứu đó;
• admin — quyền quản trị (mô-đun Quản trị, Quản lý vắng mặt, Quản lý thời khóa biểu).

Máy chủ còn biết đến các phạm vi OIDC (openid, email, profile) và các phạm vi OneRoster chỉ đọc (tiền tố imsglobal.org). Nhóm sau là nhóm đặc quyền: một ứng dụng khách không thể tự gán chúng cho mình qua đăng ký động; chúng phải được một quản trị viên cấp phát trên hồ sơ của ứng dụng khách.

Phạm vi thực sự được cấp là phần giao giữa những gì ứng dụng khách yêu cầu và những gì đã đăng ký cho nó: một ứng dụng khách không bao giờ nhận được nhiều hơn những gì ghi trên hồ sơ của mình. Trong luồng có người dùng, màn hình đồng ý (/oauth/consent) hiển thị tên và logo của dịch vụ đang yêu cầu cùng danh sách dễ đọc các phạm vi được yêu cầu, kèm hai nút Chấp nhận và Từ chối. Phê duyệt sẽ cấp mã ủy quyền và đưa người dùng trở lại dịch vụ; từ chối sẽ đưa họ trở lại kèm lỗi access_denied.

Đăng ký động ứng dụng khách

Điểm truy cập /oauth/register triển khai việc đăng ký động (Dynamic Client Registration, RFC 7591): một dịch vụ tuân thủ có thể tự khai báo mình làm ứng dụng khách, không cần can thiệp thủ công từ trước. Chính điều này cho phép một tác nhân MCP tự cấu hình chỉ từ URL của máy chủ.

Đăng ký động không thể tự gán cho mình phạm vi đặc quyền (các phạm vi OneRoster): chúng bị âm thầm loại bỏ, và nếu không còn phạm vi hợp lệ nào, read:basic được cấp mặc định. Các phạm vi đặc quyền vẫn chỉ dành cho việc cấp phát của một quản trị viên.

Màn hình quản lý ứng dụng khách OAuth2

Trên các tài khoản Premium, bạn quản trị ứng dụng khách từ Quản trị → Nhập và xuất dữ liệu, mục OAuth2, bằng nút OAuth2. Việc truy cập trước hết đòi hỏi mật khẩu quản trị viên — một bước xác nhận thêm trước khi màn hình mở ra.

Màn hình liệt kê các ứng dụng khách đã đăng ký và, với từng ứng dụng, hiển thị trạng thái (đang hoạt động / ngừng hoạt động), tên, các phạm vi, các đầu mối liên hệ và các URI (trang web, logo, URI chuyển hướng). Bạn có thể:

• Đăng ký một ứng dụng khách — điền tên, một software_id tùy chọn, các phạm vi, các đầu mối liên hệ, trang web, logo và các URI chuyển hướng. Khi tạo, Omniscol hiển thị client_id và client_secret đúng một lần duy nhất.
• Sửa một ứng dụng khách — chỉ những trường an toàn mới sửa được: tên, phạm vi, đầu mối liên hệ, trang web và logo. Các URI chuyển hướng, software_id và bí mật không sửa được ở đây.
• Bật hoặc tắt một ứng dụng khách — mã thông báo của một ứng dụng khách đã tắt sẽ bị từ chối ngay từ lệnh gọi kế tiếp.
• Xóa một ứng dụng khách — việc xóa là vĩnh viễn.

Bí mật của ứng dụng khách

client_secret chỉ hiển thị đúng một lần duy nhất, lúc đăng ký. Về phía mình, Omniscol chỉ giữ lại một mã băm của bí mật, không bao giờ giữ bí mật ở dạng rõ: nó không thể được hiển thị lại hay lấy lại về sau. Hãy chép nó ngay vào một trình quản lý bí mật.

Còn client_id thì tất định: nó suy ra từ tên tài khoản, tên ứng dụng khách và một mã băm lấy từ siêu dữ liệu kỹ thuật của ứng dụng khách đó. Nhờ vậy, hai lần đăng ký giống hệt nhau sẽ rơi vào cùng một mã định danh.

Làm mới bí mật (xoay vòng)

Bí mật xoay vòng được: thao tác này cấp một bí mật mới, chỉ giữ lại mã băm mới, và chỉ trả về bí mật mới ấy một lần. Thao tác này được thực hiện qua điểm truy cập quản lý đăng ký động (/oauth/register/<client_id>/rotation) và đòi phải xuất trình mã thông báo đăng ký đã trao cho ứng dụng khách lúc nó đăng ký động. Vì thế thao tác này không khởi động được từ màn hình quản lý nói trên: màn hình đó không xử lý mã thông báo ấy.

OAuth2 hay khóa API: chọn cái nào

Omniscol đưa ra hai cơ chế truy cập dành cho máy, với hai mô hình tin cậy khác nhau:

• OAuth2 (trang này) — một bên thứ ba đã đăng ký nhận được, sau khi có sự đồng ý của một người dùng, một mã thông báo có thời hạn ngắn (1 giờ), bị giới hạn trong các phạm vi đã cấp, làm mới được và thu hồi được (bằng cách tắt ứng dụng khách). Luồng client_credentials còn bao quát thêm trường hợp giữa máy với máy không có người dùng. Đây là phương thức phù hợp với một dịch vụ bên thứ ba đã xác định, với MCP và với OneRoster.
• Khóa API (xem API Omniscol) — một mã thông báo độc lập do máy chủ ký, mang sẵn trong mình một danh sách các điểm truy cập được phép và do chính bạn trao cho hệ thống bên ngoài: không có bên thứ ba đăng ký, không có màn hình đồng ý, không có làm mới. Đây là việc quản trị viên ủy nhiệm chính quyền hạn của mình cho một hệ thống mà họ làm chủ.

Tóm lại: khóa API phù hợp khi chính bạn trao quyền truy cập cho một hệ thống bạn kiểm soát; OAuth2 phù hợp khi một dịch vụ bên thứ ba đã xác định cần có được quyền truy cập ủy nhiệm, giới hạn theo phạm vi và thu hồi được, hoặc khi giao thức bắt buộc như vậy (MCP, OneRoster).