ASP.NET Core Integration

HsSqlAgent.Server is an embeddable ASP.NET Core class-library package. In 2.0.2, new integrations start with an optionless core and explicitly select the capabilities the host needs.

Install

dotnet add package HsSqlAgent.Server

Existing application with its own login and permissions

This is the preferred embedding shape when your ASP.NET Core application already has authentication and authorization.

1. Keep the host authentication and authorization setup

   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 does not replace the host’s default authentication scheme, authorization policy provider, or default authorization policy.

2. Compose only the hs-sql-agent capabilities you need

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

   Do not call AddHsSqlAgentBuiltInAuth() in this mode. The host’s authenticated HttpContext.User is used instead.

3. Let the host own the ASP.NET Core pipeline

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

   UseHsSqlAgentAdminApi() does not call MapControllers() for the host. ASP.NET Core controller endpoint mapping remains the application’s decision.

In host-authorization mode HsSqlAgent does not publish its built-in AuthController, MemberController, or RoleController, and it does not install the HsSqlAgent identity schema. JWT, SMTP, password-reset, and OIDC options are therefore not required.

HsSqlAgent Admin permission filters pass the requested stable canonical permission keys to the configured host policy through HsSqlAgentPermissionResource.Permissions. The host can enforce a coarse policy such as an Admin role, or map those keys into its own fine-grained permission model.

Add MCP independently

MCP is a separate machine-access security boundary. Add it only when the embedded application should expose the MCP server:

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

Then map it after the application is built:

app.UseHsSqlAgentMcp();

MCP keys, tool scope, table scope, rate limits, and HMAC validation remain independent from the human/Admin host-authorization policy.

Use the built-in Admin identity only when wanted

If the application wants HsSqlAgent’s own JWT/member/role model, select that capability explicitly instead of 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();

Built-in authentication schemes are namespaced (HsSqlAgent.Jwt, HsSqlAgent.ExternalCookie, and HsSqlAgent.Oidc) and do not become the host application’s defaults. Built-in identity and host-authorization mode are mutually exclusive.

The packaged Admin UI is also optional:

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

If the UI is omitted, the Admin API can still be consumed by the host application’s own frontend.

Capability-owned options

New code configures the capability that owns a setting:

Unselected capabilities do not allocate or validate their options. Existing defaults are preserved by the modular API; selecting host authorization does not force you to configure built-in JWT/OIDC/SMTP settings.

Current HTTP surface

These mounts are intentionally fixed in 2.0.2. Arbitrary relocation is not advertised until routing, frontend base paths/assets, callbacks, and security boundaries can move together.

Legacy compatibility

Existing package consumers can continue to use the aggregate API:

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

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

HsSqlAgentServiceOptions, AddHsSqlAgent(), and UseHsSqlAgent() remain compatibility surfaces. New integrations should prefer AddHsSqlAgentCore() plus explicit capability registration.

Related documentation