Skip to content

SigNoz is an open-source, OpenTelemetry-native observability platform for your team and their AI agents. Get logs, metrics, and traces in one tool with features like APM, distributed tracing, log management, infra monitoring, etc. Combined with SigNoz MCP and a native AI teammate (in SigNoz Cloud) it helps you build more resilient apps.

6.2 KB
Raw Blame

AuthZ Components

Quick reference for permission-gating UI. All components use AND semantics: user needs ALL permissions in checks array.

Decision Tree

Need to gate...
├── A button? → AuthZButton
├── Rows of a dropdown menu? → AuthZDropdown
├── Any element with tooltip on deny? → AuthZTooltip
├── A section inside a page? → withAuthZContent (preferred)
│   └── Need JSX wrapper? → AuthZGuardContent
├── An entire page/route? → withAuthZPage (preferred)
│   └── Need JSX wrapper? → AuthZGuardPage
├── Need full control over fallback? → withAuthZ / AuthZGuard
└── None of above fit?
    ├── Can create wrapper component? → Create it (like AuthZButton)
    └── Last resort → useAuthZ hook directly

Building Permissions

Use buildPermission, buildObjectString or pre-built constants. Never cast with as BrandedPermission.

import { buildPermission, buildObjectString } from 'lib/authz/hooks/useAuthZ/utils';
import { 
  RoleCreatePermission,
  buildRoleReadPermission 
} from 'lib/authz/hooks/useAuthZ/permissions/role.permissions';

// Static permission (pre-built)
const checks = [RoleCreatePermission];

// Dynamic permission (builder fn)
const checks = [buildRoleReadPermission(roleId)];

// Custom permission (buildPermission + buildObjectString)
const checks = [buildPermission('read', buildObjectString('dashboard', dashboardId))];

Creating Permission Helpers

When adding authz to a new resource, create a permissions file under lib/authz/hooks/useAuthZ/permissions/.

// lib/authz/hooks/useAuthZ/permissions/dashboard.permissions.ts
import { buildPermission } from '../utils';
import type { BrandedPermission } from '../types';

// Collection-level — wildcard, no specific id needed
export const DashboardCreatePermission = buildPermission('create', 'dashboard:*');
export const DashboardListPermission = buildPermission('list', 'dashboard:*');

// Resource-level — require specific id
export const buildDashboardReadPermission = (id: string): BrandedPermission =>
  buildPermission('read', `dashboard:${id}`);
export const buildDashboardUpdatePermission = (id: string): BrandedPermission =>
  buildPermission('update', `dashboard:${id}`);
export const buildDashboardDeletePermission = (id: string): BrandedPermission =>
  buildPermission('delete', `dashboard:${id}`);

Pattern:

  • <Resource><Action>Permission → collection-level const (wildcard *)
  • build<Resource><Action>Permission(id) → resource-level fn (specific id)

Components

AuthZButton

Button that disables + shows tooltip when denied.

import { SACreatePermission } from 'lib/authz/hooks/useAuthZ/permissions/service-account.permissions';

<AuthZButton checks={[SACreatePermission]} onClick={handleCreate}>
  Create
</AuthZButton>

AuthZDropdown

Dropdown whose item, link and submenu rows take optional checks, at the top level or inside a group. A pending row shows as loading, a denied row is disabled with the denial tooltip. Checks run on first open. A row's own disabled or loading outranks its checks: spread blockedBy(reason) from ./AuthZDropdown/utils for a non-permission block such as a lock.

<AuthZDropdown
  nativeButton
  side="bottom"
  align="end"
  items={[
    { type: 'item', value: 'view', label: 'View', onClick: onView },
    { type: 'item', value: 'delete', label: 'Delete', danger: true, checks: [buildDashboardDeletePermission(id)], onClick: onDelete },
  ]}
>
  <Button aria-label="Actions">...</Button>
</AuthZDropdown>

AuthZTooltip

Wraps any element. Disables child + shows denial tooltip.

import { buildSADeletePermission } from 'lib/authz/hooks/useAuthZ/permissions/service-account.permissions';

<AuthZTooltip checks={[buildSADeletePermission(accountId)]}>
  <IconButton icon={<Trash />} onClick={handleDelete} />
</AuthZTooltip>

withAuthZPage (preferred for pages)

HOC for route-level gating. Wrap at export. Shows PermissionDeniedFullPage + AppLoading.

import { RoleListPermission } from 'lib/authz/hooks/useAuthZ/permissions/role.permissions';

function RolesPage(): JSX.Element {
  return <div>...</div>;
}

export default withAuthZPage(RolesPage, {
  checks: [RoleListPermission],
});

withAuthZContent (preferred for sections)

HOC for inline sections. Shows PermissionDeniedCallout on deny.

import { buildRoleReadPermission } from 'lib/authz/hooks/useAuthZ/permissions/role.permissions';

function RoleEditor(): JSX.Element {
  return <div>...</div>;
}

// Dynamic checks from route params
export default withAuthZContent(RoleEditor, {
  checks: (_props, ctx) => [buildRoleReadPermission(ctx.params.roleId)],
});

withAuthZ

HOC base. No default fallback. Use when you need custom fallback.

import { buildPermission } from 'lib/authz/hooks/useAuthZ/utils';

export default withAuthZ(SecretPanel, {
  checks: [buildPermission('write', 'settings:org')],
  fallback: <p>No access</p>,
});

AuthZGuardPage

JSX variant of withAuthZPage. Use when HOC not possible (conditional rendering).

import { RoleListPermission } from 'lib/authz/hooks/useAuthZ/permissions/role.permissions';

<AuthZGuardPage checks={[RoleListPermission]}>
  <RolesPage />
</AuthZGuardPage>

AuthZGuardContent

JSX variant of withAuthZContent. Use when HOC not possible.

import { RoleCreatePermission } from 'lib/authz/hooks/useAuthZ/permissions/role.permissions';

<AuthZGuardContent checks={[RoleCreatePermission]}>
  <RoleEditor />
</AuthZGuardContent>

AuthZGuard

JSX base guard. No default fallback. Use when you need custom fallback in JSX.

import { buildPermission } from 'lib/authz/hooks/useAuthZ/utils';

<AuthZGuard
  checks={[buildPermission('write', 'settings:org')]}
  fallback={<p>No access</p>}
  fallbackOnLoading={<Spinner />}
>
  <SecretContent />
</AuthZGuard>

Fallback Components

Don't use these components directly, always prefer using via withAuthZ and their variants.

  • PermissionDeniedCallout: inline error callout. Shows user/{id} is not authorized to perform {permissions}.
  • PermissionDeniedFullPage: full-page centered error. Same message, bigger presentation.