> ## 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-Hans/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-Hans/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-Hans/signals/data-sources)。

## 选择连接方式

| | **Okta (SSWS)** | **Okta (OAuth 2.0)** |
| - | - | - |
| 凭据 | 您在管理控制台中创建的 API 令牌 | 您生成并注册的客户端 ID 和私有 JWK |
| 设置 | 三个步骤，无需生成密钥材料 | 九个步骤，包括生成 RSA 密钥对 |
| 所需管理员角色 | 只读管理员，分配给令牌的所有者 | 只读管理员，分配给应用程序 |
| 令牌有效期 | 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. 在管理控制台中，转到 **Directory** → **人**。
    2. 点击 **Add person**，并创建一个用户，例如 `svc-livingsecurity@yourcompany.com`。
    3. 激活该账户。
  </Step>

  <Step title="分配只读管理员角色">
    平台仅执行读取操作。授予超出读取范围的权限，会使令牌拥有其从不使用的权限。

    1. 转到 **安全** → **Administrators**。
    2. 点击 **Add administrator**，并选择上一步中创建的用户。
    3. 分配 **Read-only Administrator** 角色。
    4. 保存。

    <Note>
      如果没有管理员角色，对 Okta Management API 的调用会返回 `200 OK` 并返回空列表。不会有 `403` 提示您缺少该角色 — 数据流只会保持为空。
    </Note>
  </Step>

  <Step title="创建 API 令牌">
    1. **以步骤 1 中的服务账户用户身份**登录管理控制台。令牌会继承创建它的账户的权限。
    2. 转到 **安全** → **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="查找您的租户子域名">
    您的管理控制台 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. **范围（Scopes）** - 以空格分隔的 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 管理控制台](https://login.okta.com/)。
2. 在左侧边栏中，转到 **Applications** > **Applications**。
3. 点击 **Create App Integration**。
4. 选择 **API Services** 作为登录方式，然后点击 **下一页**。

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

5. 为您的应用程序命名，然后点击 **保存**。
6. 在应用程序的 **General** 选项卡中找到您的 **客户端 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 可以直接在管理控制台中为您生成 RSA 密钥对：

1. 在管理控制台中，打开您的 API Services 应用程序。
2. 转到 **General** 选项卡，并滚动到 **PUBLIC KEYS** 部分。
3. 点击 **Add Key**，然后选择 **Generate new key**。
4. 点击 **保存** — 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 密钥对，在 Okta 中注册**公有** JWK，并将**私有** JWK 提供给 Living Security Platform。

**生成私有 JWK**，请使用以下 Node.js 脚本（需要 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. 在管理控制台中，打开您的 API Services 应用程序。
2. 转到 **General** 选项卡，并滚动到 **PUBLIC KEYS** 部分。
3. 点击 **Add Key**，粘贴上述脚本输出的**公有 JWK JSON**，然后点击 **保存**。

<Note>
  私有 JWK 是您要粘贴到 Living Security Platform 中的内容。它包含全部密钥材料（`d`、`p`、`q`、`dp`、`dq`、`qi`）以及 `kid`。请妥善保密。
</Note>

#### 步骤 3：查找您的 Okta 域名

仅输入您的 Okta 租户子域名 — 即 `.okta.com` 之前的部分。

* 在管理控制台中，浏览器地址栏会显示类似 `https://dev-12345678-admin.okta.com` 的 URL。
* 您的 **Okta 域名**仅为子域名（例如 `dev-12345678`），而不是 `dev-12345678.okta.com`。
* 或者，在管理控制台中转到 **设置** > **Account** 查找您的 Okta 域名，然后使用其中的子域名部分。

#### 步骤 4：为应用程序授予 API 范围

Okta 要求每个令牌请求中至少包含一个范围。在应用程序请求特定范围之前，必须先授予这些范围：

1. 在管理控制台中，转到 **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. 在管理控制台中，转到 **安全** > **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. 点击 **保存**。

<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（客户端凭据）进行身份验证的表单。
2. 输入您的 **客户端 ID**。
3. 粘贴您的 **私钥 (JWK)** — 即上述脚本生成的完整 JSON 对象（单行或格式化均可）。
4. 将您的 **Okta 域名** 仅输入为租户子域名（例如 `dev-12345678`）。
5. 以空格分隔的列表形式输入**范围**（例如 `okta.users.read okta.logs.read`）。
6. 提交表单，即可成功通过身份验证。

您现已连接到 Okta（客户端凭据）。

***

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