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

# Okta 整合設定

> 將 Okta 連線至 Living Security，以取得使用者生命週期、驗證、MFA 及管理活動資料。

export const PublicIntegrationNextSteps = () => <>
    <hr />
    <h2>相關資源</h2>
    <ul>
      <li>
        <a href="/zh-Hant/signals/data-sources">了解整合資料如何轉換為人員風險管理訊號</a>
      </li>
      <li>
        <a href="https://www.livingsecurity.com/integrations">探索 Living Security 整合</a>
      </li>
      <li>
        <a href="https://app.livingsecurity.ai/">開啟 Living Security Platform</a>
      </li>
      <li>
        <a href="https://www.livingsecurity.com/request-demo/">申請 Living Security 示範</a>
      </li>
    </ul>
  </>;

export const EgressIpSafelist = ({system}) => <Note>
    <strong>請將 Living Security 同步作業的全部四個輸出 IP 位址</strong>新增至{' '}
    {system} 的允許清單。若 {system} 要求使用 CIDR 表示法，請將每個位址分別以單一主機形式輸入，並加上 <code>/32</code>：
    <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 />
    流量可能從這四個位址中的任何一個送出，因此僅將其中部分位址加入允許清單，會導致間歇性的同步失敗。這四個位址在 Living Security 的所有區域中皆相同。如需完整清單、變更政策及疑難排解資訊，請參閱{' '}
    <a href="/zh-Hant/integrations/managing/egress-ip-addresses">
      設定整合輸出 IP 位址
    </a>。
  </Note>;

export const ConnectInPlatform = ({tile, children}) => <Step title="在 Living Security Platform 中輸入憑證">
    <p>
      由擁有 Living Security 存取權限的人員完成——即計畫負責人，或已受邀的系統管理員（委派設定）。
    </p>
    <ol>
      <li>
        前往 <strong>設定 → 集成 → 目錄</strong>，找到{' '}
        <strong>{tile}</strong> 圖磚，然後按一下 <strong>連接</strong>。
      </li>
      <li>
        填寫以下欄位，然後按一下 <strong>連接</strong>。
      </li>
    </ol>
    {children}
  </Step>;

## 概觀

Okta 可提供經過正規化的使用者生命週期、驗證、MFA 及管理活動資料。經審查的範例包括：

* `account.locked` — 帳號遭鎖定
* `mfa.factor.activated` — 啟用額外的 MFA 因素
* `auth.login.failed` — 登入失敗

兩種連線方式讀取的資料串流相同：使用者目錄 (`/api/v1/users`) 與系統記錄 (`/api/v1/logs`)。請參閱[整合資料如何轉換為訊號](/zh-Hant/signals/data-sources)。

## 選擇連線方式

| | **Okta (SSWS)** | **Okta (OAuth 2.0)** |
| - | - | - |
| 憑證 | 您在 Admin Console 中建立的 API 權杖 | 您產生並註冊的用戶端 ID 與私密 JWK |
| 設定 | 三個步驟，無需產生金鑰資料 | 九個步驟，包括產生 RSA 金鑰組 |
| 所需的管理員角色 | Read-only administrator，指派給權杖的擁有者 | Read-only administrator，指派給應用程式 |
| 權杖有效期限 | 閒置 30 天後停用 | 無到期日；金鑰組由您自行輪替 |
| 適用時機 | 建議大多數組織採用此方式 | 您的安全性政策禁止使用長期有效的 API 權杖 |

兩種方式所需的存取權限相同，因此選擇的重點在於憑證的處理方式，而非平台可讀取的內容。

***

## 選項 A — API 權杖 (SSWS)

*建議採用。*

### Living Security 所需資訊

| 憑證 | 說明 |
| - | - |
| **API 金鑰** | Okta API 權杖。連線對話方塊將此欄位標示為 **API 金鑰** |
| **租戶子網域** | `<tenant>.okta.com` 中的 `<tenant>` — 僅填寫子網域，而非完整 URL |

### 先決條件

* 您必須是 Okta **Super Administrator**，才能建立服務帳號使用者、指派管理員角色及建立 API 權杖。

