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 Bắt Buộc / Đường Dẫn Không Bắt Buộc
- 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 việc 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). |
| Đường dẫn Đăng xuất | Điểm cuối đăng xuất cho người dùng (ví dụ: /logout). |
| URI Chuyển hướng Sau Đăng xuất | Tham số và giá trị URI chuyển hướng cho đường dẫn đăng xuất |
| Chỉ Bearer | Xác định xem có yêu cầu mã thông báo bearer hay không: có (chỉ xác thực bằng mã thông báo) hoặc không (cho phép cả xác thực bằng mã thông báo và chuyển hướng đăng nhập). |
| Phạm vi | Xác định các cấp độ truy cập (mặc định: openid). |
| Điểm cuối Kiểm tra | URL để xác thực mã thông báo. |
| URL Đăng nhập | Điểm cuối API cho việc đăng nhập của người dùng. |
| Miền Cookie | Miền liên quan đến cookie xác thực (ví dụ: skapim.com). |
| Tên Tiêu đề Bỏ qua | 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). |
| Khóa Bỏ qua | Giá trị khóa bỏ qua thực tế. |
| Thời gian Hết hạn Mã thông báo Làm mới | Thời gian hết hạn của mã thông báo (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. |
| Bảo mật | Bật hoặc tắt cookie bảo mật (mặc định: false). |
| Hành động Không xác thực | 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). |
| Cho phép IP / Từ chối IP | Cho phép hoặc chặn các IP cụ thể khỏi xác thực OIDC. |
Luồng này thường được sử dụng cho machine-to-machine authentication hoặc các khách hàng đáng tin cậy.
| Configuration Field | Description |
|---|---|
| Vùng | Tên của vùng xác thực. Ví dụ: auth |
| ID Khách hàng | Định danh duy nhất được cấp bởi nhà cung cấp OIDC (ví dụ: tài khoản). |
| Mật khẩu Khách hàng | Mật khẩu khách hàng cần thiết cho xác thực. |
| Khám phá | URL đến điểm cuối khám phá của nhà cung cấp (ví dụ: https://oidcprovider/.well-known/openid-configuration). |
| Đường dẫn Đăng xuất | Điểm cuối đăng xuất cho người dùng (ví dụ: /Logout). |
| Đường dẫn URI chuyển hướng | Điểm cuối để chuyển hướng người dùng sau khi đăng nhập (ví dụ: /auth/api/login). |
| Phạm vi | 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. |
| Bảo mật | Chuyển đổi để bật / tắt tùy chọn bảo mật |
| Thời gian hết hạn Token làm mới | Thời gian hết hạn token (mặc định: 3600 giây). |
| URL đăng nhập | Điểm cuối API cho việc đăng nhập của người dùng. |
| Tên phiên | Xác định tên lưu trữ phiên (ví dụ: apim_prod_session). |
| Miền cookie | Miền liên quan đến cookie xác thực (ví dụ: skapim.com). |
| Tên tiêu đề bỏ qua | 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). |
| Khóa bỏ qua | Giá trị khóa bỏ qua thực tế. |
| URI chuyển hướng sau khi đăng nhập | URL để chuyển hướng người dùng sau khi đăng nhập thành công. |
| URI chuyển hướng sau khi đăng xuất | 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 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 để xác thực. |
| Redis Database | Chỉ định chỉ số cơ sở dữ liệu nào để 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 cấu hình Redis phân tán cho lưu trữ phiên.
| Configuration Field | Description |
|---|---|
| Redis Cluster Nodes | Địa chỉ nút cụm (ví dụ: redis-cluster.apim:6379). |
| Redis Cluster Password | Mật khẩu để xác thực. |
| Redis Cluster Name | Chỉ đị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 Đườ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 Gateway 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, việc đăng xuất sẽ đượ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
