Plugin OpenID Connect

Plugin OpenID Connect (tên kỹ thuật openid-connect, nhóm Authentication) bảo vệ Route / Service bằng luồng xác thực OAuth 2.0 / OpenID Connect (OIDC) thông qua một Identity Provider (IdP) bên ngoài như Keycloak, Auth0, Google, Okta.

Plugin có 2 chế độ, chọn bằng thuộc tính bearer_only:

Chế độ	bearer_only	Cách hoạt động
Authorization Code	false (mặc định)	API Gateway chuyển người dùng sang trang đăng nhập của IdP, rồi quay lại ứng dụng và tự quản lý session. Phù hợp ứng dụng web.
Bearer token	true	Mọi request phải kèm access token hợp lệ, không chuyển hướng đăng nhập. Phù hợp API và microservice không giữ session.

Trường hợp sử dụng

• Tổ chức đã có IdP và yêu cầu người dùng đăng nhập bằng tài khoản IdP trước khi truy cập ứng dụng web phía sau API Gateway.
• API dành cho microservice hoặc đối tác, chỉ chấp nhận access token do IdP cấp.
• API chỉ cho phép gọi khi access token có đủ các scope yêu cầu.

cảnh báo

Chuẩn bị trước 3 thông tin từ IdP: client_id, client_secret và discovery URL (dạng https://your-idp.example.com/.well-known/openid-configuration).

Tạo plugin OpenID Connect

Để tạo plugin OpenID Connect, bạn thực hiện các bước sau:

1. Chọn API Gateway → Plugin ở menu bên trái, chọn API Gateway ở góc trên bên phải, nhấn New plugin, rồi chọn OpenID Connect trong popup Add plugin. Bạn cũng có thể thêm từ tab Plugins của Route / Service, xem Thêm Plugin.

2. Nhập Display Name tại mục Basic Information. Xem Basic Information.

3. Chọn mục Configuration. Form hiển thị sẵn 5 thuộc tính bắt buộc, kèm khối Quick Start Templates:

Attribute	Bắt buộc	Mô tả
bearer_only	Y	false (mặc định): chế độ Authorization Code, chuyển người dùng sang IdP đăng nhập. true: chỉ chấp nhận request có sẵn bearer access token hợp lệ.
client_id	Y	OAuth 2.0 Client ID của API Gateway đã đăng ký tại IdP.
client_secret	Y	OAuth 2.0 Client Secret để API Gateway xác thực với IdP khi gọi token / introspection endpoint.
discovery	Y	URL tài liệu OIDC Discovery (.well-known/openid-configuration), nơi IdP công bố các endpoint (authorization, token, userinfo, jwks…).
scope	Y	Các scope OIDC yêu cầu, quyết định thông tin người dùng IdP trả về. Phải có openid để nhận claim sub định danh người dùng.

Nhấn Attribute (N) để bật thêm các thuộc tính khác nếu cần:

Attribute	Bắt buộc	Mô tả
session	N	Object chứa secret, khóa (tối thiểu 16 ký tự) để mã hóa session cookie khi bearer_only là false.
redirect_uri	N	URI IdP chuyển về sau khi đăng nhập thành công, nên là đường dẫn con của Route. Mặc định /callback.
logout_path	N	Đường dẫn trên API Gateway, request tới đường dẫn này sẽ đăng xuất phiên OIDC hiện tại.
token_endpoint_auth_method	N	Cách API Gateway xác thực khi gọi token endpoint để đổi authorization code lấy token, ví dụ client_secret_basic, client_secret_post.
use_jwks	N	Dùng JSON Web Key Set (JWKS) của IdP để kiểm chứng chữ ký token.
required_scopes	N	Các scope bắt buộc có trong access token, dùng cùng introspection khi bearer_only là true. Thiếu scope thì request bị từ chối 403.
introspection_endpoint	N	URL introspection endpoint (RFC 7662) để kiểm tra access token. Để trống thì lấy theo discovery.
introspection_endpoint_auth_method	N	Cách API Gateway xác thực khi gọi introspection endpoint.
ssl_verify	N	Kiểm tra chứng chỉ SSL của IdP.
leeway	N	Dung sai (giây) khi kiểm tra hạn token, bù lệch đồng hồ giữa IdP và API Gateway.

Dùng Quick Start Templates (tùy chọn): nhấn Use Template trên thẻ tương ứng để điền nhanh cấu hình.

Template	Dùng khi	Thuộc tính được điền thêm
Standard Authorization Flow (Authorization Code, Authorization Code + PKCE)	Ứng dụng web: người dùng đăng nhập ở IdP rồi quay lại ứng dụng.	session, redirect_uri, logout_path, token_endpoint_auth_method, use_jwks
Bearer Token Mode (Client Credentials, Introspection Flow)	API / microservice không giữ session, mọi request phải kèm access token.	bearer_only = true, required_scopes, introspection_endpoint, introspection_endpoint_auth_method, token_endpoint_auth_method, use_jwks. Bỏ session, redirect_uri, logout_path.

cảnh báo

Template chỉ điền giá trị giữ chỗ (your-client-id, your-client-secret, https://your-idp.example.com/...). Thay bằng giá trị thật của IdP trước khi nhấn Create.

4. Chọn mục Scope, chọn Global hoặc Scoped rồi gán Route / Service cần bảo vệ. Xem Scope.

5. Nhấn Create. Thông báo Plugin created successfully hiển thị. Kiểm tra lại cột Enabled trên danh sách, và tab Plugins của Route / Service nếu bạn gán Scoped.

Cấu hình mẫu

Cấu hình mặc định với 5 thuộc tính bắt buộc:

{
  "bearer_only": false,
  "client_id": "your-client-id",
  "client_secret": "your-client-secret",
  "discovery": "https://your-idp.example.com/.well-known/openid-configuration",
  "scope": "openid profile"
}

Sau khi dùng template Standard Authorization Flow:

{
  "bearer_only": false,
  "client_id": "your-client-id",
  "client_secret": "your-client-secret",
  "discovery": "https://your-idp.example.com/.well-known/openid-configuration",
  "scope": "openid profile",
  "session": {
    "secret": "change-me-session-secret"
  },
  "redirect_uri": "/callback",
  "logout_path": "/logout",
  "token_endpoint_auth_method": "client_secret_basic",
  "use_jwks": true
}

Sau khi dùng template Bearer Token Mode:

{
  "bearer_only": true,
  "client_id": "your-client-id",
  "client_secret": "your-client-secret",
  "discovery": "https://your-idp.example.com/.well-known/openid-configuration",
  "scope": "openid",
  "required_scopes": [],
  "introspection_endpoint": "https://your-idp.example.com/oauth2/introspect",
  "introspection_endpoint_auth_method": "client_secret_basic",
  "token_endpoint_auth_method": "client_secret_basic",
  "use_jwks": true
}

ghi chú

Đường dẫn introspection khác nhau tùy IdP. Lấy đúng giá trị introspection_endpoint mà discovery document của IdP công bố, hoặc xóa field này để API Gateway tự lấy theo discovery.

Kiểm tra hoạt động

Khi người dùng truy cập Route / Service được bảo vệ:

• bearer_only là false: trình duyệt được chuyển sang trang đăng nhập của IdP trước khi vào ứng dụng.
• bearer_only là true: request không kèm access token hợp lệ bị từ chối 401.

Bước tiếp theo

• Tổng quan Plugin
• Plugin CORS