PrimusSaaS.Rbac.Dapper 1.0.1

PrimusSaaS.Rbac.Dapper

Dapper storage adapter for PrimusSaaS.Rbac. A lightweight, provider-agnostic alternative to the EF Core adapter that gives you full control over SQL. No DbContext, no migrations, no EF dependency.

Start here

• First runnable Dapper + SQLite path: /docs/modules/rbac/verified-dapper-quickstart
• Existing host integration path: /docs/modules/rbac/integration-guide
• Core RBAC concepts and package map: /docs/modules/rbac
• Exact repository implementation reference: examples/RbacDapperQuickstart

Installation

# Core RBAC + Dapper adapter
dotnet add package PrimusSaaS.Rbac
dotnet add package PrimusSaaS.Rbac.Dapper

# Pick your ADO.NET driver (the adapter has no opinion on provider)
dotnet add package Microsoft.Data.SqlClient   # SQL Server
dotnet add package Npgsql                     # PostgreSQL
dotnet add package Microsoft.Data.Sqlite      # SQLite

Quickstart

Follow steps 1-5 in order for the minimum runnable setup. Step 6 is optional programmatic seeding. Steps 1 and 2 (schema + config) must be done before the app starts because the adapter checks for seed data on startup.

First-time integration order

If you are using this package for the first time, follow this order exactly:

1. choose your database driver
2. configure ConnectionStrings:Rbac
3. create the RBAC schema
4. implement IRbacDbConnectionFactory
5. register AddPrimusRbacDapper(...)
6. seed initial RBAC data
7. test one allow case and one deny case

The main difference from the EF Core adapter is step 3: the schema must already exist before the store is first resolved.

1 — Add the connection string

// appsettings.json
{
  "ConnectionStrings": {
    "Rbac": "Server=localhost;Database=MyApp;Trusted_Connection=True;"
  },
  "Rbac": {
    "SeedMode": "none"
  }
}

SeedMode options: none (production default), minimal (one catch-all permission), sample (demo roles and groups for local dev).

2 — Create the schema

Run the DDL once against your database before first launch. See the full DDL section below for the complete script.

3 — Implement IRbacDbConnectionFactory

This is the one class you write — it tells the adapter how to get a connection:

using System.Data;
using Microsoft.Data.SqlClient;
using PrimusSaaS.Rbac.Dapper;

public class RbacConnectionFactory : IRbacDbConnectionFactory
{
    private readonly string _connectionString;

    public RbacConnectionFactory(IConfiguration config)
        => _connectionString = config.GetConnectionString("Rbac")!;

    public IDbConnection CreateConnection() => new SqlConnection(_connectionString);
}

For PostgreSQL, swap SqlConnection for NpgsqlConnection. For SQLite, use SqliteConnection. The adapter works with any IDbConnection.

4 — Register in Program.cs

using PrimusSaaS.Rbac;
using PrimusSaaS.Rbac.Dapper;

// Register the connection factory (singleton — connection pooling is handled by the driver)
builder.Services.AddSingleton<IRbacDbConnectionFactory, RbacConnectionFactory>();

// Register RBAC with Dapper store
builder.Services.AddPrimusRbacDapper(opts =>
    builder.Configuration.GetSection("Rbac").Bind(opts));

// Optional: enable PostgreSQL session variable initializer for DB RLS policies
builder.Services.AddPrimusRbacPostgresRls();

What gets registered in DI:

Note: RbacDapperStore also implements IRbacStoreAsync, which RbacService.EvaluateAsync() discovers at runtime via cast — no separate DI registration is needed.

When using PostgreSQL Row-Level Security policies that reference current_setting('app.rbac_actor'), app.rbac_roles, or app.rbac_tenant, call AddPrimusRbacPostgresRls() so IRbacRlsInitializer resolves to PostgresRbacRlsInitializer instead of the default no-op implementation.

5 — Protect your endpoints

Option A — attribute-based (AspNetCore package required):

dotnet add package PrimusSaaS.Rbac.AspNetCore

// On your endpoint or controller
[PrimusRbacAuthorize("orders", "read")]
public IActionResult GetOrders() { ... }

No extra AddPrimusRbacAspNetCore() registration method exists. Referencing the package is enough; the integration surface is the attribute and the .RequirePrimusRbac(...) endpoint filter.

