Skip to content

Add concise quickstart section to Django documentation #364

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
nijel merged 4 commits into from
Nov 10, 2025
Merged

Add concise quickstart section to Django documentation #364

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
474fb7f
Initial plan
Copilot Nov 10, 2025
ced10cc
Add Django quickstart/tutorial guide to documentation
Copilot Nov 10, 2025
fb55a54
Update Django docs with concise quickstart section instead of separat…
Copilot Nov 10, 2025
bc7d8c3
Remove confusing common settings examples from quickstart
Copilot Nov 10, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
69 changes: 69 additions & 0 deletions docs/configuration/django.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,75 @@ And for MongoEngine_ ORM::
$ pip install social-auth-app-django-mongoengine


Quickstart
----------

This quickstart covers the essential configuration to get social authentication working in your Django project.

**1. Add to INSTALLED_APPS**::

INSTALLED_APPS = (
...
'social_django',
)

**2. Configure authentication backends** (example for Google OAuth2)::

AUTHENTICATION_BACKENDS = (
'social_core.backends.google.GoogleOAuth2',
'django.contrib.auth.backends.ModelBackend', # Keep for username/password login
)

**3. Add OAuth credentials to settings.py**:

This is where you configure your ``client_id``, ``client_secret``, and ``scope`` for each provider::

# Google OAuth2
SOCIAL_AUTH_GOOGLE_OAUTH2_KEY = 'your-client-id.apps.googleusercontent.com'
SOCIAL_AUTH_GOOGLE_OAUTH2_SECRET = 'your-client-secret'
SOCIAL_AUTH_GOOGLE_OAUTH2_SCOPE = [
'https://www.googleapis.com/auth/userinfo.email',
'https://www.googleapis.com/auth/userinfo.profile',
]

For other providers, the pattern is ``SOCIAL_AUTH_<PROVIDER>_KEY``, ``SOCIAL_AUTH_<PROVIDER>_SECRET``, and ``SOCIAL_AUTH_<PROVIDER>_SCOPE``. See :doc:`/backends/index` for provider-specific settings.

.. warning::
Never commit credentials to version control. Use environment variables instead::

import os
SOCIAL_AUTH_GOOGLE_OAUTH2_KEY = os.environ.get('GOOGLE_OAUTH2_KEY')
SOCIAL_AUTH_GOOGLE_OAUTH2_SECRET = os.environ.get('GOOGLE_OAUTH2_SECRET')

**4. Add URLs to urls.py**::

urlpatterns = [
...
path('', include('social_django.urls', namespace='social')),
]

**5. Configure redirect URLs**::

LOGIN_URL = '/login/'
LOGIN_REDIRECT_URL = '/'
LOGOUT_REDIRECT_URL = '/'

**6. Run migrations**::

python manage.py migrate

**7. Add login link in template**::

<a href="{% url 'social:begin' 'google-oauth2' %}">Login with Google</a>

.. note::
**Database considerations**: SQLite has field length limitations that can cause issues. For production, use PostgreSQL or MySQL. If using MySQL InnoDB or SQLite, add::

SOCIAL_AUTH_UID_LENGTH = 223

For additional configuration options, see :doc:`/configuration/settings`.


Register the application
------------------------

Expand Down