---

#  Django Org Authz

A reusable Django app for managing **roles**, **permissions**, and **organization-based access control** (RBAC).
Built for **multi-tenant systems** to simplify role management and make authorization consistent across projects.

---

##  Features

* 🔹 **Organization-aware roles** – manage users and permissions scoped by organization
* 🔹 **Fine-grained permissions** – control access to models, routes, or actions
* 🔹 **Plug-and-play setup** – install, migrate, and use in minutes
* 🔹 **REST API ready** – works seamlessly with Django REST Framework
* 🔹 **Auth-flexible** – supports both **JWT** and **session-based** authentication

---

##  Use Case

Ideal for SaaS or multi-tenant Django applications where each organization has its own users, roles, and access levels.

---

##  Installation

```bash
pip install django-org-authz
```

Then add it to your Django settings:

```python
INSTALLED_APPS = [
    ...,
    'rest_framework',
    'org_authz',
]
```

---

##  Configuration

Ensure your Django REST Framework settings support both session and JWT authentication (optional but recommended):

```python
REST_FRAMEWORK = {
    'DEFAULT_AUTHENTICATION_CLASSES': [
        'rest_framework.authentication.SessionAuthentication',
        'rest_framework_simplejwt.authentication.JWTAuthentication',
    ],
    'DEFAULT_PERMISSION_CLASSES': [
        'rest_framework.permissions.IsAuthenticated',
    ],
}
```

Then apply migrations:

```bash
python manage.py migrate
```

---

##  Models Overview

| Model              | Description                                       |
| ------------------ | ------------------------------------------------- |
| **Organization**   | Represents a tenant or company                    |
| **Role**           | Defines a role within an organization             |
| **Permission**     | Defines an action or capability                   |
| **RolePermission** | Connects roles to permissions                     |
| **UserRole**       | Connects users to roles in specific organizations |

---

##  API Endpoints

Once installed, the package registers the following routes (using DRF’s DefaultRouter):

| Endpoint              | Description           |
| --------------------- | --------------------- |
| `/api/organizations/` | Manage organizations  |
| `/api/roles/`         | Manage roles          |
| `/api/permissions/`   | Manage permissions    |
| `/api/user-roles/`    | Assign users to roles |

---

##  Usage Example

### Assign a Role to a User

```python
from org_authz.models import Organization, Role, UserRole
from django.contrib.auth.models import User

org = Organization.objects.create(name="Acme Inc", slug="acme")
user = User.objects.create_user(username="john", password="secret")
role = Role.objects.create(name="Manager", organization=org)

UserRole.objects.create(user=user, role=role, organization=org)
```

### Protect a View with a Permission

```python
from org_authz.decorators import require_permission

@require_permission("can_view_reports")
def reports_view(request):
    ...
```

This works for both **session-authenticated** and **JWT-authenticated** users.

---

##  Contributing

Contributions, feature requests, and feedback are welcome!
To contribute:

```bash
git clone https://github.com/<your-username>/django-org-authz
cd django-org-authz
pip install -r requirements.txt
python manage.py test
```

---

##  License

This project is licensed under the **MIT License** – free for commercial and personal use.

---

##  Author

**Victor Mwendwa**
 Full Stack Developer 
 [vicmwe184@gmail.com](mailto:vicmwe184@gmail.com)

---