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

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

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

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

这两种用途共享同一个外部连接。Sudomimus 作为 OIDC <strong>接入方（relying party）</strong>或 SAML <strong>服务提供方（service provider）</strong>连接到你的 IdP；IdP 仍然是企业身份的权威来源。

## 外部连接存储什么

你可以在 With 门户中为组织注册外部连接。每个连接都有显示名称和不可变的协议，其余配置取决于所选协议。

### OIDC

| 字段 | 是什么 |
|---|---|
| **显示名称** | 显示在登录按钮和管理界面上（例如「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 响应都不会返回该值，门户也无法将它重新显示出来。轮换时请提交新密钥；编辑其他字段而不希望更换密钥时，将该字段留空。

### SAML

| 字段 | 是什么 |
|---|---|
| **IdP Entity ID** | Sudomimus 在 SAML Assertion 中接受的精确 issuer。 |
| **IdP SSO URL** | 接收 SP 发起的 AuthnRequest 的 HTTPS 地址。 |
| **签名证书** | 一个或多个 IdP 签名证书。证书轮换期间可同时保留旧证书和新证书。 |
| **Subject 来源** | Assertion 的 `NameID` 或一个指定属性。它定义外部凭据身份，因此不可变。 |
| **资料属性** | 可选的邮箱、名字和姓氏属性名。 |

连接详情页会显示 Sudomimus 固定的 SP Entity ID 和 Assertion Consumer Service（ACS）地址。请把两者注册到 IdP。SAML 连接没有 client secret。

当前支持 SAML 2.0、SP 发起的浏览器 SSO：使用 HTTP-Redirect 发送 AuthnRequest、使用 HTTP-POST 接收响应，并要求 Assertion 已签名。暂不支持 IdP 发起的 SSO、加密 Assertion、Single Logout、元数据导入和签名 AuthnRequest。

## 配置教程

<CardGrid>
<LinkCard
    title="配置 OIDC 外部连接"
    description="在 IdP 创建机密 OIDC 客户端、注册 callback，并测试企业登录。"
    href="/zh-cn/domains-federation/configure-oidc-connector/"
/>
<LinkCard
    title="配置 SAML 外部连接"
    description="注册 Sudomimus SP 与 ACS、配置签名 Assertion，并测试企业登录。"
    href="/zh-cn/domains-federation/configure-saml-connector/"
/>
</CardGrid>

## 保存时的校验

创建或更新 OIDC 连接时，Sudomimus 会**立即读取 IdP 的发现文档**。如果 issuer 无法访问或无效，保存会返回 `FederationConnectorDiscoveryFailed`。SAML 配置会在保存时做结构校验；Assertion 签名和协议约束会在每次登录时验证。

## OIDC 重定向 URI

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

```text
https://federation.sudomimus.com/oidc/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>