0
# Pipeline System
1

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

4
## Capabilities
5

6
### Default Authentication Pipeline
7

8
The standard authentication pipeline processes social login through predefined steps that can be customized or extended.
9

10
```python { .api }
11
DEFAULT_AUTH_PIPELINE: tuple = (
12
    # Get user information from provider response
13
    "social_core.pipeline.social_auth.social_details",
14
    # Extract unique identifier from provider
15
    "social_core.pipeline.social_auth.social_uid", 
16
    # Verify authentication is allowed for this user/domain
17
    "social_core.pipeline.social_auth.auth_allowed",
18
    # Check if social account already exists
19
    "social_core.pipeline.social_auth.social_user",
20
    # Generate username for new users
21
    "social_core.pipeline.user.get_username",
22
    # Send email validation if configured
23
    # "social_core.pipeline.mail.mail_validation",
24
    # Associate account by email if enabled  
25
    # "social_core.pipeline.social_auth.associate_by_email",
26
    # Create user account if needed
27
    "social_core.pipeline.user.create_user",
28
    # Create social account association
29
    "social_core.pipeline.social_auth.associate_user", 
30
    # Store additional provider data
31
    "social_core.pipeline.social_auth.load_extra_data",
32
    # Update user with latest provider info
33
    "social_core.pipeline.user.user_details",
34
)
35
```
36

37
### Default Disconnect Pipeline
38

39
The standard disconnection pipeline for removing social account associations.
40

41
```python { .api }
42
DEFAULT_DISCONNECT_PIPELINE: tuple = (
43
    # Verify user can disconnect this account
44
    "social_core.pipeline.disconnect.allowed_to_disconnect",
45
    # Collect social associations to remove
46
    "social_core.pipeline.disconnect.get_entries", 
47
    # Revoke access tokens when possible
48
    "social_core.pipeline.disconnect.revoke_tokens",
49
    # Remove social account associations
50
    "social_core.pipeline.disconnect.disconnect",
51
)
52
```
53

54
### Social Authentication Pipeline Functions
55

56
Core pipeline functions that handle social authentication data processing and user management.
57

