快速开始

安装

pnpm add samlesa

如果你正在修改这个仓库本身：

pnpm install
pnpm run build
pnpm test

推荐的接入思路

最顺手的起步方式是：

1. 用 metadata 初始化对端实体
2. 用对象配置初始化本端实体
3. 先跑通 createLoginRequest() / parseLoginResponse() 这一条主链路
4. 再按需要补充签名、加密、Artifact 或增强功能

最小 SP 示例

import { readFileSync } from 'node:fs';
import { IdentityProvider, ServiceProvider } from 'samlesa';

const sp = ServiceProvider({
  entityID: 'https://sp.example.com/metadata',
  privateKey: readFileSync('./certs/sp.key'),
  signingCert: readFileSync('./certs/sp.crt'),
  assertionConsumerService: [
    {
      Binding: 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST',
      Location: 'https://sp.example.com/saml/acs'
    }
  ],
  singleLogoutService: [
    {
      Binding: 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect',
      Location: 'https://sp.example.com/saml/logout'
    }
  ]
});

const idp = IdentityProvider({
  metadata: readFileSync('./metadata/idp.xml')
});

const loginRequest = sp.createLoginRequest(idp, 'redirect');

console.log(loginRequest.entityEndpoint);
console.log(loginRequest.context);

最小 IdP 示例

import { readFileSync } from 'node:fs';
import { IdentityProvider, ServiceProvider } from 'samlesa';

const idp = IdentityProvider({
  entityID: 'https://idp.example.com/metadata',
  privateKey: readFileSync('./certs/idp.key'),
  signingCert: readFileSync('./certs/idp.crt'),
  singleSignOnService: [
    {
      Binding: 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST',
      Location: 'https://idp.example.com/saml/sso'
    }
  ]
});

const sp = ServiceProvider({
  metadata: readFileSync('./metadata/sp.xml')
});

const loginResponse = await idp.createLoginResponse({
  sp,
  binding: 'post',
  user: {
    NameID: 'user@example.com'
  }
});

console.log(loginResponse.entityEndpoint);
console.log(loginResponse.context);

SP 解析登录响应

const result = await sp.parseLoginResponse(idp, 'post', {
  body: {
    SAMLResponse: '<base64 response here>'
  }
});

console.log(result.extract.nameID);
console.log(result.extract.attributes);

IdP 解析登录请求

const result = await idp.parseLoginRequest(sp, 'redirect', {
  query: {
    SAMLRequest: '<deflated request here>',
    RelayState: 'state-123'
  }
});

console.log(result.extract.request);
console.log(result.extract.issuer);

什么时候优先用 metadata

只要你已经拿到了对端 metadata，就优先传 metadata：

• endpoint 会从 metadata 解析
• 证书会从 metadata 解析
• want*Signed 期望值会按 metadata 回填
• 你的本地配置和对端声明更不容易漂移

第一个生产可用版本建议先做这些

• 保持 strictSecurity: true
• 不要主动开启 allowLegacySha1
• 不要主动开启 allowCertificateUsageMismatch
• 先使用默认算法组合
• 把 SP / IdP metadata 都纳入配置源
• 在业务层记录 InResponseTo、RelayState、NameID 和主要状态码，便于排错

下一步看哪里

• 想查默认值、证书、算法和增强配置：看“实体与配置”
• 想选 Binding：看“Bindings 与流程”
• 想做 Artifact 前后信道：看“Artifact Binding”
• 想查公开导出和类型：看“API 参考”和“类型与配置模型”