app.MapGet("/orders", () => Results.Ok())
   .RequireAuthorization()
   .RequirePrimusRbac("orders", "read");

Option B — programmatic check via IRbacService:

public class OrdersController : ControllerBase
{
    private readonly IRbacService _rbac;
    public OrdersController(IRbacService rbac) => _rbac = rbac;

    public async Task<IActionResult> GetOrders()
    {
        var decision = await _rbac.EvaluateAsync(new RbacAccessRequest
        {
            PrincipalId = User.FindFirstValue(ClaimTypes.NameIdentifier)!,
            Resource    = "orders",
            Action      = "read",
            TenantId    = User.FindFirstValue("tid")
        });

        if (!decision.Allowed)
            return Forbid();

        return Ok(await _orderService.GetAllAsync());
    }
}

6 — Seed initial roles and permissions (optional)

Use SeedPrimusRbac after app.Build() to create your initial data programmatically:

var app = builder.Build();

app.Services.SeedPrimusRbac(rbac =>
{
    rbac.UpsertPermission(new RbacPermission(
        Id: "perm:orders:read",
        Action: "read",
        Resource: "orders",
        Effect: RbacEffect.Allow,
        Scope: new RbacScope(ApplicationId: "my-app")));

    rbac.UpsertRole(new RbacRole(
        Id: "role:viewer",
        Name: "Viewer",
        Scope: new RbacScope(ApplicationId: "my-app"),
        PermissionIds: new[] { "perm:orders:read" }));
});

Schema DDL

Column names match the EF Core adapter so you can swap providers without migrating data. Run the script once before first launch.

SQL Server

CREATE TABLE RbacRoles (
    Id               NVARCHAR(120)  NOT NULL PRIMARY KEY,
    Name             NVARCHAR(120)  NOT NULL,
    ApplicationId    NVARCHAR(100)  NULL,
    TenantId         NVARCHAR(100)  NULL,
    Environment      NVARCHAR(50)   NULL,   -- maps to RbacScope.Qualifier
    PermissionIdsJson NVARCHAR(MAX) NOT NULL DEFAULT '[]',
    InheritsJson     NVARCHAR(MAX)  NULL,
    Description      NVARCHAR(MAX)  NULL,
    MetadataJson     NVARCHAR(MAX)  NULL
);
CREATE INDEX IX_RbacRoles_Name  ON RbacRoles (Name);
CREATE INDEX IX_RbacRoles_Scope ON RbacRoles (ApplicationId, TenantId, Environment);

CREATE TABLE RbacPermissions (
    Id                  NVARCHAR(120)  NOT NULL PRIMARY KEY,
    Action              NVARCHAR(80)   NOT NULL,
    Resource            NVARCHAR(200)  NOT NULL,
    Effect              INT            NOT NULL,
    ApplicationId       NVARCHAR(100)  NULL,
    TenantId            NVARCHAR(100)  NULL,
    Environment         NVARCHAR(50)   NULL,
    Description         NVARCHAR(MAX)  NULL,
    ConditionsJson      NVARCHAR(MAX)  NULL,
    ConditionGroupsJson NVARCHAR(MAX)  NULL,
    MetadataJson        NVARCHAR(MAX)  NULL
);
CREATE INDEX IX_RbacPermissions_ActionResource ON RbacPermissions (Action, Resource);
CREATE INDEX IX_RbacPermissions_Scope          ON RbacPermissions (ApplicationId, TenantId, Environment, Action, Resource);

CREATE TABLE RbacAssignments (
    Id            NVARCHAR(140)  NOT NULL PRIMARY KEY,
    PrincipalId   NVARCHAR(120)  NOT NULL,
    PrincipalType NVARCHAR(40)   NOT NULL,
    RoleId        NVARCHAR(120)  NOT NULL,
    ApplicationId NVARCHAR(100)  NULL,
    TenantId      NVARCHAR(100)  NULL,
    Environment   NVARCHAR(50)   NULL,
    ExpiresAt     DATETIME2      NULL,
    Enabled       BIT            NOT NULL DEFAULT 1,
    AttributesJson NVARCHAR(MAX) NULL
);
CREATE INDEX IX_RbacAssignments_PrincipalId   ON RbacAssignments (PrincipalId);
CREATE INDEX IX_RbacAssignments_RoleId        ON RbacAssignments (RoleId);
CREATE INDEX IX_RbacAssignments_PrincipalScope ON RbacAssignments (PrincipalId, ApplicationId, TenantId, Environment);

