0
# Social Auth Core
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: social-auth-core  
7
- **Language**: Python
8
- **Installation**: `pip install social-auth-core`
9
- **Optional Dependencies**: `pip install social-auth-core[all]` for all provider-specific dependencies
10

11
## Core Imports
12

13
```python
14
import social_core
15
```
16

17
Common imports for authentication flows:
18

19
```python
20
from social_core.actions import do_auth, do_complete
21
from social_core.backends.utils import get_backend, load_backends
22
from social_core.strategy import BaseStrategy
23
from social_core.storage import UserMixin, AssociationMixin
24
```
25

26
For working with specific authentication backends:
27

28
```python
29
from social_core.backends.google import GoogleOAuth2
30
from social_core.backends.facebook import FacebookOAuth2  
31
from social_core.backends.github import GithubOAuth2
32
```
33

34
## Basic Usage
35

36
```python
37
from social_core.actions import do_auth, do_complete
38
from social_core.backends.google import GoogleOAuth2
39
from social_core.strategy import BaseStrategy
40

41
# Initialize a strategy (framework-specific implementation required)
42
strategy = MyCustomStrategy(storage=my_storage)
43

44
# Initialize a backend
45
backend = GoogleOAuth2(strategy, redirect_uri='/auth/complete/google/')
46

47
# Start authentication flow
48
auth_response = do_auth(backend, redirect_name='next')
49

50
# Complete authentication (in callback view)
51
user = do_complete(backend, login_func=my_login_func, user=current_user)
52

53
# Access user data
54
if user:
55
    print(f"Authenticated user: {user.username}")
56
    print(f"Provider: {user.social_user.provider}")
57
    print(f"UID: {user.social_user.uid}")
58
    print(f"Access token: {user.social_user.access_token}")
59
```
60

61
## Architecture
62

63
Social Auth Core is built around several key components that work together to provide flexible social authentication:
64

65
- **Backends**: Provider-specific authentication implementations (OAuth, OpenID, SAML)
66
- **Strategy**: Framework-agnostic interface for request/response handling and storage
67
- **Pipeline**: Configurable workflow system for processing authentication steps  
68
- **Storage**: Abstract data models for users, social accounts, and associations
69
- **Actions**: High-level functions that orchestrate the authentication flow
70

71
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.
72

73
## Capabilities
74

75
### Authentication Actions
76

77
High-level functions that orchestrate the complete authentication flow from initiation to completion, handling session management, redirect validation, and pipeline execution.
78

79
```python { .api }
80
def do_auth(backend, redirect_name="next"):
81
    """
82
    Initiate authentication flow with the specified backend.
83
    
84
    Parameters:
85
    - backend: Authentication backend instance
86
    - redirect_name: Name of redirect parameter (default: "next")
87
    
88
    Returns:
89
    Backend-specific response (redirect or HTML)
90
    """
91

92
def do_complete(backend, login, user=None, redirect_name="next", *args, **kwargs):
93
    """
94
    Complete authentication flow and return authenticated user.
95
    
96
    Parameters:
97
    - backend: Authentication backend instance  
98
    - login: Login function to call on successful auth
99
    - user: Current user instance (optional)
100
    - redirect_name: Name of redirect parameter (default: "next")
101
    
102
    Returns:
103
    Authenticated user instance or None
104
    """
105
```
106

107
[Authentication Actions](./authentication-actions.md)
108

109
### Authentication Backends
110

111
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.
112

113
```python { .api }  
114
class BaseAuth:
115
    """Base authentication backend class."""
116
    name: str
117
    supports_inactive_user: bool
118
    ID_KEY: str
119
    EXTRA_DATA: list | None
120
    
121
    def __init__(self, strategy, redirect_uri=None): ...
122
    def start(self): ...
123
    def complete(self, *args, **kwargs): ...
124
    def auth_url(self) -> str: ...
125
    def authenticate(self, *args, **kwargs): ...
126

127
# Major provider backends
128
class GoogleOAuth2(BaseAuth): ...
129
class FacebookOAuth2(BaseAuth): ...  
130
class GithubOAuth2(BaseAuth): ...
131
class TwitterOAuth(BaseAuth): ...
132
class LinkedinOAuth2(BaseAuth): ...
133
```
134

135
[Authentication Backends](./authentication-backends.md)
136