58
```python { .api }
59
def social_details(backend, details, response, *args, **kwargs):
60
    """
61
    Extract user details from provider response.
62
    
63
    Processes the authentication response to extract user information
64
    like name, email, username, and other profile data into a standardized format.
65
    
66
    Parameters:
67
    - backend: Authentication backend instance
68
    - details: User details dictionary (may be pre-populated)
69
    - response: Raw provider response data
70
    - Additional pipeline arguments
71
    
72
    Returns:
73
    Dictionary with 'details' key containing extracted user information
74
    """
75

76
def social_uid(backend, details, response, *args, **kwargs):
77
    """
78
    Extract unique identifier from provider response.
79
    
80
    Gets the provider-specific unique identifier that will be used
81
    to link the social account to local user records.
82
    
83
    Parameters:
84
    - backend: Authentication backend instance  
85
    - details: User details dictionary
86
    - response: Raw provider response data
87
    - Additional pipeline arguments
88
    
89
    Returns:
90
    Dictionary with 'uid' key containing provider user ID
91
    """
92

93
def auth_allowed(backend, details, response, *args, **kwargs):
94
    """
95
    Verify that authentication is allowed.
96
    
97
    Checks domain whitelists, email restrictions, and other access controls
98
    to determine if this user should be allowed to authenticate with this provider.
99
    
100
    Parameters:
101
    - backend: Authentication backend instance
102
    - details: User details dictionary  
103
    - response: Raw provider response data
104
    - Additional pipeline arguments
105
    
106
    Returns:
107
    None if allowed, raises AuthForbidden if not allowed
108
    
109
    Raises:
110
    - AuthForbidden: If user is not permitted to authenticate
111
    """
112

113
def social_user(backend, uid, user=None, *args, **kwargs):
114
    """
115
    Check if social account already exists.
116
    
117
    Looks up existing social account associations for this provider and UID,
118
    returning the associated user if found.
119
    
120
    Parameters:
121
    - backend: Authentication backend instance
122
    - uid: Provider user ID
123
    - user: Current user instance (optional)
124
    - Additional pipeline arguments
125
    
126
    Returns:
127
    Dictionary with 'social' and 'user' keys if account exists,
128
    empty dictionary if no existing association found
129
    """
130

131
def associate_by_email(backend, details, user=None, *args, **kwargs):
132
    """
133
    Associate social account with user by matching email address.
134
    
135
    Attempts to link the social account to an existing user account
136
    that has the same email address as provided by the social provider.
137
    
138
    Parameters:
139
    - backend: Authentication backend instance
140
    - details: User details dictionary containing email
141
    - user: Current user instance (optional)
142
    - Additional pipeline arguments
143
    
144
    Returns:
145
    Dictionary with 'user' key if association created
146
    """
147

148
def associate_user(backend, uid, user=None, *args, **kwargs):
149
    """
150
    Create association between social account and user.
151
    
152
    Creates the database record that links the social provider account
153
    to the local user account, storing the UID and provider information.
154
    
155
    Parameters:
156
    - backend: Authentication backend instance
157
    - uid: Provider user ID
158
    - user: User instance to associate with
159
    - Additional pipeline arguments
160
    
161
    Returns:
162
    Dictionary with 'social' key containing the association record
163
    """
164

165
def load_extra_data(backend, details, response, uid, user, *args, **kwargs):
166
    """
167
    Store additional provider data in social account.
168
    
169
    Saves extra information from the provider response (like access tokens,
170
    refresh tokens, profile data) to the social account record for later use.
171
    
172
    Parameters:
173
    - backend: Authentication backend instance
174
    - details: User details dictionary
175
    - response: Raw provider response data
176
    - uid: Provider user ID
177
    - user: User instance
178
    - Additional pipeline arguments
179
    
180
    Returns:
181
    Dictionary with updated social account information
182
    """
183
```
184

185
### Pipeline Constants and Configuration
186

187
Essential constants used throughout the pipeline system.
188

189
```python { .api }
190
# User fields that are automatically populated from provider data
191
USER_FIELDS: list = ["username", "email"]
192

193
# Data types that can be safely serialized in pipeline storage
194
SERIALIZABLE_TYPES: tuple = (
195
    dict, list, tuple, set, frozenset, bool, int, float, str, bytes, type(None)
196
)
197
```
198

199
### Pipeline Utilities
200

201
Helper functions for managing pipeline data and execution.
202

203
```python { .api }
204
def is_dict_type(value):
205
    """
206
    Check if value is a dictionary-like type.
207
    
208
    Parameters:
209
    - value: Value to check
210
    
211
    Returns:
212
    Boolean indicating if value is dict-like
213
    """
214

215
def partial_prepare(strategy, backend, next_step, user=None, social=None, *args, **kwargs):
216
    """
217
    Prepare partial pipeline data for storage.
218
    
219
    Parameters:
220
    - strategy: Strategy instance
221
    - backend: Authentication backend instance  
222
    - next_step: Next pipeline step index
223
    - user: User instance (optional)
224
    - social: Social account instance (optional)
225
    - Additional pipeline arguments
226
    
227
    Returns:
228
    Partial pipeline object
229
    """
230

231
def partial_store(strategy, backend, next_step, user=None, social=None, *args, **kwargs):
232
    """
233
    Store partial pipeline data.
234
    
235
    Parameters:
236
    - strategy: Strategy instance
237
    - backend: Authentication backend instance
238
    - next_step: Next pipeline step index
239
    - user: User instance (optional)
240
    - social: Social account instance (optional)
241
    - Additional pipeline arguments
242
    
243
    Returns:
244
    Stored partial pipeline object
245
    """
246

247
def partial_load(strategy, token):
248
    """
249
    Load partial pipeline data from token.
250
    
251
    Parameters:
252
    - strategy: Strategy instance
253
    - token: Partial pipeline token
254
    
255
    Returns:
256
    Partial pipeline object or None
257
    """
258
```
259

