Xeku.ApiKey.WebApi 0.0.0.7

Xeku.ApiKey.WebApi

ASP.NET Core Web API module providing API Key authentication for XAF applications.

繁體中文文檔

Features

• X-API-Key Header Authentication: Standard API Key authentication via HTTP header.
• XAF Security Integration: Integrates with XAF permission system via ClaimsPrincipal.
• Admin Management Endpoints: RESTful API endpoints for managing keys (admin only).
• Swagger Support: Built-in support for API Key authorization in Swagger UI.
• Multiple Auth Schemes: Works seamlessly alongside JWT authentication.

Authentication Flow

sequenceDiagram
    Client->>API: Request with X-API-Key header
    API->>ApiKeyAuthenticationHandler: Authenticate
    ApiKeyAuthenticationHandler->>Database: Query ApiKeyInfo by hash
    Database-->>ApiKeyAuthenticationHandler: ApiKeyInfo
    ApiKeyAuthenticationHandler->>ApiKeyAuthenticationHandler: Create ClaimsPrincipal
    ApiKeyAuthenticationHandler-->>API: AuthenticationTicket
    API-->>Client: Response with user permissions

Installation

0. NuGet Package

dotnet add package Xeku.ApiKey.WebApi

1. Register XAF Authentication Provider

Add in builder.Security block in Startup.cs:

builder.Security
    .AddAuthenticationProvider<ApiKeyAuthenticationProvider<ApplicationUser>>();

2. ⚠️ CRITICAL: Configure Antiforgery

WARNING: Skipping this step will cause ALL ApiKey requests to return HTTP 400 Bad Request!

XAF Web API includes built-in antiforgery protection that conflicts with API Key authentication. You MUST exclude the ApiKey and JWT Bearer schemes:

builder.Security
    .UseIntegratedMode(options => { ... })
    .AddPasswordAuthentication(options => { ... })
    .ConfigureAntiforgery(options =>
    {
        options.ExcludeAuthenticationSchemes.Add(ApiKeyAuthenticationHandler.SchemeName);
        options.ExcludeAuthenticationSchemes.Add(JwtBearerDefaults.AuthenticationScheme);
    });

3. Add ApiKey Authentication Service

Add after services.AddAuthentication().AddJwtBearer(...):

services.AddXekuApiKeyWebApi();

Note: AddXekuApiKeyWebApi() automatically configures ForwardDefaultSelector to route requests with X-API-Key header to the ApiKey authentication scheme.

4. Update Authorization Policy

services.AddAuthorization(options =>
{
    options.DefaultPolicy = new AuthorizationPolicyBuilder(
        JwtBearerDefaults.AuthenticationScheme)
            .RequireAuthenticatedUser()
            .RequireXafAuthentication()
            .Build();
});

Tip: Since ForwardDefaultSelector handles routing, only JwtBearerDefaults.AuthenticationScheme is needed in the policy.

Usage

Add X-API-Key header to HTTP requests:

curl -H "X-API-Key: cak_your-api-key" \
     https://localhost:5001/api/odata/YourEntity

AI Agent Integration

Suggested Context

• Endpoint Protection: Use [Authorize(AuthenticationSchemes = "ApiKey")] for specific controllers.
• Audit Requirement: Always log the NameIdentifier claim returned by the API key handler.

Common Tasks

• "How do I add API Key support to my existing OData service?"
• "Generate an API key for user 'ServiceAccount' via the management API."

Related Projects

• Xeku.ApiKey - Core module

License

MIT License