实体与配置
两类配置入口
Section titled “两类配置入口”ServiceProvider() 和 IdentityProvider() 都支持两种主流方式：
- 直接传 metadata XML
- 传对象配置，由库生成 metadata
metadata 驱动
Section titled “metadata 驱动”const sp = ServiceProvider({ metadata: readFileSync('./metadata/sp.xml')});对象配置驱动
Section titled “对象配置驱动”const idp = IdentityProvider({ entityID: 'https://idp.example.com/metadata', signingCert: readFileSync('./certs/idp.crt'), privateKey: readFileSync('./certs/idp.key'), singleSignOnService: [ { Binding: 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST', Location: 'https://idp.example.com/saml/sso' } ]});实体基础默认值定义在 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 | '' |
一个需要特别注意的细节是：如果你把 strictSecurity 显式设成 false，而又没有手动指定 allowLegacySha1，当前实现会把 allowLegacySha1 一并放宽。
metadata 的优先级
Section titled “metadata 的优先级”当你传入 metadata 时，metadata 不只是“给你展示一下”，它会参与实际配置回填。
例如：
- SP 会按 metadata 回填
authnRequestsSigned - SP 会按 metadata 回填
wantAssertionsSigned - IdP 会按 metadata 回填
wantAuthnRequestsSigned - 两边都会优先回填
nameIDFormat
所以 metadata 驱动配置不是装饰功能，而是当前实现里最自然的配置方式。
ServiceProvider 常用字段
Section titled “ServiceProvider 常用字段”标识与元数据
Section titled “标识与元数据”metadataentityIDnameIDFormatsigningCertencryptCert
assertionConsumerServicesingleLogoutServiceartifactResolutionService
privateKeyprivateKeyPassencPrivateKeyencPrivateKeyPassrequestSignatureAlgorithmdataEncryptionAlgorithmkeyEncryptionAlgorithmkeyEncryptionDigestkeyEncryptionMgf1keyEncryptionOAEPParamssignatureConfigtransformationAlgorithms
strictSecurityallowLegacySha1allowCertificateUsageMismatchauthnRequestsSignedwantAssertionsSignedwantMessageSignedwantLogoutRequestSignedwantLogoutResponseSignedisAssertionEncryptedallowCreateclockDrifts
loginRequestTemplatelogoutRequestTemplateauthnRequestEnhancementsconditionsEnhancementssubjectConfirmationEnhancementsmetadataEnhancements
IdentityProvider 常用字段
Section titled “IdentityProvider 常用字段”标识与元数据
Section titled “标识与元数据”metadataentityIDnameIDFormatsigningCertencryptCert
singleSignOnServicesingleLogoutServiceartifactResolutionService
privateKeyprivateKeyPassencPrivateKeyencPrivateKeyPassrequestSignatureAlgorithmdataEncryptionAlgorithmkeyEncryptionAlgorithmkeyEncryptionDigestkeyEncryptionMgf1keyEncryptionOAEPParams
strictSecurityallowLegacySha1allowCertificateUsageMismatchwantAuthnRequestsSignedwantLogoutRequestSignedwantLogoutResponseSignedmessageSigningOrderisAssertionEncryptedtagPrefixgenerateID
loginResponseTemplatelogoutRequestTemplateauthnRequestEnhancementsconditionsEnhancementssubjectConfirmationEnhancementsmetadataEnhancements
默认推荐组合
Section titled “默认推荐组合”这是当前最推荐、也最贴合默认实现的组合：
- 请求签名：
RSA_SHA512 - 断言加密：
AES_256_GCM - 密钥加密：
RSA_OAEP_MGF1P
算法常量来自 Constants.algorithms / urn.ts，常用分组包括：
RSA_SHA1RSA_SHA224RSA_SHA256RSA_SHA384RSA_SHA512ECDSA_SHA256ECDSA_SHA384ECDSA_SHA512RSA_PSS_SHA256EDDSA_ED25519EDDSA_ED488
数据加密算法
Section titled “数据加密算法”AES_128_CBCAES_192_CBCAES_256_CBCAES_128_GCMAES_192_GCMAES_256_GCMAES_128_CTRAES_192_CTRAES_256_CTRTRIPLE_DES
密钥加密算法
Section titled “密钥加密算法”RSA_OAEP_MGF1PRSA_OAEPRSA_1_5AES_128_KWAES_192_KWAES_256_KWAES_128_GCM_KWAES_192_GCM_KWAES_256_GCM_KW
Metadata 对象的作用
Section titled “Metadata 对象的作用”除了高层实体，库还直接导出：
SPMetadataIdPMetadata
它们适合做这些事：
- 从 XML metadata 解析 endpoint
- 读取证书和
NameIDFormat - 生成 metadata XML
- 导出 metadata 到文件
如果你只需要“拿现成 metadata 做接入”，通常直接把 metadata 传给高层实体即可，不一定要先自己实例化 SPMetadata 或 IdPMetadata。
推荐配置实践
Section titled “推荐配置实践”- 优先使用 metadata 驱动对端配置
- 保持
strictSecurity: true - 使用默认算法组合起步
- 明确区分 signing cert 和 encryption cert
- 为 SP 和 IdP 都配置清晰的 endpoint 列表
- 没有必要时关闭
strictSecurity - 把
allowLegacySha1当成默认兼容开关 - 长期依赖
allowCertificateUsageMismatch - 一上来就跳过高层实体 API，直接手写
SamlLib调用