Authorized pages
Read the page of an EF Core query a subject may see, with ToPageAsync.
A list endpoint reads authorized data one page at a time: ToPageAsync on your EF Core query, with the subject and the permission each row needs. It returns only rows the subject may see, in your query's order. For one resource, use CheckAccessAsync or AuthorizedDetailAsync. Those are the two ways to read authorized data.
ToPageAsync authorizes a subject ID; it does not authenticate the request. Validate a bearer token for the API's exact audience before the endpoint runs, then use the validated token's user ID as the FGA subject.
Index the columns the list sorts by, as you would for any database:
protected override void OnApplicationModelCreating(ModelBuilder modelBuilder)
{
modelBuilder.Entity<Chain>(entity =>
{
entity.HasKey(c => c.Id);
entity.Property(c => c.Name).HasMaxLength(200);
entity.HasIndex(c => new { c.Name, c.Id }); // the order the list pages by
});
}Then page the query with the subject, the permission, a page size, and the previous page's cursor:
var page = await db.Chains
.AsNoTracking()
.Where(c => c.Name.Contains(search)) // your filters, any number
.OrderBy(c => c.Name) // the order; the key is appended
.ToPageAsync(subjectId, "CHAIN_VIEW", pageSize: 20, cursor: request.Cursor);
return Results.Ok(page.ToResponse(c => new ChainDto(c.Id, c.Name)));ToPageAsync resolves the subject's principals (the subject plus its active groups) and the permission, then reads your query in its order and checks each row, for about a page of rows. When few of them are visible, it reads the order under each node the caller is granted instead (SqlOS keeps a copy of every index of a protected table under every node of the resource tree, in tables of its own), so a caller who can see 3 rows of a million costs about a page, not the table. The page's rows are then loaded through your query (Include, tracking) and checked once more.
The query must start from a DbSet of a context that derives from SqlOSDbContext<TContext>. Each index adds a table to your EF model (SqlOSFgaPage_Chains_Name, and SqlOSFgaPage_Chains_Id for the key), so your next migration creates it. SqlOSDbContext keeps it current in the same transaction as every save, and fills it on the first start after you add the index. See Paginating authorized lists for the cursor, the response, and what the query may contain.
Pass NextCursor back as the next request's cursor. Do not write your own position filter (.Where(c => c.Name.CompareTo(lastSeen) > 0), keyset libraries, since= parameters): ToPageAsync seeks under each of the caller's nodes from the cursor, and a hand-written position is just another filter there, so every page walks the caller's rows from the start of the order.
ToPageAsync logs a warning naming the index to add.SqlOS has no authorized count, Any, join, or unpaged list. Each of those costs every row the caller can see, which is what pages exist to avoid. Show a page and its HasNextPage instead of a total, and check one resource with CheckAccessAsync instead of asking whether any row is visible. Sorting, search, and projection are ordinary EF Core on the query you page; project after the page with page.ToResponse(...).
From the retail example app (examples/SqlOS.Example.Api/FgaRetail/Endpoints/ChainEndpoints.cs):
group.MapGet("/", async (
ExampleAppDbContext context,
HttpContext http,
int pageSize = 10,
string? search = null,
string? cursor = null) =>
{
var subjectId = RetailSubjectResolver.ResolveSubjectId(http);
IQueryable<Chain> query = context.Chains.AsNoTracking();
if (!string.IsNullOrWhiteSpace(search))
query = query.Where(c => c.Name.ToLower().Contains(search.ToLower()));
SqlOSCursorPage<Chain> page;
try
{
page = await query.OrderBy(c => c.Name)
.ToPageAsync(subjectId, RetailPermissionKeys.ChainView, Math.Clamp(pageSize, 1, 100), cursor, http.RequestAborted);
}
catch (Exception exception) when (exception is SqlOSCursorException or ArgumentException { ParamName: "cursor" })
{
return Results.BadRequest(new { error = SqlOSCursorException.ErrorCode, message = exception.Message });
}
return Results.Ok(page.ToResponse(c => new ChainDto { Id = c.Id, Name = c.Name }));
});ToPageAsyncFor single-resource access, use AuthorizedDetailAsync. For mutations, use CheckAccessAsync.