Bitzsoft.Integrations.SsoRedirect 1.0.0-alpha.7

Bitzsoft.Integrations.SsoRedirect

SSO 跳转通用管道 — 通过纯配置对接任意 SSO 平台，无需编写代码。

功能

• 配置驱动：四种认证模式（UrlTemplate / AesEncryption / ApiRedirect / Pipeline）覆盖绝大多数 SSO 场景
• 管道可组合：Pipeline 模式支持任意步骤编排（加密、签名、JWT、API 调用），内置 11 种步骤 + 自定义步骤逃生口
• 多算法支持：AES（ECB/CBC）、RSA（PKCS1/OAEP）、HMAC-SHA256/SHA1、MD5、HS256 JWT
• API 跳转：支持 JSON 提取与 302 重定向两种 API 响应解析
• 第三方请求日志：内置 RequestLogging DelegatingHandler，记录 ApiRedirect / Pipeline API 步骤的 HTTP 请求与响应
• IConfiguration 绑定：支持从 appsettings.json 配置节加载全部参数

设计理念

传统做法是每个 SSO 供应商写一个 Provider 项目。SsoRedirect 将 SSO 跳转抽象为配置驱动的可组合管道：

前三种为预设模式，覆盖 80% 场景。Pipeline 模式通过字典配置任意步骤组合，适用于 RSA → API → MD5 签名、JWT Bearer → API 等多步串联场景。

新对接一个 SSO 平台？ 只需要配置，不需要新建项目。

安装

dotnet add package Bitzsoft.Integrations.SsoRedirect

快速开始

模式一：UrlTemplate（URL 模板替换）

最常用的模式。平台给一个 SSO URL 模板，你把参数填进去。

using Bitzsoft.Integrations.SsoRedirect;

// 例：法信
services.AddBitzsoftSsoRedirect(options =>
{
    options.ProviderName = "法信";
    options.AuthMode = SsoAuthMode.UrlTemplate;
    options.SsoUrlTemplate = "https://www.faxin.cn/sso?uid={userId}&token={token}&t={timestamp}";
    options.Token = "your-sso-token";
});

// 例：带 HMAC 签名的平台
services.AddBitzsoftSsoRedirect(options =>
{
    options.ProviderName = "某平台";
    options.AuthMode = SsoAuthMode.UrlTemplate;
    options.SsoUrlTemplate = "https://sso.example.com/login?uid={userId}&t={timestamp}";
    options.SignSecret = "your-hmac-secret";
    options.SignAlgorithm = "HMAC-SHA256"; // 或 HMAC-SHA1、MD5
});

支持的占位符：

配置 SignSecret 后，签名会自动作为 sign 查询参数追加到 URL。

模式二：AesEncryption（AES 加密）

平台要求加密令牌的场景。构造明文 → AES 加密 → Base64 → 拼接 URL。

// 例：威科先行（AES-ECB）
services.AddBitzsoftSsoRedirect(options =>
{
    options.ProviderName = "wkinfo";
    options.AuthMode = SsoAuthMode.AesEncryption;
    options.Token = "your-app-secret";
    options.AesKey = "your-app-secret";
    options.AesCipherMode = "ECB";
    options.AesPlainTextTemplate = "{timestamp}-{tenantName}";
    options.TenantName = "your-tenant";
    options.AesUrlTemplate = "https://law.wkinfo.com.cn/oauth/thirdParty/login?appId=your-app-id&cipher={cipher}";
});

// 例：AES-CBC 模式
services.AddBitzsoftSsoRedirect(options =>
{
    options.ProviderName = "某平台";
    options.AuthMode = SsoAuthMode.AesEncryption;
    options.AesPlainTextTemplate = "{userId}|{timestampMs}|{token}";
    options.AesKey = "your-32-byte-aes-key-here";
    options.AesIv = "your-16-byte-iv";
    options.AesCipherMode = "CBC";
    options.AesUrlTemplate = "https://www.example.com/sso?loginid={userId}&ts={timestamp}&token={cipher}";
});

明文模板占位符：

URL 模板占位符：

密钥不足 16/24/32 字节时自动补零，超过 32 字节会抛异常。

模式三：ApiRedirect（API 获取链接）

需要先调外部 API 获取访问链接或令牌的场景。

// 例：API 返回 JSON 中的 URL
services.AddBitzsoftSsoRedirect(options =>
{
    options.ProviderName = "探案家";
    options.AuthMode = SsoAuthMode.ApiRedirect;
    options.ApiUrl = "https://api.example.com/getKey";
    options.ApiMethod = "POST";
    options.ApiBodyTemplate = "{\"userName\":\"{userId}\",\"appId\":\"{appId}\"}";
    options.ApiResponseCodePath = "code";
    options.ApiSuccessCode = "0";
    options.ApiResponseUrlPath = "data.appKey";
    options.ApiResultUrlTemplate = "https://jumpscope.cn/taj/assetVerification?appKey={apiResult}";
    options.AppId = "your-app-id";
    options.Token = "your-token";
});

