---
title: 配置 SAML 外部连接
description: 在身份提供方中把 Sudomimus 注册为 SAML 服务提供方，创建外部连接，并端到端验证签名 Assertion。
editUrl: true
head: []
template: doc
sidebar:
  order: 6
  hidden: false
  attrs: {}
pagefind: true
draft: false
---

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

本教程把企业身份提供方配置为 **SAML 2.0 外部连接**。Sudomimus 是服务提供方（SP）：它向 IdP 发送 AuthnRequest，验证 IdP 提交到 ACS 的签名 Assertion，再进入与 OIDC 联合登录相同的第一层、第二层和签发流程。

## 开始之前

你需要：

- 在 [With 门户](https://with.sudomimus.com/)中拥有一个组织；
- 有权在 IdP 中创建 SAML 应用；
- IdP Entity ID 和用于 SP-initiated 登录的 SSO URL；
- IdP 用于签署 Assertion 的公钥 X.509 证书。

Sudomimus 只支持 SP 发起的 SAML 浏览器 SSO。初始 AuthnRequest 使用 HTTP-Redirect binding，响应必须通过 HTTP-POST binding 返回。

## 1. 在 IdP 创建 SAML 应用

创建一个自定义 SAML 2.0 应用，并注册以下生产环境 SP 值：

| IdP 设置 | 值 |
|---|---|
| SP Entity ID / Audience | `urn:sudomimus:production:federation-sp` |
| ACS / Reply URL | `https://federation.sudomimus.com/saml/acs` |
| 发起模式 | SP-initiated |
| Response binding | HTTP-POST |
| Assertion 签名 | 必须启用 |

ACS 必须精确匹配，Assertion 中的 audience 必须是上面的 SP Entity ID。配置非生产环境时，请改用该环境连接详情页显示的只读 SP Entity ID 和 ACS。

:::caution[必须签署 Assertion]
Sudomimus 要求 **Assertion** 本身带有签名。只签署外层 SAML Response 不够。不要启用加密 Assertion；当前不支持它。
:::

## 2. 配置 Subject 与资料属性

稳定的外部身份通常来自 SAML `NameID`。请让 `NameID` 在该用户的生命周期内保持稳定，并在这个 IdP 应用中唯一；不要使用可变的显示名称。

你也可以通过 SAML Attribute 释放资料值。记录每个属性的精确名称；如果 IdP 使用 URI 风格名称，也要完整记录：

| 建议用途 | 属性名称示例 |
|---|---|
| 邮箱 | `mail` |
| 名字 | `given_name` |
| 姓氏 | `family_name` |

这些只是示例，不是规定的字面量。在 With 中输入的名称必须与 Assertion 实际发送的 Attribute 名称完全一致。

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

## 3. 收集 IdP 配置值

从 IdP 复制：

- 作为 Assertion issuer 的精确 **IdP Entity ID**；
- 接收 AuthnRequest 的 HTTPS **IdP SSO URL**；
- 当前有效的 Assertion 签名证书。

请把证书导出为 PEM 编码的 X.509 公钥证书，并保留头尾：

```text
-----BEGIN CERTIFICATE-----
MIIC...
-----END CERTIFICATE-----
```

不要粘贴私钥。证书轮换期间，请在重叠窗口内同时配置新旧公钥证书，确认新证书生效后再移除旧证书。

## 4. 在 With 中创建连接

在 With 门户中：

1. 打开你的组织。
2. 打开**外部连接**并选择**新建连接**。
3. 选择 **SAML 2.0**。
4. 输入显示名称、IdP Entity ID、IdP SSO URL 和签名证书。
5. 根据需要输入精确的邮箱、名字和姓氏属性名。
6. 创建连接。

With 门户创建的新 SAML 连接会使用 `NameID` 作为稳定 subject 来源。协议、IdP Entity ID 和 subject 来源共同定义凭据命名空间，之后不能修改；如需改变其中任意一项，请创建新连接。

连接详情页会再次显示权威的 SP Entity ID 和 ACS。测试之前，请将其与 IdP 中注册的值逐一比较。

## 5. 使用该连接

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

<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 开关。

## 6. 测试登录

使用一个非管理员测试用户，启动对应的应用级或域级登录流程。

确认：

- 浏览器把 SP 发起的 AuthnRequest 送到配置的 IdP；
- IdP 把响应 POST 到精确的 ACS；
- Assertion issuer、audience、recipient 和 `InResponseTo` 与当前流程匹配；
- Assertion 包含一个 AuthnStatement 且处于有效时间窗口；
- Assertion 本身由已配置证书签名，而不只是外层 Response；
- 第二层允许最终得到的身份。

初次协议冒烟测试可以使用 `EVERYONE` 第二层规则。若使用 `EMAIL`，要确保映射的邮箱属性存在，而且该邮箱域名已由连接所属组织验证。

Sudomimus 会拒绝重放的请求和 Assertion。浏览器看到的错误会被刻意保持为通用信息，因此排查配置时应先查看 IdP 的 SAML Response 检查工具，并逐项核对上面的清单。

## 不支持的设置

不要启用 IdP-initiated SSO、加密 Assertion、Single Logout、Artifact Binding、Metadata Import、Requested Authentication Context Policy 或签名 AuthnRequest。当前不会接受这些 profile。

## 相关内容

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