<Steps>
  <Step title="建立權杖擁有者使用者">
    Okta API 權杖具有建立該權杖之使用者的權限，且若該使用者遭停用，權杖即會失效。請建立專用的服務帳號，而非使用個人管理員帳號，以確保連線不受人員異動影響。

    1. 在 Admin Console 中，前往 **Directory** → **People**。
    2. 按一下 **Add person**，並建立使用者，例如 `svc-livingsecurity@yourcompany.com`。
    3. 啟用該帳號。
  </Step>

  <Step title="指派唯讀管理員角色">
    平台僅進行讀取。授予超過讀取權限的存取權，會使權杖擁有從未使用的權限。

    1. 前往 **Security** → **Administrators**。
    2. 按一下 **Add administrator**，並選取上一步建立的使用者。
    3. 指派 **Read-only Administrator** 角色。
    4. 按一下 **Save**。

    <Note>
      若未指派管理員角色，對 Okta Management API 的呼叫仍會以 `200 OK` 成功，但會傳回空白清單。系統不會出現 `403` 來告知您缺少角色 — 資料串流只會持續為空。
    </Note>
  </Step>

  <Step title="建立 API 權杖">
    1. 以步驟 1 建立的**服務帳號使用者**登入 Admin Console。權杖會繼承建立它的帳號。
    2. 前往 **Security** → **API**，並開啟 **Tokens** 索引標籤。
    3. 按一下 **Create token**，為其命名，例如 `Living Security Platform`，然後按一下 **Create token**。
    4. 請立即複製權杖值 — Okta 僅顯示一次，之後不會再顯示。

    <Warning>
      Okta 會在 API 權杖**閒置 30 天**後將其停用。此整合的同步作業至少每天執行一次，因此運作中的連線會讓自己的權杖保持有效。若連線暫停超過一個月，則需要新的權杖。
    </Warning>

    <EgressIpSafelist system="Okta" />

    <Note>
      僅當您的 Okta 組織依**網路區域**限制 API 存取時，上述位址清單才有意義。大多數組織並未如此設定。
    </Note>
  </Step>

  <Step title="找出您的租戶子網域">
    您的 Admin Console URL 類似 `https://acme-admin.okta.com`。租戶子網域為 `acme` — 不含 `-admin` 後綴、不含 `.okta.com`，也不含 `https://`。
  </Step>

  <ConnectInPlatform tile="Okta (SSWS)">
    | 欄位 | 值 |
    | - | - |
    | **API 金鑰** | 步驟 3 取得的 API 權杖 |
    | **租戶子網域** | 步驟 4 取得的子網域（例如 `acme`） |
  </ConnectInPlatform>
</Steps>

您現在已連線至 Okta (SSWS)。

### 疑難排解

<AccordionGroup>
  <Accordion title="401 Unauthorized">
    權杖無效、已遭撤銷，或因閒置 30 天而遭停用。請以服務帳號使用者建立新權杖，並在連線中重新輸入。
  </Accordion>

  <Accordion title="已連線，但所有資料串流皆為空">
    權杖的擁有者沒有管理員角色。請將 **Read-only Administrator** 指派給服務帳號（步驟 2）— 當缺少該角色時，API 會傳回 `200 OK` 及空白清單，而非錯誤。
  </Accordion>

  <Accordion title="人員異動後同步失敗">
    若建立權杖的使用者遭停用，權杖即會失效。這就是權杖應屬於服務帳號而非個人的原因。
  </Accordion>
</AccordionGroup>

***

## 選項 B — OAuth 2.0 服務應用程式

當您的安全性政策不允許使用長期有效的 API 權杖時，請使用此方式。它以用戶端 ID 與您自有的 RSA 金鑰組取代權杖。在平台中，這是位於 **設定 → 集成 → 目錄** 下的 **Okta (OAuth 2.0)** 圖磚。

若要使用 Client Credentials 向 Okta 進行驗證，您需要下列項目：

1. **用戶端 ID** - 您的 Okta API Services 應用程式的唯一識別碼。
2. **私密金鑰 (JWK)** - JSON Web Key 格式的 RSA 私密金鑰，其公開金鑰已註冊於您的 Okta 應用程式。
3. **Okta 網域** - 僅填寫您的 Okta 租戶子網域（例如 `dev-12345678`），而非完整主機名稱。
4. **範圍** - 以空格分隔的 Okta Management API 範圍清單（例如 `okta.users.read okta.logs.read`）。

本指南將引導您在 Okta 中建立使用 `private_key_jwt` 驗證的 API Services 應用程式。

### 先決條件：

