django-gauth 0.3.1

A Django app for providing the Google's discovery based Oauth2 authentication mechanism is HTTP/HTTPS oriented Django Servers/Projects.

Google Auth ^{[ Django ]}

Official Documentation Demo Integration / Samples

Why django-gauth?

Google sign-in for Django in 5 minutes — without the django-allauth configuration maze.

django-gauth does exactly one thing well: add Google OAuth2 login to an HTTP/HTTPS Django project, with a working landing page included — no multi-provider abstractions, no sprawling configuration, just the Google flow, clearly documented.

	django-gauth	django-allauth	Roll-your-own
Setup for just Google	⚡ Minimal (3 settings + 1 URL include)	🧩 Broad, multi-step config	🛠️ Manual OAuth wiring
Built-in login page	✅ Ships a landing page	➖ Bring your own templates	❌ Build it yourself
Nested & dynamic auth (return-to-origin)	✅ Built-in schemes	➖ DIY	❌ DIY
Session lifecycle (auto-refresh + revoking logout)	✅ Built-in, configurable policy	➖ DIY	❌ DIY
Scope	🎯 Google OAuth2 only	🌐 Many providers	🎯 Whatever you build
Needs a User model + migrations	✅ No — session-only	➖ Yes — DB-backed	🛠️ Up to you
Learning curve	📉 Low	📈 Higher (large surface)	⚠️ Easy to get OAuth subtly wrong
Typed & tested	✅ Type hints + 100% coverage	✅ Mature	➖ Up to you

Reach for django-allauth or python-social-auth when you need real user accounts — a User row per person, many providers, account linking, or email workflows. Reach for django-gauth when you just need to answer "is this a signed-in Google user?" for an SPA or API backend — session-only, no User model, no migrations — with a JSON /gauth/session probe and a configurable session policy.

ℹ️ Transparent refresh and SPA support aren't unique (social-auth has a refresh helper; allauth has a Headless API). django-gauth's contribution is delivering them in that stateless, User-model-free setting — where you'd otherwise wire it by hand.

✨ Standout feature — Nested & Dynamic Auth

Modern UIs place the "Sign in with Google" button inline — inside modals, deep within a workflow, or when a session expires mid-task. django-gauth brings users back to the exact page (and state) they authenticated from, out of the box — no more dumping them on a generic dashboard.

• 🎯 Return-to-origin redirection — send users straight back to where they started.
• 🧩 SPA-ready — first-class support for React/Vue via query-parameter or header schemes (PRESERVE_ORIGIN_QP / PRESERVE_ORIGIN_HP), with redirect or json responses.
• 🔒 Safe by default — origins are same-origin validated to block open-redirect attacks.

📌 Availability: This feature is available in django-gauth >= 0.3.0.

👉 Read about Redirection Schemes →

✨ Standout feature — Django User Integration (opt-in)

Want request.user, @login_required, and admin login backed by Google — without an extra User model, a token table, or migrations? Flip one switch and django-gauth maps Google identities onto your project's existing AUTH_USER_MODEL:

• 👤 Real request.user — @login_required, LoginRequiredMixin, and the Django admin just work.
• 🧩 Zero django-gauth migrations — get-or-create on your existing auth_user; no models of our own.
• 🛡️ Safe by default — verified-email gated, unusable passwords, and a manage.py check for misconfig.
• 🔌 Dual-mode guards — gauth_required / GauthRequiredMixin work with or without integration.

📌 Availability: This feature is available in django-gauth >= 0.3.0.

⚠️ Limitation: The view-protection guards (gauth_required / GauthRequiredMixin) support Django native views only — they are not compatible with Django REST Framework views (APIView, ViewSet, @api_view). DRF-native adapters are planned; until then, protect DRF endpoints with DRF's own authentication/permission classes. See the troubleshooting notes.

👉 Read about Django User Integration →

Installation

Source	Command
GitHub	pip install -e git+https://github.com/masterPiece93/django-gauth.git#egg=django_gauth
PyPi	pip install django-gauth

📌 Compatibility note: If you must stay on django-gauth < 0.2.1, pin google-auth-oauthlib<1.3.0,>=1.0.0 in your project requirements to avoid PKCE-related OAuth failures. Higher Versions 0.2.1+ pin this for you, so no need to worry with them!

Quickstart

1. add the app name : django_gauth in INSTALLED_APPS entry of you project ( in settings.py file )

2. add required configuration variables ( in settings.py file )

   # settings.py
   GOOGLE_CLIENT_ID= env("GOOGLE_CLIENT_ID")           # << set according to your oauth2 client
   GOOGLE_CLIENT_SECRET= env("GOOGLE_CLIENT_SECRET")   # << set according to your oauth2 client
   GOOGLE_AUTH_FINAL_REDIRECT_URL= None        # defaults to `<host>/gauth/`
   CREDENTIALS_SESSION_KEY_NAME= "credentials" # defaults to `credentials`
   STATE_KEY_NAME= "oauth_state"               # defaults to `oauth_state`
   SCOPE= [
       "https://www.googleapis.com/auth/userinfo.email"    # always preffered
       ,"https://www.googleapis.com/auth/userinfo.profile" # always preffered
       ,"openid"                                           # always preffered
       ,"https://www.googleapis.com/auth/drive"            # based on your usage
   ]
   os.environ['OAUTHLIB_INSECURE_TRANSPORT'] = '1'         # strictly for local-development only
   

   • os.environ['OAUTHLIB_INSECURE_TRANSPORT'] = '1' directs the server to accept in-secure (http) connections .

3. configure auth urls ( in urls.py file of root )

   # urls.py
   from django.contrib import admin
   from django.urls import path, include
   
   urlpatterns = [
       path('admin/', admin.site.urls),
       path('gauth/', include('django_gauth.urls')),
       
       # add your other app's urls
       # ...
   
   ]
   

4. now run your project server

   • once your server is up & running , navigate to .../gauth, this is the master interface ( default landing page )
   • click on Authenticate button to launch Google Oauth2 Login .
   • just follow the flow you are directed to .
   • post authentication , you'll be redirected back to .../gauth

• NOTE : useually all servers ( wsgi, asgi, uWsgi) runs default on http://127.0.0.1:PORT/ , hence always take care to set the redirect endpoints in your google oauth2 client app in accordance with 127.0.0.1 , don't mistake to consider localhost , 0.0.0.0 and 127.0.0.1 as the same thing while dealing with redirect uri's .
  • For example : suppose you have set http://localhost:PORT/gauth/google-callback as your redirect uri , then take note of running your django app on localhost:PORT only !!

---

Changelog

See CHANGELOG.md for the full release history and notable changes in each version.

Releases

See Github Releases for the details of each release in each version .