Todo Sample

The Todo sample is the canonical "ship hosted AuthPage plus simple FGA fast" walkthrough.

It keeps the model intentionally small:

• hosted AuthPage first
• passwordless email-code sign in/sign up when TodoSample__EnableEmailOtp=true
• seeded email branding for the built-in OTP and invitation templates
• one user = one tenant boundary
• one tenant resource with child todo resources
• SQL-backed FGA list filtering and simple auth checks in minimal APIs
• a protected resource with audience enforcement
• protected-resource metadata for MCP clients
• preregistered local development with todo-local
• a todo-cli device-flow client and runnable .NET CLI
• portable public-client onboarding with CIMD and optional DCR

Run it#

ACS_COMMUNICATION_SERVICE_NAME=<acs-communication-service-name>
AZURE_RESOURCE_GROUP=<resource-group>
ACS_FROM_ADDRESS=no-reply@example.com
 
ACS_CONN=$(az communication list-key \
  --name "$ACS_COMMUNICATION_SERVICE_NAME" \
  --resource-group "$AZURE_RESOURCE_GROUP" \
  --query primaryConnectionString \
  -o tsv)
 
TodoSample__EnableEmailOtp=true \
SqlOS__EmailOtp__AzureCommunicationServicesConnectionString="$ACS_CONN" \
SqlOS__EmailOtp__FromAddress="$ACS_FROM_ADDRESS" \
dotnet run --project examples/SqlOS.Todo.AppHost/SqlOS.Todo.AppHost.csproj

Open http://localhost:5080/.

If you already ran an older version of the Todo sample, reset the Todo sample SQL database or persistent volume once before rerunning. Existing rows are not backfilled into the FGA graph.

What the sample includes#

Hosted AuthPage first#

The default path is a seeded browser client called todo-web.

Use the landing page to:

• start email-code sign in
• start email-code sign up
• land in a tiny Todo UI backed by the sample API

The Todo app only starts the OAuth request. SqlOS AuthPage owns credential collection, OTP delivery, OTP verification, user creation on signup, and the redirect back with an authorization code.

The sample also seeds email branding with SeedAuthEmails(...), so the default OTP emails use the Todo application name and colors without a custom template.

Simple FGA#

The Todo sample now models every todo as an FGA resource.

Hierarchy:

• root
• tenant::{userId}
• todo::{todoId}

Role and permission matrix:

• tenant_owner
• TENANT_CREATE_TODO
• TODO_READ
• TODO_WRITE

The app grants tenant_owner on the user tenant node. Child todo resources inherit access from that node, so the sample can:

• list todos with GetAuthorizationFilterAsync<TodoItem>(...)
• authorize create against the tenant node
• authorize toggle/delete against the todo resource

That keeps the controller code small while still populating the FGA dashboard with a real tree.

Protected resource behavior#

The sample API protects /api/todos with audience-aware token validation.

It also exposes:

• GET /.well-known/oauth-protected-resource

And when a caller presents no token or the wrong audience, the API returns:

• 401 Unauthorized
• a WWW-Authenticate header with resource_metadata

That means the sample demonstrates both sides at once:

• protected-resource metadata for MCP/public-client flows
• simple FGA subject sync, grants, hierarchy, and SQL-backed authorization

Local preregistered client#

For localhost development, use the seeded client:

• client_id: todo-local
• redirect URI: http://localhost:3100/oauth/callback
• auth method: public PKCE only

This is the easiest local loop before you publish the sample on a stable HTTPS origin.

Local Emcy broker client#

For the Emcy-hosted local Todo MCP flow, use the additional seeded client:

• client_id: todo-mcp-local
• redirect URI: http://localhost:5150/api/v1/hosted-mcp/todo-local/oauth/callback
• auth method: public PKCE only

This client exists so Emcy can broker the downstream Todo authorization flow while the Todo API itself keeps the same OAuth and audience behavior.

Todo CLI device flow#

The sample also seeds a public CLI client:

• client_id: todo-cli
• grant types: device code + refresh token
• audience/resource: the Todo API resource

Run the AppHost, then in another terminal:

dotnet run --project examples/SqlOS.Todo.Cli -- login
dotnet run --project examples/SqlOS.Todo.Cli -- whoami
dotnet run --project examples/SqlOS.Todo.Cli -- add "Ship device OAuth"
dotnet run --project examples/SqlOS.Todo.Cli -- list
dotnet run --project examples/SqlOS.Todo.Cli -- toggle <todo-id>

login prints and opens verification_uri_complete. Sign in through SqlOS AuthPage, approve the CLI request, then return to the terminal. Tokens are stored under ~/.sqlos/todo-cli/tokens.json for the demo.

More detail: CLI OAuth.

Portable public clients#

Once the sample is reachable on public HTTPS, you can use both public-client onboarding paths.

CIMD#

The sample publishes a metadata document at:

/clients/portable-client.json

That document is useful as:

• a working reference for the shape of a client_id metadata document
• a starter path when you want to point a portable client at a stable HTTPS URL

DCR#

DCR stays off by default. Enable it when you need compatibility clients:

TodoSample__EnableDcr=true

Then use:

POST /sqlos/auth/register

This is the compatibility path for clients that still expect dynamic client registration.

Why this sample exists#

Use the Todo sample when your question is:

"How do I ship hosted auth, simple FGA, and protected-resource metadata with very little app code?"

Use the broader Example stack when your question is:

"How do I explore all of SqlOS, including OIDC, SAML, org workflows, and richer multi-tenant FGA?"