---
title: 配置 OIDC 外部连接
description: 在身份提供方中把 Sudomimus 注册为 OIDC 机密客户端，创建外部连接，并端到端验证企业登录。
editUrl: true
head: []
template: doc
sidebar:
  order: 5
  hidden: false
  attrs: {}
pagefind: true
draft: false
---

import { CardGrid, LinkCard } from "@astrojs/starlight/components";

本教程把企业身份提供方配置为 **OIDC 外部连接**。Sudomimus 是接入方（relying party）：浏览器会被重定向到你的 IdP；IdP 返回后，Sudomimus 验证 ID Token，再进入正常的第一层、第二层和签发流程。

## 开始之前

你需要：

- 在 [With 门户](https://with.sudomimus.com/)中拥有一个组织；
- 有权在 IdP 中创建应用；
- IdP 支持 OpenID Connect Discovery、Authorization Code、机密客户端、PKCE `S256` 和 RS256 签名的 ID Token；
- IdP 签发的 client secret。

先决定该连接是作为某个应用的**「使用……登录」**按钮、用于已验证域名的强制 SSO，还是两者都用。同一个连接支持这两种模式。

## 1. 在 IdP 创建客户端

在 IdP 中创建 **Web** 或**机密** OIDC 应用。不同提供方使用的名称可能不同，请按下表配置：

| IdP 设置 | 值 |
|---|---|
| 应用类型 | Web / confidential client |
| Grant 或流程 | Authorization Code |
| Redirect URI | `https://federation.sudomimus.com/oidc/callback` |
| PKCE | 启用；必须接受 `S256` |
| 客户端认证 | Client secret |
| Scopes | 至少包含 `openid`；通常使用 `openid email profile` |

Redirect URI 必须精确匹配。不要注册 Core UI 的地址：提供方响应会终止于 Auth API。

离开 IdP 前记录以下值：

- 精确的 **Issuer URL**；
- **Client ID**；
- **Client Secret**。

:::note[Issuer 与 Discovery]
保存连接时，Sudomimus 会读取 `<issuer>/.well-known/openid-configuration`。Discovery 文档必须返回完全相同的 issuer，并提供安全的 HTTPS authorization、token 和 JWKS 端点。
:::

## 2. 配置 Claims

每个 ID Token 都必须包含稳定且非空的 `sub`。Sudomimus 还会验证 `iss`、`aud`、`exp`、`iat`、每次登录的 `nonce`、RS256 签名，以及签名 `kid` 是否存在于 Discovery 得到的 JWKS 中。

以下标准 claims 可选，但通常很有用：

| Claim | 用途 |
|---|---|
| `email` + `email_verified: true` | 用于账户匹配和邮箱所有权判断的候选邮箱 |
| `given_name` | 名字资料值 |
| `family_name` | 姓氏资料值 |

IdP 验证过的邮箱不会自动获得 Sudomimus 信任。只有当该连接所属组织当前持有相应邮箱域名的已验证声明时，它才能用于邮箱所有权和账户匹配。

## 3. 在 With 中创建连接

在 With 门户中：

1. 打开你的组织。
2. 打开**外部连接**并选择**新建连接**。
3. 选择 **OpenID Connect**。
4. 输入显示名称、Issuer URL、Client ID 和 Client Secret。
5. 输入由空格或换行分隔的 scopes。必须包含 `openid`，通常从 `openid email profile` 开始。
6. 创建连接。

Sudomimus 会立即验证 issuer 和 Discovery 文档。无法访问或验证时会返回 `FederationConnectorDiscoveryFailed`。

Client secret 是只写信息：保存时会被加密，之后不会通过连接 API 或门户返回。请把原始值保存在 secret manager 中；只有轮换时才输入新值。

## 4. 使用该连接

选择其中一种或同时使用：

<CardGrid>
<LinkCard
    title="应用级登录"
    description="添加一条指向该连接的 ENTERPRISE_FEDERATION_APPLICATION_MANAGED 第一层规则。"
    href="/zh-cn/domains-federation/sign-in-with-your-idp/#应用级登录"
/>
<LinkCard
    title="域级强制 SSO"
    description="验证域名，将该连接绑定到 SSO_ONLY，并让参与应用允许 ENTERPRISE_FEDERATION_DOMAIN_MANAGED。"
    href="/zh-cn/domains-federation/sign-in-with-your-idp/#强制-sso域级管理"
/>
</CardGrid>

协议已经由连接固定，两种第一层规则都不需要额外的 OIDC/SAML 开关。

## 5. 测试登录

使用一个非管理员测试用户，并确保它拥有你刚刚配置的 claims。

应用级模式下，为应用开启一个 Inquiry，然后选择该连接对应的**「使用……登录」**按钮。域级模式下，输入已验证 `SSO_ONLY` 域名中的邮箱，然后通过要求的连接继续。

确认：

- 浏览器到达预期的 IdP tenant；
- IdP 返回固定的 Auth API callback；
- 登录进入应用正常的完成路径；
- 第二层允许该测试身份。协议冒烟测试可以先用 `EVERYONE`；若使用 `EMAIL`，要确保它匹配 Sudomimus 可以信任的邮箱。

如果连接保存成功但登录失败，先检查注册的 Redirect URI、ID Token 的 `nonce`、audience 与 issuer、RS256 签名、JWKS `kid`，以及配置的 scopes 是否真正释放了预期 claims。浏览器看到的联合登录错误会被刻意保持为通用信息。

## 相关内容

<CardGrid>
<LinkCard
    title="外部连接参考"
    description="字段语义、生命周期规则、校验和 secret 处理方式。"
    href="/zh-cn/domains-federation/federation-connectors/"
/>
<LinkCard
    title="配置 SAML 外部连接"
    description="在相同的企业联合登录模式中使用 SAML 2.0，而不是 OIDC。"
    href="/zh-cn/domains-federation/configure-saml-connector/"
/>
</CardGrid>