260
### User Management Pipeline Functions
261

262
Pipeline functions focused on user account creation and profile management.
263

264
```python { .api }
265
def get_username(strategy, details, backend, user=None, *args, **kwargs):
266
    """
267
    Generate username for user account.
268
    
269
    Creates a unique username based on provider data, handling conflicts
270
    by appending random strings until a unique username is found.
271
    
272
    Parameters:
273
    - strategy: Strategy instance
274
    - details: User details dictionary
275
    - backend: Authentication backend instance
276
    - user: Existing user instance (optional)
277
    - Additional pipeline arguments
278
    
279
    Returns:
280
    Dictionary with 'username' key containing generated username
281
    """
282

283
def create_user(strategy, details, backend, user=None, *args, **kwargs):
284
    """
285
    Create new user account if needed.
286
    
287
    Creates a new user account using the provided details if no existing
288
    user was found in earlier pipeline steps.
289
    
290
    Parameters:
291
    - strategy: Strategy instance
292
    - details: User details dictionary with user information
293
    - backend: Authentication backend instance
294
    - user: Existing user instance (optional)
295
    - Additional pipeline arguments
296
    
297
    Returns:
298
    Dictionary with 'user' and 'is_new' keys
299
    """
300

301
def user_details(strategy, details, backend, user=None, *args, **kwargs):
302
    """
303
    Update user account with latest provider information.
304
    
305
    Updates the user's profile information with the latest data from
306
    the social provider, such as name, email, or other profile fields.
307
    
308
    Parameters:
309
    - strategy: Strategy instance
310
    - details: User details dictionary with updated information
311
    - backend: Authentication backend instance  
312
    - user: User instance to update
313
    - Additional pipeline arguments
314
    
315
    Returns:
316
    Dictionary with updated user information
317
    """
318
```
319

320
### Email Validation Pipeline Functions
321

322
Pipeline functions for handling email verification workflows.
323

324
```python { .api }
325
def mail_validation(strategy, backend, code, *args, **kwargs):
326
    """
327
    Send email validation message to user.
328
    
329
    Sends a validation email to the user's email address to confirm
330
    ownership before completing the authentication process.
331
    
332
    Parameters:
333
    - strategy: Strategy instance
334
    - backend: Authentication backend instance
335
    - code: Validation code or token
336
    - Additional pipeline arguments
337
    
338
    Returns:
339
    Partial pipeline data to pause authentication until validation
340
    """
341
```
342

343
### Disconnection Pipeline Functions
344

345
Pipeline functions for removing social account associations.
346

347
```python { .api }
348
def allowed_to_disconnect(backend, user, user_social_auth, *args, **kwargs):
349
    """
350
    Verify that user is allowed to disconnect social account.
351
    
352
    Ensures the user won't be locked out of their account by removing
353
    this social authentication method (e.g., check for password or other login methods).
354
    
355
    Parameters:
356
    - backend: Authentication backend instance
357
    - user: User instance
358
    - user_social_auth: Social account association to disconnect
359
    - Additional pipeline arguments
360
    
361
    Raises:
362
    - NotAllowedToDisconnect: If disconnection would lock out user
363
    """
364

365
def get_entries(strategy, backend, user, user_social_auth, *args, **kwargs):
366
    """
367
    Collect social account associations to disconnect.
368
    
369
    Gathers all social account records that should be removed for this
370
    user and provider combination.
371
    
372
    Parameters:
373
    - strategy: Strategy instance
374
    - backend: Authentication backend instance
375
    - user: User instance
376
    - user_social_auth: Social account association to disconnect
377
    - Additional pipeline arguments
378
    
379
    Returns:
380
    Dictionary with 'entries' key containing associations to remove
381
    """
382

383
def revoke_tokens(strategy, backend, user, user_social_auth, *args, **kwargs):
384
    """
385
    Revoke access tokens with provider.
386
    
387
    Attempts to revoke access and refresh tokens with the social provider
388
    to ensure the application no longer has access to user data.
389
    
390
    Parameters:
391
    - strategy: Strategy instance
392
    - backend: Authentication backend instance
393
    - user: User instance
394
    - user_social_auth: Social account association being disconnected
395
    - Additional pipeline arguments
396
    """
397

398
def disconnect(strategy, backend, user, user_social_auth, *args, **kwargs):
399
    """
400
    Remove social account associations.
401
    
402
    Deletes the social account association records from the database,
403
    completing the disconnection process.
404
    
405
    Parameters:
406
    - strategy: Strategy instance
407
    - backend: Authentication backend instance
408
    - user: User instance
409
    - user_social_auth: Social account association to remove
410
    - Additional pipeline arguments
411
    """
412
```
413

