Metadata-Version: 2.4
Name: django-azuread-token-validator
Version: 0.1.2
Summary: Django middleware to validate Azure AD JWT tokens and enrich requests with user data
Author: Marlon Passos
Author-email: marlonjbpassos@gmail.com
Keywords: django azure ad jwt middleware authentication sso drf
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: Django
Classifier: Framework :: Django :: 3.2
Classifier: Framework :: Django :: 4.0
Classifier: Framework :: Django :: 4.1
Classifier: Framework :: Django :: 4.2
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Internet :: WWW/HTTP :: Session
Classifier: Topic :: Security
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Django>=3.2
Requires-Dist: PyJWT>=2.0
Requires-Dist: requests>=2.25
Requires-Dist: cryptography>=40.0.0
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: keywords
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary


# django-azuread-token-validator (azvalidator)

Django middleware for validating JWT tokens issued by Azure AD and enriching the request object with additional user profile information. This middleware is designed exclusively for use with Django REST Framework (DRF) to securely and seamlessly protect API routes.

---

## Installation

You can install the package via pip directly from PyPI (or your private repository):

```bash
pip install django-azuread-token-validator
```

Or, if you prefer to install it from the local source code:

```bash
git clone https://github.com/MarlonPassos/django-azuread-token-validator.git
cd django-azuread-token-validator
pip install .
```

---

## Middleware Configuration

### 1. Add the middleware to your `settings.py`

Include the full path of the middleware in the `MIDDLEWARE` list:

```python
MIDDLEWARE = [
    # Default Django middlewares...
    'django.middleware.security.SecurityMiddleware',
    'django.contrib.sessions.middleware.SessionMiddleware',
    'django.middleware.common.CommonMiddleware',

    # Azure AD validation middleware
    'azvalidator.middleware.AzureADTokenValidatorMiddleware',  # adjust the path as needed

    # Other middlewares...
]
```

### 2. Environment variables for configuration

In `settings.py`, configure the following variables:

```python
# Azure AD JWKS endpoint URL (to fetch public verification keys)
AZURE_AD_JWKS_URL = "https://login.microsoftonline.com/<tenant_id>/discovery/keys"

# JWKS cache timeout in seconds (default: 3600)
AZURE_AD_CACHE_TIMEOUT = 3600

# Enable or disable token signature verification (default: True)
AZURE_AD_VERIFY_SIGNATURE = True

# Expected JWT token issuer (default: https://login.microsoftonline.com/<tenant_id>/v2.0)
AZURE_AD_ISSUER_URL = "https://login.microsoftonline.com/<tenant_id>/v2.0"

# Expected audience identifier in the JWT token (usually the client_id or App ID URI)
AZURE_AD_AUDIENCE = "api://<client_id>"

# List of accepted JWT algorithms (default: ["RS256"])
AZURE_AD_ALGORITHMS = ["RS256"]

# Default username for Client Credentials tokens (app-to-app)
AZURE_AD_DEFAULT_APP_USERNAME = "app"

# Default role for Client Credentials tokens
AZURE_AD_DEFAULT_APP_ROLE = "AppRole"

# External service URL to fetch additional user information (optional)
AZURE_AD_AUX_USERINFO_SERVICE_URL = "https://api.example.com/userinfo"

# Bearer token for authenticating with the additional service (optional)
AZURE_AD_AUX_USERINFO_SERVICE_TOKEN = "secret-token"

# Timeout for requests to the additional service in seconds (default: 10)
AZURE_AD_AUX_USERINFO_SERVICE_TIMEOUT = 10

# Mapping between fields returned by the additional service and request attributes
# Format: {"service_field": "request_attribute_name"}
AZURE_AD_AUX_USERINFO_MAPPING = {
    "department": "azure_department",
    "department_number": "azure_department_number",
    "company": "azure_company",
    "employee_number": "azure_employee_role",
}
```

### 3. Usage in views

To enable token validation in a DRF view or viewset, set the attribute `azure_authentication = True` in the view class:

```python
from rest_framework import viewsets, routers
from rest_framework.response import Response


class DummyViewSet(viewsets.ViewSet):
    azure_authentication = True

    def list(self, request):
        return Response(
            {
                "user": getattr(request, "azure_username", None),
                "roles": getattr(request, "azure_roles", []),
                "email": getattr(request, "azure_email", None),
            }
        )
```

---

## Application Authentication in Azure AD

The package provides a utility function to authenticate applications in Azure AD using the `client_credentials` flow. This function is useful for scenarios where an application needs to communicate with another protected application.

### Function: `generate_app_azure_token`

The `generate_app_azure_token` function returns a valid access token for the application. The token is cached and automatically renewed upon expiration.

#### Example usage:

```python
from azvalidator.utils import generate_app_azure_token

# Get the access token
access_token = generate_app_azure_token()
print(f"Access token: {access_token}")
```

Ensure the following variables are configured correctly for the function to work:

```python
# Azure AD authentication endpoint URL
AZURE_AD_URL = "https://login.microsoftonline.com"

# Azure AD Tenant ID
AZURE_AD_TENANT_ID = "<tenant_id>"

# Grant type (must be "client_credentials")
AZURE_AD_APP_SIIGO_GRANT_TYPE = "client_credentials"

# Client ID registered in Azure AD
AZURE_AD_APP_SIIGO_CLIENT_ID = "<client_id>"

# Client secret registered in Azure AD
AZURE_AD_APP_SIIGO_CLIENT_SECRET = "<client_secret>"

# Required access scope
AZURE_AD_APP_SIIGO_SCOPE = "https://graph.microsoft.com/.default"
```

---

## External Service for Additional User Information

### Purpose

The middleware can enrich the `request` object with extra data fetched from an external service, in addition to the basic Azure AD token data.

### How it works

- After validating the token, the middleware makes an HTTP GET request to:

  ```
  {AZURE_AD_AUX_USERINFO_SERVICE_URL}/{username}/
  ```

- If configured, it sends a Bearer token via the `Authorization` header for authentication.

- The external service must return a JSON response with the additional user data.

### External service specifications

- **Endpoint:** REST, accepting GET requests at the URL `/username/`
- **Authentication:** Optional via Bearer Token
- **Response:** JSON with fields containing user data (example below)

Example JSON response:

```json
{
  "department": "Information Technology",
  "department_number": "123",
  "company": "MyCompany",
  "employee_number": "456789",
  "other_field": "value"
}
```

### Mapping data to the `request`

The dictionary `AZURE_AD_AUX_USERINFO_MAPPING` defines which fields from the JSON response will be added to the `request` object and under which names, for example:

```python
AZURE_AD_AUX_USERINFO_MAPPING = {
    "department": "azure_department",
    "department_number": "azure_department_number",
    "company": "azure_company",
    "employee_number": "azure_employee_role",
}
```

### Timeout and Resilience

- Request timeout is configurable via `AZURE_AD_AUX_USERINFO_SERVICE_TIMEOUT` (default: 10 seconds).
- If the service is unavailable or an error occurs, the middleware logs the failure and continues the request without additional data.

---

## Tests

The package's test suite covers the main middleware scenarios to ensure robustness:

- Validation of a valid token with the `preferred_username` claim.
- Rejection of a token without the `preferred_username` claim (returns HTTP 401).
- Rejection of a token with an invalid signature.
- Rejection of an expired token.
- Handling of Client Credentials tokens (app-to-app).
- Enrichment of the request with additional information via an external service.
- Appropriate responses with status 401 or 500 based on detected errors.

### Basic test example:

```bash
cd tests && pip install -r requirements.txt && python manage.py test
```
