Thiết lập tích hợp Okta - Living Security Platform

Tổng quan

Okta có thể cung cấp dữ liệu đã được chuẩn hóa về vòng đời người dùng, xác thực, MFA và hoạt động quản trị. Các ví dụ đã được xem xét bao gồm:

account.locked — tài khoản bị khóa
mfa.factor.activated — kích hoạt thêm các yếu tố MFA
auth.login.failed — đăng nhập không thành công

Cả hai phương thức kết nối đều đọc cùng hai luồng dữ liệu — thư mục người dùng (/api/v1/users) và nhật ký hệ thống (/api/v1/logs). Xem cách dữ liệu tích hợp trở thành tín hiệu.

Chọn phương thức kết nối

	Okta (SSWS)	Okta (OAuth 2.0)
Thông tin xác thực	Một API token do Quý vị tạo trong Admin Console	Một ID khách hàng và một JWK riêng tư do Quý vị tạo và đăng ký
Thiết lập	Ba bước, không cần tạo khóa mật mã	Chín bước, bao gồm việc tạo cặp khóa RSA
Vai trò quản trị viên bắt buộc	Quản trị viên chỉ đọc, được gán cho chủ sở hữu của token	Quản trị viên chỉ đọc, được gán cho ứng dụng
Thời hạn của token	Bị vô hiệu hóa sau 30 ngày không sử dụng	Không hết hạn; Quý vị tự chịu trách nhiệm xoay vòng cặp khóa
Nên sử dụng khi	Đây là lựa chọn được khuyến nghị cho hầu hết các tổ chức	Chính sách bảo mật của Quý vị không cho phép dùng API token có thời hạn dài

Cả hai phương thức đều yêu cầu cùng quyền truy cập, vì vậy lựa chọn này liên quan đến cách quản lý thông tin xác thực, không phải đến dữ liệu mà nền tảng có thể đọc.

Tùy chọn A — API token (SSWS)

Được khuyến nghị.

Những gì Living Security cần

Thông tin xác thực	Mô tả
Khóa API	Một API token của Okta. Hộp thoại kết nối gắn nhãn trường này là Khóa API
Tenant subdomain	`<tenant>` trong `<tenant>.okta.com` — chỉ là tên miền phụ, không phải URL đầy đủ

Điều kiện tiên quyết

Quý vị phải là Super Administrator của Okta để tạo người dùng tài khoản dịch vụ, gán vai trò quản trị viên và tạo API token.

Tạo người dùng sở hữu token

Một API token của Okta mang quyền hạn của người dùng đã tạo ra nó và sẽ ngừng hoạt động nếu người dùng đó bị vô hiệu hóa. Hãy tạo một tài khoản dịch vụ riêng thay vì dùng tài khoản quản trị cá nhân, để kết nối không bị gián đoạn khi nhân sự thay đổi.

Trong Admin Console, đi tới Directory → People.
Nhấp Add person và tạo một người dùng, ví dụ như svc-livingsecurity@yourcompany.com.
Kích hoạt tài khoản.

Gán vai trò quản trị viên chỉ đọc

Nền tảng chỉ thực hiện thao tác đọc. Việc cấp nhiều hơn quyền đọc sẽ trao cho token những quyền mà nó không bao giờ sử dụng.

Đi tới Security → Administrators.
Nhấp Add administrator và chọn người dùng từ bước trước.
Gán vai trò Read-only Administrator.
Lưu.

Nếu không có vai trò quản trị viên, các lệnh gọi tới Okta Management API vẫn thành công với 200 OK và trả về một danh sách rỗng. Không có 403 nào cho biết vai trò bị thiếu — các luồng dữ liệu chỉ đơn giản là vẫn trống.

Tạo API token

Đăng nhập vào Admin Console bằng người dùng tài khoản dịch vụ từ bước 1. Token kế thừa quyền của tài khoản tạo ra nó.
Đi tới Security → API và mở tab Tokens.
Nhấp Create token, đặt tên cho token, ví dụ như Living Security Platform, rồi nhấp Create token.
Hãy sao chép giá trị token ngay bây giờ — Okta chỉ hiển thị một lần và sẽ không hiển thị lại.

Okta vô hiệu hóa API token sau 30 ngày không sử dụng. Các lần đồng bộ trong tích hợp này chạy ít nhất một lần mỗi ngày, do đó một kết nối đang hoạt động sẽ tự giữ token của mình luôn có hiệu lực. Một kết nối bị tạm dừng trong một tháng sẽ cần một token mới.

