Fine-grained authorization (FGA) models resource access as relationships. Use it when roles alone cannot express rules such as “Alice can edit document 42,” “engineering group can view folder 7,” or “document viewers inherit access from parent folder.”
Current availability
Authdog includes an environment-scoped Zanzibar-style FGA engine and console surface. Its RPC service is currently internal infrastructure, not a documented public API at api.authdog.com. Do not call /fga.v1.FgaService/* paths from production applications or depend on their request format. Authentication may be deployment-specific, and compatibility is not guaranteed.
Use RBAC permissions for supported public application integration unless Authdog has enabled FGA for your environment and provided an integration contract.
Core model
Relationship tuple has this conceptual form:
document:roadmap#editor@user:aliceParts:
document— object namespaceroadmap— application-defined object IDeditor— relationuser:alice— subject
Subject can also be userset:
document:roadmap#viewer@group:engineering#memberThis grants document viewer relation to members of engineering group.
Authdog stores tuples per environment with uniqueness across object, relation, and subject. Deleting environment removes its FGA tuples.
Authorization model
One active JSON model can be stored per environment. Model defines namespaces, relations, and bounded rewrite rules:
this— direct tuplescomputedUserset— include another relation on same objecttupleToUserset— follow relation to related object, then evaluate relation thereunion— grant when any child rule grants
Built-in fallback model demonstrates groups, environments, folders, and documents. Environment owners imply editors; editors imply viewers. Document viewers can inherit folder viewer relationship through parent.
Fallback is an implementation default, not substitute for explicit production design. Object IDs and relationship lifecycle must match your application's source of truth.
Design a model
- List protected object types:
document,folder,workspace. - Define relations in product language:
owner,editor,viewer. - Identify direct grants, group grants, and inheritance.
- Map every sensitive operation to required object relation.
- Add tuples when membership or ownership changes.
- Remove tuples on revocation and resource deletion.
- Test allowed and denied cases, including inherited access.
Prefer few stable relations. Avoid encoding transient request context into persistent tuples; use contextual relationships only when supported integration explicitly defines them.
Runtime decisions
Engine supports conceptual operations:
- Check — whether subject holds relation on object.
- BatchCheck — multiple checks in one request.
- ListObjects — objects in namespace available to subject.
- Write/Delete — mutate tuples.
- Read — inspect tuples.
- Expand — flatten relation to concrete subjects.
Unknown namespace or relation is rejected. Check returns boolean and fails closed when relation cannot be established. Per-environment model is cached briefly for decision performance; model changes may not be visible instantly across every isolate.
These operation names describe current engine behavior, not public endpoint commitment.
Enforce in your application
Authorization check must run on backend for every protected operation. Client-side visibility is only UX. Use stable user and object identifiers, include correct Authdog environment, and default to deny on timeout or error.
For list pages, avoid fetching every object and checking one by one. Use supported list operation or maintain application index consistent with relationship tuples. Always re-check before mutation because list results can become stale.
Security and operations
- Keep tuple writes behind trusted backend.
- Validate object ownership before writing delegation tuple.
- Treat group membership updates as security-sensitive.
- Remove relationships when users, groups, or resources are deleted.
- Log model and tuple changes through Audit logs.
- Test cycles and deep inheritance before rollout.
- Separate development and production models by Authdog environment.
- Maintain break-glass process outside normal relationship graph.
FGA answers relationship question; it does not authenticate user. Validate Authdog session first, then evaluate authorization.