SAML 2.0 增强能力

这部分解决什么问题

很多项目在“最小 SSO 跑通”之后，还会遇到这些需求：

• 请求更强的认证上下文
• 需要代理 SSO / Scoping
• 需要声明 OneTimeUse 或 ProxyRestriction
• 需要更细粒度的 SubjectConfirmationData
• 需要在 metadata 中带 Organization 和 ContactPerson

samlesa 当前实现已经把这些增强能力接进了类型和高层配置。

高层配置入口

增强功能主要通过这些配置字段进入：

• authnRequestEnhancements
• conditionsEnhancements
• subjectConfirmationEnhancements
• metadataEnhancements

它们同时出现在：

• ServiceProviderSettings
• IdentityProviderSettings
• MetadataSpOptions
• MetadataIdpOptions

authnRequestEnhancements

当前支持：

• scoping
• requestedAuthnContext
• forceAuthn
• isPassive
• consent
• attributeConsumingServiceIndex
• providerName

示例：

const sp = ServiceProvider({
  ...config,
  authnRequestEnhancements: {
    forceAuthn: true,
    requestedAuthnContext: {
      comparison: 'exact',
      classRefs: [
        'urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport'
      ]
    },
    providerName: 'samlesa demo SP'
  }
});

scoping

适用于代理登录或控制 IdP 选择范围的场景。

字段包括：

• proxyCount
• requesterID
• idpList

示例：

authnRequestEnhancements: {
  scoping: {
    proxyCount: 1,
    requesterID: ['https://sp.example.com/metadata'],
    idpList: [
      {
        providerID: 'https://idp-a.example.com/metadata',
        name: 'Primary IdP'
      }
    ]
  }
}

requestedAuthnContext

适用于 MFA、LoA 或强认证要求场景。

字段包括：

• comparison
• classRefs
• declRefs

示例：

authnRequestEnhancements: {
  requestedAuthnContext: {
    comparison: 'minimum',
    classRefs: [
      'urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport'
    ]
  }
}

conditionsEnhancements

当前支持：

• oneTimeUse
• proxyRestriction

示例：

const idp = IdentityProvider({
  ...config,
  conditionsEnhancements: {
    oneTimeUse: { enabled: true },
    proxyRestriction: {
      count: 1,
      audience: ['https://sp.example.com/metadata']
    }
  }
});

subjectConfirmationEnhancements

当前支持：

• address
• notBefore
• notOnOrAfter
• recipient
• inResponseTo

这在你需要精细控制断言使用窗口和接收方时很有用。

metadataEnhancements

当前支持：

• organization
• contactPerson

示例：

const sp = ServiceProvider({
  ...config,
  metadataEnhancements: {
    organization: {
      name: { value: 'Example Corp', 'xml:lang': 'en' },
      displayName: { value: 'Example', 'xml:lang': 'en' },
      url: { value: 'https://example.com', 'xml:lang': 'en' }
    },
    contactPerson: [
      {
        contactType: 'technical',
        emailAddress: 'ops@example.com'
      }
    ]
  }
});

当前实现里的边界

这些增强能力的目标是“补标准表达力”，不是“替代整个消息模板系统”。

适合：

• 加标准字段
• 满足对端对 AuthnRequest / Metadata 的规范要求
• 让高层 API 仍然可用

不适合：

• 把大量业务私有 XML 直接塞进去
• 用增强字段去绕过既有模板和验证逻辑

如果你需要完全自定义 XML 结构，应该优先考虑模板和 SamlLib。