CREATE TABLE RbacGroups (
    Id            NVARCHAR(140)  NOT NULL PRIMARY KEY,
    Name          NVARCHAR(120)  NOT NULL,
    Type          NVARCHAR(80)   NOT NULL,
    ApplicationId NVARCHAR(100)  NULL,
    TenantId      NVARCHAR(100)  NULL,
    Environment   NVARCHAR(50)   NULL,
    ParentId      NVARCHAR(140)  NULL,
    Description   NVARCHAR(MAX)  NULL,
    MetadataJson  NVARCHAR(MAX)  NULL
);
CREATE INDEX IX_RbacGroups_ParentId ON RbacGroups (ParentId);
CREATE INDEX IX_RbacGroups_Type     ON RbacGroups (Type);
CREATE INDEX IX_RbacGroups_Scope    ON RbacGroups (ApplicationId, TenantId, Environment);

CREATE TABLE RbacMemberships (
    Id            NVARCHAR(160)  NOT NULL PRIMARY KEY,
    GroupId       NVARCHAR(140)  NOT NULL,
    PrincipalId   NVARCHAR(120)  NOT NULL,
    PrincipalType NVARCHAR(40)   NOT NULL,
    ApplicationId NVARCHAR(100)  NULL,
    TenantId      NVARCHAR(100)  NULL,
    Environment   NVARCHAR(50)   NULL,
    ExpiresAt     DATETIME2      NULL,
    Enabled       BIT            NOT NULL DEFAULT 1,
    AttributesJson NVARCHAR(MAX) NULL
);
CREATE INDEX IX_RbacMemberships_GroupId       ON RbacMemberships (GroupId);
CREATE INDEX IX_RbacMemberships_PrincipalId   ON RbacMemberships (PrincipalId);
CREATE INDEX IX_RbacMemberships_GroupPrincipal ON RbacMemberships (GroupId, PrincipalId);
CREATE INDEX IX_RbacMemberships_Scope         ON RbacMemberships (PrincipalId, ApplicationId, TenantId, Environment);

PostgreSQL

CREATE TABLE "RbacRoles" (
    "Id"               VARCHAR(120)  NOT NULL PRIMARY KEY,
    "Name"             VARCHAR(120)  NOT NULL,
    "ApplicationId"    VARCHAR(100)  NULL,
    "TenantId"         VARCHAR(100)  NULL,
    "Environment"      VARCHAR(50)   NULL,
    "PermissionIdsJson" TEXT         NOT NULL DEFAULT '[]',
    "InheritsJson"     TEXT          NULL,
    "Description"      TEXT          NULL,
    "MetadataJson"     TEXT          NULL
);
CREATE INDEX "IX_RbacRoles_Name"  ON "RbacRoles" ("Name");
CREATE INDEX "IX_RbacRoles_Scope" ON "RbacRoles" ("ApplicationId", "TenantId", "Environment");

CREATE TABLE "RbacPermissions" (
    "Id"                  VARCHAR(120) NOT NULL PRIMARY KEY,
    "Action"              VARCHAR(80)  NOT NULL,
    "Resource"            VARCHAR(200) NOT NULL,
    "Effect"              INT          NOT NULL,
    "ApplicationId"       VARCHAR(100) NULL,
    "TenantId"            VARCHAR(100) NULL,
    "Environment"         VARCHAR(50)  NULL,
    "Description"         TEXT         NULL,
    "ConditionsJson"      TEXT         NULL,
    "ConditionGroupsJson" TEXT         NULL,
    "MetadataJson"        TEXT         NULL
);
CREATE INDEX "IX_RbacPermissions_ActionResource" ON "RbacPermissions" ("Action", "Resource");
CREATE INDEX "IX_RbacPermissions_Scope"          ON "RbacPermissions" ("ApplicationId", "TenantId", "Environment", "Action", "Resource");

