75 lines
4.4 KiB
Markdown
75 lines
4.4 KiB
Markdown
# Permissions and Access Control
|
|
|
|
## Purpose
|
|
Explain role-based permissions, account ownership rules, and how viewsets enforce access across the stack.
|
|
|
|
## Code Locations (exact paths)
|
|
- Role-based permissions: `backend/igny8_core/auth/permissions.py`
|
|
- User roles and helpers: `backend/igny8_core/auth/models.py`
|
|
- Account context middleware: `backend/igny8_core/auth/middleware.py`
|
|
- Base viewsets with override/bypass logic: `backend/igny8_core/api/base.py`
|
|
- DRF settings: `backend/igny8_core/settings.py`
|
|
|
|
## High-Level Responsibilities
|
|
- Enforce role-based access (developer, owner, admin, editor, viewer, system_bot).
|
|
- Enforce tenant/site/sector scoping with selective overrides for privileged roles.
|
|
- Block access when accounts lack active plans.
|
|
|
|
## Detailed Behavior
|
|
- Roles are stored on `User.role`; helper methods (`is_admin_or_developer`, `is_developer`, `is_system_account_user`, `has_role`) drive bypass logic.
|
|
- Permission classes:
|
|
- `IsOwnerOrAdmin`: allows authenticated users with roles owner/admin/developer or superuser.
|
|
- `IsEditorOrAbove`: allows editor/admin/owner/developer or superuser.
|
|
- `IsViewerOrAbove`: allows any authenticated user.
|
|
- `AccountPermission`: ensures the user is authenticated, not a system bot unless intended, and matches object account when present; system bots bypass account checks.
|
|
- Base viewsets:
|
|
- `AccountModelViewSet` filters by `account` unless `is_admin_or_developer` or `is_system_account_user` is true; create sets `account` automatically; delete protects system account slugs.
|
|
- `SiteSectorModelViewSet` extends filtering to `site`/`sector` when models have those fields.
|
|
- Middleware:
|
|
- `AccountContextMiddleware` denies requests when user lacks an account or active plan (403/402), logging out session users and returning JSON errors.
|
|
- System accounts (`aws-admin`, `default-account`, `default`) and system bots are privileged; system accounts are protected from deletion.
|
|
|
|
## Data Structures / Models Involved (no code)
|
|
- `User` with `role` and account FK.
|
|
- `Account` with `status` and `plan` used for gating.
|
|
- `SiteUserAccess` for per-site grants evaluated by `User.get_accessible_sites`.
|
|
|
|
## Execution Flow
|
|
- Middleware validates account/plan and sets `request.account`.
|
|
- DRF authentication sets `request.user`; permission classes on views (and base viewsets) check role/account match.
|
|
- Querysets are filtered by tenant/site/sector; privileged roles may bypass filtering.
|
|
- Soft-delete or delete operations respect system account protection.
|
|
|
|
## Cross-Module Interactions
|
|
- All module viewsets inherit base classes, so account/site/sector scoping and role-based bypass apply uniformly.
|
|
- Integration endpoints using API key auth rely on `request.site`/`request.account` set earlier.
|
|
|
|
## State Transitions (if applicable)
|
|
- Account status and plan activation affect access; changing these alters middleware decisions immediately due to per-request user refresh.
|
|
|
|
## Error Handling
|
|
- Middleware returns structured JSON errors for missing account or inactive plan.
|
|
- Base viewsets wrap permission and validation failures into unified error responses.
|
|
- Permission classes return standard DRF permission denials for unauthenticated/unauthorized users.
|
|
|
|
## Tenancy Rules
|
|
- Default: filter data to `request.account`; site/sector models further constrain by site/sector.
|
|
- Overrides: developers/admins/system-account users can see across accounts; system bots can access any account/object; system accounts cannot be deleted.
|
|
|
|
## Billing Rules (if applicable)
|
|
- Active plan required; enforced in middleware before permission checks.
|
|
|
|
## Background Tasks / Schedulers (if applicable)
|
|
- Background tasks should be invoked with account/site identifiers to maintain the same isolation rules; role checks occur at request time, not within tasks.
|
|
|
|
## Key Design Considerations
|
|
- Centralize role checks to avoid per-view duplication.
|
|
- Maintain middleware-first gating to prevent expensive processing before authorization.
|
|
- Preserve protection of system accounts and allow ops-level overrides without compromising tenant isolation.
|
|
|
|
## How Developers Should Work With This Module
|
|
- Apply permission classes (`IsOwnerOrAdmin`, `IsEditorOrAbove`, etc.) on viewsets/endpoints as needed.
|
|
- Always inherit from `AccountModelViewSet`/`SiteSectorModelViewSet` for scoped data access.
|
|
- Avoid bypassing middleware plan checks; if admin-only, use explicit admin routes instead.
|
|
- When adding new privileged behaviors, reuse `User` role helpers and system-account detection.
|