// 例：API 返回 302 重定向
services.AddBitzsoftSsoRedirect(options =>
{
    options.ProviderName = "某平台";
    options.AuthMode = SsoAuthMode.ApiRedirect;
    options.ApiUrl = "https://api.example.com/redirect?uid={userId}&t={timestamp}";
    options.ApiMethod = "GET";
    options.ApiResponseType = "redirect"; // 从 Location 头获取 URL
});

API 请求体占位符： {userId}、{appId}、{timestamp}、{token}

API 响应配置：

模式四：Pipeline（可组合步骤管道）

当 SSO 流程涉及多步骤串联（如 RSA 加密 → API 调用 → MD5 签名），预设模式无法满足时使用。

// 例：见微数据 — RSA 加密 → API 调用 → MD5 签名
services.AddBitzsoftSsoRedirect(options =>
{
    options.ProviderName = "见微数据";
    options.AuthMode = SsoAuthMode.Pipeline;

    // 步骤链（按序执行）
    options.PipelineSteps =
    [
        "template",              // 1. 构造 RSA 明文 → PlainText
        "rsa",                    // 2. RSA 加密 PlainText → CipherText
        "template:requestBody",   // 3. 构造 API 请求体（含密文）→ RequestBody
        "apiCall",                // 4. 调 API → ApiResult
        "sign",                   // 5. MD5 签名 → Signature
        "appendSignature",        // 6. 追加签名到 URL
    ];

    // 步骤模板
    options.StepTemplates = new()
    {
        ["template"] = """{"userId":"{userId}","timestamp":"{timestamp}","platform":"web_common"}""",
        ["template:requestBody"] = """{"codestr":"{cipher}","codeType":"jy","redirect":0}""",
    };

    // 步骤参数（键格式: "步骤名:参数名"）
    options.StepParameters = new()
    {
        ["rsa:PublicKey"] = "MIIBIjANBg...",
        ["apiCall:Url"] = "https://api.jianweidata.com/getUserInstValidate",
        ["apiCall:Method"] = "POST",
        ["apiCall:ResponseUrlPath"] = "location",
        ["apiCall:ResponseCodePath"] = "code",
        ["apiCall:SuccessCode"] = "0",
        ["sign:Algorithm"] = "MD5",
        ["sign:Secret"] = "",
    };
});

// 例：网核宝 — HS256 JWT Bearer 鉴权后调用 API
services.AddBitzsoftSsoRedirect(options =>
{
    options.ProviderName = "网核宝";
    options.AuthMode = SsoAuthMode.Pipeline;
    options.Token = "{id}.{secret}"; // 网核宝 API Key
    options.PipelineSteps =
    [
        "jwtBearer",
        "template:requestBody",
        "apiCall",
    ];
    options.StepTemplates = new()
    {
        ["template:requestBody"] = """{"caseCodes":["111111","222222"]}""",
    };
    options.StepParameters = new()
    {
        ["apiCall:Url"] = "https://open.wanghebao.com/api/case_codes",
        ["apiCall:Method"] = "POST",
        ["apiCall:ResponseCodePath"] = "status",
        ["apiCall:SuccessCode"] = "true",
        ["apiCall:ResponseUrlPath"] = "",
    };
});

内置步骤

步骤参数键

自定义步骤

当内置步骤无法满足需求时，可通过委托注入自定义逻辑：

options.CustomSteps = new()
{
    ["myCustomStep"] = (context, ct) =>
    {
        context.ExtraParams["customKey"] = "computed-value";
        return ValueTask.CompletedTask;
    },
};

使用服务

using Bitzsoft.Integrations.SsoRedirect;

public class SsoService
{
    private readonly SsoRedirectProvider _provider;

    public SsoService(SsoRedirectProvider provider)
    {
        _provider = provider;
    }

    public async Task<string> GetLoginUrlAsync(string userId, string? redirectTo = null)
    {
        var result = await _provider.GenerateAccessUrlAsync(userId, redirectTo);
        Console.WriteLine($"链接在 {result.ExpiresAt:HH:mm:ss} 过期");
        return result.Url;
    }
}

从 IConfiguration 绑定

// appsettings.json
// {
//   "SsoRedirect": {
//     "ProviderName": "某平台",
//     "AuthMode": "UrlTemplate",
//     "SsoUrlTemplate": "https://...",
//     "Token": "..."
//   }
// }

services.AddBitzsoftSsoRedirect(configuration, "SsoRedirect");

第三方请求日志

内置 Bitzsoft.Integrations.RequestLogging 出站请求记录管道，默认使用 NullRequestLogStore 不持久化。

// ① 默认：启用记录管道但不持久化（日志丢弃）
services.AddBitzsoftSsoRedirect(options => { /* ... */ });

// ② 持久化：宿主注册 IRequestLogStore 实现后，所有出站请求自动落库
services.AddRequestLogging<MyRequestLogStore>(opts =>
{
    opts.MaxBodyLength = 8192;
    opts.SensitiveFields.Add("mySecret");
});
services.AddBitzsoftSsoRedirect(options => { /* ... */ });

完整配置参考

通用配置

UrlTemplate 模式

AesEncryption 模式

ApiRedirect 模式

Pipeline 模式

已对接供应商

核心类型

依赖

• Microsoft.Extensions.Http — HttpClient 工厂支持（ApiRedirect / Pipeline API 步骤）
• Bitzsoft.Integrations.Compatibility — 基础工具库