Getting Started

Prerequisites

.NET 8+ (the repo samples target .NET 9)
SQL Server with a connection string your EF DbContext can use
For the Todo sample: run via Aspire AppHost (starts SQL Server in a container) or point at your own instance

You'll learn how to install SqlOS, wire a minimal host, run the Todo sample, and pick the next doc for your use case.

Install the package

Add SqlOS to your ASP.NET app.

Register on your DbContext

Implement the SqlOS interfaces and call AddSqlOS during host setup.

Map routes and verify

Call MapSqlOS(), start the app, and open the admin dashboard.

Install#

BASH

dotnet add package SqlOS

Minimal host#

A complete minimal Program.cs for an owned web app with hosted auth:

CSHARP

using Microsoft.EntityFrameworkCore;
using SqlOS.Extensions;
 
var builder = WebApplication.CreateBuilder(args);
 
builder.Services.AddDbContext<AppDbContext>(options =>
    options.UseSqlServer(builder.Configuration.GetConnectionString("DefaultConnection")));
 
builder.AddSqlOS<AppDbContext>(options =>
{
    options.AuthServer.Issuer = "https://localhost:5001/sqlos/auth";
    options.AuthServer.PublicOrigin = "https://localhost:5001";
    options.AuthServer.SeedOwnedWebApp(
        "web",
        "My Application",
        "https://localhost:5001/auth/callback");
});
 
var app = builder.Build();
app.MapSqlOS();
app.Run();

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());
    }
}

appsettings.json needs a SQL Server connection string and optional dashboard password:

JSON

{
  "ConnectionStrings": {
    "DefaultConnection": "Server=localhost;Database=SqlOSApp;Trusted_Connection=True;TrustServerCertificate=True"
  },
  "SqlOS": {
    "Dashboard": {
      "AuthMode": "Password",
      "Password": "change-me-in-production"
    }
  }
}

Map routes#

CSHARP

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

This gives you:

Path	What it does
`/sqlos`	Admin dashboard
`/sqlos/auth/*`	OAuth 2.0 endpoints, hosted AuthPage, Email OTP, invitations
`/sqlos/admin/auth`	Auth management UI
`/sqlos/admin/fga`	FGA management UI

Seed a client#

CSHARP

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

Verify it works#

Start your app and open /sqlos/admin/auth/ (or /sqlos for the main dashboard).
Sign in with the dashboard password from appsettings.json when AuthMode is Password.
Confirm you can browse organizations, users, and clients.

SqlOS dashboard home

Run the right sample#

Fastest path — hosted auth, simple FGA, and client onboarding:

BASH

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

The AppHost starts SQL Server and the Todo API. Open the URL shown in the console, then /sqlos/admin/auth/.

The Todo sample covers:

hosted auth first
per-user tenant + todo resource hierarchy
SQL-backed FGA filtering
optional headless, CIMD, and DCR flows

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.

Choose your path#

Hosted auth UI

Branded login, dashboard, and OAuth flows out of the box.

Headless / SPA

Build your own UI on the same OAuth and session APIs.

FGA basics

Model resources, grants, and EF Core query filters.

API reference

Endpoint and method reference when you need a specific contract.

Deep dives#

The Developer's Guide to Hierarchical RBAC
Headless auth patterns
Guides — task-oriented walkthroughs

Next steps#

AuthServer Overview — identity, sessions, and auth flows
Todo Sample — hosted auth and FGA in one sample
Configuration — service registration and dashboard setup

Minimal host#

A complete minimal Program.cs for an owned web app with hosted auth:

CSHARP

using Microsoft.EntityFrameworkCore;
using SqlOS.Extensions;
 
var builder = WebApplication.CreateBuilder(args);
 
builder.Services.AddDbContext<AppDbContext>(options =>
    options.UseSqlServer(builder.Configuration.GetConnectionString("DefaultConnection")));
 
builder.AddSqlOS<AppDbContext>(options =>
{
    options.AuthServer.Issuer = "https://localhost:5001/sqlos/auth";
    options.AuthServer.PublicOrigin = "https://localhost:5001";
    options.AuthServer.SeedOwnedWebApp(
        "web",
        "My Application",
        "https://localhost:5001/auth/callback");
});
 
var app = builder.Build();
app.MapSqlOS();
app.Run();

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());
    }
}

appsettings.json needs a SQL Server connection string and optional dashboard password:

JSON

{
  "ConnectionStrings": {
    "DefaultConnection": "Server=localhost;Database=SqlOSApp;Trusted_Connection=True;TrustServerCertificate=True"
  },
  "SqlOS": {
    "Dashboard": {
      "AuthMode": "Password",
      "Password": "change-me-in-production"
    }
  }
}

Path

What it does

/sqlos

Admin dashboard

/sqlos/auth/*

OAuth 2.0 endpoints, hosted AuthPage, Email OTP, invitations

/sqlos/admin/auth

Auth management UI

/sqlos/admin/fga

FGA management UI

Run the right sample#

Fastest path — hosted auth, simple FGA, and client onboarding:

BASH

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

The AppHost starts SQL Server and the Todo API. Open the URL shown in the console, then /sqlos/admin/auth/.

The Todo sample covers:

hosted auth first
per-user tenant + todo resource hierarchy
SQL-backed FGA filtering
optional headless, CIMD, and DCR flows

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

Install the package

Register on your DbContext

Map routes and verify

Install#

Minimal host#

Set up your DbContext#

Map routes#

Seed a client#

Verify it works#

Run the right sample#

Schema management#

Choose your path#

Hosted auth UI

Headless / SPA

FGA basics

API reference

Deep dives#

Next steps#

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

Install the package

Register on your DbContext

Map routes and verify

Install#

Minimal host#

Set up your DbContext#

Map routes#

Seed a client#

Verify it works#

Run the right sample#

Schema management#

Choose your path#

Hosted auth UI

Headless / SPA

FGA basics

API reference

Deep dives#

Next steps#