django-sso-oauth

Django OAuth authentication for the admin interface and the frontend.

Replaces the default Django admin login with an OAuth 2.0 / OpenID Connect flow, and provides the same flow for regular (non-staff) site users. 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

pip install django-sso-oauth

Configuration

1. Environment variables

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

The three URL variables accept either a URL name (admin:index, dashboard) or an absolute path (/dashboard/). A single DJANGO_SSO_OAUTH_REDIRECT_URL is shared by both the admin and the frontend flow.

2. Add to INSTALLED_APPS

INSTALLED_APPS = [
    ...
    "django_sso_oauth",
]

3. Add middleware

Add OauthSessionMiddleware after AuthenticationMiddleware in your MIDDLEWARE setting:

MIDDLEWARE = [
    "django.middleware.security.SecurityMiddleware",
    "django.contrib.sessions.middleware.SessionMiddleware",
    "django.contrib.auth.middleware.AuthenticationMiddleware",
    "django_sso_oauth.middleware.OauthSessionMiddleware",  # <-- add here
    ...
]

The middleware only sets request.user when an SSO session is present, so ordinary Django authentication (e.g. a local superuser) keeps working alongside SSO.

4. Wire up URLs

In your project's urls.py, override the default admin login, add the frontend login/logout routes, and add the shared OAuth callback:

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_admin),            # replaces default admin login
    path("user/login/", sso_views.login_user, name="userlogin"),
    path("user/logout/", sso_views.logout_user, name="userlogout"),
    path("admin/", admin.site.urls),
    path("sso/callback/", sso_views.oauth_redirect),        # OAuth callback
    ...
]

Important: admin/login/ must be declared before admin.site.urls so it takes precedence. The sso/callback/ path must match DJANGO_SSO_OAUTH_REDIRECT_URL.

5. Frontend usage

Point Django's LOGIN_URL at the frontend login view so @login_required sends users into the SSO flow:

LOGIN_URL = "/user/login/"

@login_required appends ?next=<original path>, which is carried through the OAuth round trip and honoured on the way back, so users land on the page they originally asked for.

How it works

1. A user visiting /admin/ is redirected to /admin/login/; a user visiting a @login_required page is redirected to /user/login/.
2. The login view redirects to the OAuth provider's authorization endpoint with a signed state parameter carrying the target (admin or user) and the next URL.
3. The provider redirects back to the callback with an authorization code and the state.
4. oauth_redirect verifies the state (rejecting forged or expired ones), 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 user must exist and be active. For the admin target the user must also be is_staff; otherwise the request is rejected with 403 and no session is created.
6. The email is stored in the session; OauthSessionMiddleware restores the user on every subsequent request.
7. /user/logout/ flushes the Django session. The provider's own session is left untouched, so a subsequent login is a silent SSO re-login.

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

Upgrading from 1.x

Version 2.0 is a breaking change:

Also note:

• The callback now requires a valid signed state parameter. Since the login views generate it, no configuration change is needed — but bookmarked or replayed callback URLs will now 400.
• The middleware no longer forces request.user to AnonymousUser when there is no SSO session.
• Error responses now return their intended status code (1.x returned 200 for every error path).

Running the tests

python runtests.py

License

MIT