Intégration ASP.NET Core

HsSqlAgent.Server est une bibliothèque ASP.NET Core intégrable. En 2.0.2, une nouvelle intégration part d’un core sans options puis sélectionne explicitement les capacités réellement nécessaires au host.

Installation

dotnet add package HsSqlAgent.Server

Application existante avec sa propre connexion et ses permissions

C’est la forme d’intégration recommandée lorsqu’une application ASP.NET Core possède déjà son système d’authentification et d’autorisation.

1. Conserver l’authentification et l’autorisation du host

   builder.Services.AddAuthentication(/* your existing schemes */);
   
   builder.Services.AddAuthorization(options =>
   {
       options.AddPolicy("SqlAgentAdmin", policy =>
       {
           policy.RequireAuthenticatedUser();
           // Add your application's requirement/handler here when
           // canonical hs-sql-agent permissions need to be evaluated.
       });
   });

   HsSqlAgent ne remplace ni le schéma d’authentification par défaut du host, ni son provider de politiques d’autorisation, ni sa politique d’autorisation par défaut.

2. Composer uniquement les capacités hs-sql-agent nécessaires

   var hs = builder.Services.AddHsSqlAgentCore();
   
   hs.AddHsSqlAgentRuntime();
   
   hs.AddHsSqlAgentAdminStore(options =>
   {
       options.Provider = "Postgres";
       options.ConnectionString =
           builder.Configuration.GetConnectionString("HsSqlAgent")!;
   });
   
   hs.AddHsSqlAgentHostAuthorization("SqlAgentAdmin");
   hs.AddHsSqlAgentAdminApi();

   Dans ce mode, n’appelez pas AddHsSqlAgentBuiltInAuth(). Le HttpContext.User déjà authentifié par le host est utilisé à la place.

3. Laisser le host posséder le pipeline ASP.NET Core

   var app = builder.Build();
   
   app.UseAuthentication();
   app.UseAuthorization();
   
   app.UseHsSqlAgentAdminApi();
   app.MapControllers();
   
   app.Run();

   UseHsSqlAgentAdminApi() n’appelle pas MapControllers() pour le host. Le mapping des endpoints de contrôleurs reste une décision de l’application ASP.NET Core.

En mode host-authorization, HsSqlAgent ne publie pas ses AuthController, MemberController ou RoleController intégrés et n’installe pas le schéma d’identité HsSqlAgent. Les options JWT, SMTP, réinitialisation de mot de passe et OIDC ne sont donc pas requises.

Les filtres de permission Admin HsSqlAgent transmettent les clés de permission canoniques demandées à la politique du host via HsSqlAgentPermissionResource.Permissions. Le host peut appliquer une politique grossière, par exemple un rôle Admin, ou mapper ces clés vers son propre modèle de permissions fines.

Ajouter MCP indépendamment

MCP constitue une frontière de sécurité machine distincte. Ajoutez-la uniquement si l’application intégrée doit exposer le serveur MCP :

hs.AddHsSqlAgentMcp(options =>
{
    options.PublicEndpoint = "https://example.com/mcp";
    options.HmacSecretKey = builder.Configuration["HMAC_KEY"]!; // >= 32 bytes
});

Puis mappez-le après construction de l’application :

app.UseHsSqlAgentMcp();

Les clés MCP, le périmètre d’outils, le périmètre de tables, les limites de débit et la validation HMAC restent indépendants de la politique d’autorisation humaine/Admin du host.

Utiliser l’identité Admin intégrée uniquement si souhaité

Si l’application veut utiliser le modèle JWT/member/role propre à HsSqlAgent, sélectionnez explicitement cette capacité au lieu de host authorization :

var hs = builder.Services.AddHsSqlAgentCore();

hs.AddHsSqlAgentRuntime();

hs.AddHsSqlAgentAdminStore(options =>
{
    options.Provider = "Sqlite";
    options.ConnectionString = "Data Source=hsagent.db";
});

hs.AddHsSqlAgentBuiltInAuth(options =>
{
    options.Jwt.SecretKey = builder.Configuration["JWT_KEY"]!; // >= 32 bytes
});

hs.AddHsSqlAgentAdminApi();

Les schémas d’authentification intégrés sont nommés HsSqlAgent.Jwt, HsSqlAgent.ExternalCookie et HsSqlAgent.Oidc et ne deviennent pas les valeurs par défaut du host. L’identité intégrée et le mode host-authorization sont mutuellement exclusifs.

L’interface Admin empaquetée est également facultative :

app.UseHsSqlAgentAdminApi();
app.MapControllers();
app.UseHsSqlAgentAdminUi();

Sans cette interface, l’API Admin peut toujours être consommée par le frontend propre à l’application.

Options possédées par chaque capacité

Le nouveau code configure la capacité propriétaire du paramètre :

Une capacité non sélectionnée n’alloue ni ne valide ses options. L’API modulaire conserve les valeurs par défaut existantes ; choisir host authorization ne force pas la configuration JWT/OIDC/SMTP intégrée.

Surface HTTP actuelle

Ces montages sont volontairement fixes en 2.0.2. Le déplacement arbitraire n’est pas annoncé comme pris en charge tant que routing, chemins de base/assets frontend, callbacks et frontières de sécurité ne peuvent pas être déplacés ensemble.

Compatibilité historique

Les consommateurs existants peuvent continuer à utiliser l’API agrégée :

builder.Services.AddHsSqlAgent(options =>
{
    // Existing aggregate configuration.
});

var app = builder.Build();
app.UseHsSqlAgent().ServeAdminUi();

HsSqlAgentServiceOptions, AddHsSqlAgent() et UseHsSqlAgent() restent des surfaces de compatibilité. Les nouvelles intégrations doivent privilégier AddHsSqlAgentCore() avec enregistrement explicite des capacités.

Documentation associée