django-social-auth-rest

Social login for Django REST Framework - with account linking, JWT tokens, and room to grow.

What This Does

django-social-auth-rest lets your users sign in with their social accounts (Google, GitHub) and returns JWT tokens your frontend can use right away. It also handles connecting and disconnecting those social accounts after the fact.

Currently supported providers: Google, GitHub
More providers are coming soon.

Features

Sign in with Google or GitHub - get back JWT access and refresh tokens
Link or unlink social accounts from an existing user profile
See which providers a user has connected
CSRF protection via signed OAuth state tokens (GitHub flow)
Rate limiting on all auth endpoints
Optional support for soft-deleted user accounts
Signals you can hook into for things like welcome emails or analytics

Requirements

Python 3.12+
Django 5.0+
Django REST Framework 3.15+

The following packages are installed automatically:

djangorestframework-simplejwt
google-auth
requests

Installation

pip install django-social-auth-rest

Setup

1. Add to `INSTALLED_APPS`

# settings.py
INSTALLED_APPS = [
    # ...
    "rest_framework",
    "django_social_auth_rest",
]

2. Set up JWT authentication

# settings.py
REST_FRAMEWORK = {
    "DEFAULT_AUTHENTICATION_CLASSES": (
        "rest_framework_simplejwt.authentication.JWTAuthentication",
    ),
}

3. Configure JWT tokens

# settings.py
from datetime import timedelta

SIMPLE_JWT = {
    "AUTH_HEADER_TYPES": ("Bearer",),
    "ACCESS_TOKEN_LIFETIME": timedelta(minutes=60),
    "REFRESH_TOKEN_LIFETIME": timedelta(days=1),
    "ROTATE_REFRESH_TOKENS": True,
    "BLACKLIST_AFTER_ROTATION": True,
}

4. Add provider credentials

Add credentials only for the providers you want to use. Providers without credentials are automatically disabled - their endpoints will not be available.

# settings.py

# GitHub (requires both values)
GITHUB_CLIENT_ID = "your-github-client-id"
GITHUB_CLIENT_SECRET = "your-github-client-secret"

# Google (requires only the client ID)
GOOGLE_CLIENT_ID = "your-google-client-id"

# add more providers here as needed

See the Provider Guides section for where to get these credentials.

5. Register the URLs

Include the base URL module plus each provider you want to enable:

# urls.py
from django.urls import path, include

urlpatterns = [
    path("api/social-auth/", include("django_social_auth_rest.urls")),
    path("api/social-auth/", include("django_social_auth_rest.urls.github")),
    path("api/social-auth/", include("django_social_auth_rest.urls.google")),
    # add more providers here as needed
]

You only need to include a provider’s URL module if you’re using that provider. See the Provider Guides section for details on each provider’s endpoints.

6. Run migrations

python manage.py migrate

Optional Settings

These settings have sensible defaults and do not need to be changed unless you have specific requirements.

Setting	Default	What It Does
`SOCIAL_AUTH_THROTTLE_RATE`	`"10/minute"`	Limits how many auth requests a user can make per minute
`SOCIAL_AUTH_STATE_SALT`	`"social-auth-state-salt"`	Salt value used to sign OAuth state tokens - change this in production
`SOCIAL_AUTH_STATE_MAX_AGE`	`300`	How long (in seconds) a state token stays valid before expiring
`SOCIAL_AUTH_USER_DELETED_FIELD`	`None`	Name of a boolean field on your user model that marks soft-deleted accounts

Provider Guides

GitHub

Getting your credentials

Go to your GitHub account → Settings → Developer Settings → OAuth Apps
Click New OAuth App
Fill in the application details and set your Authorization callback URL
Copy the Client ID and generate a Client Secret

Settings

# settings.py
GITHUB_CLIENT_ID = "your-github-client-id"
GITHUB_CLIENT_SECRET = "your-github-client-secret"

Urls

# urls.py
from django.urls import path, include

urlpatterns = [
    path("api/social-auth/", include("django_social_auth_rest.urls.github")),
]

How it works

GitHub uses the standard OAuth 2.0 authorization code flow. Your frontend redirects the user to GitHub, which then redirects back with a temporary code. That code is sent to your backend to complete the login.

A signed state token is used to prevent CSRF attacks - your frontend must request one before starting the flow and include it throughout.

Frontend requests a state token  →  GET /api/social-auth/github/state/
Frontend redirects user to GitHub with client_id and state token
User authorizes on GitHub, gets redirected back with a code and state
Frontend sends code + state to  POST /api/social-auth/github/login/
Backend validates the state, exchanges the code, and returns JWT tokens

Endpoints

Get a state token (required before starting the OAuth flow)

GET /api/social-auth/github/state/

Response:

{
  "state": "<SIGNED_STATE_TOKEN>"
}

Login

