tessl/pypi-social-auth-core
Python social authentication framework with 195+ backend providers for OAuth, OpenID Connect, and SAML integration.
—
Pending
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
Pending
The risk profile of this skill
index.mddocs/
Social Auth Core
A comprehensive Python social authentication framework that enables developers to integrate OAuth, OpenID Connect, SAML, and other social authentication providers into web applications. Social Auth Core provides a unified interface for 195+ authentication backends, a flexible pipeline system for customizing authentication workflows, and framework-agnostic design supporting multiple web frameworks and storage solutions.
Package Information
- Package Name: social-auth-core
- Language: Python
- Installation:
pip install social-auth-core - Optional Dependencies:
pip install social-auth-core[all]for all provider-specific dependencies
Core Imports
import social_coreCommon imports for authentication flows:
from social_core.actions import do_auth, do_complete
from social_core.backends.utils import get_backend, load_backends
from social_core.strategy import BaseStrategy
from social_core.storage import UserMixin, AssociationMixinFor working with specific authentication backends:
from social_core.backends.google import GoogleOAuth2
from social_core.backends.facebook import FacebookOAuth2
from social_core.backends.github import GithubOAuth2Basic Usage
from social_core.actions import do_auth, do_complete
from social_core.backends.google import GoogleOAuth2
from social_core.strategy import BaseStrategy
# Initialize a strategy (framework-specific implementation required)
strategy = MyCustomStrategy(storage=my_storage)
# Initialize a backend
backend = GoogleOAuth2(strategy, redirect_uri='/auth/complete/google/')
# Start authentication flow
auth_response = do_auth(backend, redirect_name='next')
# Complete authentication (in callback view)
user = do_complete(backend, login_func=my_login_func, user=current_user)
# Access user data
if user:
print(f"Authenticated user: {user.username}")
print(f"Provider: {user.social_user.provider}")
print(f"UID: {user.social_user.uid}")
print(f"Access token: {user.social_user.access_token}")Architecture
Social Auth Core is built around several key components that work together to provide flexible social authentication:
- Backends: Provider-specific authentication implementations (OAuth, OpenID, SAML)
- Strategy: Framework-agnostic interface for request/response handling and storage
- Pipeline: Configurable workflow system for processing authentication steps
- Storage: Abstract data models for users, social accounts, and associations
- Actions: High-level functions that orchestrate the authentication flow
This modular design allows the library to work with any Python web framework (Django, Flask, Pyramid, etc.) by implementing a custom strategy class, while maintaining consistent behavior across all authentication providers.
Capabilities
Authentication Actions
High-level functions that orchestrate the complete authentication flow from initiation to completion, handling session management, redirect validation, and pipeline execution.
def do_auth(backend, redirect_name="next"):
"""
Initiate authentication flow with the specified backend.
Parameters:
- backend: Authentication backend instance
- redirect_name: Name of redirect parameter (default: "next")
Returns:
Backend-specific response (redirect or HTML)
"""
def do_complete(backend, login, user=None, redirect_name="next", *args, **kwargs):
"""
Complete authentication flow and return authenticated user.
Parameters:
- backend: Authentication backend instance
- login: Login function to call on successful auth
- user: Current user instance (optional)
- redirect_name: Name of redirect parameter (default: "next")
Returns:
Authenticated user instance or None
"""Authentication Backends
195+ authentication provider implementations supporting OAuth 1.0/2.0, OpenID Connect, SAML, and custom protocols. Each backend handles provider-specific authentication flows, token management, and user data extraction.
class BaseAuth:
"""Base authentication backend class."""
name: str
supports_inactive_user: bool
ID_KEY: str
EXTRA_DATA: list | None
def __init__(self, strategy, redirect_uri=None): ...
def start(self): ...
def complete(self, *args, **kwargs): ...
def auth_url(self) -> str: ...
def authenticate(self, *args, **kwargs): ...
# Major provider backends
class GoogleOAuth2(BaseAuth): ...
class FacebookOAuth2(BaseAuth): ...
class GithubOAuth2(BaseAuth): ...
class TwitterOAuth(BaseAuth): ...
class LinkedinOAuth2(BaseAuth): ...Pipeline System
Configurable workflow system that processes authentication through a series of steps, enabling customization of user creation, data handling, email validation, and account association logic.
DEFAULT_AUTH_PIPELINE: tuple
DEFAULT_DISCONNECT_PIPELINE: tuple
# Pipeline functions
def social_details(backend, details, response, *args, **kwargs): ...
def social_uid(backend, details, response, *args, **kwargs): ...
def auth_allowed(backend, details, response, *args, **kwargs): ...
def social_user(backend, uid, user=None, *args, **kwargs): ...
def get_username(strategy, details, backend, user=None, *args, **kwargs): ...
def create_user(strategy, details, backend, user=None, *args, **kwargs): ...
def associate_user(backend, uid, user=None, *args, **kwargs): ...Storage Models
Abstract base classes and mixins for implementing user accounts, social account associations, and authentication data storage with any database or ORM system.
class UserMixin:
"""Mixin for user social auth models."""
ACCESS_TOKEN_EXPIRED_THRESHOLD: int
provider: str
uid: str | None
extra_data: dict | None
def get_backend(self, strategy): ...
def get_backend_instance(self, strategy): ...
def refresh_token(self, strategy, *args, **kwargs): ...
def set_extra_data(self, extra_data): ...
class AssociationMixin:
"""Mixin for association models."""
class BaseStorage:
"""Abstract base storage interface."""Strategy Interface
Framework-agnostic interface that adapts social-auth-core to work with any Python web framework by implementing request/response handling, session management, and storage operations.
class BaseStrategy:
"""Base strategy class for framework integration."""
ALLOWED_CHARS: str
DEFAULT_TEMPLATE_STRATEGY: type
SESSION_SAVE_KEY: str
def __init__(self, storage=None, tpl=None): ...
def setting(self, name: str, default=None, backend=None): ...
def request_data(self, merge=True): ...
def redirect(self, url: str): ...
def html(self, content: str): ...
def get_pipeline(self, backend): ...
def authenticate(self, *args, **kwargs): ...Utilities and Helpers
Collection of utility functions for URL manipulation, session handling, pipeline data management, user validation, and security operations used throughout the authentication process.
def module_member(name: str): ...
def user_agent() -> str: ...
def url_add_parameters(url: str, params: dict, _unquote_query: bool = False) -> str: ...
def sanitize_redirect(allowed_hosts: list, redirect_uri: str) -> str: ...
def user_is_authenticated(user) -> bool: ...
def user_is_active(user) -> bool: ...
def partial_pipeline_data(backend, user, *args, **kwargs): ...
# Constants
SETTING_PREFIX: str = "SOCIAL_AUTH"
PARTIAL_TOKEN_SESSION_NAME: str = "partial_pipeline_token"Exception Handling
Comprehensive exception hierarchy for handling authentication errors, backend issues, pipeline failures, and security violations with detailed error information.
class SocialAuthBaseException(ValueError):
"""Base class for pipeline exceptions."""
class AuthException(SocialAuthBaseException):
"""Auth process exception."""
class WrongBackend(SocialAuthBaseException):
"""Incorrect authentication service error."""
class MissingBackend(WrongBackend):
"""Missing backend entry error."""
class NotAllowedToDisconnect(SocialAuthBaseException):
"""User not allowed to disconnect social account."""
class StrategyMissingFeatureError(SocialAuthBaseException):
"""Strategy does not support this feature."""