ShiftSoftware/UnifiedAttestation

# ShiftSoftware Unified Attestation 一个为 Azure Functions（隔离工作器模型）设计的强大、统一的安全层，用于验证 iOS、Android 和华为设备上移动客户端请求的完整性。它确保传入的请求源自运行在真实设备上的合法、未经篡改的移动应用程序版本。 ## 功能 - **多平台支持**：支持 Apple App Attest、Google Play Integrity（通过 Firebase App Check）和华为移动服务（HMS）UserDetect。 - **防重放保护**：可选的网络级一次性使用验证，防止重放攻击。 - **Azure Functions 中间件**：使用 `[ValidateAttestation]` 属性的简洁声明式安全机制。 - **安全凭证管理**：与 Azure Key Vault 的内置集成，用于证书管理。 - **开发旁路**：通过将 `AddAttestationVerification` 的 `useFakeService` 参数设为 `true`，提供无缝的本地开发体验，使用 `FakeAttestationService`。 - **高性能**：对服务器到服务器的 OAuth 令牌进行智能缓存，以遵守 API 速率限制并最小化延迟。 ## 包 ### `ShiftSoftware.UnifiedAttestation` 核心服务、模型和抽象。包含与平台无关的 Firebase 和 HMS 验证业务逻辑。 ### `ShiftSoftware.UnifiedAttestation.Functions` Azure Functions 隔离工作器集成。提供依赖项注入扩展和中间件管道。 ## 安装 通过 .NET CLI 安装包： ``` dotnet add package ShiftSoftware.UnifiedAttestation.Functions ``` ## 配置 在 `Program.cs` 中，使用 `AddAttestationVerification` 扩展方法注册验证服务： ``` using Microsoft.Extensions.Hosting; var host = new HostBuilder() .ConfigureFunctionsWorkerDefaults(builder => { builder.AddAttestationVerification( firebaseProjectNumber: Environment.GetEnvironmentVariable("FIREBASE_PROJECT_NUMBER"), serviceAccountKeyVaultCertificate: Environment.GetEnvironmentVariable("FIREBASE_CERT_NAME"), serviceAccountEmail: Environment.GetEnvironmentVariable("FIREBASE_CLIENT_EMAIL"), keyVaultUri: Environment.GetEnvironmentVariable("KEY_VAULT_URI"), hmsAppId: Environment.GetEnvironmentVariable("HMS_APP_ID"), hmsClientId: Environment.GetEnvironmentVariable("HMS_CLIENT_ID"), hmsClientSecret: Environment.GetEnvironmentVariable("HMS_CLIENT_SECRET"), headerKey: "X-App-Attestation-Token" // Optional: Defaults to Verification-Token useFakeService: true, // Optional: Defaults to false. Set to true to bypass validation in Development environment for easier local testing. ); }) .Build(); host.Run(); ``` ## 用法 ### 保护端点 将 `[ValidateAttestation]` 属性应用于任何需要保护的 HTTP 触发器函数。中间件将拦截请求，验证头信息中提供的令牌，并在请求到达业务逻辑之前拒绝未授权的请求。 ``` using Microsoft.AspNetCore.Mvc; using Microsoft.Azure.Functions.Worker; using Microsoft.AspNetCore.Http; public class AttestationEndpoints { [Function(nameof(AttestedPing))] [ValidateAttestation(withReplayProtection: false)] public IActionResult AttestedPing( [HttpTrigger(AuthorizationLevel.Anonymous, "get", Route = "secure/ping")] HttpRequest req) { return new OkObjectResult(new { message = "Success!", deviceStatus = "Attested & Trusted" }); } } ``` ## 防重放保护 对于高价值的端点（如支付或登录），可以启用防重放保护。这会强制令牌通过网络调用消耗一次提供程序，确保其永远无法再次使用。 ``` [ValidateAttestation(withReplayProtection: true)] ``` ## 开发模式 在使用 Azure Functions Core Tools 本地运行时，可以通过将 `AddAttestationVerification` 函数的 `useFakeService` 参数设置为 `true` 来旁路令牌验证。 注册逻辑会自动将真实的验证服务替换为 `FakeAttestationService`。这允许前端开发人员通过简单地传递任意字符串（例如 `Verification-Token: dev-test`）来测试端点，而无需配置物理设备或真实的 App Check 项目。 ## Azure 托管注意事项（证书加载） 如果 Azure 应用服务应用或 Azure Functions 应用（在基于应用服务的托管模式下，例如专用/应用服务计划）在从 Key Vault 加载 Firebase 服务账户证书时遇到证书私钥导入错误（`CryptographicException`），请在 **应用设置** 中设置以下环境变量： - `WEBSITE_LOAD_USER_PROFILE=1` 这将启用加载完整用户配置文件，并解决该托管模式下的证书私钥加载问题。

标签：API速率限制, Azure Functions, Azure Key Vault, FakeAttestationService, Firebase App Check, Google Play Integrity, iOS App Attest, Isolated Worker Model, .NET安全中间件, OAuth令牌缓存, Replay Protection, ValidateAttestation, 中间件安全, 云端安全验证, 依赖注入, 华为HMS UserDetect, 反篡改, 声明式安全, 多人体追踪, 安全凭据, 客户端完整性验证, 应用加固, 开发环境伪造服务, 移动安全SDK, 移动应用安全, 统一验证层, 证书管理, 跨平台验证, 重放攻击防护, 高性能缓存