# Building Identity Federation With Saml Azure Ad

> 在本地部署的 Active Directory 与 Azure AD（Microsoft Entra ID）之间建立 SAML 2.0 身份联合（Identity Federation），实现无缝跨域认证和云应用 SSO。

- Skill: `killvxk/building-identity-federation-with-saml-azure-ad` (Agent Skill, multi-file: 8 files)
- Install (CLI): `npx skillmds@latest add killvxk/building-identity-federation-with-saml-azure-ad`
- Raw SKILL.md: https://api.skillmd.com/api/skills/killvxk/building-identity-federation-with-saml-azure-ad/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- License: Apache-2.0
- Author: killvxk (https://skillmd.com/u/killvxk)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/killvxk/building-identity-federation-with-saml-azure-ad

---


# 使用 SAML Azure AD 构建身份联合

## 概述

身份联合（Identity Federation）使由一个身份提供商（IdP）认证的用户能够访问另一个身份提供商管理的资源，而无需维护独立的凭据。本技能涵盖在组织本地 Active Directory（通过 AD FS 或第三方 IdP）与 Microsoft Entra ID（原 Azure AD）之间建立 SAML 2.0 联合，以及为第三方 SaaS 应用配置联合 SSO。联合认证消除了密码同步的顾虑，将认证权限保留在本地，同时将 SSO 扩展到云资源。

## 前置条件

- 本地部署的 Active Directory 域
- AD FS 2019+ 或第三方 SAML IdP（Okta、Ping 等）
- Microsoft Entra ID 租户（建议 P1 或 P2 授权）
- Azure AD Connect（若使用带密码哈希同步备份的混合身份）
- 联合端点的公共 TLS 证书
- 联合服务名称的 DNS 记录

## 核心概念

### 联合模型

| 模型 | 认证权威 | 使用场景 |
|-------|------------------------|----------|
| 联合模式（AD FS） | 本地 AD FS | 监管要求认证保留在本地 |
| 托管模式（PHS） | 带密码哈希同步的 Azure AD | 最简单的云认证，无需 AD FS |
| 托管模式（PTA） | 通过直通代理的本地服务 | 云认证对照本地 AD 验证 |
| 第三方联合 | 外部 IdP（Okta、Ping） | 多 IdP 环境 |

### SAML 联合架构

```
用户 → 云应用（SP）
   │
   └── 重定向至 Azure AD
          │
          ├── Azure AD 检查联合域
          │
          └── 重定向至本地 AD FS
                 │
                 ├── AD FS 对 Active Directory 进行认证
                 │
                 ├── AD FS 签发 SAML 令牌
                 │
                 └── 令牌回传至 Azure AD
                        │
                        ├── Azure AD 验证联合信任
                        │
                        ├── Azure AD 签发自身令牌
                        │
                        └── 用户获取云应用访问令牌
```

### 联合信任组件

| 组件 | 描述 |
|-----------|-------------|
| 令牌签名证书 | IdP 用于签名 SAML 断言的 X.509 证书 |
| 联合元数据 | 描述 IdP 端点和功能的 XML 文档 |
| 依赖方信任 | AD FS 中每个 SP（Azure AD）的配置 |
| 声明规则 | 将 AD 属性转换为 SAML 声明 |
| 签发者 URI | IdP 的唯一标识符（实体 ID） |

## 实施步骤

### 步骤 1：准备 AD FS 基础设施

```powershell
# 安装 AD FS 角色
Install-WindowsFeature ADFS-Federation -IncludeManagementTools

# 配置 AD FS 场
Install-AdfsFarm `
    -CertificateThumbprint $certThumbprint `
    -FederationServiceDisplayName "Corp Federation Service" `
    -FederationServiceName "fs.corp.example.com" `
    -ServiceAccountCredential $gmsaCredential

# 验证 AD FS 是否正常运行
Get-AdfsProperties | Select-Object HostName, Identifier, FederationPassiveAddress
```

### 步骤 2：配置 Azure AD 联合域

```powershell
# 安装 Microsoft Graph PowerShell 模块
Install-Module Microsoft.Graph -Scope CurrentUser

# 连接到 Microsoft Graph
Connect-MgGraph -Scopes "Domain.ReadWrite.All"

# 将托管域转换为联合域
# 使用 AD FS 联合元数据 URL
$domainId = "corp.example.com"
$federationConfig = @{
    issuerUri = "http://fs.corp.example.com/adfs/services/trust"
    metadataExchangeUri = "https://fs.corp.example.com/adfs/services/trust/mex"
    passiveSignInUri = "https://fs.corp.example.com/adfs/ls/"
    signOutUri = "https://fs.corp.example.com/adfs/ls/?wa=wsignout1.0"
    signingCertificate = $base64Cert
    preferredAuthenticationProtocol = "saml"
}

# 将联合设置应用到域
New-MgDomainFederationConfiguration -DomainId $domainId -BodyParameter $federationConfig
```

### 步骤 3：配置 AD FS 声明规则

```powershell
# 为 Azure AD 添加依赖方信任
Add-AdfsRelyingPartyTrust `
    -Name "Microsoft Office 365 Identity Platform" `
    -MetadataUrl "https://nexus.microsoftonline-p.com/federationmetadata/2007-06/federationmetadata.xml"

# 配置声明规则
$rules = @"
@RuleTemplate = "LdapClaims"
@RuleName = "Extract AD Attributes"
c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname",
   Issuer == "AD AUTHORITY"]
=> issue(store = "Active Directory",
   types = ("http://schemas.xmlsoap.org/claims/UPN",
            "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
            "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname",
            "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname"),
   query = ";userPrincipalName,mail,givenName,sn;{0}",
   param = c.Value);

@RuleTemplate = "PassThroughClaims"
@RuleName = "Pass Through UPN as NameID"
c:[Type == "http://schemas.xmlsoap.org/claims/UPN"]
=> issue(Type = "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier",
   Issuer = c.Issuer, OriginalIssuer = c.OriginalIssuer,
   Value = c.Value,
   ValueType = c.ValueType,
   Properties["http://schemas.xmlsoap.org/ws/2005/05/identity/claimproperties/format"]
       = "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent");
"@

Set-AdfsRelyingPartyTrust `
    -TargetName "Microsoft Office 365 Identity Platform" `
    -IssuanceTransformRules $rules
```

### 步骤 4：配置第三方 SaaS 联合

对于每个通过 Azure AD 支持 SAML SSO 的 SaaS 应用：

1. 导航至 Microsoft Entra 管理中心 > 企业应用程序
2. 从应用库添加应用程序（或创建自定义 SAML）
3. 配置单点登录 > SAML：
   - 标识符（实体 ID）：应用程序的实体 ID
   - 回复 URL（ACS）：应用程序的断言使用者服务 URL
   - 登录 URL：应用程序的登录 URL
4. 映射用户属性/声明：
   - NameID：user.userprincipalname（电子邮件格式）
   - 应用程序要求的其他声明
5. 下载联合元数据 XML 或证书
6. 使用 Azure AD 的联合详情配置 SaaS 应用

### 步骤 5：证书生命周期管理

AD FS 令牌签名证书会过期，必须进行续订：

```powershell
# 检查当前证书到期时间
Get-AdfsCertificate -CertificateType Token-Signing | Select-Object Thumbprint, NotAfter

# AD FS 支持自动滚动更新（默认启用）
Get-AdfsProperties | Select-Object AutoCertificateRollover

# 若需要手动轮换：
# 1. 添加新证书作为次要证书
Set-AdfsCertificate -CertificateType Token-Signing -Thumbprint $newThumbprint -IsPrimary $false
# 2. 用新证书更新 Azure AD
# 3. 提升为主要证书
Set-AdfsCertificate -CertificateType Token-Signing -Thumbprint $newThumbprint -IsPrimary $true
# 4. 移除旧证书
Remove-AdfsCertificate -CertificateType Token-Signing -Thumbprint $oldThumbprint
```

## 验证清单

- [ ] AD FS 场正常运行，具有有效的 TLS 和令牌签名证书
- [ ] Azure AD 域已配置为联合域，元数据正确
- [ ] 声明规则正确地将 AD 属性转换为 SAML 断言
- [ ] 测试用户能够端到端通过联合流程进行认证
- [ ] 在 AD FS 或 Azure AD 条件访问级别强制执行 MFA
- [ ] 启用证书自动滚动更新或已计划手动轮换
- [ ] 联合元数据端点可公开访问
- [ ] 已配置智能锁定以防止暴力破解
- [ ] 已在 AD FS 上配置外网锁定策略
- [ ] 已为 AD FS 健康状况和证书到期配置监控
- [ ] 灾难恢复：托管认证回退方案已记录

## 参考资料

- [Microsoft Entra 联合文档](https://learn.microsoft.com/en-us/entra/identity/hybrid/connect/whatis-fed)
- [AD FS 设计指南](https://learn.microsoft.com/en-us/windows-server/identity/ad-fs/design/ad-fs-design-guide)
- [为 Azure AD 联合配置 AD FS](https://learn.microsoft.com/en-us/entra/identity/hybrid/connect/how-to-connect-fed-management)
- [SAML 2.0 认证 - OASIS](https://docs.oasis-open.org/security/saml/v2.0/)