OpenID Connect (OIDC)
Tổng quan
OIDC (OpenID Connect) Policy cho phép xác thực và ủy quyền cho các API bằng cách tích hợp với một Nhà cung cấp OIDC. Điều này đảm bảo rằng chỉ những người dùng đã xác thực mới có thể truy cập API, thông qua cách tiếp cận dựa trên token hoặc một quy trình ủy quyền.
Chi tiết cấu hình
Đường dẫn yêu cầu / Đường dẫn không yêu cầu
- Required Path: Xác thực OIDC chỉ được thực thi cho các đường dẫn được liệt kê.
- Not Required Path: Xác thực OIDC bị bỏ qua cho các đường dẫn được liệt kê, nhưng được thực thi cho tất cả các đường dẫn khác.
- Nếu không có đường dẫn nào được chỉ định, xác thực OIDC sẽ áp dụng cho tất cả các đường dẫn.
- Việc chuyển đổi giữa các tùy chọn đường dẫn sẽ yêu cầu xác nhận.
Cấu hình loại cấp phép
Chính sách OIDC hỗ trợ hai Grant Types, xác định quy trình xác thực:
- Authorization Code Grant: Chuyển hướng người dùng đến nhà cung cấp OIDC để xác thực.
- Password Grant: Trực tiếp trao đổi thông tin xác thực của người dùng để lấy một ID token.
Mỗi loại cấp phép có bộ cấu hình riêng:
Authorization Code Grant:Quy trình này chủ yếu được sử dụng cho web applications, nơi người dùng xác thực qua một trang đăng nhập.
| Configuration Field | Description |
|---|---|
| Realm | Tên của miền xác thực. Ví dụ: realms_name |
| Client ID | Định danh duy nhất được cấp bởi nhà cung cấp OIDC. |
| Client Secret | Mật khẩu của client cần thiết cho xác thực. |
| Discovery | URL đến điểm cuối khám phá của nhà cung cấp (ví dụ: https://oidcprovider/.well-known/openid-configuration). |
| Logout Path | Điểm cuối đăng xuất cho người dùng (ví dụ: /logout). |
| Redirect URI After Logout | Tham số và giá trị URI chuyển hướng cho đường dẫn đăng xuất |
| Bearer Only | Xác định xem token bearer có cần thiết hay không: có (chỉ xác thực bằng token) hoặc không (cho phép cả xác thực bằng token và chuyển hướng đăng nhập). |
| Scope | Xác định mức độ truy cập (mặc định: openid). |
| Introspection Endpoint | URL để xác thực token. |
| Login URL | Điểm cuối API cho đăng nhập người dùng. |
| Cookie Domain | Miền liên quan đến cookie xác thực (ví dụ: skapim.com). |
| Bypass Header Name | Cho phép bỏ qua xác thực cho các yêu cầu cụ thể bằng cách sử dụng một khóa tiêu đề (ví dụ: x-oidc-api-key). |
| Bypass Key | Giá trị khóa bỏ qua thực tế. |
| Refresh Token Expiration | Thời gian hết hạn token (mặc định: 3600 giây). |
| SameSite | Cài đặt cookie để kiểm soát việc xử lý yêu cầu giữa các trang. Tùy chọn: Lax, Strict, hoặc None. |
| Secure | Bật hoặc tắt cookie bảo mật (mặc định: false). |
| Unauth Action | Xác định hành vi khi xác thực thất bại. Tùy chọn: Chuyển hướng đến trang đăng nhập hoặc Trả về 401 (Từ chối). |
| Allow IP / Deny IP | Cho phép hoặc chặn các IP cụ thể khỏi xác thực OIDC. |
Quy trình này thường được sử dụng cho machine-to-machine authentication hoặc các client đáng tin cậy.
| Configuration Field | Description |
|---|---|
| Realm | Tên của miền xác thực. Ví dụ: auth |
| Client ID | Định danh duy nhất được cấp bởi nhà cung cấp OIDC (ví dụ: account). |
| Client Secret | Mật khẩu của client cần thiết cho xác thực. |
| Discovery | URL đến điểm cuối khám phá của nhà cung cấp (ví dụ: https://oidcprovider/.well-known/openid-configuration). |
| Logout Path | Điểm cuối đăng xuất cho người dùng (ví dụ: /Logout). |
| Redirect URI path | Điểm cuối để chuyển hướng người dùng sau khi đăng nhập (ví dụ: /auth/api/login). |
| Scope | Xác định mức độ truy cập (mặc định: openid). |
| SameSite | Cài đặt cookie để kiểm soát việc xử lý yêu cầu giữa các trang. Tùy chọn: Lax, Strict, hoặc None. |
| Secure | Chuyển đổi để bật / tắt tùy chọn bảo mật |
| Refresh Token Expiration | Thời gian hết hạn token (mặc định: 3600 giây). |
| Login URL | Điểm cuối API cho đăng nhập người dùng. |
| Session Name | Xác định tên lưu trữ phiên (ví dụ: apim_prod_session). |
| Cookie Domain | Miền liên quan đến cookie xác thực (ví dụ: skapim.com). |
| Bypass Header Name | Cho phép bỏ qua xác thực cho các yêu cầu cụ thể bằng cách sử dụng một khóa tiêu đề (ví dụ: x-oidc-api-key). |
| Bypass Key | Giá trị khóa bỏ qua thực tế. |
| Redirect After Login URI | URL để chuyển hướng người dùng sau khi đăng nhập thành công. |
| Redirect After Logout URI | URL để chuyển hướng người dùng sau khi đăng xuất. |
Lưu ý:
- Authorization Code Grant yêu cầu chuyển hướng đến trang đăng nhập, trong khi Password Grant là một yêu cầu API trực tiếp.
- Bearer Only Mode:
- Nếu được đặt thành có, chỉ cho phép xác thực dựa trên token.
- Nếu được đặt thành không, cả chuyển hướng đăng nhập và xác thực bằng token đều được hỗ trợ.
Lựa chọn cơ sở dữ liệu Redis
Dữ liệu phiên có thể được lưu trữ trong các loại cơ sở dữ liệu Redis khác nhau. Redis type được chọn xác định các cấu hình cần được thiết lập.
APIM Redis (Default)- Sử dụng APIM Redis tích hợp sẵn cho lưu trữ phiên.
- Không cần cấu hình bổ sung.
- Cho phép kết nối đến một phiên bản Redis bên ngoài.
| Configuration Field | Description |
|---|---|
| Redis Host | Địa chỉ của máy chủ Redis (ví dụ: 127.0.0.1). |
| Redis Port | Số cổng của máy chủ Redis (ví dụ: 6379). |
| Redis Password | Mật khẩu cho xác thực. |
| Redis Database | Xác định chỉ số cơ sở dữ liệu nào sẽ sử dụng (ví dụ: 1). |
| Redis Pool Size | Số lượng kết nối tối đa trong pool kết nối Redis (mặc định: 1000). |
| Redis Pool Backlog | Số lượng yêu cầu tối đa đang chờ một kết nối khả dụng (mặc định: 30). |
- Sử dụng thiết lập Redis phân tán cho lưu trữ phiên.
| Configuration Field | Description |
|---|---|
| Redis Cluster Nodes | Địa chỉ của các nút trong cụm (ví dụ: redis-cluster.apim:6379). |
| Redis Cluster Password | Mật khẩu cho xác thực. |
| Redis Cluster Name | Xác định tên cụm (ví dụ: kong_redis_cluster). |
| Redis Connect Timeout | Thời gian chờ để thiết lập kết nối Redis (mặc định: 1000ms). |
| Redis Read Timeout | Thời gian chờ để đọc dữ liệu từ Redis (mặc định: 1000ms). |
| Redis Send Timeout | Thời gian chờ để gửi dữ liệu đến Redis (mặc định: 1000ms). |
| Redis Pool Size | Số lượng kết nối tối đa trong pool kết nối Redis (mặc định: 1000). |
| Redis Pool Backlog | Số lượng kết nối đang chờ tối đa (mặc định: 30). |
| Redis Keepalive Timeout | Thời gian nhàn rỗi tối đa trước khi kết nối Redis bị đóng (mặc định: 55000ms). |
Ghi chú bổ sung về hành vi xác thực OIDC
OIDC (OpenID Connect) cho phép các ứng dụng khách xác thực người dùng thông qua một Nhà cung cấp OIDC bên ngoài.
Hành vi của Đường dẫn Đăng xuất và URI Chuyển hướng
Khi cấu hình Đường dẫn Đăng xuất và URI Chuyển hướng Sau Đăng xuất, hành vi phụ thuộc vào cấu trúc của Cổng API của bạn:
- Giả sử URL Cổng của bạn là https://your.domain.com và Đường dẫn Cơ sở của API là /basePath.
- Nếu bạn đặt Đường dẫn Đăng xuất trong chính sách OIDC là /logout, thì URL đăng xuất đầy đủ sẽ trở thành: https://your.domain.com/basePath/logout
- Khi URL này được gọi, quá trình đăng xuất được xử lý nội bộ bởi Nhà cung cấp OIDC.
- Sau khi đăng xuất, trình duyệt sẽ được chuyển hướng đến URI Chuyển Hướng Sau Đăng Xuất (tức là giá trị redirect_uri), điều này phải được xác định rõ ràng trong yêu cầu.
ghi chú
Nếu URL đăng xuất đầy đủ và redirect_uri không được thiết lập đúng cách, quá trình đăng xuất có thể không chuyển hướng như mong đợi.
Hai Phương Thức Xác Thực Được Hỗ Trợ
OIDC cho phép hai cách để thực hiện xác thực:
- Màn hình đăng nhập được chuyển hướng qua trình duyệt: Trình duyệt được chuyển hướng đến trang đăng nhập OIDC để xác thực người dùng.
- ID token trong yêu cầu: Khách hàng gửi ID token trực tiếp qua HTTP mà không chuyển hướng người dùng.
Hành vi của các phương thức này phụ thuộc vào cài đặt bearerOnly:
| Giá trị bearerOnly | Hành vi |
|---|---|
| không | Cả hai phương thức (1) và (2) đều được phép. |
| có | Chỉ phương thức (2) được phép. Hệ thống không chuyển hướng đến trang đăng nhập. |
Xác Thực Token và Định Dạng Header
- Để xác thực ID token bằng phương thức (2), bạn phải cấu hình Điểm Cuối Kiểm Tra — điểm cuối kiểm tra tính hợp lệ của token.
- Khi gọi API với ID token, hãy bao gồm token trong header yêu cầu theo định dạng sau:
Authorization: bearer your_ID_token
