🛡️ Configurations Reference

The django-rebac package utilizes strict Python dataclasses to define authorization rules. This ensures type safety, auto-completion in modern IDEs, and prevents misconfiguration before your app even boots.

There are two primary configuration classes you will use: RebacModelConfig (for database models) and RebacViewConfig (for API views).

Configuration Defaults

DEFAULTS `module-attribute`

DEFAULTS: dict[str, Any] = {'BACKEND': 'rebac.backends.openfga.client.OpenFGABackend', 'BACKEND_OPTIONS': {}, 'BATCH_SIZE': 50, 'MAX_RETRIES': 5, 'REQUEST_HEADER_MAPPINGS': {'X-User-Id': 'rebac_user'}, 'ENABLE_OUTBOX_ADMIN': True, 'REBAC_USER_ATTR': 'rebac_user', 'REBAC_USER_PREFIX': 'user:', 'LOCAL_DEV_FALLBACK': {'USE_DJANGO_USER': True, 'STATIC_USER_ID': None}}

Sensible defaults for the django-rebac integration.

Attributes:

Name	Type	Description
`BACKEND`	`str`	The dot-path to the ReBAC engine adapter. Defaults to `django_rebac.backends.openfga.client.OpenFGABackend`.
`BACKEND_OPTIONS`	`dict[str, Any]`	Backend-specific configuration (e.g., API URLs, Store IDs, or Pre-shared Keys).
`BATCH_SIZE`	`int`	Number of items to process in a single synchronization batch. Defaults to `50`.
`MAX_RETRIES`	`int`	How many times to retry failed synchronization attempts. Defaults to `5`.
`REQUEST_HEADER_MAPPINGS`	`dict[str, str]`	Mapping of incoming request headers to ReBAC context variables.
`ENABLE_OUTBOX_ADMIN`	`bool`	If True, registers the ReBAC Outbox model in the Django Admin. Defaults to `True`.
`REBAC_USER_ATTR`	`str`	The attribute on the request/user object to use for ReBAC identity.
`REBAC_USER_PREFIX`	`str`	Prefix added to user IDs (e.g., `user:123`).
`LOCAL_DEV_FALLBACK`	`dict[str, Any]`	Settings for local development when identity providers are absent. USE_DJANGO_USER: Fallback to native Django session user. Defaults to `True`. STATIC_USER_ID: A hardcoded ID for rapid testing. Defaults to `None`.

Setting Variable Name

Avoiding to use DEFAULT = .... The correct variable name in settings.py is REBAC_CONFIG = { ... } !!!

1. View Configuration

The RebacViewConfig dataclass centralizes all ReBAC authorization rules for your Django Views and ViewSets. By attaching this configuration to your view, the underlying permission classes (IsRebacAuthorized) and mixins (RebacViewMixin) automatically enforce access control.

The Golden Rule: Check Permissions, Not Roles

When configuring a view, you must only check Permissions (e.g., can_read_document, can_update). You should never check roles directly.

Configuration for enforcing ReBAC authorization checks on Django views and ViewSets.

This dataclass centralizes all authorization settings needed to protect API endpoints with ReBAC checks. It supports multiple authorization strategies including object-level permission checks, filtered list queries, and custom action-based relations.

Attributes:

Name	Type	Description
`object_type`	`str`	The ReBAC type name for objects managed by this view (e.g., "document", "workspace"). Must match the type used in your schema and model configurations.
`list_relation`	`str \| None`	The relation required specifically to list objects (GET /api/docs/). If omitted, the framework safely falls back to using `read_relation`.
`disable_list_filter`	`bool`	A strict boolean flag to explicitly bypass ReBAC filtering on list endpoints. Defaults to False.
`read_relation`	`str \| None`	The relation required to view/list objects (e.g., "can_read_document"). Set to None to skip read authorization checks.
`update_relation`	`str \| None`	The relation required to modify existing objects (e.g., "can_update"). Checked on PUT/PATCH requests. Set to None to skip checks.
`delete_relation`	`str \| None`	The relation required to remove objects (e.g., "can_delete"). Checked on DELETE requests. Set to None to skip checks.
`lookup_header`	`str \| None`	An optional HTTP header name (e.g., "HTTP_X_CONTEXT_ORG_ID") used to extract the target object ID statelessly, bypassing database lookups.
`lookup_url_kwarg`	`str \| None`	An optional URL kwarg name (e.g., "org_id") used to extract the target object ID from the router statelessly.
`create_scope_type`	`str \| None`	For POST/creation requests, the type of the parent object that must exist (e.g., "folder"). Requires `create_scope_field` and `create_relation` to also be set.
`create_scope_field`	`str \| None`	The Django model field containing the parent object's ID. Extracted from the request data to build the parent object reference.
`create_relation`	`str \| None`	The permission required on the parent object to allow creation (e.g., "can_add_items"). Checked before allowing object creation.
`action_relations`	`dict[str, str]`	Mapping of custom ViewSet action names to ReBAC permissions. Keys must match the action names in your ViewSet's `@action` decorators.