137
### Pipeline System
138

139
Configurable workflow system that processes authentication through a series of steps, enabling customization of user creation, data handling, email validation, and account association logic.
140

141
```python { .api }
142
DEFAULT_AUTH_PIPELINE: tuple
143
DEFAULT_DISCONNECT_PIPELINE: tuple
144

145
# Pipeline functions
146
def social_details(backend, details, response, *args, **kwargs): ...
147
def social_uid(backend, details, response, *args, **kwargs): ...  
148
def auth_allowed(backend, details, response, *args, **kwargs): ...
149
def social_user(backend, uid, user=None, *args, **kwargs): ...
150
def get_username(strategy, details, backend, user=None, *args, **kwargs): ...
151
def create_user(strategy, details, backend, user=None, *args, **kwargs): ...
152
def associate_user(backend, uid, user=None, *args, **kwargs): ...
153
```
154

155
[Pipeline System](./pipeline-system.md)
156

157
### Storage Models  
158

159
Abstract base classes and mixins for implementing user accounts, social account associations, and authentication data storage with any database or ORM system.
160

161
```python { .api }
162
class UserMixin:
163
    """Mixin for user social auth models."""
164
    ACCESS_TOKEN_EXPIRED_THRESHOLD: int
165
    provider: str
166
    uid: str | None
167
    extra_data: dict | None
168
    
169
    def get_backend(self, strategy): ...
170
    def get_backend_instance(self, strategy): ...
171
    def refresh_token(self, strategy, *args, **kwargs): ...
172
    def set_extra_data(self, extra_data): ...
173
    
174
class AssociationMixin:
175
    """Mixin for association models."""
176
    
177
class BaseStorage:
178
    """Abstract base storage interface."""
179
```
180

181
[Storage Models](./storage-models.md)
182

183
### Strategy Interface
184

185
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.
186

187
```python { .api }
188
class BaseStrategy:
189
    """Base strategy class for framework integration."""
190
    ALLOWED_CHARS: str
191
    DEFAULT_TEMPLATE_STRATEGY: type
192
    SESSION_SAVE_KEY: str
193
    
194
    def __init__(self, storage=None, tpl=None): ...
195
    def setting(self, name: str, default=None, backend=None): ...
196
    def request_data(self, merge=True): ...
197
    def redirect(self, url: str): ...
198
    def html(self, content: str): ...
199
    def get_pipeline(self, backend): ...
200
    def authenticate(self, *args, **kwargs): ...
201
```
202

203
[Strategy Interface](./strategy-interface.md)
204

205
### Utilities and Helpers
206

207
Collection of utility functions for URL manipulation, session handling, pipeline data management, user validation, and security operations used throughout the authentication process.
208

209
```python { .api }
210
def module_member(name: str): ...
211
def user_agent() -> str: ...
212
def url_add_parameters(url: str, params: dict, _unquote_query: bool = False) -> str: ...
213
def sanitize_redirect(allowed_hosts: list, redirect_uri: str) -> str: ...
214
def user_is_authenticated(user) -> bool: ...
215
def user_is_active(user) -> bool: ...
216
def partial_pipeline_data(backend, user, *args, **kwargs): ...
217

218
# Constants
219
SETTING_PREFIX: str = "SOCIAL_AUTH"
220
PARTIAL_TOKEN_SESSION_NAME: str = "partial_pipeline_token"
221
```
222

223
[Utilities and Helpers](./utilities-helpers.md)
224

225
### Exception Handling
226

227
Comprehensive exception hierarchy for handling authentication errors, backend issues, pipeline failures, and security violations with detailed error information.
228

229
```python { .api }
230
class SocialAuthBaseException(ValueError):
231
    """Base class for pipeline exceptions."""
232

233
class AuthException(SocialAuthBaseException):
234
    """Auth process exception."""
235
    
236
class WrongBackend(SocialAuthBaseException):
237
    """Incorrect authentication service error."""
238
    
239
class MissingBackend(WrongBackend):
240
    """Missing backend entry error."""
241
    
242
class NotAllowedToDisconnect(SocialAuthBaseException):
243
    """User not allowed to disconnect social account."""
244
    
245
class StrategyMissingFeatureError(SocialAuthBaseException):
246
    """Strategy does not support this feature."""
247
```
248

249
[Exception Handling](./exception-handling.md)