tessl/pypi-social-auth-core
Python social authentication framework with 195+ backend providers for OAuth, OpenID Connect, and SAML integration.
—
Pending
pipeline-system.mddocs/
Pipeline System
The pipeline system provides a configurable workflow for processing social authentication through a series of discrete steps. This allows customization of user creation, data handling, email validation, account association logic, and other authentication behaviors without modifying core library code.
Capabilities
Default Authentication Pipeline
The standard authentication pipeline processes social login through predefined steps that can be customized or extended.
DEFAULT_AUTH_PIPELINE: tuple = (
# Get user information from provider response
"social_core.pipeline.social_auth.social_details",
# Extract unique identifier from provider
"social_core.pipeline.social_auth.social_uid",
# Verify authentication is allowed for this user/domain
"social_core.pipeline.social_auth.auth_allowed",
# Check if social account already exists
"social_core.pipeline.social_auth.social_user",
# Generate username for new users
"social_core.pipeline.user.get_username",
# Send email validation if configured
# "social_core.pipeline.mail.mail_validation",
# Associate account by email if enabled
# "social_core.pipeline.social_auth.associate_by_email",
# Create user account if needed
"social_core.pipeline.user.create_user",
# Create social account association
"social_core.pipeline.social_auth.associate_user",
# Store additional provider data
"social_core.pipeline.social_auth.load_extra_data",
# Update user with latest provider info
"social_core.pipeline.user.user_details",
)Default Disconnect Pipeline
The standard disconnection pipeline for removing social account associations.
DEFAULT_DISCONNECT_PIPELINE: tuple = (
# Verify user can disconnect this account
"social_core.pipeline.disconnect.allowed_to_disconnect",
# Collect social associations to remove
"social_core.pipeline.disconnect.get_entries",
# Revoke access tokens when possible
"social_core.pipeline.disconnect.revoke_tokens",
# Remove social account associations
"social_core.pipeline.disconnect.disconnect",
)Social Authentication Pipeline Functions
Core pipeline functions that handle social authentication data processing and user management.
def social_details(backend, details, response, *args, **kwargs):
"""
Extract user details from provider response.
Processes the authentication response to extract user information
like name, email, username, and other profile data into a standardized format.
Parameters:
- backend: Authentication backend instance
- details: User details dictionary (may be pre-populated)
- response: Raw provider response data
- Additional pipeline arguments
Returns:
Dictionary with 'details' key containing extracted user information
"""
def social_uid(backend, details, response, *args, **kwargs):
"""
Extract unique identifier from provider response.
Gets the provider-specific unique identifier that will be used
to link the social account to local user records.
Parameters:
- backend: Authentication backend instance
- details: User details dictionary
- response: Raw provider response data
- Additional pipeline arguments
Returns:
Dictionary with 'uid' key containing provider user ID
"""
def auth_allowed(backend, details, response, *args, **kwargs):
"""
Verify that authentication is allowed.
Checks domain whitelists, email restrictions, and other access controls
to determine if this user should be allowed to authenticate with this provider.
Parameters:
- backend: Authentication backend instance
- details: User details dictionary
- response: Raw provider response data
- Additional pipeline arguments
Returns:
None if allowed, raises AuthForbidden if not allowed
Raises:
- AuthForbidden: If user is not permitted to authenticate
"""
def social_user(backend, uid, user=None, *args, **kwargs):
"""
Check if social account already exists.
Looks up existing social account associations for this provider and UID,
returning the associated user if found.
Parameters:
- backend: Authentication backend instance
- uid: Provider user ID
- user: Current user instance (optional)
- Additional pipeline arguments
Returns:
Dictionary with 'social' and 'user' keys if account exists,
empty dictionary if no existing association found
"""
def associate_by_email(backend, details, user=None, *args, **kwargs):
"""
Associate social account with user by matching email address.
Attempts to link the social account to an existing user account
that has the same email address as provided by the social provider.
Parameters:
- backend: Authentication backend instance
- details: User details dictionary containing email
- user: Current user instance (optional)
- Additional pipeline arguments
Returns:
Dictionary with 'user' key if association created
"""
def associate_user(backend, uid, user=None, *args, **kwargs):
"""
Create association between social account and user.
Creates the database record that links the social provider account
to the local user account, storing the UID and provider information.
Parameters:
- backend: Authentication backend instance
- uid: Provider user ID
- user: User instance to associate with
- Additional pipeline arguments
Returns:
Dictionary with 'social' key containing the association record
"""
def load_extra_data(backend, details, response, uid, user, *args, **kwargs):
"""
Store additional provider data in social account.
Saves extra information from the provider response (like access tokens,
refresh tokens, profile data) to the social account record for later use.
Parameters:
- backend: Authentication backend instance
- details: User details dictionary
- response: Raw provider response data
- uid: Provider user ID
- user: User instance
- Additional pipeline arguments
Returns:
Dictionary with updated social account information
"""Pipeline Constants and Configuration
Essential constants used throughout the pipeline system.
# User fields that are automatically populated from provider data
USER_FIELDS: list = ["username", "email"]
# Data types that can be safely serialized in pipeline storage
SERIALIZABLE_TYPES: tuple = (
dict, list, tuple, set, frozenset, bool, int, float, str, bytes, type(None)
)Pipeline Utilities
Helper functions for managing pipeline data and execution.
def is_dict_type(value):
"""
Check if value is a dictionary-like type.
Parameters:
- value: Value to check
Returns:
Boolean indicating if value is dict-like
"""
def partial_prepare(strategy, backend, next_step, user=None, social=None, *args, **kwargs):
"""
Prepare partial pipeline data for storage.
Parameters:
- strategy: Strategy instance
- backend: Authentication backend instance
- next_step: Next pipeline step index
- user: User instance (optional)
- social: Social account instance (optional)
- Additional pipeline arguments
Returns:
Partial pipeline object
"""
def partial_store(strategy, backend, next_step, user=None, social=None, *args, **kwargs):
"""
Store partial pipeline data.
Parameters:
- strategy: Strategy instance
- backend: Authentication backend instance
- next_step: Next pipeline step index
- user: User instance (optional)
- social: Social account instance (optional)
- Additional pipeline arguments
Returns:
Stored partial pipeline object
"""
def partial_load(strategy, token):
"""
Load partial pipeline data from token.
Parameters:
- strategy: Strategy instance
- token: Partial pipeline token
Returns:
Partial pipeline object or None
"""User Management Pipeline Functions
Pipeline functions focused on user account creation and profile management.
def get_username(strategy, details, backend, user=None, *args, **kwargs):
"""
Generate username for user account.
Creates a unique username based on provider data, handling conflicts
by appending random strings until a unique username is found.
Parameters:
- strategy: Strategy instance
- details: User details dictionary
- backend: Authentication backend instance
- user: Existing user instance (optional)
- Additional pipeline arguments
Returns:
Dictionary with 'username' key containing generated username
"""
def create_user(strategy, details, backend, user=None, *args, **kwargs):
"""
Create new user account if needed.
Creates a new user account using the provided details if no existing
user was found in earlier pipeline steps.
Parameters:
- strategy: Strategy instance
- details: User details dictionary with user information
- backend: Authentication backend instance
- user: Existing user instance (optional)
- Additional pipeline arguments
Returns:
Dictionary with 'user' and 'is_new' keys
"""
def user_details(strategy, details, backend, user=None, *args, **kwargs):
"""
Update user account with latest provider information.
Updates the user's profile information with the latest data from
the social provider, such as name, email, or other profile fields.
Parameters:
- strategy: Strategy instance
- details: User details dictionary with updated information
- backend: Authentication backend instance
- user: User instance to update
- Additional pipeline arguments
Returns:
Dictionary with updated user information
"""Email Validation Pipeline Functions
Pipeline functions for handling email verification workflows.
def mail_validation(strategy, backend, code, *args, **kwargs):
"""
Send email validation message to user.
Sends a validation email to the user's email address to confirm
ownership before completing the authentication process.
Parameters:
- strategy: Strategy instance
- backend: Authentication backend instance
- code: Validation code or token
- Additional pipeline arguments
Returns:
Partial pipeline data to pause authentication until validation
"""Disconnection Pipeline Functions
Pipeline functions for removing social account associations.
def allowed_to_disconnect(backend, user, user_social_auth, *args, **kwargs):
"""
Verify that user is allowed to disconnect social account.
Ensures the user won't be locked out of their account by removing
this social authentication method (e.g., check for password or other login methods).
Parameters:
- backend: Authentication backend instance
- user: User instance
- user_social_auth: Social account association to disconnect
- Additional pipeline arguments
Raises:
- NotAllowedToDisconnect: If disconnection would lock out user
"""
def get_entries(strategy, backend, user, user_social_auth, *args, **kwargs):
"""
Collect social account associations to disconnect.
Gathers all social account records that should be removed for this
user and provider combination.
Parameters:
- strategy: Strategy instance
- backend: Authentication backend instance
- user: User instance
- user_social_auth: Social account association to disconnect
- Additional pipeline arguments
Returns:
Dictionary with 'entries' key containing associations to remove
"""
def revoke_tokens(strategy, backend, user, user_social_auth, *args, **kwargs):
"""
Revoke access tokens with provider.
Attempts to revoke access and refresh tokens with the social provider
to ensure the application no longer has access to user data.
Parameters:
- strategy: Strategy instance
- backend: Authentication backend instance
- user: User instance
- user_social_auth: Social account association being disconnected
- Additional pipeline arguments
"""
def disconnect(strategy, backend, user, user_social_auth, *args, **kwargs):
"""
Remove social account associations.
Deletes the social account association records from the database,
completing the disconnection process.
Parameters:
- strategy: Strategy instance
- backend: Authentication backend instance
- user: User instance
- user_social_auth: Social account association to remove
- Additional pipeline arguments
"""Pipeline Utilities
Helper functions for managing partial pipeline data and interruptions.
def partial_prepare(backend, user, uid, details, *args, **kwargs):
"""
Prepare data for partial pipeline storage.
Serializes pipeline data for storage when authentication flow
needs to be interrupted (e.g., for email validation).
Parameters:
- backend: Authentication backend instance
- user: User instance (optional)
- uid: Provider user ID
- details: User details dictionary
- Additional pipeline arguments
Returns:
Dictionary with pipeline data ready for storage
"""
def partial_store(strategy, pipeline, *args, **kwargs):
"""
Store partial pipeline data.
Saves pipeline state to session or database for later resumption
when authentication flow is interrupted.
Parameters:
- strategy: Strategy instance
- pipeline: Pipeline configuration
- Additional pipeline arguments
Returns:
Partial pipeline token for resuming later
"""
def partial_load(strategy, token):
"""
Load partial pipeline data.
Retrieves previously stored pipeline state using the provided token
to resume an interrupted authentication flow.
Parameters:
- strategy: Strategy instance
- token: Partial pipeline token
Returns:
Stored pipeline data dictionary or None if not found
"""Custom Pipeline Configuration
Customizing Pipeline Steps
# Add custom pipeline function
def require_email(strategy, details, *args, **kwargs):
if not details.get('email'):
raise AuthException(backend, 'Email is required')
return {}
# Custom authentication pipeline
SOCIAL_AUTH_PIPELINE = (
'social_core.pipeline.social_auth.social_details',
'social_core.pipeline.social_auth.social_uid',
'myapp.pipeline.require_email', # Custom step
'social_core.pipeline.social_auth.auth_allowed',
'social_core.pipeline.social_auth.social_user',
'social_core.pipeline.user.get_username',
'social_core.pipeline.user.create_user',
'social_core.pipeline.social_auth.associate_user',
'social_core.pipeline.social_auth.load_extra_data',
'social_core.pipeline.user.user_details',
)Partial Pipeline Handling
The pipeline system supports interrupting authentication for additional user input:
def collect_extra_info(strategy, backend, user, *args, **kwargs):
"""Collect additional user information if needed."""
if user and not user.phone_number:
# Interrupt pipeline to collect phone number
return strategy.redirect('/auth/phone-number/')
return {}The pipeline system's modular design enables fine-grained control over authentication workflows while maintaining security and consistency across different providers and use cases.
Install with Tessl CLI
npx tessl i tessl/pypi-social-auth-core