* 您必須擁有 Okta 帳號。您可以在 [developer.okta.com](https://developer.okta.com/signup/) 註冊免費的開發人員帳號。

#### 步驟 1：建立您的 Okta API Services 應用程式

1. 登入您的 [Okta Admin Console](https://login.okta.com/)。
2. 在左側邊欄中，前往 **Applications** > **Applications**。
3. 按一下 **Create App Integration**。
4. 選取 **API Services** 作為登入方式，然後按一下 **Next**。

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

5. 為您的應用程式命名，然後按一下 **Save**。
6. 在應用程式的 **General** 索引標籤上，找到您的 **Client ID** — 您將在最後一個步驟中用到它。
7. 將 Client authentication 設定為 **Public key / Private key**。`okta.*` 範圍僅支援此驗證方式。

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

8. 停用 **Proof of possession (DPoP)** — 系統不支援此功能。

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

<Note>
  應用程式必須建立為 **API Services**。
</Note>

#### 步驟 2：產生並註冊您的 RSA 金鑰組

##### 使用 Okta 金鑰產生器

Okta 可直接在 Admin Console 中為您產生 RSA 金鑰組：

1. 在 Admin Console 中，開啟您的 API Services 應用程式。
2. 前往 **General** 索引標籤，並捲動至 **PUBLIC KEYS** 區段。
3. 按一下 **Add Key**，然後選取 **Generate new key**。
4. 按一下 **Save** — Okta 會產生金鑰組，並僅顯示一次**私密金鑰 (JWK)**。
5. 請立即複製並儲存私密金鑰 JSON — 之後不會再顯示。

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

6. 公開金鑰會自動註冊至您的應用程式。

<Note>
  請在關閉對話方塊前複製私密 JWK。在最後一個步驟中，將其貼至 Living Security Platform 的**私密金鑰**欄位。
</Note>

##### 建立您自己的金鑰

Okta 對 API Services 應用程式使用 `private_key_jwt`。您需要產生 RSA 金鑰組，將**公開** JWK 註冊至 Okta，並將**私密** JWK 提供給 Living Security Platform。

**使用下列 Node.js 指令碼產生私密 JWK**（需要 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));
```

**在 Okta 中註冊公開 JWK：**

1. 在 Admin Console 中，開啟您的 API Services 應用程式。
2. 前往 **General** 索引標籤，並捲動至 **PUBLIC KEYS** 區段。
3. 按一下 **Add Key**，貼上上述指令碼輸出的**公開 JWK JSON**，然後按一下 **Save**。

<Note>
  您要貼至 Living Security Platform 的是私密 JWK。它包含所有金鑰資料（`d`、`p`、`q`、`dp`、`dq`、`qi`）以及 `kid`。請妥善保密。
</Note>

#### 步驟 3：找出您的 Okta 網域

僅輸入您的 Okta 租戶子網域 — 即 `.okta.com` 之前的部分。

* 在 Admin Console 中，瀏覽器網址列會顯示類似 `https://dev-12345678-admin.okta.com` 的 URL。
* 您的 **Okta 網域**僅為子網域（例如 `dev-12345678`），而非 `dev-12345678.okta.com`。
* 或者，您也可以在 Admin Console 中前往 **Settings** > **Account** 查看您的 Okta 網域，然後使用其中的子網域部分。

#### 步驟 4：為您的應用程式授予 API 範圍

Okta 要求每個權杖請求中至少包含一個範圍。應用程式必須先被授予特定範圍，才能請求這些範圍：

1. 在 Admin Console 中，前往 **Applications** > **Applications**，並開啟您的應用程式。
2. 按一下 **Okta API Scopes** 索引標籤。
3. 授予您的整合所需的範圍：`okta.users.read` 與 `okta.logs.read`。

完整的可用範圍清單請參閱 [Okta Management API 參考文件](https://developer.okta.com/docs/api/oauth2/#okta-admin-management)。

#### 步驟 5：為您的應用程式指派管理員角色

僅授予範圍並不足夠 — 若您的應用程式沒有管理員角色，Okta Management API 端點（例如 `/api/v1/users`）會靜默地傳回空白的 `200 []` 回應。您必須至少指派 **Read-Only Administrator**：

1. 在 Admin Console 中，前往 **Security** > **Administrators**（或前往 **Applications** > **Applications** > 您的應用程式 > **Admin roles**）。
2. 按一下 **Add administrator assignment**，並選取您的 API Services 應用程式。

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

3. 指派 **Read-Only Administrator** 角色（或更高的角色，視您所需的範圍而定）。
4. 按一下 **Save**。

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

<Note>
  若沒有管理員角色，API 呼叫仍會以 `200 OK` 成功，但會傳回空白結果，且不會出現 `403` 錯誤來指出問題。
</Note>

#### 步驟 6：在 Living Security Platform 中輸入憑證

取得您的**用戶端 ID**、**私密金鑰 (JWK)**、**Okta 網域**及**範圍**之後：

1. 開啟需要向 Okta (Client Credentials) 進行驗證的表單。
2. 輸入您的**用戶端 ID**。
3. 貼上您的**私密金鑰 (JWK)** — 即上述指令碼產生的完整 JSON 物件（單行或格式化皆可）。
4. 將您的 **Okta 網域**僅以租戶子網域輸入（例如 `dev-12345678`）。
5. 以空格分隔的清單輸入**範圍**（例如 `okta.users.read okta.logs.read`）。
6. 提交表單後，即可成功完成驗證。

您現在已連線至 Okta (Client Credentials)。

***

<Note>本文件的部分內容改編自 [Nango](https://nango.dev/docs/)，並依據 [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.