概览

项目定位

samlesa 的定位不是“只提供若干 XML helper”，而是把常见 SAML 2.0 接入拆成两层：

• 高层实体层：ServiceProvider、IdentityProvider
• 低层能力层：SamlLib、Extractor、Soap、Utility、schema validator

如果你的目标是做一个可落地的 SSO / SLO 集成，优先从高层实体 API 开始。只有在你已经明确需要自定义模板、单独验签或做库级二次封装时，再往低层走。

核心能力

当前实现重点覆盖以下能力：

• SP 发起登录请求，IdP 发起登录响应
• IdP 解析登录请求，SP 解析登录响应
• Redirect / POST / SimpleSign / Artifact Binding
• Metadata 生成、导出、解析和部分增强元素支持
• XML Signature 验证
• Assertion 加密和解密
• XML Schema 校验
• SAML 2.0 增强元素构建与集成

支持的 Binding

登录相关

• redirect
• post
• simpleSign
• artifact

注销相关

• redirect
• post

后信道 SOAP

• Artifact Resolve / Artifact Response

默认值

实体构造默认值来自 src/entity.ts：

配置项	默认值
strictSecurity	true
allowLegacySha1	false
allowCertificateUsageMismatch	false
messageSigningOrder	sign-then-encrypt
allowCreate	false
isAssertionEncrypted	false
requestSignatureAlgorithm	RSA_SHA512
dataEncryptionAlgorithm	AES_256_GCM
keyEncryptionAlgorithm	RSA_OAEP_MGF1P
relayState	''

算法能力

默认推荐组合

当前实现的默认安全组合是：

• 消息签名：RSA_SHA512
• 断言数据加密：AES_256_GCM
• 会话密钥加密：RSA_OAEP_MGF1P

常量表暴露的算法族

Constants.algorithms 和 urn.ts 中暴露了较完整的算法常量与映射：

• 签名算法：RSA-SHA1/224/256/384/512、ECDSA-SHA256/384/512、RSA-PSS-SHA256、Ed25519、Ed448
• 摘要算法：SHA-1 / SHA-224 / SHA-256 / SHA-384 / SHA-512
• 数据加密：AES-CBC / AES-GCM / AES-CTR / TripleDES
• 密钥加密：RSA-OAEP / RSA-1_5 / AES Key Wrap / AES GCM Key Wrap

如果你只做标准企业接入，文档和示例建议围绕默认的 RSA + AES-GCM + OAEP 组合展开。

当前实现的安全特征

当前版本默认已经包含这些安全收紧：

• 拒绝 XXE、DOCTYPE、ENTITY 注入
• 先做 schema 校验，再进入签名验证和业务字段校验
• Response 只接受单个顶层 Assertion 或 EncryptedAssertion
• SOAP ArtifactResponse 只接受单个 resolved message
• 默认拒绝 SHA-1 家族签名算法
• 默认校验证书用途，不允许随意把 encryption cert 当 signing cert 用

推荐使用层级

第一层：高层 API

适用于大多数应用：

• ServiceProvider()
• IdentityProvider()
• createLoginRequest()
• createLoginResponse()
• parseLoginRequest()
• parseLoginResponse()

第二层：Metadata 对象

适用于 metadata 管理和调试：

• SPMetadata
• IdPMetadata

第三层：低层模块

适用于模板定制、验签、解密、调试和库级封装：

• SamlLib
• Extractor
• Soap
• Utility
• validate()
• validateMetadata()

最重要的实践建议

如果你已经拿到了对端 metadata，优先使用 metadata 驱动配置，而不是手写 endpoint 和证书。这和当前实现的工作方式最一致，也最不容易把签名期望、证书用途和 endpoint 配错。