Authdog

Security guide

Authorization & Access Control

Authentication tells you who is calling. Authorization decides whether that caller may do the thing they're asking to do. This guide picks one server-side model per environment (RBAC, ABAC, or FGA), configures a baseline, and verifies enforcement fails closed.

Prerequisites

  • An Authdog project with separate development, staging, and production environments.
  • Working authentication and backend session validation.
  • An inventory of protected resources and actions.
  • A list of job functions, customer-organization boundaries, and exceptional access cases.
  • Test users representing allowed and denied scenarios.

Don't design authorization around UI visibility. A hidden button improves usability; only a backend check protects the action.

Implementation

1. Choose one model per environment

RBAC bases decisions on roles and their permissions, the default, and fits access that maps to job functions. ABAC evaluates Rego policies over subject, resource, and request attributes, use it when rules depend on ownership, department, or amount. FGA stores Zanzibar-style relationship tuples for per-object, hierarchical access, sharing models like documents and folders. Each environment runs exactly one model.

2. Build an RBAC baseline

Define granular capability strings (invoices:read, users:suspend) and compose them into a small set of roles (member, billing, admin). A user's effective permissions are the union of every role they hold. Prefer group-derived assignment for enterprise customers when their directory is the source of truth, see User provisioning with SCIM.

3. Keep customer access organization-scoped

Model B2B customers as organizations inside an environment. A user may belong to several with different roles in each. Test cross-organization denial explicitly, a valid session and role in one organization must not imply access to another.

4. Enforce every protected action on the server

Validate the session, then check the exact permission, policy, or relationship the operation requires before entering the handler. Gate on invoices:read, not on assumptions about what admin currently contains. Missing identity, validation failure, or unavailable policy data must never fall through to business logic.

5. Introduce ABAC or FGA only for real requirements

Use ABAC when decisions depend on attributes of both caller and resource; keep Rego policies small and covered by positive and negative test cases. Use FGA when access exists through relationships and inheritance. Avoid recreating ABAC with hundreds of RBAC roles.

Security considerations

  • Default to deny and grant only named capabilities.
  • Enforce backend checks even when clients hide unauthorized controls.
  • Use organization context in every customer-scoped lookup and decision.
  • Review direct assignments that can outlive directory group membership.
  • Test policy errors and missing context, not only explicit deny responses.
  • Keep a recovery path for authorized operators when changing production roles or policies.

Validation checklist

  • Environment uses the intended single authorization model.
  • Every protected action maps to a documented permission, policy rule, or relation.
  • Authenticated user without required access receives denial.
  • Missing and invalid sessions receive denial.
  • User with access in organization A cannot access organization B.
  • Group membership grants the mapped role after provisioning.
  • Policy or authorization-service errors fail closed.

Troubleshooting

User is authenticated but denied: inspect active organization, role sources, and whether the backend checks the expected capability.

Group mapping does not grant a role: verify group name or external ID, target role, and match type; re-apply rules to existing groups.

Cross-customer access test succeeds: ensure resource lookup is scoped to the active organization before authorization.

Next steps