ASP.NET-Core-Integration

HsSqlAgent.Server ist ein einbettbares ASP.NET-Core-Klassenbibliothekspaket. Neue Integrationen in 2.0.2 beginnen mit einem Core ohne Options und wählen danach ausdrücklich die Capabilities, die der Host benötigt.

Installation

dotnet add package HsSqlAgent.Server

Bestehende Anwendung mit eigenem Login und Berechtigungen

Wenn Ihre ASP.NET-Core-Anwendung bereits Authentifizierung und Autorisierung besitzt, ist dies die bevorzugte Einbettungsform.

1. Authentifizierung und Autorisierung des Hosts beibehalten

   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 ersetzt weder das Standard-Authentication-Scheme des Hosts noch dessen Authorization Policy Provider oder Standard-Policy.

2. Nur benötigte hs-sql-agent-Capabilities zusammensetzen

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

   Rufen Sie in diesem Modus nicht AddHsSqlAgentBuiltInAuth() auf. Stattdessen wird der bereits authentifizierte HttpContext.User des Hosts verwendet.

3. ASP.NET-Core-Pipeline beim Host belassen

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

   UseHsSqlAgentAdminApi() ruft MapControllers() nicht für den Host auf. Das Mapping der ASP.NET-Core-Controller-Endpunkte bleibt Aufgabe der Anwendung.

Im Host-Authorization-Modus veröffentlicht HsSqlAgent seine integrierten AuthController, MemberController und RoleController nicht und installiert auch kein HsSqlAgent-Identity-Schema. JWT-, SMTP-, Passwort-Reset- und OIDC-Options sind daher nicht erforderlich.

Die Admin-Permission-Filter von HsSqlAgent übergeben die angeforderten stabilen canonical permission keys über HsSqlAgentPermissionResource.Permissions an die konfigurierte Host-Policy. Der Host kann eine grobe Regel wie eine Admin-Rolle durchsetzen oder diese Schlüssel auf sein eigenes fein abgestuftes Berechtigungsmodell abbilden.

MCP unabhängig hinzufügen

MCP ist eine eigene Sicherheitsgrenze für Maschinenzugriff. Fügen Sie diese Capability nur hinzu, wenn die eingebettete Anwendung einen MCP-Server bereitstellen soll:

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

Nach dem Erstellen der Anwendung wird MCP gemountet:

app.UseHsSqlAgentMcp();

MCP-Schlüssel, Tool-Scope, Tabellen-Scope, Rate Limits und HMAC-Validierung bleiben unabhängig von der Host-Authorization-Policy für menschliche/Admin-Zugriffe.

Integrierte Admin-Identität nur bei Bedarf verwenden

Soll die Anwendung das eigene JWT-/Member-/Role-Modell von HsSqlAgent verwenden, wählen Sie diese Capability explizit statt 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();

Die integrierten Authentication Schemes besitzen eigene Namen (HsSqlAgent.Jwt, HsSqlAgent.ExternalCookie, HsSqlAgent.Oidc) und werden nicht zu den Standard-Schemes der Host-Anwendung. Built-in Identity und Host-Authorization-Modus schließen sich gegenseitig aus.

Auch die mitgelieferte Admin UI ist optional:

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

Ohne diese UI kann das eigene Frontend des Hosts die Admin API weiterhin verwenden.

Options gehören der jeweiligen Capability

Neuer Code konfiguriert Einstellungen direkt an der Capability, der sie gehören:

Nicht ausgewählte Capabilities erzeugen oder validieren ihre Options nicht. Die modulare API behält bestehende Standardwerte bei; Host Authorization zwingt die Anwendung nicht zur Konfiguration von integriertem JWT/OIDC/SMTP.

Aktuelle HTTP-Oberfläche

Diese Mounts sind in 2.0.2 bewusst fest. Beliebige Relokation wird nicht als unterstützt beworben, solange Routing, Frontend-Basispfade/Assets, Callbacks und Sicherheitsgrenzen nicht gemeinsam verschoben werden können.

Abwärtskompatibilität

Bestehende Paketnutzer können weiterhin die aggregierte API verwenden:

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

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

HsSqlAgentServiceOptions, AddHsSqlAgent() und UseHsSqlAgent() bleiben Kompatibilitätsschnittstellen. Neue Integrationen sollten AddHsSqlAgentCore() plus explizite Capability-Registrierung bevorzugen.

Verwandte Dokumentation