API 参考

顶层导出

来自 index.ts 的主要公开导出有：

• ServiceProvider
• ServiceProviderInstance
• IdentityProvider
• IdentityProviderInstance
• SPMetadata
• IdPMetadata
• Utility
• SamlLib
• Constants
• Extractor
• Soap
• validate
• validateMetadata
• setSchemaValidator
• setDOMParserOptions
• saml2-enhancements 中的导出

先选哪一层 API

第一层：高层实体

优先使用：

• ServiceProvider()
• IdentityProvider()

它们覆盖绝大多数真实接入场景。

第二层：Metadata 与低层模块

当你需要更多控制时，再使用：

• SPMetadata
• IdPMetadata
• Extractor
• Soap
• Utility
• validate()

第三层：协议级操作

只有在你确定要处理签名、解密、模板和单独验签时，再深入：

• SamlLib

ServiceProvider

工厂函数：

import { ServiceProvider } from 'samlesa';

const sp = ServiceProvider(config);

主要方法

createLoginRequest(idp, binding, customTagReplacement?)

生成登录请求。

常用 binding：

• redirect
• post
• simpleSign
• artifact

parseLoginResponse(idp, binding, request)

解析登录响应。

Artifact 模式下会自动进入 Artifact 解析链路。

createArtifactResolveRequest(idp, artifact)

生成 ArtifactResolve SOAP 请求。

createArtifactResolveResponse(idp, config?)

生成 ArtifactResponse SOAP 响应。

parseArtifactResolveRequest(idp, xml)

解析收到的 ArtifactResolve 请求。

parseArtifactResolveResponse(idp, xml, inResponseTo?)

解析收到的 ArtifactResponse 响应。

getMetadata()

返回当前 SP metadata XML。

exportMetadata(filePath)

把 metadata 导出到文件。

getEntitySetting()

读取当前实体最终生效的配置对象。

IdentityProvider

工厂函数：

import { IdentityProvider } from 'samlesa';

const idp = IdentityProvider(config);

主要方法

createLoginResponse(params)

生成登录响应，支持：

• post
• redirect
• simpleSign
• artifact

parseLoginRequest(sp, binding, request)

解析来自 SP 的登录请求。

createArtifactResolveRequest(sp, artifact)

生成 ArtifactResolve SOAP 请求。

createArtifactResolveResponse(params)

生成 ArtifactResponse SOAP 响应。

parseArtifactResolveRequest(sp, xml)

解析收到的 ArtifactResolve 请求。

parseArtifactResolveResponse(sp, xml, inResponseTo?)

解析收到的 ArtifactResponse 响应。

getMetadata()

返回当前 IdP metadata XML。

exportMetadata(filePath)

把 metadata 导出到文件。

getEntitySetting()

读取当前实体最终生效的配置对象。

登录与注销公共能力

Entity 基类中还提供这些能力给 SP / IdP 复用：

• createLogoutRequest()
• createLogoutResponse()
• parseLogoutRequest()
• parseLogoutResponse()
• verifyFields()

如果你需要 SLO，优先从这些高层入口开始。

SPMetadata / IdPMetadata

适合：

• 解析 metadata XML
• 获取 endpoint
• 获取证书
• 读取 NameIDFormat
• 生成或导出 metadata

常见能力

SPMetadata

• getMetadata()
• exportMetadata()
• isAuthnRequestSigned()
• isWantAssertionsSigned()
• getAssertionConsumerService(binding)
• getSingleLogoutService(binding)
• getArtifactResolutionService(binding)

IdPMetadata

• getMetadata()
• exportMetadata()
• isWantAuthnRequestsSigned()
• getSingleSignOnService(binding)
• getSingleLogoutService(binding)
• getArtifactResolutionService(binding)

validate() / validateMetadata()

validate(xml, isSoap?)

做普通消息或 SOAP 消息的 schema 校验。

validateMetadata(xml, isParse?)

做 metadata 的 XSD 校验，并可选返回：

• metadataType: 'IdP' | 'SP' | 'both' | 'unknown'

setSchemaValidator() / setDOMParserOptions()

这两个是全局上下文级别的定制入口：

• setSchemaValidator({ validate })
• setDOMParserOptions(options)

更适合：

• 测试
• 封装库
• 统一接管底层校验或解析行为

Extractor

负责低层字段提取，不负责完整认证决策。

适用场景：

• 登录请求 / 响应调试
• Artifact SOAP 消息字段提取
• metadata 低层映射

Soap

当前主要包含：

• sendArtifactResolve()
• sendArtifactResponse()
• createArt()
• parseArt()
• encodeXmlToIso88591()

主要用于 Artifact Binding。

Utility

当前常见实用方法：

• base64Encode()
• base64Decode()
• inflateString()
• readPrivateKey()
• normalizeCertificates()
• validateCertificate()
• validateRelayState()
• sanitizeLog()

SamlLib

如果你要直接处理协议层，可以重点看这些方法：

• verifySignature()
• constructSAMLSignature()
• verifyMessageSignature()
• encryptAssertion()
• decryptAssertion()
• replaceTagsByValue()
• attributeStatementBuilder()
• createKeySection()
• getDigestMethod()

这层能力很强，但也意味着你需要自己承担更多协议细节和错误处理责任。