Browse Source

feat(docs): 添加OpenApi模块文档

pull/1049/head
feijie 1 year ago
parent
commit
d30c7e558a
  1. 104
      aspnet-core/framework/open-api/LINGYUN.Abp.OpenApi.Authorization/README.EN.md
  2. 104
      aspnet-core/framework/open-api/LINGYUN.Abp.OpenApi.Authorization/README.md
  3. 93
      aspnet-core/framework/open-api/LINGYUN.Abp.OpenApi.IdentityServer/README.EN.md
  4. 93
      aspnet-core/framework/open-api/LINGYUN.Abp.OpenApi.IdentityServer/README.md
  5. 105
      aspnet-core/framework/open-api/LINGYUN.Abp.OpenApi/README.EN.md
  6. 105
      aspnet-core/framework/open-api/LINGYUN.Abp.OpenApi/README.md

104
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<AbpOpenApiOptions> options,
IOptions<AbpExceptionHandlingOptions> exceptionHandlingOptions)
: base(nonceStore, appKeyStore, clientChecker, ipAddressChecker,
clientInfoProvider, options, exceptionHandlingOptions)
{
}
// Override authentication logic
public override async Task<bool> 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/)

104
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<AbpOpenApiOptions> options,
IOptions<AbpExceptionHandlingOptions> exceptionHandlingOptions)
: base(nonceStore, appKeyStore, clientChecker, ipAddressChecker,
clientInfoProvider, options, exceptionHandlingOptions)
{
}
// 重写认证逻辑
public override async Task<bool> 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/)

93
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<AppDescriptor> 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/)

93
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<AppDescriptor> 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/)

105
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<AbpOpenApiOptions>(configuration.GetSection("OpenApi"));
}
```
3. Custom Client Verification (Optional)
```csharp
public class CustomClientChecker : IClientChecker
{
public Task<bool> 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<bool> 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/)

105
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<AbpOpenApiOptions>(configuration.GetSection("OpenApi"));
}
```
3. 自定义客户端验证(可选)
```csharp
public class CustomClientChecker : IClientChecker
{
public Task<bool> IsGrantAsync(string clientId, CancellationToken cancellationToken = default)
{
// 实现自定义的客户端验证逻辑
return Task.FromResult(true);
}
}
```
4. 自定义IP地址验证(可选)
```csharp
public class CustomIpAddressChecker : IIpAddressChecker
{
public Task<bool> 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/)
Loading…
Cancel
Save