Raises:

Type	Description
`ValueError`	If `create_scope_type`, `create_scope_field`, and `create_relation` are partially defined (all or none must be provided).

2. Model Configuration

The RebacModelConfig dataclass acts as a translation layer. It reads soft-reference identifiers (like UUIDs) from your Django Model instances and converts them into strict Zanzibar Tuples using the Transactional Outbox pattern.

The Golden Rule: Assign Roles, Not Permissions

When configuring a model's creators or parents, you must only assign base Roles (e.g., owner, editor). Models should never directly grant atomic permissions.

Complete configuration for synchronizing a Django model with ReBAC relationship tuples.

This is the primary configuration class that defines how a Django model maps to ReBAC objects, relationships, and ownership patterns. The configuration drives automatic tuple creation/deletion when model instances are created, updated, or deleted.

Attributes:

Name	Type	Description
`object_type`	`str`	The ReBAC type name for this Django model (e.g., "document", "folder"). This should match your schema's type definitions exactly.
`parents`	`list[RebacParentConfig]`	List of parent relationship configurations that establish structural access patterns. Each RebacParentConfig defines how this object relates to parent objects, enabling inherited permissions.
`creators`	`list[RebacCreatorConfig]`	List of creator relationship configurations that automatically grant ownership roles to subjects who create instances. Each RebacCreatorConfig defines which field represents the creator and what role to assign.

Example

RebacModelConfig(
    object_type="document",
    parents=[
        RebacParentConfig(
            relation="folder",
            parent_type="folder",
            local_field="folder_id"
        )
    ],
    creators=[
        RebacCreatorConfig(
            relation="editor",
            local_field="creator_id"
        )
    ]
)

Raises:

Type	Description
`ValueError`	If `object_type` is empty, or if duplicate relations are defined across parents and creators (which would cause tuple conflicts).

Defines how a child object relates to its parent in the ReBAC authorization graph.

This configuration establishes a "Structural Link" between objects, enabling inherited access patterns. For example, a "folder" belongs to an "organization", allowing subjects with access to the organization to automatically inherit access to the folder based on your ReBAC schema.

Attributes:

Name	Type	Description
`relation`	`str`	The structural relationship name in the ReBAC model (e.g., "organization", "parent"). This must match a relation defined in your schema.
`parent_type`	`str`	The ReBAC object type of the parent entity (e.g., "organization", "workspace"). The format should match your type definitions.
`local_field`	`str`	The Django model field name that stores the parent's primary key. This field should be a ForeignKey or contain the parent object's ID.

Example

RebacParentConfig(
    relation="organization",
    parent_type="organization",
    local_field="org_id"
)

Defines the ownership role assigned to a subject when they create an object.

This configuration automatically grants the creator specific roles on the object they create, implementing the "creator owns their content" pattern. The relationship is established at creation time via Django's save lifecycle.

Attributes:

Name	Type	Description
`relation`	`str`	The Role name in the ReBAC model representing ownership (e.g., "owner", "editor", "author"). This must match a role defined in your schema that accepts the subject type.
`local_field`	`str`	The Django model field name that stores the creator's subject ID. Typically, this is a ForeignKey to the User model or a UUID field named "creator_id", "owner_id", etc.
`user_type`	`str`	The ReBAC type for the creator (defaults to "user"). Override this if the creator is a machine role, API key, or team.

Example

RebacCreatorConfig(
    relation="editor",
    local_field="creator_id"
)

🛡️ Configurations Reference

Configuration Defaults

DEFAULTS module-attribute

1. View Configuration

2. Model Configuration

DEFAULTS `module-attribute`