类型与配置模型
这一页的目标
Section titled “这一页的目标”如果你在 TypeScript 项目里使用 samlesa，真正决定接入体验的除了 API，还有这些配置和返回类型本身。这一页按“类型做什么”来梳理，而不是机械罗列字段。
实体配置类型
Section titled “实体配置类型”ServiceProviderSettings
Section titled “ServiceProviderSettings”用于配置 ServiceProvider()。
它负责定义：
- SP 的实体标识
- ACS / SLO / ARS 端点
- 签名和加密证书
- 私钥和签名算法
- 安全开关
- 请求模板和增强能力
最常见字段：
metadataentityIDprivateKeysigningCertencryptCertassertionConsumerServicesingleLogoutServiceartifactResolutionServicestrictSecurityallowLegacySha1allowCertificateUsageMismatchrequestSignatureAlgorithmdataEncryptionAlgorithmkeyEncryptionAlgorithm
IdentityProviderSettings
Section titled “IdentityProviderSettings”用于配置 IdentityProvider()。
它负责定义：
- IdP 的实体标识
- SSO / SLO / ARS 端点
- 响应签名和断言加密行为
- 私钥和证书
- 请求 / 响应模板
- 增强能力
最常见字段：
metadataentityIDprivateKeysigningCertencryptCertsingleSignOnServicesingleLogoutServiceartifactResolutionServicestrictSecuritywantAuthnRequestsSignedmessageSigningOrderisAssertionEncrypted
Metadata 配置类型
Section titled “Metadata 配置类型”MetadataSpOptions
Section titled “MetadataSpOptions”用于直接构建 SP metadata，而不一定要先实例化 ServiceProvider。
适合：
- 单独生成 metadata
- 管理 metadata 输出
- 在工具链里做 metadata 构建
MetadataIdpOptions
Section titled “MetadataIdpOptions”用于直接构建 IdP metadata。
适合：
- 单独生成或导出 IdP metadata
- 不走完整高层实体流程的配置场景
SSOService
Section titled “SSOService”虽然它在源码里是内部辅助类型，但你在配置时会直接按这个结构传值：
{ Binding: 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST', Location: 'https://sp.example.com/saml/acs', isDefault: true}它的作用是描述：
- 这个端点对应哪个 binding
- 实际 URL 是什么
- 是否是默认端点
属性消费服务类型
Section titled “属性消费服务类型”这些类型主要用于 SP metadata 里的 AttributeConsumingService：
ServiceNameRequestedAttributeAttributeConsumingServiceAttrService
ServiceName
Section titled “ServiceName”表示一个带语言标签的名称：
{ value: 'Example Portal', lang: 'en'}RequestedAttribute
Section titled “RequestedAttribute”描述一个请求属性：
namefriendlyNameisRequirednameFormatattributeValue
AttributeConsumingService
Section titled “AttributeConsumingService”把一组服务名、描述和请求属性组织在一起，用于 metadata 暴露“我希望 IdP 返回哪些属性”。
增强能力类型
Section titled “增强能力类型”AuthnRequestEnhancedConfig
Section titled “AuthnRequestEnhancedConfig”作用：增强 AuthnRequest。
字段包括：
scopingrequestedAuthnContextforceAuthnisPassiveconsentattributeConsumingServiceIndexproviderName
ScopingConfig
Section titled “ScopingConfig”作用：定义代理 SSO 相关的 Scoping 元素。
RequestedAuthnContextConfig
Section titled “RequestedAuthnContextConfig”作用：定义认证上下文等级要求。
ConditionsEnhancedConfig
Section titled “ConditionsEnhancedConfig”作用：增强断言 Conditions。
字段包括：
oneTimeUseproxyRestriction
SubjectConfirmationDataConfig
Section titled “SubjectConfirmationDataConfig”作用：增强 SubjectConfirmationData 的时间、接收方和来源约束。
MetadataEnhancedConfig
Section titled “MetadataEnhancedConfig”作用：把 Organization 和 ContactPerson 补进 metadata。
模板相关类型
Section titled “模板相关类型”当前源码里暴露了这些模板类型：
LoginResponseTemplateAttributeStatementTemplateAttributeTemplateLoginRequestTemplateLogoutRequestTemplateLogoutResponseTemplate
它们的作用是：
- 给高层流程保留模板定制能力
- 允许你在标准流程之上替换部分 XML 模板
如果你只是正常接入，通常不需要先改模板。
绑定与上下文类型
Section titled “绑定与上下文类型”BindingContext
Section titled “BindingContext”最基础的消息上下文，通常至少会有：
contextid
PostBindingContext
Section titled “PostBindingContext”在 BindingContext 基础上增加：
entityEndpointtyperelayState
SimpleSignBindingContext
Section titled “SimpleSignBindingContext”在 PostBindingContext 基础上再增加：
sigAlgsignaturekeyInfo
这些类型决定了不同 binding 的返回值长什么样。
低层签名类型
Section titled “低层签名类型”SignatureVerifierOptions
Section titled “SignatureVerifierOptions”用于 SamlLib.verifySignature()。
主要字段：
metadatakeyFilesignatureAlgorithmstrictSecurityallowLegacySha1allowCertificateUsageMismatch
SignatureSecurityOptions
Section titled “SignatureSecurityOptions”用于更细粒度地控制低层签名安全策略。
SignatureConfig
Section titled “SignatureConfig”用于指定签名插入位置和前缀：
{ prefix: 'ds', location: { reference: "/*[local-name(.)='AuthnRequest']", action: 'append' }}什么时候需要显式导入类型
Section titled “什么时候需要显式导入类型”如果你在业务项目里主要只是初始化 SP / IdP，很多时候靠推断就够了。
这些场景更适合显式导入类型：
- 你在封装自己的 SAML 适配层
- 你要共享一份强类型配置对象
- 你在写测试夹具和协议级 helper
- 你在给 metadata / 增强配置做复用