Danh sách địa chỉ ở trên chỉ quan trọng nếu tổ chức Okta của Quý vị hạn chế quyền truy cập API theo network zone. Hầu hết các tổ chức không áp dụng hạn chế này.

Tìm tenant subdomain của Quý vị

URL Admin Console của Quý vị có dạng https://acme-admin.okta.com. Tenant subdomain là acme — không có hậu tố -admin, không có .okta.com và không có https://.

Quý vị đã kết nối với Okta (SSWS).

Khắc phục sự cố

401 Unauthorized

Token không hợp lệ, đã bị thu hồi hoặc đã bị vô hiệu hóa sau 30 ngày không hoạt động. Hãy tạo một token mới bằng người dùng tài khoản dịch vụ và nhập lại token đó vào kết nối.

Đã kết nối nhưng mọi luồng dữ liệu đều trống

Chủ sở hữu của token không có vai trò quản trị viên. Hãy gán Read-only Administrator cho tài khoản dịch vụ (bước 2) — khi thiếu vai trò, API trả về 200 OK cùng một danh sách rỗng thay vì báo lỗi.

Đồng bộ thất bại sau khi nhân sự thay đổi

Token ngừng hoạt động nếu người dùng đã tạo ra nó bị vô hiệu hóa. Đây là lý do token nên thuộc về một tài khoản dịch vụ, không phải một cá nhân.

Tùy chọn B — Ứng dụng dịch vụ OAuth 2.0

Hãy sử dụng phương thức này khi chính sách bảo mật của Quý vị không cho phép dùng API token có thời hạn dài. Phương thức này thay token bằng một ID khách hàng và một cặp khóa RSA do Quý vị sở hữu. Trên nền tảng, đây là ô Okta (OAuth 2.0), trong Cài đặt → Tích hợp → Danh mục. Để xác thực với Okta bằng Client Credentials, Quý vị cần có những thông tin sau:

ID khách hàng - Mã định danh duy nhất cho ứng dụng Okta API Services của Quý vị.
Private Key (JWK) - Khóa riêng tư RSA ở định dạng JSON Web Key, có khóa công khai được đăng ký trong ứng dụng Okta của Quý vị.
Okta Domain - Chỉ tenant subdomain Okta của Quý vị (ví dụ: dev-12345678), không phải tên máy chủ đầy đủ.
Scopes - Danh sách các scope của Okta Management API, phân tách bằng dấu cách (ví dụ: okta.users.read okta.logs.read).

Hướng dẫn này sẽ giúp Quý vị tạo một ứng dụng API Services trong Okta với xác thực private_key_jwt.

Điều kiện tiên quyết:

Quý vị phải có tài khoản Okta. Hãy đăng ký tài khoản nhà phát triển miễn phí tại developer.okta.com.

Bước 1: Tạo ứng dụng Okta API Services

Đăng nhập vào Okta Admin Console của Quý vị.
Trong thanh bên trái, đi tới Applications > Applications.
Nhấp Create App Integration.
Chọn API Services làm phương thức đăng nhập và nhấp Tiếp theo.

Đặt tên cho ứng dụng của Quý vị và nhấp Lưu.
Trên tab General của ứng dụng, tìm ID khách hàng của Quý vị — Quý vị sẽ cần đến nó ở bước cuối cùng.
Đặt Client authentication thành Public key / Private key. Các scope okta.* chỉ được hỗ trợ với phương thức xác thực này.

Tắt Proof of possession (DPoP) — tính năng này không được hỗ trợ.

Ứng dụng phải được tạo dưới dạng API Services.

Bước 2: Tạo và đăng ký cặp khóa RSA

Sử dụng trình tạo khóa của Okta

Okta có thể tạo cặp khóa RSA cho Quý vị ngay trong Admin Console:

Trong Admin Console, mở ứng dụng API Services của Quý vị.
Đi tới tab General và cuộn xuống phần PUBLIC KEYS.
Nhấp Add Key, sau đó chọn Generate new key.
Nhấp Lưu — Okta tạo cặp khóa và hiển thị Private Key (JWK) một lần duy nhất.
Hãy sao chép và lưu ngay đoạn JSON của khóa riêng tư — nó sẽ không được hiển thị lại.

Khóa công khai được tự động đăng ký với ứng dụng của Quý vị.

Hãy sao chép JWK riêng tư trước khi đóng hộp thoại. Dán nó vào trường Private Key trong Living Security Platform ở bước cuối cùng.

Tự tạo khóa

Okta sử dụng private_key_jwt cho các ứng dụng API Services. Quý vị tạo một cặp khóa RSA, đăng ký JWK công khai với Okta và cung cấp JWK riêng tư cho Living Security Platform. Tạo JWK riêng tư bằng đoạn mã Node.js sau (yêu cầu Node.js 18+):

