building-identity-federation-with-saml-azure-ad

name	building-identity-federation-with-saml-azure-ad
description	在本地部署的 Active Directory 与 Azure AD（Microsoft Entra ID）之间建立 SAML 2.0 身份联合（Identity Federation），实现无缝跨域认证和云应用 SSO。
domain	cybersecurity
subdomain	identity-access-management
tags	["saml","azure-ad","entra-id","federation","identity","sso","adfs","hybrid-identity"]
version	1.0
author	mahipal
license	Apache-2.0

使用 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 基础设施

# 安装 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 联合域

# 安装 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 声明规则

# 为 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 令牌签名证书会过期，必须进行续订：

# 检查当前证书到期时间
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 联合文档
• AD FS 设计指南
• 为 Azure AD 联合配置 AD FS
• SAML 2.0 认证 - OASIS