> ## Documentation Index
> Fetch the complete documentation index at: https://docs.livingsecurity.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Thiết lập tích hợp Okta

> Kết nối Okta với Living Security để thu thập dữ liệu về vòng đời người dùng, xác thực, MFA và hoạt động quản trị.

export const PublicIntegrationNextSteps = () => <>
    <hr />
    <h2>Tài nguyên liên quan</h2>
    <ul>
      <li>
        <a href="/vi/signals/data-sources">Tìm hiểu cách dữ liệu tích hợp trở thành các tín hiệu Human Risk Management</a>
      </li>
      <li>
        <a href="https://www.livingsecurity.com/integrations">Khám phá các Tích hợp của Living Security</a>
      </li>
      <li>
        <a href="https://app.livingsecurity.ai/">Mở Living Security Platform</a>
      </li>
      <li>
        <a href="https://www.livingsecurity.com/request-demo/">Yêu cầu bản demo của Living Security</a>
      </li>
    </ul>
  </>;

export const EgressIpSafelist = ({system}) => <Note>
    <strong>Hãy thêm cả bốn địa chỉ IP egress đồng bộ của Living Security</strong> vào danh sách cho phép trong{' '}
    {system}. Nhập từng địa chỉ dưới dạng một máy chủ đơn lẻ với <code>/32</code> nếu {system} yêu cầu ký hiệu CIDR:
    <br />
    <code>52.34.139.153/32</code>, <code>54.69.127.183/32</code>, <code>44.247.133.183/32</code>,{' '}
    <code>52.26.211.56/32</code>
    <br />
    <br />
    Lưu lượng có thể xuất phát từ bất kỳ địa chỉ nào trong bốn địa chỉ này, vì vậy nếu chỉ đưa một số địa chỉ vào danh sách cho phép, quá trình đồng bộ sẽ thỉnh thoảng bị lỗi. Bốn địa chỉ này giống nhau ở mọi khu vực của Living Security. Xem{' '}
    <a href="/vi/integrations/managing/egress-ip-addresses">
      Cấu hình địa chỉ IP egress của Tích hợp
    </a>{' '}
    để biết danh sách đầy đủ, chính sách thay đổi và cách khắc phục sự cố.
  </Note>;

export const ConnectInPlatform = ({tile, children}) => <Step title="Nhập thông tin xác thực vào Living Security Platform">
    <p>
      Bước này do người có quyền truy cập Living Security thực hiện — chủ sở hữu chương trình, hoặc quản trị viên hệ thống nếu người đó đã được mời (thiết lập được ủy quyền).
    </p>
    <ol>
      <li>
        Truy cập <strong>Cài đặt → Tích hợp → Danh mục</strong>, tìm thẻ{' '}
        <strong>{tile}</strong>, rồi nhấp vào <strong>Kết nối</strong>.
      </li>
      <li>
        Điền các trường bên dưới, sau đó nhấp vào <strong>Kết nối</strong>.
      </li>
    </ol>
    {children}
  </Step>;

## 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](/vi/signals/data-sources).

## 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.

<Steps>
  <Step title="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.

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

  <Step title="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.

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

    <Note>
      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.
    </Note>
  </Step>

  <Step title="Tạo API token">
    1. Đă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ó.
    2. Đi tới **Security** → **API** và mở tab **Tokens**.
    3. Nhấp **Create token**, đặt tên cho token, ví dụ như `Living Security Platform`, rồi nhấp **Create token**.
    4. 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.

    <Warning>
      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.
    </Warning>

    <EgressIpSafelist system="Okta" />

    <Note>
      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.
    </Note>
  </Step>

  <Step title="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://`.
  </Step>

  <ConnectInPlatform tile="Okta (SSWS)">
    | Trường | Giá trị |
    | - | - |
    | **Khóa API** | API token từ bước 3 |
    | **Tenant subdomain** | Tên miền phụ từ bước 4 (ví dụ: `acme`) |
  </ConnectInPlatform>
</Steps>

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

### Khắc phục sự cố

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="Đã 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.
  </Accordion>

  <Accordion title="Đồ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.
  </Accordion>
</AccordionGroup>

***

## 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:

1. **ID khách hàng** - Mã định danh duy nhất cho ứng dụng Okta API Services của Quý vị.
2. **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ị.
3. **Okta Domain** - Chỉ tenant subdomain Okta của Quý vị (ví dụ: `dev-12345678`), không phải tên máy chủ đầy đủ.
4. **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](https://developer.okta.com/signup/).

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

1. Đăng nhập vào [Okta Admin Console](https://login.okta.com/) của Quý vị.
2. Trong thanh bên trái, đi tới **Applications** > **Applications**.
3. Nhấp **Create App Integration**.
4. Chọn **API Services** làm phương thức đăng nhập và nhấp **Tiếp theo**.

<img src="https://raw.githubusercontent.com/NangoHQ/nango/master/docs/api-integrations/okta-cc/select-api-service.png" style={{maxWidth: "550px"}} />

5. Đặt tên cho ứng dụng của Quý vị và nhấp **Lưu**.
6. 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.
7. Đặ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.

<img src="https://raw.githubusercontent.com/NangoHQ/nango/master/docs/api-integrations/okta-cc/select-public-private-key.png" style={{maxWidth: "550px"}} />

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

<img src="https://raw.githubusercontent.com/NangoHQ/nango/master/docs/api-integrations/okta-cc/disable-dpop.png" style={{maxWidth: "550px"}} />

<Note>
  Ứng dụng phải được tạo dưới dạng **API Services**.
</Note>

#### 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:

1. Trong Admin Console, mở ứng dụng API Services của Quý vị.
2. Đi tới tab **General** và cuộn xuống phần **PUBLIC KEYS**.
3. Nhấp **Add Key**, sau đó chọn **Generate new key**.
4. 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.
5. 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.

<img src="https://raw.githubusercontent.com/NangoHQ/nango/master/docs/api-integrations/okta-cc/create-public-key.png" style={{maxWidth: "550px"}} />

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

<Note>
  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.
</Note>

##### 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+):

```javascript theme={null}
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:**

1. Trong Admin Console, mở ứng dụng API Services của Quý vị.
2. Đi tới tab **General** và cuộn xuống phần **PUBLIC KEYS**.
3. 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**.

<Note>
  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.
</Note>

#### 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:

1. Trong Admin Console, đi tới **Applications** > **Applications** và mở ứng dụng của Quý vị.
2. Nhấp tab **Okta API Scopes**.
3. 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](https://developer.okta.com/docs/api/oauth2/#okta-admin-management).

#### 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**:

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

<img src="https://raw.githubusercontent.com/NangoHQ/nango/master/docs/api-integrations/okta-cc/admin-role-dropdown.png" style={{maxWidth: "550px"}} />

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

<img src="https://raw.githubusercontent.com/NangoHQ/nango/master/docs/api-integrations/okta-cc/add-admin-role.png" style={{maxWidth: "550px"}} />

<Note>
  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 đề.
</Note>

#### 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**:

1. Mở biểu mẫu mà Quý vị cần xác thực với Okta (Client Credentials).
2. Nhập **ID khách hàng** của Quý vị.
3. 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).
4. Nhập **Okta Domain** của Quý vị chỉ ở dạng tenant subdomain (ví dụ: `dev-12345678`).
5. 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`).
6. 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).

***

<Note>Một số phần của tài liệu này được điều chỉnh từ [Nango](https://nango.dev/docs/), được sử dụng theo [Elastic License 2.0](https://github.com/NangoHQ/nango?tab=License-1-ov-file#readme).</Note>

<PublicIntegrationNextSteps />


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.