diff --git a/aspnet-core/framework/open-api/LINGYUN.Abp.OpenApi.Authorization/README.EN.md b/aspnet-core/framework/open-api/LINGYUN.Abp.OpenApi.Authorization/README.EN.md new file mode 100644 index 000000000..e86616a03 --- /dev/null +++ b/aspnet-core/framework/open-api/LINGYUN.Abp.OpenApi.Authorization/README.EN.md @@ -0,0 +1,104 @@ +# LINGYUN.Abp.OpenApi.Authorization + +OpenApi authentication authorization middleware module, providing AppKey/AppSecret based API signature authentication middleware functionality for ABP applications. + +## Features + +* Provides OpenApi authentication middleware +* Supports request signature verification +* Supports replay attack prevention (Nonce random number verification) +* Supports request timestamp verification +* Supports client whitelist verification +* Supports IP address whitelist verification +* Supports custom authentication logic +* Supports exception handling and error message wrapping + +## Installation + +```bash +dotnet add package LINGYUN.Abp.OpenApi.Authorization +``` + +## Module Dependencies + +```csharp +[DependsOn(typeof(AbpOpenApiAuthorizationModule))] +public class YouProjectModule : AbpModule +{ + // other +} +``` + +## Basic Usage + +1. Enable OpenApi Authentication Middleware + ```csharp + public void Configure(IApplicationBuilder app) + { + // Add OpenApi authentication middleware + app.UseOpenApiAuthorization(); + } + ``` + +2. Custom Authentication Service (Optional) + ```csharp + public class CustomOpenApiAuthorizationService : OpenApiAuthorizationService + { + public CustomOpenApiAuthorizationService( + INonceStore nonceStore, + IAppKeyStore appKeyStore, + IClientChecker clientChecker, + IIpAddressChecker ipAddressChecker, + IWebClientInfoProvider clientInfoProvider, + IOptionsMonitor options, + IOptions exceptionHandlingOptions) + : base(nonceStore, appKeyStore, clientChecker, ipAddressChecker, + clientInfoProvider, options, exceptionHandlingOptions) + { + } + + // Override authentication logic + public override async Task AuthorizeAsync(HttpContext httpContext) + { + // Implement custom authentication logic + return await base.AuthorizeAsync(httpContext); + } + } + ``` + +## Authentication Process + +1. Validate Client IP Address + * Verify if the client IP address is within the allowed range through the `IIpAddressChecker` interface + +2. Validate Application Credentials + * Verify AppKey, signature, nonce, and timestamp in request headers + * Get application information through the `IAppKeyStore` interface + * Verify client access permission through the `IClientChecker` interface + * Validate signature validity and timeliness + +## Signature Rules + +1. Sort request parameters by parameter name in ASCII order +2. Convert sorted parameters to query string using URL encoding (UTF-8) +3. Concatenate request path and query string, then perform MD5 encryption to get the signature + +Example: +``` +Request path: /api/test +Parameters: + appKey=test + appSecret=123456 + nonce=abc + t=1577808000000 + +Signature calculation: +1. Sort and concatenate parameters: appKey=test&appSecret=123456&nonce=abc&t=1577808000000 +2. Concatenate with request path: /api/test?appKey=test&appSecret=123456&nonce=abc&t=1577808000000 +3. URL encode and MD5 encrypt to get the final signature +``` + +## More Information + +* [LINGYUN.Abp.OpenApi](../LINGYUN.Abp.OpenApi/README.md) +* [ABP Framework](https://abp.io/) diff --git a/aspnet-core/framework/open-api/LINGYUN.Abp.OpenApi.Authorization/README.md b/aspnet-core/framework/open-api/LINGYUN.Abp.OpenApi.Authorization/README.md new file mode 100644 index 000000000..893d3c8e5 --- /dev/null +++ b/aspnet-core/framework/open-api/LINGYUN.Abp.OpenApi.Authorization/README.md @@ -0,0 +1,104 @@ +# LINGYUN.Abp.OpenApi.Authorization + +OpenApi 认证授权中间件模块,为 ABP 应用程序提供基于 AppKey/AppSecret 的 API 签名认证中间件功能。 + +## 功能特性 + +* 提供 OpenApi 认证中间件 +* 支持请求签名验证 +* 支持防重放攻击(Nonce随机数验证) +* 支持请求时间戳验证 +* 支持客户端白名单验证 +* 支持IP地址白名单验证 +* 支持自定义认证逻辑 +* 支持异常处理和错误信息包装 + +## 安装 + +```bash +dotnet add package LINGYUN.Abp.OpenApi.Authorization +``` + +## 模块引用 + +```csharp +[DependsOn(typeof(AbpOpenApiAuthorizationModule))] +public class YouProjectModule : AbpModule +{ + // other +} +``` + +## 基本用法 + +1. 启用 OpenApi 认证中间件 + ```csharp + public void Configure(IApplicationBuilder app) + { + // 添加 OpenApi 认证中间件 + app.UseOpenApiAuthorization(); + } + ``` + +2. 自定义认证服务(可选) + ```csharp + public class CustomOpenApiAuthorizationService : OpenApiAuthorizationService + { + public CustomOpenApiAuthorizationService( + INonceStore nonceStore, + IAppKeyStore appKeyStore, + IClientChecker clientChecker, + IIpAddressChecker ipAddressChecker, + IWebClientInfoProvider clientInfoProvider, + IOptionsMonitor options, + IOptions exceptionHandlingOptions) + : base(nonceStore, appKeyStore, clientChecker, ipAddressChecker, + clientInfoProvider, options, exceptionHandlingOptions) + { + } + + // 重写认证逻辑 + public override async Task AuthorizeAsync(HttpContext httpContext) + { + // 实现自定义认证逻辑 + return await base.AuthorizeAsync(httpContext); + } + } + ``` + +## 认证流程 + +1. 验证客户端IP地址 + * 通过 `IIpAddressChecker` 接口验证客户端IP地址是否在允许范围内 + +2. 验证应用凭证 + * 验证请求头中的 AppKey、签名、随机数和时间戳 + * 通过 `IAppKeyStore` 接口获取应用信息 + * 通过 `IClientChecker` 接口验证客户端是否允许访问 + * 验证签名的有效性和时效性 + +## 签名规则 + +1. 请求参数按照参数名ASCII码从小到大排序 +2. 使用URL编码(UTF-8)将排序后的参数转换为查询字符串 +3. 将请求路径和查询字符串拼接后进行MD5加密得到签名 + +示例: +``` +请求路径:/api/test +参数: + appKey=test + appSecret=123456 + nonce=abc + t=1577808000000 + +签名计算: +1. 参数排序并拼接:appKey=test&appSecret=123456&nonce=abc&t=1577808000000 +2. 拼接请求路径:/api/test?appKey=test&appSecret=123456&nonce=abc&t=1577808000000 +3. URL编码并MD5加密得到最终签名 +``` + +## 更多信息 + +* [LINGYUN.Abp.OpenApi](../LINGYUN.Abp.OpenApi/README.md) +* [ABP框架](https://abp.io/) diff --git a/aspnet-core/framework/open-api/LINGYUN.Abp.OpenApi.IdentityServer/README.EN.md b/aspnet-core/framework/open-api/LINGYUN.Abp.OpenApi.IdentityServer/README.EN.md new file mode 100644 index 000000000..f58b03b06 --- /dev/null +++ b/aspnet-core/framework/open-api/LINGYUN.Abp.OpenApi.IdentityServer/README.EN.md @@ -0,0 +1,93 @@ +# LINGYUN.Abp.OpenApi.IdentityServer + +OpenApi IdentityServer integration module, providing IdentityServer-based AppKey/AppSecret storage implementation. + +## Features + +* IdentityServer-based AppKey/AppSecret storage +* Automatic mapping of AppKey to IdentityServer client identifier +* Automatic mapping of AppSecret to client secret +* Support for signature validity period configuration +* Support for client name configuration +* Automatic creation and update of client information + +## Installation + +```bash +dotnet add package LINGYUN.Abp.OpenApi.IdentityServer +``` + +## Module Dependencies + +```csharp +[DependsOn(typeof(AbpOpenApiIdentityServerModule))] +public class YouProjectModule : AbpModule +{ + // other +} +``` + +## How It Works + +1. AppKey Mapping + * AppKey is mapped to IdentityServer's ClientId + * Client query and management through the `IClientRepository` interface + +2. AppSecret Mapping + * AppSecret is mapped to client secret + * Secret is stored with AppSecret as identifier + +3. Signature Validity Period + * SignLifetime is stored as a custom property of the client + * Property name is "SignLifetime", value is validity period in seconds + +## Basic Usage + +1. Store Application Credentials + ```csharp + public class YourService + { + private readonly IAppKeyStore _appKeyStore; + + public YourService(IAppKeyStore appKeyStore) + { + _appKeyStore = appKeyStore; + } + + public async Task CreateAppAsync() + { + var descriptor = new AppDescriptor( + appName: "Test Application", + appKey: "your-app-key", + appSecret: "your-app-secret", + signLifeTime: 300 // 5 minutes validity + ); + + await _appKeyStore.StoreAsync(descriptor); + } + } + ``` + +2. Query Application Credentials + ```csharp + public class YourService + { + private readonly IAppKeyStore _appKeyStore; + + public YourService(IAppKeyStore appKeyStore) + { + _appKeyStore = appKeyStore; + } + + public async Task GetAppAsync(string appKey) + { + return await _appKeyStore.FindAsync(appKey); + } + } + ``` + +## More Information + +* [LINGYUN.Abp.OpenApi](../LINGYUN.Abp.OpenApi/README.md) +* [LINGYUN.Abp.OpenApi.Authorization](../LINGYUN.Abp.OpenApi.Authorization/README.md) +* [IdentityServer](https://identityserver4.readthedocs.io/) diff --git a/aspnet-core/framework/open-api/LINGYUN.Abp.OpenApi.IdentityServer/README.md b/aspnet-core/framework/open-api/LINGYUN.Abp.OpenApi.IdentityServer/README.md new file mode 100644 index 000000000..2b9191912 --- /dev/null +++ b/aspnet-core/framework/open-api/LINGYUN.Abp.OpenApi.IdentityServer/README.md @@ -0,0 +1,93 @@ +# LINGYUN.Abp.OpenApi.IdentityServer + +OpenApi IdentityServer 集成模块,提供基于 IdentityServer 的 AppKey/AppSecret 存储实现。 + +## 功能特性 + +* 基于 IdentityServer 的 AppKey/AppSecret 存储 +* 自动将 AppKey 映射为 IdentityServer 客户端标识 +* 自动将 AppSecret 映射为客户端密钥 +* 支持签名有效期配置 +* 支持客户端名称配置 +* 自动创建和更新客户端信息 + +## 安装 + +```bash +dotnet add package LINGYUN.Abp.OpenApi.IdentityServer +``` + +## 模块引用 + +```csharp +[DependsOn(typeof(AbpOpenApiIdentityServerModule))] +public class YouProjectModule : AbpModule +{ + // other +} +``` + +## 工作原理 + +1. AppKey 映射 + * AppKey 将被映射为 IdentityServer 的 ClientId + * 通过 `IClientRepository` 接口进行客户端查询和管理 + +2. AppSecret 映射 + * AppSecret 将被映射为客户端密钥(Client Secret) + * 密钥将以 AppSecret 作为标识存储 + +3. 签名有效期 + * SignLifetime 将被存储为客户端的自定义属性 + * 属性名为 "SignLifetime",值为有效期秒数 + +## 基本用法 + +1. 存储应用凭证 + ```csharp + public class YourService + { + private readonly IAppKeyStore _appKeyStore; + + public YourService(IAppKeyStore appKeyStore) + { + _appKeyStore = appKeyStore; + } + + public async Task CreateAppAsync() + { + var descriptor = new AppDescriptor( + appName: "测试应用", + appKey: "your-app-key", + appSecret: "your-app-secret", + signLifeTime: 300 // 5分钟有效期 + ); + + await _appKeyStore.StoreAsync(descriptor); + } + } + ``` + +2. 查询应用凭证 + ```csharp + public class YourService + { + private readonly IAppKeyStore _appKeyStore; + + public YourService(IAppKeyStore appKeyStore) + { + _appKeyStore = appKeyStore; + } + + public async Task GetAppAsync(string appKey) + { + return await _appKeyStore.FindAsync(appKey); + } + } + ``` + +## 更多信息 + +* [LINGYUN.Abp.OpenApi](../LINGYUN.Abp.OpenApi/README.md) +* [LINGYUN.Abp.OpenApi.Authorization](../LINGYUN.Abp.OpenApi.Authorization/README.md) +* [IdentityServer](https://identityserver4.readthedocs.io/) diff --git a/aspnet-core/framework/open-api/LINGYUN.Abp.OpenApi/README.EN.md b/aspnet-core/framework/open-api/LINGYUN.Abp.OpenApi/README.EN.md new file mode 100644 index 000000000..532707bac --- /dev/null +++ b/aspnet-core/framework/open-api/LINGYUN.Abp.OpenApi/README.EN.md @@ -0,0 +1,105 @@ +# LINGYUN.Abp.OpenApi + +OpenApi authentication module, providing AppKey/AppSecret based API signature authentication functionality for ABP applications. + +## Features + +* Supports AppKey/AppSecret authentication +* Supports request signature verification +* Supports replay attack prevention (Nonce random number verification) +* Supports request timestamp verification +* Supports client whitelist +* Supports IP address whitelist +* Supports multilingual error messages + +## Installation + +```bash +dotnet add package LINGYUN.Abp.OpenApi +``` + +## Module Dependencies + +```csharp +[DependsOn(typeof(AbpOpenApiModule))] +public class YouProjectModule : AbpModule +{ + // other +} +``` + +## Configuration + +```json +{ + "OpenApi": { + "IsEnabled": true, // Enable API signature check, default: true + "RequestNonceExpireIn": "00:10:00", // Request nonce expiration time, default: 10 minutes + "AppDescriptors": [ // AppKey configuration list + { + "AppName": "Test Application", // Application name + "AppKey": "your-app-key", // Application key + "AppSecret": "your-app-secret", // Application secret + "AppToken": "optional-token", // Optional application token + "SignLifetime": 300 // Signature validity period (seconds) + } + ] + } +} +``` + +## Basic Usage + +1. Configure AppKey/AppSecret + * Add AppKey and AppSecret in the configuration file + * Or implement custom `IAppKeyStore` interface to manage AppKey + +2. Enable OpenApi Authentication + ```csharp + public override void ConfigureServices(ServiceConfigurationContext context) + { + var configuration = context.Services.GetConfiguration(); + Configure(configuration.GetSection("OpenApi")); + } + ``` + +3. Custom Client Verification (Optional) + ```csharp + public class CustomClientChecker : IClientChecker + { + public Task IsGrantAsync(string clientId, CancellationToken cancellationToken = default) + { + // Implement custom client verification logic + return Task.FromResult(true); + } + } + ``` + +4. Custom IP Address Verification (Optional) + ```csharp + public class CustomIpAddressChecker : IIpAddressChecker + { + public Task IsGrantAsync(string ipAddress, CancellationToken cancellationToken = default) + { + // Implement custom IP address verification logic + return Task.FromResult(true); + } + } + ``` + +## Error Codes + +* AbpOpenApi:9100 - Invalid AppKey +* AbpOpenApi:9101 - AppKey not found +* AbpOpenApi:9110 - Invalid sign +* AbpOpenApi:9111 - Sign not found +* AbpOpenApi:9210 - Request timed out or session expired +* AbpOpenApi:9211 - Timestamp not found +* AbpOpenApi:9220 - Repeatedly initiated requests +* AbpOpenApi:9221 - Nonce not found +* AbpOpenApi:9300 - Client is not within the allowed range +* AbpOpenApi:9400 - Client IP is not within the allowed range + +## More Information + +* [ABP Framework](https://abp.io/) diff --git a/aspnet-core/framework/open-api/LINGYUN.Abp.OpenApi/README.md b/aspnet-core/framework/open-api/LINGYUN.Abp.OpenApi/README.md new file mode 100644 index 000000000..0d0086b2d --- /dev/null +++ b/aspnet-core/framework/open-api/LINGYUN.Abp.OpenApi/README.md @@ -0,0 +1,105 @@ +# LINGYUN.Abp.OpenApi + +OpenApi 认证模块,为 ABP 应用程序提供基于 AppKey/AppSecret 的 API 签名认证功能。 + +## 功能特性 + +* 支持 AppKey/AppSecret 认证 +* 支持请求签名验证 +* 支持防重放攻击(Nonce随机数验证) +* 支持请求时间戳验证 +* 支持客户端白名单 +* 支持IP地址白名单 +* 支持多语言错误消息 + +## 安装 + +```bash +dotnet add package LINGYUN.Abp.OpenApi +``` + +## 模块引用 + +```csharp +[DependsOn(typeof(AbpOpenApiModule))] +public class YouProjectModule : AbpModule +{ + // other +} +``` + +## 配置项 + +```json +{ + "OpenApi": { + "IsEnabled": true, // 是否启用API签名检查,默认: true + "RequestNonceExpireIn": "00:10:00", // 请求随机数过期时间,默认: 10分钟 + "AppDescriptors": [ // AppKey配置列表 + { + "AppName": "测试应用", // 应用名称 + "AppKey": "你的AppKey", // 应用标识 + "AppSecret": "你的AppSecret", // 应用密钥 + "AppToken": "可选的Token", // 可选的应用令牌 + "SignLifetime": 300 // 签名有效期(秒) + } + ] + } +} +``` + +## 基本用法 + +1. 配置 AppKey/AppSecret + * 在配置文件中添加 AppKey 和 AppSecret + * 或者实现自定义的 `IAppKeyStore` 接口来管理 AppKey + +2. 启用 OpenApi 认证 + ```csharp + public override void ConfigureServices(ServiceConfigurationContext context) + { + var configuration = context.Services.GetConfiguration(); + Configure(configuration.GetSection("OpenApi")); + } + ``` + +3. 自定义客户端验证(可选) + ```csharp + public class CustomClientChecker : IClientChecker + { + public Task IsGrantAsync(string clientId, CancellationToken cancellationToken = default) + { + // 实现自定义的客户端验证逻辑 + return Task.FromResult(true); + } + } + ``` + +4. 自定义IP地址验证(可选) + ```csharp + public class CustomIpAddressChecker : IIpAddressChecker + { + public Task IsGrantAsync(string ipAddress, CancellationToken cancellationToken = default) + { + // 实现自定义的IP地址验证逻辑 + return Task.FromResult(true); + } + } + ``` + +## 错误代码 + +* AbpOpenApi:9100 - 无效的应用标识 +* AbpOpenApi:9101 - 未携带应用标识 +* AbpOpenApi:9110 - 无效的签名 +* AbpOpenApi:9111 - 未携带签名 +* AbpOpenApi:9210 - 请求超时或会话已过期 +* AbpOpenApi:9211 - 未携带时间戳标识 +* AbpOpenApi:9220 - 重复发起的请求 +* AbpOpenApi:9221 - 未携带随机数 +* AbpOpenApi:9300 - 客户端不在允许的范围内 +* AbpOpenApi:9400 - 客户端IP不在允许的范围内 + +## 更多信息 + +* [ABP框架](https://abp.io/)