Google Auth ^{[ Django ]}

• Official Documentation
• Demo Integration / Samples

✨ Feature Spotlight — 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 — instead of dumping them on a generic dashboard.

• 🎯 Return-to-origin redirection — nested & dynamic Google authentication from anywhere in your app.
• 🧩 SPA-ready (React/Vue) — 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.

👉 Learn more: Redirection Schemes

How is it different from allauth / social-auth?

django-allauth and python-social-auth are full authentication frameworks — they bind to Django's User model and persist accounts and tokens in the database (their own models + migrations). That's what powers real user accounts, many providers, email/password, and account linking.

django-gauth fills a deliberately narrower niche: it keeps Google identity in the session only — no User model, no migrations, no ORM token store — and exposes it as a JSON /gauth/session probe with a configurable session policy.

	django-gauth	allauth / social-auth
Requires a Django User	❌ session-only	✅
DB models + migrations	❌ none	✅
Providers	Google only	Many
Account management (signup, email, linking)	❌	✅
Footprint	one small app	full framework

• Reach for allauth / social-auth when you want real user accounts — a User row per person, multiple providers, email/password, or account linking.
• Reach for django-gauth when you just need to answer "is this request a signed-in Google user?" for an SPA or API backend — without adopting an auth framework, a User table, or migrations.

ℹ️ 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.

✨ Feature Spotlight — 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 that catches misconfig.
• 🔌 Dual-mode guards — gauth_required / GauthRequiredMixin work with or without integration.

👉 Availability: 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.

👉 Learn more: Django User Integration

Developer Zone

Developer README

• New here? See why pdm.lock exists.

Installation

from GitHub :

# Editable Installation (for Development)
pip install -e git+https://github.com/xavient/django-gauth.git#egg=django_gauth

# Main Branch (Latest Version)
pip install git+https://github.com/xavient/django-gauth.git

from PyPi

pip install django-gauth

from test PyPi

pip install -i https://test.pypi.org/simple/ 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. Versions 0.2.1+ pin this for you.

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 : usually 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 same 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 only !!

NOTE :

---

Important Points ^{To Be Noted}

#1.

for production applications , that are working on https , must ensure the following settings for django to be https aware :

USE_X_FORWARDED_HOST = True
SECURE_PROXY_SSL_HEADER = ('HTTP_X_FORWARDED_PROTO', 'https')

Your reverse proxy should add the X-Forwarded-Proto: https header to requests forwarded to Django. Configure your reverse proxy to set X-Forwarded-Proto header ( Nginx Example ):

server {
    listen 80;
    server_name yourdomain.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl;
    server_name yourdomain.com;

    # ... SSL configuration ...

    location / {
        proxy_pass http://your_django_app_server;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto https; # Crucial line
    }
}

#2.

django_gauth app package serves a landing page for authentication , which will be served from within your application server when you include django_gauth in your project and use . Hence you have to take care of the static content rendring in your django project when you are deploying it on server .

• although no extra javascript or html file is included as static content , but there are two logo images that are displayed on navbar of landing page

  1. Organisation logo on the left
  2. placeholder image in case of no profile picture

  For these two , your project must manage the static content stratagy on production environments

  The steps for managing static content in a django project - Refer the documentation for collecting the static files to a central folder - Then you'll have to mount the folder path for static files folder staticfiles to a volume location in your docker container - Then you'll have to whitelist this path on /static/ route publicly on either your ingress file or nginx.conf file if you are using Nginx .

  Although , if you don't want the defaut logo ( which is very likely ) and placeholder image or you don't want to do the above mentioned arrangement for staticfile in your project, you can also configure them to your own via your settings . There is a settings variable which is set in following fashion :

  Setting own static content

  DJANGO_GAUTH_UI_CONFIG={
      "index":{
          "navbar":{
              "logo":"<hosted-url-for-your-organisation-logo>",
              "profile_picture_absence":"<hosted-url-for-the-placeholder-image>"
          }
      }
  }