Metadata-Version: 2.4
Name: django-sso-oauth
Version: 1.0.1
Summary: Django OAuth authentication middleware for admin interface
Author-email: Hiep Ho Minh <hiephm@gmail.com>
License: MIT License
        
        Copyright (c) 2026 Hiep Ho Minh
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/hiephm/django-sso-oauth
Project-URL: Issues, https://github.com/hiephm/django-sso-oauth/issues
Keywords: django,oauth,sso,authentication,admin
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Web Environment
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: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
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: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Django>=3.2
Requires-Dist: requests>=2.20
Requires-Dist: PyJWT>=2.0
Dynamic: license-file

# 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
