Production Access Control with RBAC
This recipe implements the tenant, subject, permission, and resource boundaries explained in Why Your NestJS RBAC Breaks in Multi-Tenant Apps.
This recipe combines four independent concerns without collapsing them into one guard:
| Layer | Responsibility |
|---|---|
@nestarc/tenancy | Resolve and isolate the current tenant. |
@nestarc/api-keys | Authenticate machine credentials and enforce coarse scopes. |
@nestarc/rbac | Authorize tenant, global, and resource-scoped actions. |
@nestarc/audit-log | Record policy mutations and denied decisions for review. |
Keep the order explicit: authenticate the subject, resolve the tenant, then evaluate RBAC. Database RLS remains the final data-isolation boundary.
One module registration
The configuration snippets below isolate one concern at a time. Combine their storage, tenantResolver, subjectResolver, and auditLogger properties into a single RbacModule.forRoot() or forRootAsync() call in the application.
1. Resolve the current compatibility boundary
Supported single-process boundary
The current tenancy 0.16.4, api-keys 0.4, RBAC 0.2.2, and audit-log 0.8 stack shares NestJS 10/11 and Prisma 6/7. Tenancy limits the framework intersection to 10/11 even though the other three packages also accept NestJS 12. Use Node ^22.23.4 || ^24.22.1 and TypeScript 5.3+.
npm install @nestarc/[email protected] @nestarc/[email protected] @nestarc/[email protected] @nestarc/[email protected]For Prisma 6, retain the client construction used below and install matching CLI/client versions. Prisma 7 is also supported: follow Prisma 7 Setup for explicit generated output, a matching PostgreSQL adapter, and audit-log's prismaModule option.
npm install @prisma/client@^6
npm install -D prisma@^6Review the API Keys 0.4 checklist and RBAC identity reconciliation before upgrading existing credentials or middleware. Exact API-key tenant identities must agree across authentication, tenancy, and RBAC. The tenancy 0.16.2 upgrade sequence also requires updating the application's Node runtime and HTTP parser graph; installing tenancy does not apply its repository overrides to this application.
2. Define one permission contract
Centralize the persisted permission strings and import this contract from guards, seeds, and service checks:
import { defineRbacPermissions } from '@nestarc/rbac';
export const permissions = defineRbacPermissions(
{
reports: {
read: 'reports.read',
export: 'reports.export',
},
projects: {
inviteMember: 'project.member.invite',
},
} as const,
{ validateDuplicates: true },
);3. Register fail-closed RBAC
Use Prisma storage for multi-instance production deployments and start with strict defaults:
import {
createStrictRbacOptions,
RbacModule,
} from '@nestarc/rbac';
import { PrismaRbacStorage } from '@nestarc/rbac/prisma';
RbacModule.forRoot(
createStrictRbacOptions({
storage: new PrismaRbacStorage(prisma),
}),
);Strict options require authorization metadata, require tenant context by default, deny storage failures, and validate tenant boundaries on writes. Mark intentionally public handlers with @SkipRbac().
4. Connect tenant context
Pass the tenant ID already resolved by your tenancy layer:
import { RbacModule, createStrictRbacOptions } from '@nestarc/rbac';
import { createTenancyTenantResolver } from '@nestarc/rbac/integrations/tenancy';
RbacModule.forRoot(
createStrictRbacOptions({
storage,
tenantResolver: createTenancyTenantResolver(
() => tenancyContext.getTenantId(),
),
}),
);Do not derive the authorization tenant independently from untrusted route data. Let authentication and tenancy middleware establish it first, and keep PostgreSQL RLS enabled for tenant-owned models.
5. Map API keys to RBAC subjects
ApiKeysGuard validates the credential and attaches API key context. The RBAC adapter maps that context to an api_key subject:
import { RbacModule, createStrictRbacOptions } from '@nestarc/rbac';
import { createApiKeySubjectResolver } from '@nestarc/rbac/integrations/api-keys';
RbacModule.forRoot(
createStrictRbacOptions({
storage,
subjectResolver: createApiKeySubjectResolver(),
}),
);Apply authentication before authorization and require both the coarse API key scope and the domain permission:
import { ApiKeysGuard, RequireScope } from '@nestarc/api-keys';
import { Can, RbacGuard } from '@nestarc/rbac';
@UseGuards(ApiKeysGuard, RbacGuard)
@RequireScope('reports', 'read')
@Can(permissions.reports.read, { tenant: 'required' })
@Get('reports')
listReports() {
return this.reports.list();
}When the same application also supports user sessions, compose a custom subjectResolver that tries the API key resolver and then maps the authenticated user. Do not let an unvalidated request object become an RBAC subject.
6. Audit policy changes and denials
Connect RBAC to the structural AuditService.log() API:
import { createAuditLogRbacLogger } from '@nestarc/rbac/integrations/audit-log';
RbacModule.forRoot(
createStrictRbacOptions({
storage,
auditLogger: createAuditLogRbacLogger({
auditLog: auditService,
source: 'rbac',
}),
}),
);The adapter records role, permission, and binding changes as successes and denied decisions as failures. It strips secret-shaped metadata before forwarding events. Keep raw tokens, request headers, request bodies, and identity-provider payloads out of custom audit metadata as well.
This adapter uses the structural AuditService.log() integration; it is separate from automatic Prisma lifecycle tracking. Audit-log 0.8.0's manual transaction helper and opt-in validation do not automatically make RBAC mutations and adapter logging one transaction. For automatic audited deletes and restores, add soft-delete 0.7.6; upgrade installations of 0.7.5 or earlier before combining them with audit-log 0.8.0. The tenant-scoped lifecycle guide pairs tenancy 0.16.4 with audit-log 0.8.0 and soft-delete 0.7.6. On the dedicated audit/soft-delete client, pass tenancyTransactionCallback() to withAuditTransaction() so the mutation and its audit record share the same RLS tenant and transaction.
7. Seed roles and verify boundaries
await rbac.createRole({
tenantId: '550e8400-e29b-41d4-a716-446655440000',
key: 'report-viewer',
permissions: [permissions.reports.read],
});
await rbac.assignRole({
tenantId: '550e8400-e29b-41d4-a716-446655440000',
subject: {
type: 'api_key',
id: 'key_1',
tenantId: '550e8400-e29b-41d4-a716-446655440000',
},
roleKey: 'report-viewer',
});Before rollout, verify:
- a valid key in the correct tenant and role is allowed;
- a valid key without the required scope is denied by
ApiKeysGuard; - a scoped key without the RBAC permission is denied by
RbacGuard; - a cross-tenant subject or resource binding is rejected;
- missing tenant and missing resource context fail closed;
- denial reasons and policy mutations reach audit storage without secrets.
Use expectRbacMatrix() to keep these combinations compact and deterministic.