Pipeline doc

diff --git a/README.rst b/README.rst
index 81f8bda9e60eee32550026922cc1b7d2f23b314a..351f3ae10c4f4aa8227237deb6f5a9ba500e1a59 100644 (file)
--- a/README.rst
+++ b/README.rst
@@ -52,6 +52,7 @@ credentials, some features are:
 
 - Custom User model override if needed (`auth.User`_ by default)
 
+- Extensible pipeline to handle authentication/association mechanism
 
 ------------
 Dependencies
@@ -317,6 +318,63 @@ Configuration
 
   Defaults to ``LOGIN_ERROR_URL``.
 
+
+-----------------------
+Authentication Pipeline
+-----------------------
+
+The final process of the authentication workflow is handled by a operations
+pipeline where custom functions can be added or default items can be removed to
+provide a custom behavior.
+
+The default pipeline mimics the user creation and basic data gathering from
+previous django-social-auth_ versions and a big set of settings (listed below)
+that were used to alter the default behavior are now deprecated in favor of
+pipeline overrides.
+
+The default pipeline is composed by::
+
+    (
+        'social_auth.backends.pipeline.social.social_auth_user',
+        'social_auth.backends.pipeline.associate.associate_by_email',
+        'social_auth.backends.pipeline.user.get_username',
+        'social_auth.backends.pipeline.user.create_user',
+        'social_auth.backends.pipeline.social.associate_user',
+        'social_auth.backends.pipeline.social.load_extra_data',
+        'social_auth.backends.pipeline.user.update_user_details'
+    )
+
+But it's possible to override it by defining the setting
+``SOCIAL_AUTH_PIPELINE``, for example a pipeline that won't create users, just
+accept already registered ones would look like this::
+
+    SOCIAL_AUTH_PIPELINE = (
+        'social_auth.backends.pipeline.social.social_auth_user',
+        'social_auth.backends.pipeline.social.load_extra_data',
+        'social_auth.backends.pipeline.user.update_user_details'
+    )
+
+Each pipeline function will receive the following parameters:
+    * Current social authentication backend
+    * User ID given by authentication provider
+    * User details given by authentication provider
+    * ``is_new`` flag (initialized in False)
+    * Any arguments passed to ``auth_complete`` backend method, default views
+      pass this arguments:
+        - current logged in user (if it's logged in, otherwise ``None``)
+        - current request
+
+Each pipeline entry must return a ``dict`` or ``None``, any value in the
+``dict`` will be used in the ``kwargs`` argument for the next pipeline entry.
+
+The workflow will be cut if the exception ``social_auth.backends.exceptions.StopPipeline``
+is raised at any point.
+
+If any function returns something else beside a ``dict`` or ``None``, the
+workflow will be cut and the value returned immediately, this is useful to
+return ``HttpReponse`` instances like ``HttpResponseRedirect``.
+
+
 -------------
 Usage example
 -------------

diff --git a/doc/index.rst b/doc/index.rst
index 926317cd0bb47414212f4fc1624eb1b819457adf..0e05651eb239f8c9d9fce669c1e39526524e4101 100644 (file)
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -15,6 +15,7 @@ Contents:
    configuration
 
    backends/index
+   pipeline
 
    signals
    contributions

diff --git a/doc/intro.rst b/doc/intro.rst
index ea32f25a9e20e98409396066c40ea3c92b6a7732..6d74dea918f9310e80f32dae1e353a38a84b8966 100644 (file)
--- a/doc/intro.rst
+++ b/doc/intro.rst
@@ -39,6 +39,8 @@ credentials, some features are:
 
 - Custom User model override if needed (`auth.User`_ by default)
 
+- Extensible pipeline to handle authentication/association mechanism
+
 .. _auth.User: http://code.djangoproject.com/browser/django/trunk/django/contrib/auth/models.py#L186
 .. _OpenId: http://openid.net/
 .. _OAuth: http://oauth.net/

diff --git a/doc/pipeline.rst b/doc/pipeline.rst
new file mode 100644 (file)
index 0000000..6c9d543
--- /dev/null
+++ b/doc/pipeline.rst
@@ -0,0 +1,53 @@
+Authentication Pipeline
+=======================
+
+The final process of the authentication workflow is handled by a operations
+pipeline where custom functions can be added or default items can be removed to
+provide a custom behavior.
+
+The default pipeline mimics the user creation and basic data gathering from
+previous django-social-auth_ versions and a big set of settings (listed below)
+that were used to alter the default behavior are now deprecated in favor of
+pipeline overrides.
+
+The default pipeline is composed by::
+
+    (
+        'social_auth.backends.pipeline.social.social_auth_user',
+        'social_auth.backends.pipeline.associate.associate_by_email',
+        'social_auth.backends.pipeline.user.get_username',
+        'social_auth.backends.pipeline.user.create_user',
+        'social_auth.backends.pipeline.social.associate_user',
+        'social_auth.backends.pipeline.social.load_extra_data',
+        'social_auth.backends.pipeline.user.update_user_details'
+    )
+
+But it's possible to override it by defining the setting
+``SOCIAL_AUTH_PIPELINE``, for example a pipeline that won't create users, just
+accept already registered ones would look like this::
+
+    SOCIAL_AUTH_PIPELINE = (
+        'social_auth.backends.pipeline.social.social_auth_user',
+        'social_auth.backends.pipeline.social.load_extra_data',
+        'social_auth.backends.pipeline.user.update_user_details'
+    )
+
+Each pipeline function will receive the following parameters:
+    * Current social authentication backend
+    * User ID given by authentication provider
+    * User details given by authentication provider
+    * ``is_new`` flag (initialized in False)
+    * Any arguments passed to ``auth_complete`` backend method, default views
+      pass this arguments:
+        - current logged in user (if it's logged in, otherwise ``None``)
+        - current request
+
+Each pipeline entry must return a ``dict`` or ``None``, any value in the
+``dict`` will be used in the ``kwargs`` argument for the next pipeline entry.
+
+The workflow will be cut if the exception ``social_auth.backends.exceptions.StopPipeline``
+is raised at any point.
+
+If any function returns something else beside a ``dict`` or ``None``, the
+workflow will be cut and the value returned immediately, this is useful to
+return ``HttpReponse`` instances like ``HttpResponseRedirect``.

diff --git a/social_auth/backends/__init__.py b/social_auth/backends/__init__.py
index eda7864eec0f60c20b283646cec75c64caa9d438..d026475d52a2f4c85b31c87abcd4947981e6804c 100644 (file)
--- a/social_auth/backends/__init__.py
+++ b/social_auth/backends/__init__.py
@@ -101,8 +101,8 @@ class SocialAuthBackend(ModelBackend):
         details = self.get_user_details(response)
         uid = self.get_user_id(details, response)
         out = self.pipeline(PIPELINE, backend=self, uid=uid,
-                            social_user=None, details=details,
-                            is_new=False, *args, **kwargs)
+                            details=details, is_new=False,
+                            *args, **kwargs)
         if not isinstance(out, dict):
             return out