Registry / auth-security / social-auth-core

social-auth-core

JSON →
library5.1.0pypypi✓ verified 24d ago

social-auth-core is the foundational library for Python Social Auth, providing a flexible, decoupled mechanism for social authentication. It abstracts away the complexities of integrating OAuth, OpenID Connect, and SAML providers, enabling developers to add various social logins easily. The current version is 4.8.5, and it maintains a regular release cadence with frequent patch and minor updates to support new backends and fix issues.

pip install social-auth-core
INSTALL
IMPORT
SIG · SOCIAL-AUTH-CORE
S
social-auth-core
auth-securitypythonv5.1.0
Install
3.7s avg
Import
427ms
Disk
44MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v5.1.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.910 runs
installs and imports cleanly · install 0.0s · import 0.440s · 45.4MB
glibc
py 3.103.910 runs
installs and imports cleanly · install 3.7s · import 0.413s · 46MB
44MB installed
● package 44MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

BaseOAuth2
from social_core.backends.oauth import BaseOAuth2
from social_core.oauth import BaseOAuth2
Backends are located under the 'backends' submodule.
BaseStrategy
from social_core.strategy import BaseStrategy
AuthException
from social_core.exceptions import AuthException

This quickstart demonstrates how to define a custom OAuth2 backend using `social-auth-core`. This core component abstracts provider specifics. For actual usage in a web application, this backend definition must be integrated with a framework-specific package (e.g., `social-auth-django`) and configured in your project's settings to provide the necessary client ID, secret, and URLs.