CREATE TABLE "RbacAssignments" (
    "Id"            VARCHAR(140) NOT NULL PRIMARY KEY,
    "PrincipalId"   VARCHAR(120) NOT NULL,
    "PrincipalType" VARCHAR(40)  NOT NULL,
    "RoleId"        VARCHAR(120) NOT NULL,
    "ApplicationId" VARCHAR(100) NULL,
    "TenantId"      VARCHAR(100) NULL,
    "Environment"   VARCHAR(50)  NULL,
    "ExpiresAt"     TIMESTAMPTZ  NULL,
    "Enabled"       BOOLEAN      NOT NULL DEFAULT TRUE,
    "AttributesJson" TEXT        NULL
);
CREATE INDEX "IX_RbacAssignments_PrincipalId"    ON "RbacAssignments" ("PrincipalId");
CREATE INDEX "IX_RbacAssignments_RoleId"         ON "RbacAssignments" ("RoleId");
CREATE INDEX "IX_RbacAssignments_PrincipalScope" ON "RbacAssignments" ("PrincipalId", "ApplicationId", "TenantId", "Environment");

CREATE TABLE "RbacGroups" (
    "Id"            VARCHAR(140) NOT NULL PRIMARY KEY,
    "Name"          VARCHAR(120) NOT NULL,
    "Type"          VARCHAR(80)  NOT NULL,
    "ApplicationId" VARCHAR(100) NULL,
    "TenantId"      VARCHAR(100) NULL,
    "Environment"   VARCHAR(50)  NULL,
    "ParentId"      VARCHAR(140) NULL,
    "Description"   TEXT         NULL,
    "MetadataJson"  TEXT         NULL
);
CREATE INDEX "IX_RbacGroups_ParentId" ON "RbacGroups" ("ParentId");
CREATE INDEX "IX_RbacGroups_Type"     ON "RbacGroups" ("Type");
CREATE INDEX "IX_RbacGroups_Scope"    ON "RbacGroups" ("ApplicationId", "TenantId", "Environment");

CREATE TABLE "RbacMemberships" (
    "Id"            VARCHAR(160) NOT NULL PRIMARY KEY,
    "GroupId"       VARCHAR(140) NOT NULL,
    "PrincipalId"   VARCHAR(120) NOT NULL,
    "PrincipalType" VARCHAR(40)  NOT NULL,
    "ApplicationId" VARCHAR(100) NULL,
    "TenantId"      VARCHAR(100) NULL,
    "Environment"   VARCHAR(50)  NULL,
    "ExpiresAt"     TIMESTAMPTZ  NULL,
    "Enabled"       BOOLEAN      NOT NULL DEFAULT TRUE,
    "AttributesJson" TEXT        NULL
);
CREATE INDEX "IX_RbacMemberships_GroupId"        ON "RbacMemberships" ("GroupId");
CREATE INDEX "IX_RbacMemberships_PrincipalId"    ON "RbacMemberships" ("PrincipalId");
CREATE INDEX "IX_RbacMemberships_GroupPrincipal" ON "RbacMemberships" ("GroupId", "PrincipalId");
CREATE INDEX "IX_RbacMemberships_Scope"          ON "RbacMemberships" ("PrincipalId", "ApplicationId", "TenantId", "Environment");

SQLite: Use TEXT for all string/JSON/datetime columns and INTEGER instead of BOOLEAN / BIT. SQLite has no VARCHAR length enforcement but specifying it is harmless.

Migrating from PrimusSaaS.Rbac.EFCore

The two adapters share the same table names, column names, and JSON encoding. Swap is straightforward:

1. Remove AddPrimusRbacEfCore<TContext>() and the EF Core package reference.
2. Add IRbacDbConnectionFactory registration + AddPrimusRbacDapper().
3. You no longer need modelBuilder.AddPrimusRbac() in your DbContext.
4. Schema stays the same — no data migration needed.

Behaviour notes

• Per-operation connections — each store method opens a fresh connection from IRbacDbConnectionFactory.CreateConnection(). ADO.NET connection pooling handles the actual socket reuse.
• Upsert strategy — SELECT EXISTS then INSERT or UPDATE (cross-database portable, no dialect-specific MERGE/ON CONFLICT).
• Async — implements IRbacStoreAsync; uses DbConnection.OpenAsync when the provider exposes it.
• Seeding — same SeedMode option as EFCore (none / minimal / sample). Seeds only when all tables are empty.