# django-sso-oauth

Django OAuth authentication middleware for admin interface.

Replaces the default Django admin login with an OAuth 2.0 / OpenID Connect flow. After a successful OAuth exchange, the user's session is maintained by a lightweight middleware that maps the OAuth identity to a Django user.

## Requirements

- Python >= 3.6
- Django >= 3.2
- `requests`
- `PyJWT`

## Installation

```bash
pip install django-sso-oauth
```

## Configuration

### 1. Environment variables

Set the following variables in your `.env` file or environment:

| Variable | Description |
|---|---|
| `DJANGO_SSO_OAUTH_BASE_URL` | Base URL of the OAuth provider (e.g. `https://sso.example.com`) |
| `DJANGO_SSO_OAUTH_CLIENT_ID` | OAuth client ID |
| `DJANGO_SSO_OAUTH_CLIENT_SECRET` | OAuth client secret |
| `DJANGO_SSO_OAUTH_REDIRECT_URL` | Redirect URI registered with the OAuth provider (e.g. `https://yourapp.example.com/admin/oauth/redirect`) |

### 2. Add to `INSTALLED_APPS`

```python
INSTALLED_APPS = [
    ...
    "django_sso_oauth",
]
```

### 3. Add middleware

Add `OauthAdminSessionMiddleware` after `SessionMiddleware` in your `MIDDLEWARE` setting:

```python
MIDDLEWARE = [
    "django.middleware.security.SecurityMiddleware",
    "django.contrib.sessions.middleware.SessionMiddleware",
    "django_sso_oauth.middleware.OauthAdminSessionMiddleware",  # <-- add here
    ...
]
```

### 4. Wire up URLs

In your project's `urls.py`, override the default admin login and add the OAuth redirect callback:

```python
from django.contrib import admin
from django.urls import path, include
from django_sso_oauth import views as sso_views

urlpatterns = [
    path("admin/login/", sso_views.login),               # replaces default admin login
    path("admin/oauth/redirect", sso_views.oauth_redirect),  # OAuth callback
    path("admin/", admin.site.urls),
    ...
]
```

> **Important:** The `admin/login/` and `admin/oauth/redirect` paths must be declared **before** `admin.site.urls` so they take precedence.

## How it works

1. When a user visits `/admin/`, Django redirects to `/admin/login/`.
2. The `login` view redirects to the OAuth provider's authorization endpoint.
3. The provider redirects back to `/admin/oauth/redirect` with an authorization code.
4. The `oauth_redirect` view exchanges the code for an access token, decodes the JWT to extract the user's email (`upn` or `unique_name` claim), and looks up the corresponding Django user.
5. The email is stored in the session; `OauthAdminSessionMiddleware` restores the user on every subsequent request.

> The Django user must already exist in the database. User provisioning is not handled by this package.

## License

MIT
