From: Matías Aguirre Date: Sun, 5 Feb 2012 17:08:36 +0000 (-0200) Subject: Pipeline doc X-Git-Url: https://git.parisson.com/?a=commitdiff_plain;h=4324de1709d30d025d68806212bb9a2fd763bfbc;p=django-social-auth.git Pipeline doc --- diff --git a/README.rst b/README.rst index 81f8bda..351f3ae 100644 --- 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 926317c..0e05651 100644 --- 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 ea32f25..6d74dea 100644 --- 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 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 eda7864..d026475 100644 --- 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