Run the Todo sample

Goal#

Create an account through the SqlOS hosted AuthPage, return to a secure ASP.NET Core cookie session, call a protected API, and inspect the corresponding SqlOS session. The companion Todo browser UI also demonstrates FGA-filtered EF Core data.

Prerequisites#

• the SqlOS repository checked out locally;
• .NET 9 SDK;
• Docker running with enough memory for SQL Server;
• ports 1435, 5080, 5090, 18890, and 18891 available.

This quickstart uses the source at SqlOS 3.24.1. Local password authentication is the default, so the first run does not require Azure Communication Services, Twilio, or an OIDC provider.

Run#

From the repository root:

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

Use the authenticated Aspire dashboard URL printed in the terminal. Its configured listener is:

https://localhost:18890

Wait for SQL Server to become healthy and for todo-api and aspnet-web to show Running. Aspire keeps the logs and resource endpoints together, which is the fastest place to diagnose a failed first start.

The AppHost uses a persistent SQL Server container on port 1435 and passes the database connection string to the API. SqlOS initializes its schema, automatically protected signing key, OAuth clients, and FGA seed data when todo-api starts.

Verify the all-.NET login#

1. Open http://localhost:5090.
2. Select Sign in with SqlOS.
3. Create a password account and organization, or sign in to an existing one.
4. Confirm the browser returns to the Razor Pages app.
5. Inspect the identity card and the 200 response from GET /api/me.
6. Select Sign out and revoke.

That proves the complete chain: ASP.NET Core challenge and PKCE, SqlOS hosted login, authorization-code exchange, application cookie, exact-audience bearer validation, and revoking logout.

Explore Todo authorization#

Open http://localhost:5080 for the companion browser client. Sign in, create two Todo items, mark one complete, and refresh. The API stores each Todo as an FGA resource and filters the EF Core list query for the current subject.

Open http://localhost:5080/sqlos/admin/fga/resources to inspect the tenant and Todo resource tree. The same dashboard exposes grants, roles, permissions, sessions, applications, and the Access Tester.

Useful endpoints#

What the sample demonstrates#

The stack contains two first-party browser clients for different learning goals:

Both clients are public, require PKCE, and receive access tokens for http://localhost:5080/api/todos.

The API also contains CLI device flow, CIMD, DCR, email OTP, and SMS OTP examples. Those are optional paths, not prerequisites for the provider-free password flow.

Common failures#

SQL Server never becomes healthy#

Confirm Docker is running and port 1435 is free. On Apple silicon, the SQL Server image runs through the platform setting in the AppHost and may take longer on first start.

The Aspire dashboard certificate is not trusted#

Trust the local development certificate with dotnet dev-certs https --trust, or use the dashboard URL printed by the AppHost process and accept the local browser warning deliberately.

Port 5080 or 5090 is already in use#

Stop the conflicting process before restarting. The issuer, audience, and callbacks use these documented origins; changing only one port produces an issuer, audience, or redirect mismatch.

Login does not return to the Razor app#

Start the challenge at http://localhost:5090 rather than opening a hosted-auth URL directly. The seeded callback must remain exactly http://localhost:5090/signin-sqlos.

Old sample data behaves differently#

The AppHost uses a persistent data volume. If you previously ran an older schema or seed model, let current startup migrations finish. Use a clean development volume only when intentionally discarding obsolete local data.

Email-code sign-in is missing#

That is expected in the provider-free default. Password signup is enabled when no OTP provider is selected. Configure email OTP only if you want to evaluate delivery; see Todo sample details.

Production notes#

The Todo project is an evaluation sample, not a production deployment template. In production:

• use HTTPS and a stable public origin;
• use CookieSecurePolicy.Always and persist Data Protection keys across replicas;
• protect /sqlos and /sqlos/admin/* with a private network, VPN, identity-aware proxy, or equivalent admin control while keeping /sqlos/auth/* reachable by users;
• store database credentials, dashboard credentials, provider secrets, and key rings outside source control;
• complete the production signing-key custody review for containers or multiple replicas;
• create application-specific resource types and permissions instead of reusing the Todo model.

Next steps#

• Understand the ASP.NET Core login
• Add SqlOS to one application
• Protect an API
• Authorize EF Core queries
• Todo sample details