const { generateKeyPairSync } = require('crypto');
const { privateKey, publicKey } = generateKeyPairSync('rsa', { modulusLength: 2048 });

const privateJwk = privateKey.export({ format: 'jwk' });
const publicJwk  = publicKey.export({ format: 'jwk' });

// Assign a kid — must match between private and public JWK
const kid = require('crypto').randomUUID();
privateJwk.kid = kid;
publicJwk.kid  = kid;

console.log('=== PUBLIC JWK (upload to Okta) ===');
console.log(JSON.stringify(publicJwk, null, 2));
console.log('\n=== PRIVATE JWK (paste into the Living Security Platform) ===');
console.log(JSON.stringify(privateJwk));

Đăng ký JWK công khai trong Okta:

Trong Admin Console, mở ứng dụng API Services của Quý vị.
Đi tới tab General và cuộn xuống phần PUBLIC KEYS.
Nhấp Add Key, dán JSON của JWK công khai là kết quả đầu ra từ đoạn mã ở trên, rồi nhấp Lưu.

JWK riêng tư là nội dung mà Quý vị dán vào Living Security Platform. Nó bao gồm toàn bộ thông tin khóa (d, p, q, dp, dq, qi) và kid. Hãy giữ bí mật.

Bước 3: Tìm Okta Domain của Quý vị

Chỉ nhập tenant subdomain Okta của Quý vị — phần đứng trước .okta.com.

Trong Admin Console, thanh địa chỉ của trình duyệt sẽ hiển thị một URL có dạng https://dev-12345678-admin.okta.com.
Okta Domain của Quý vị chỉ là tên miền phụ (ví dụ: dev-12345678), không phải dev-12345678.okta.com.
Ngoài ra, hãy đi tới Cài đặt > Account trong Admin Console để tìm Okta domain của Quý vị, sau đó dùng phần tên miền phụ.

Bước 4: Cấp API scope cho ứng dụng của Quý vị

Okta yêu cầu ít nhất một scope trong mọi yêu cầu token. Trước khi ứng dụng của Quý vị có thể yêu cầu các scope cụ thể, các scope đó phải được cấp:

Trong Admin Console, đi tới Applications > Applications và mở ứng dụng của Quý vị.
Nhấp tab Okta API Scopes.
Cấp các scope mà tích hợp của Quý vị yêu cầu: okta.users.read và okta.logs.read.

Danh sách đầy đủ các scope khả dụng có trong tài liệu tham khảo Okta Management API.

Bước 5: Gán vai trò quản trị viên cho ứng dụng của Quý vị

Chỉ cấp scope là chưa đủ — các endpoint của Okta Management API (ví dụ: /api/v1/users) sẽ âm thầm trả về phản hồi 200 [] rỗng nếu ứng dụng của Quý vị không có vai trò quản trị viên. Quý vị phải gán ít nhất Read-Only Administrator:

Trong Admin Console, đi tới Security > Administrators (hoặc đi tới Applications > Applications > ứng dụng của Quý vị > Admin roles).
Nhấp Add administrator assignment và chọn ứng dụng API Services của Quý vị.

Gán vai trò Read-Only Administrator (hoặc cao hơn, tùy theo các scope Quý vị cần).
Nhấp Lưu.

Nếu không có vai trò quản trị viên, các lệnh gọi API vẫn thành công với 200 OK nhưng trả về kết quả rỗng và không có lỗi 403 nào cho biết vấn đề.

Bước 6: Nhập thông tin xác thực trong Living Security Platform

Sau khi Quý vị đã có ID khách hàng, Private Key (JWK), Okta Domain và Scopes:

Mở biểu mẫu mà Quý vị cần xác thực với Okta (Client Credentials).
Nhập ID khách hàng của Quý vị.
Dán Private Key (JWK) của Quý vị — toàn bộ đối tượng JSON từ đoạn mã ở trên (dạng một dòng hoặc đã định dạng).
Nhập Okta Domain của Quý vị chỉ ở dạng tenant subdomain (ví dụ: dev-12345678).
Nhập Scopes dưới dạng danh sách phân tách bằng dấu cách (ví dụ: okta.users.read okta.logs.read).
Gửi biểu mẫu, và Quý vị sẽ được xác thực thành công.

Quý vị đã kết nối với Okta (Client Credentials).

Một số phần của tài liệu này được điều chỉnh từ Nango, được sử dụng theo Elastic License 2.0.

Tích hợp