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.
- For automated enterprise access, provisioned IdP groups or HRIS departments.
Do not design authorization around UI visibility. A hidden button improves usability, but only a backend check protects the underlying action.
Implementation
1. Choose one model per environment
Use the simplest model that expresses current requirements:
- RBAC bases decisions on roles and their permissions. It is the default and fits access that maps to job functions.
- ABAC evaluates Rego policies using subject, resource, and request-context attributes. Use it when rules depend on ownership, department, region, amount, or similar data.
- FGA stores Zanzibar-style relationship tuples and supports per-object, hierarchical access. Use it for sharing models such as users, teams, folders, and documents.
Each environment runs exactly one model. Use staging to evaluate a richer model before changing production behavior. Because authorization design changes can lock out valid users or grant excess access, record expected allow and deny cases before rollout.
2. Build an RBAC baseline
For most applications, start with RBAC. In the console, define granular capability strings such as:
invoices:read
invoices:write
users:suspendCompose them into a small set of understandable roles such as member, billing, and admin. A user's effective permissions are the union of permissions from every role they hold.
Roles can reach a user through:
- Direct assignment.
- Organization membership and organization-scoped roles.
- IdP or HRIS group-to-role mappings.
Prefer group-derived assignment for enterprise customers when their directory is the source of truth. Authdog group mappings can match a group display name case-insensitively or an external ID exactly. Applying a mapping is additive: matching roles are added without deleting existing manual assignments.
See User provisioning with SCIM for directory synchronization and mapping operations.
3. Keep customer access organization-scoped
Model B2B customers as organizations inside an environment. A user may belong to several organizations and hold different roles in each. Use the active organization in the validated identity context when making organization-specific decisions.
Test cross-organization denial explicitly. A valid session and a role in one organization must not imply access to another customer's resources.
4. Enforce every protected action on the server
Validate the Authdog session before authorization. Then request or evaluate the permission, policy, or relationship required by the operation before entering the protected handler or resolver.
Use exact capabilities rather than broad role-name checks where possible. For example, gate invoice reading on invoices:read, not on assumptions about what admin or billing currently contains. This lets role composition evolve without rewriting route policy.
Authdog's authorization model is server-side and documented to fail closed on errors. Your application should preserve that behavior: missing identity, validation failure, unavailable policy data, or an explicit deny must not fall through to business logic.
5. Introduce ABAC or FGA only for real requirements
Use ABAC when authorization depends on attributes of both caller and resource. Keep Rego policies small, versioned, and covered by positive and negative examples.
Use FGA when access exists through relationships and inheritance, such as a user viewing a document because they can view its parent folder. Define tuple naming conventions and remove relationships as part of resource and membership lifecycle handling.
Avoid recreating ABAC with hundreds of RBAC roles or recreating object relationships as ad hoc user metadata. Pick the model that matches the decision inputs.
Security considerations
- Default to deny and grant only named capabilities.
- Enforce backend checks even when clients hide unauthorized controls.
- Separate tenant administration from application-resource permissions.
- Use organization context in every customer-scoped lookup and decision.
- Review direct assignments that can outlive directory group membership.
- Treat user metadata and IdP attributes as authorization inputs only after their source and update lifecycle are understood.
- Test policy errors and missing context, not only explicit deny responses.
- Use audit records for investigation, never as an authorization source.
- 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.
- Test user with required access succeeds.
- 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.
- Removing upstream membership removes expected group-derived access in the tested lifecycle.
- Direct assignments are reviewed for conflicts with automated access.
- Policy or authorization-service errors fail closed.
Troubleshooting
User is authenticated but denied: inspect active organization, role sources, permission membership, and whether the backend is checking the expected capability.
Group mapping does not grant a role: verify environment, group display name or external ID, target role, and mapping match type. Re-apply rules to existing groups after adding a mapping.
User retains unexpected access: inspect all role sources. Effective permissions are a union, and group mapping is additive; direct or organization assignments may still grant the capability.
Cross-customer access test succeeds: ensure resource lookup is scoped to active organization before authorization and that no environment-wide role bypasses that scope.
ABAC result differs from expectation: capture complete policy input, including absent or differently typed attributes, and test the exact Rego version deployed to that environment.
FGA inheritance is wrong: inspect direct tuples, parent relationships, and model rewrite rules for the specific object.
Next steps
- Connect enterprise identities through Authentication and SSO.
- Drive access from directory groups with User provisioning with SCIM.
- Define account operations in User management.
- Review complete control rollout in Enterprise-ready Authdog.