import os from social_core.backends.oauth import BaseOAuth2 # This example demonstrates how to define a custom OAuth2 backend using social-auth-core. # To use this in a web application, you would also need a framework-specific integration # (e.g., social-auth-django) and configure it in your project's settings. class MyCustomOAuth2Backend(BaseOAuth2): name = 'my-custom-oauth2' AUTHORIZATION_URL = os.environ.get('MY_CUSTOM_OAUTH2_AUTHORIZATION_URL', 'https://example.com/oauth/authorize') ACCESS_TOKEN_URL = os.environ.get('MY_CUSTOM_OAUTH2_ACCESS_TOKEN_URL', 'https://example.com/oauth/token') SCOPE_SEPARATOR = ',' DEFAULT_SCOPE = ['email', 'profile'] EXTRA_DATA = [ ('id', 'id'), ('expires_in', 'expires'), ('token_type', 'token_type'), ] def get_user_details(self, response): """Return user details from example.com account.""" return { 'username': response.get('email') or response.get('name'), 'email': response.get('email'), 'fullname': response.get('name') } def user_data(self, access_token, *args, **kwargs): """Loads user data from the custom service using the access_token.""" # In a real backend, you'd make an API call to fetch user info. # For this quickstart, we return mock data. # Example of a real call: # url = 'https://api.example.com/userinfo' # headers = {'Authorization': f'Bearer {access_token}'} # response = self.get_json(url, headers=headers) # return response return {'id': 'user123', 'email': 'user@example.com', 'name': 'Test User'} # To integrate this, you would typically add 'my_app.backends.MyCustomOAuth2Backend' # to your framework's SOCIAL_AUTH_AUTHENTICATION_BACKENDS setting.
Debug
Known issues
breakingPython 3.9 support was dropped in version 4.8.0. Users on Python 3.9 or older must upgrade to Python 3.10+.
fix
Upgrade your Python environment to version 3.10 or newer.
affects: 4.8.0+
breakingNumerous social authentication backends have been removed across recent versions (e.g., itembase, nk, AOL OpenID, BitBucket OAuth 1.0, khanacademy). Users relying on these backends will find them unavailable.
fix
Consult the changelog for specific backend removals. If your backend was removed, you may need to implement a custom backend or find an alternative authentication method.
affects: 4.6.0, 4.7.0, 4.8.2+
breakingFor the SAML backend, missing configured attributes now cause an `AuthMissingParameter` error. Previously, these might have been silently ignored.
fix
Ensure that all attributes expected by your SAML configuration are correctly provided by the Identity Provider (IdP). Implement robust error handling for `AuthMissingParameter`.
affects: 4.8.0+
breakingOAuth2 backends now default to using the POST method for token exchange (e.g., getting access tokens). This change occurred in version 4.6.0.
fix
Review existing custom OAuth2 backend implementations to ensure they are compatible with POST requests for token exchange. Most standard compliant providers will support POST, but older or non-standard ones might break.
affects: 4.6.0+
gotcha`social-auth-core` is a core library and requires a framework-specific integration package (e.g., `social-auth-django`, `social-auth-flask`, `social-auth-pyramid`) to be used in a web application context.
fix
Install the appropriate `social-auth-*` package for your web framework in addition to `social-auth-core`.
affects: All versions
gotchaThe `ID_KEY` used for identifying users, which defaults to `id`, became configurable in version 4.8.2. If you have custom logic relying on the fixed 'id' key or are extending backends, this might impact your code.
fix
If customizing user identification, ensure your logic accounts for the configurable `ID_KEY` (e.g., `SOCIAL_AUTH_UID_KEY`).
affects: 4.8.2+
Errors
Common errors & fixes
social_core.exceptions.MissingBackend: Backend not found
This error occurs when the social authentication backend specified in the URL or request parameters is not registered in the `AUTHENTICATION_BACKENDS` setting, or the URL configuration is incorrect.
fix
Ensure the desired backend (e.g., `'social_core.backends.google.GoogleOAuth2'`) is correctly listed in your Django `settings.py` `AUTHENTICATION_BACKENDS` list and your project's URLs are properly configured to include `social_django.urls`.
django.urls.exceptions.NoReverseMatch: Reverse for 'social:begin' with no arguments not found.
This error indicates that Django cannot find a URL pattern named 'begin' within the 'social' namespace, usually because `social_django.urls` is not included in your project's `urls.py` with the correct namespace.
fix
In your project's `urls.py`, ensure you include `social_django.urls` with the `namespace='social'` argument: `path('oauth/', include('social_django.urls', namespace='social'))`.
ModuleNotFoundError: No module named 'social_django'
This occurs when the `social-auth-app-django` package, which provides Django integration for `social-auth-core`, has not been installed or is not correctly added to your project's `INSTALLED_APPS`.
fix
Install the Django integration package using pip: `pip install social-auth-app-django`. Then, add `'social_django'` to your `INSTALLED_APPS` in `settings.py`.
social_core.exceptions.AuthMissingParameter: missing client_id and/or client_secret
This error means that required authentication parameters, typically `CLIENT_ID` and `CLIENT_SECRET`, are not defined in your Django `settings.py` for the social backend you are trying to use.
fix
Define the necessary `SOCIAL_AUTH_<BACKEND_NAME>_KEY` (for client ID) and `SOCIAL_AUTH_<BACKEND_NAME>_SECRET` (for client secret) variables in your `settings.py`, replacing `<BACKEND_NAME>` with the uppercase name of your social backend (e.g., `GOOGLE_OAUTH2`).
ProgrammingError: relation "social_auth_usersocialauth" does not exist
This error indicates that the necessary database tables for `social_django` have not been created, usually because Django database migrations have not been applied.
fix
After adding `'social_django'` to `INSTALLED_APPS`, run Django migrations to create the required tables: `python manage.py migrate social_django`.
Upgrade
Version history
5.1.0latest on PyPI · released Aug 6, 2026
Audit
Dependencies
PyJWTrequiredRequired for JSON Web Token handling, especially for OpenID Connect and some OAuth2 backends.
requestsrequiredEssential for making HTTP requests to OAuth/OpenID providers.
defusedxmloptionalUsed for SAML backend to parse XML securely.
lxmloptionalUsed for SAML backend for XML processing.
social-auth-djangooptionalRequired for integration with Django projects.
social-auth-flaskoptionalRequired for integration with Flask projects.
Agent activity
13 hits · last 30 days
node
8
OpenAI (training)
1
Resources
social-auth-core — pip install social-auth-core · libregistry