SqlOS

Getting Started

Getting Started

Install SqlOS and run the example stack in five minutes.

9 sections
Quick start

Install SqlOS, map the routes, and get auth plus FGA in one pass

The fastest path is still the same: add the package, register it on your DbContext, and map app.MapSqlOS(). The difference now is that the docs surface is also showing the same shared EmcyDocs components.

Jump to install

Install the package

Add SqlOS to your app and keep your auth plus authorization runtime inside the same ASP.NET process.

Register the DbContext integration

Point SqlOS at your EF Core context so it can wire auth and FGA tables into the host application.

Map the routes

Expose the dashboard, OAuth/OIDC endpoints, hosted auth UI, and FGA admin screens through app.MapSqlOS().

Install#

BASH
dotnet add package SqlOS

Configure services#

Register SqlOS on your DbContext:

CSHARP
builder.AddSqlOS<AppDbContext>();
Minimal host setup
•Program.csservice registration + route mapping
•AppDbContext.csauth + FGA interfaces
•appsettings.jsondashboard auth settings

Set up your DbContext#

Your context implements the SqlOS interfaces. This sample includes both auth and FGA:

CSHARP
public sealed class AppDbContext : DbContext,
    ISqlOSAuthServerDbContext,
    ISqlOSFgaDbContext
{
    public DbSet<Project> Projects => Set<Project>();
 
    public IQueryable<SqlOSFgaAccessibleResource> IsResourceAccessible(
        string subjectId,
        string permissionKey)
        => FromExpression(() =>
            IsResourceAccessible(subjectId, permissionKey));
 
    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        base.OnModelCreating(modelBuilder);
        modelBuilder.UseSqlOS(GetType());
    }
}

Map routes#

CSHARP
var app = builder.Build();
app.MapSqlOS();

This gives you:

PathWhat it does
/sqlosAdmin dashboard
/sqlos/auth/*OAuth 2.0 endpoints (authorize, token, JWKS)
/sqlos/admin/authAuth management UI
/sqlos/admin/fgaFGA management UI

Seed a client#

Register your frontend as an OAuth client so users can sign in immediately:

CSHARP
builder.AddSqlOS<AppDbContext>(options =>
{
    options.AuthServer.SeedOwnedWebApp(
        "my-app",
        "My Application",
        "http://localhost:3000/auth/callback");
});

That is the default story for most teams: an owned app, hosted auth, and a seeded client.

Protect the dashboard#

Set a dashboard password in appsettings.json:

JSON
{
  "SqlOS": {
    "Dashboard": {
      "AuthMode": "Password",
      "Password": "your-strong-password"
    }
  }
}

Run the right sample#

If your first goal is hosted auth, simple FGA, and public-client onboarding, start with the Todo sample:

BASH
dotnet run --project examples/SqlOS.Todo.AppHost/SqlOS.Todo.AppHost.csproj

That sample focuses on:

  • hosted auth first
  • per-user tenant + todo resource hierarchy
  • SQL-backed FGA filtering and simple auth checks
  • headless follow-on
  • protected-resource metadata
  • preregistration, CIMD, and optional DCR

Schema management#

SqlOS owns its own tables

SqlOS runs its own SQL scripts on host startup. Your EF migrations do not own those tables.

If you migrate before the app has started SqlOS once, call SqlOSBootstrapper.InitializeAsync() first. The example API shows that pattern when your tables reference SqlOS.

Next steps#