414
### Pipeline Utilities
415

416
Helper functions for managing partial pipeline data and interruptions.
417

418
```python { .api }
419
def partial_prepare(backend, user, uid, details, *args, **kwargs):
420
    """
421
    Prepare data for partial pipeline storage.
422
    
423
    Serializes pipeline data for storage when authentication flow
424
    needs to be interrupted (e.g., for email validation).
425
    
426
    Parameters:
427
    - backend: Authentication backend instance
428
    - user: User instance (optional)
429
    - uid: Provider user ID
430
    - details: User details dictionary
431
    - Additional pipeline arguments
432
    
433
    Returns:
434
    Dictionary with pipeline data ready for storage
435
    """
436

437
def partial_store(strategy, pipeline, *args, **kwargs):
438
    """
439
    Store partial pipeline data.
440
    
441
    Saves pipeline state to session or database for later resumption
442
    when authentication flow is interrupted.
443
    
444
    Parameters:
445
    - strategy: Strategy instance  
446
    - pipeline: Pipeline configuration
447
    - Additional pipeline arguments
448
    
449
    Returns:
450
    Partial pipeline token for resuming later
451
    """
452

453
def partial_load(strategy, token):
454
    """
455
    Load partial pipeline data.
456
    
457
    Retrieves previously stored pipeline state using the provided token
458
    to resume an interrupted authentication flow.
459
    
460
    Parameters:
461
    - strategy: Strategy instance
462
    - token: Partial pipeline token
463
    
464
    Returns:
465
    Stored pipeline data dictionary or None if not found
466
    """
467
```
468

469
## Custom Pipeline Configuration
470

471
### Customizing Pipeline Steps
472

473
```python
474
# Add custom pipeline function
475
def require_email(strategy, details, *args, **kwargs):
476
    if not details.get('email'):
477
        raise AuthException(backend, 'Email is required')
478
    return {}
479

480
# Custom authentication pipeline
481
SOCIAL_AUTH_PIPELINE = (
482
    'social_core.pipeline.social_auth.social_details',
483
    'social_core.pipeline.social_auth.social_uid', 
484
    'myapp.pipeline.require_email',  # Custom step
485
    'social_core.pipeline.social_auth.auth_allowed',
486
    'social_core.pipeline.social_auth.social_user',
487
    'social_core.pipeline.user.get_username',
488
    'social_core.pipeline.user.create_user',
489
    'social_core.pipeline.social_auth.associate_user',
490
    'social_core.pipeline.social_auth.load_extra_data',
491
    'social_core.pipeline.user.user_details',
492
)
493
```
494

495
### Partial Pipeline Handling
496

497
The pipeline system supports interrupting authentication for additional user input:
498

499
```python
500
def collect_extra_info(strategy, backend, user, *args, **kwargs):
501
    """Collect additional user information if needed."""
502
    if user and not user.phone_number:
503
        # Interrupt pipeline to collect phone number
504
        return strategy.redirect('/auth/phone-number/')
505
    return {}
506
```
507

508
The pipeline system's modular design enables fine-grained control over authentication workflows while maintaining security and consistency across different providers and use cases.