---
title: 外部连接
description: 把组织自有的 OIDC 身份提供方注册为一个可复用的外部连接，再用它来提供企业登录或强制某个域名走 SSO。
editUrl: true
head: []
template: doc
sidebar:
  order: 4
  hidden: false
  attrs: {}
pagefind: true
draft: false
---

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

**外部连接（federation connector）**表示组织自有的外部 OIDC 身份提供方。注册一次后，可以在多个应用和域名策略中复用。如果公司使用 Microsoft Entra ID、Okta、Google Workspace、Ping、Auth0 或其他符合标准的 OIDC 提供方，可以将它注册为外部连接，然后：

- 在你的某个应用上以**「使用 …… 登录」按钮**提供它（[应用级管理](/zh-cn/domains-federation/sign-in-with-your-idp/)），也可以
- **强制**某个已验证域名的用户都走它（[域级管理 / 强制 SSO](/zh-cn/domains-federation/sign-in-with-your-idp/)）。

这两种用途共享同一个外部连接。Sudomimus 作为**接入方（relying party，OIDC 客户端）**连接到你的 IdP；IdP 仍然是企业身份的权威来源。

## 外部连接存储什么

你可以在 With 门户中为组织注册外部连接。它包含以下配置：

| 字段 | 是什么 |
|---|---|
| **显示名称** | 显示在登录按钮和管理界面上（例如「Acme Corp SSO」）。 |
| **Issuer** | 你 IdP 的 issuer URL（`https://login.acme.example`）。Sudomimus 会从 `<issuer>/.well-known/openid-configuration` 拉取其 OIDC 发现文档。 |
| **Client ID** | Sudomimus 向你的 IdP 出示的 OAuth 客户端 ID。 |
| **Client Secret** | 机密客户端密钥。**静态加密存储**且**只写**——见下文。 |
| **Scopes** | Sudomimus 请求的作用域；必须包含 `openid`。 |

每个外部连接都有一个不透明的**外部连接锚点（connector anchor）**，例如 `Bastion-K7Q2-M9XB-3FNP-Covenant`。开发者通过该值在规则和策略中引用外部连接；内部标识符不会离开系统。

:::note[机密客户端 + PKCE]
Sudomimus 以**机密客户端**身份、使用 client secret 向你的 IdP 认证，并在每次授权时使用 **PKCE（S256）**。暂不支持 `private_key_jwt` 与公开（无密钥）客户端——Sudomimus 首先面向的提供方（Entra、Okta、Workspace）都支持机密客户端 + PKCE。
:::

### Client Secret 永远不会回显给你

Client secret 在保存时立即加密。外部连接列表、详情页和 API 响应都不会返回该值，门户也无法将它重新显示出来。轮换时请提交新密钥；编辑其他字段而不希望更换密钥时，将该字段留空。

## 保存时的校验

创建或更新外部连接时，Sudomimus 会**立即读取 IdP 的发现文档**。如果 issuer 无法访问或未发布有效的 OIDC 发现文档，保存会返回 `FederationConnectorDiscoveryFailed`，而不会保留无效配置。这样可以在保存时发现问题，而不是等到首次登录时才失败。

## 要在你 IdP 上注册的重定向 URI

Sudomimus 对**所有**外部连接使用同一个固定的重定向 URI。IdP 通过每次登录的 `state` 值区分流程，而不是通过不同的重定向 URI。外部连接页面会以只读方式显示该地址；请将它添加到 IdP 应用允许的重定向 URI：

```text
https://via.sudomimus.com/oauth/enterprise-federation/callback
```

## 管理外部连接

- **停用**一个外部连接，可在不删除它的情况下让它退役——在你迁移 IdP 时很有用。
- **删除**会把它彻底移除。

:::caution[使用中的外部连接无法被移除]
仍被引用的外部连接无法被停用或删除：

- 被某个第一层应用登录规则引用 → `FederationConnectorInUse`；
- 被某个域名的 `SSO_ONLY` 登录策略绑定 → `FederationConnectorInUseByLoginPolicy`。

请先移除相关规则，或将域名策略改回 `ALLOW_ALL`。这项限制可以防止仍在强制 SSO 的域名引用已经删除的 IdP。
:::

## 配额

每个组织可持有的外部连接数量有限（默认 **3** 个）。Sudomimus 工作人员可应请求提高上限。该配额只在自助界面上强制执行。

## 浏览外部连接

With 门户有一个顶层的**外部连接**视图，带组织切换器，列出你所有组织下的每一个外部连接。

## 相关

<CardGrid>
<LinkCard
    title="使用你的 IdP 登录"
    description="让外部连接派上用场——作为应用按钮，或作为强制-SSO 的域名策略。"
    href="/zh-cn/domains-federation/sign-in-with-your-idp/"
/>
<LinkCard
    title="域名登录策略"
    description="把外部连接绑定到一个已验证域名，强制其用户走 SSO。"
    href="/zh-cn/domains-federation/domain-login-policy/"
/>
</CardGrid>