POST /api/social-auth/github/login/
Content-Type: application/json

{
  "code": "<AUTHORIZATION_CODE>",
  "state": "<SIGNED_STATE_TOKEN>"
}

Response:

{
  "access": "<JWT_ACCESS_TOKEN>",
  "refresh": "<JWT_REFRESH_TOKEN>"
}

Link account (requires authentication)

POST /api/social-auth/github/link/
Authorization: Bearer <JWT_ACCESS_TOKEN>
Content-Type: application/json

{
  "code": "<AUTHORIZATION_CODE>",
  "state": "<SIGNED_STATE_TOKEN>"
}

Returns 204 No Content on success.

Unlink account (requires authentication)

POST /api/social-auth/github/unlink/
Authorization: Bearer <JWT_ACCESS_TOKEN>

Returns 204 No Content on success.

Google

Getting your credentials

Go to Google Cloud Console
Create a project (or select an existing one)
Navigate to APIs & Services → Credentials
Click Create Credentials → OAuth 2.0 Client ID
Copy the Client ID

Settings

# settings.py
GOOGLE_CLIENT_ID = "your-google-client-id"

Urls

# urls.py
from django.urls import path, include

urlpatterns = [
    path("api/social-auth/", include("django_social_auth_rest.urls.google")),
]

How it works

Google uses an ID token flow. Your frontend handles the Google sign-in and receives an ID token from Google. It sends that token to your backend, which validates it and issues JWT tokens.

User signs in with Google on your frontend
Frontend receives a Google ID token
Frontend sends the token to POST /api/social-auth/google/login/
Backend validates the token with Google
Backend returns JWT access and refresh tokens

Endpoints

Login

POST /api/social-auth/google/login/
Content-Type: application/json

{
  "token": "<GOOGLE_ID_TOKEN>"
}

Response:

{
  "access": "<JWT_ACCESS_TOKEN>",
  "refresh": "<JWT_REFRESH_TOKEN>"
}

Link account (requires authentication)

POST /api/social-auth/google/link/
Authorization: Bearer <JWT_ACCESS_TOKEN>
Content-Type: application/json

{
  "token": "<GOOGLE_ID_TOKEN>"
}

Returns 204 No Content on success.

Unlink account (requires authentication)

POST /api/social-auth/google/unlink/
Authorization: Bearer <JWT_ACCESS_TOKEN>

Returns 204 No Content on success.

Linked Accounts

Returns a list of all enabled providers and whether the current user has connected each one.

Requires authentication.

GET /api/social-auth/linked-accounts/
Authorization: Bearer <JWT_ACCESS_TOKEN>

Response:

{
  "providers": [
    {
      "label": "Google",
      "is_linked": true
    },
    {
      "label": "GitHub",
      "is_linked": false
    }
    // more providers as configured
  ]
}

Soft-Deleted Accounts

If your app uses soft deletion (marking users as deleted rather than removing them from the database), you can block deleted accounts from signing in.

Set SOCIAL_AUTH_USER_DELETED_FIELD to the name of the boolean field on your user model:

# settings.py
SOCIAL_AUTH_USER_DELETED_FIELD = "is_deleted"

Example user model:

class User(AbstractUser):
    is_deleted = models.BooleanField(default=False)

When this is configured, any user with is_deleted = True will be blocked from logging in, linking, or creating a new account through social auth.

Signals

The package sends Django signals for key events. You can connect to these to run your own code - for example, sending a welcome email when a new user registers.

Signal	When it fires
`new_user_registered`	A new account is created for the first time via social auth
`login_successful`	A user successfully signs in
`link_account_successful`	A social account is linked to a user
`unlink_account_successful`	A social account is removed from a user

All signals include these keyword arguments: request, user, provider.

Example:

from django.dispatch import receiver
from django_social_auth_rest.signals import new_user_registered

@receiver(new_user_registered)
def on_new_user(sender, request, user, provider, **kwargs):
    print(f"New user {user.email} joined via {provider}")
    # send welcome email, create profile, etc.

Contributing

Contributions are welcome. If you find a bug or want to suggest an improvement, please open an issue first so we can discuss it.

More authentication providers are planned - if you’d like to add one, open an issue to coordinate.

License

MIT - see LICENSE for details.

This site is open source. Improve this page.

django-social-auth-rest

What This Does

Features

Requirements

Installation

Setup

1. Add to INSTALLED_APPS

2. Set up JWT authentication

3. Configure JWT tokens

4. Add provider credentials

5. Register the URLs

6. Run migrations

Optional Settings

Provider Guides

GitHub

Getting your credentials

Settings

Urls

How it works

Endpoints

Google

Getting your credentials

Settings

Urls

How it works

Endpoints

Linked Accounts

Soft-Deleted Accounts

Signals

Contributing

License

1. Add to `INSTALLED_APPS`