Commits

Kenneth Love  committed 4d66fa9

django-social-auth

  • Participants
  • Parent commits 77919a0

Comments (0)

Files changed (2)

File docs/django_social_auth.rst

+============================
+``django-social-auth`` Setup
+============================
+
+1. Install the app
+------------------
+
+    ``pip install django-social-auth`` and wait a few minutes. This is a good time to get your API keys set up with Twitter, Facebook, whatever.
+
+
+2. ``settings.py``, where the work is really done
+-------------------------------------------------
+
+    1. Once it's installed, add it to your ``INSTALLED_APPS``.
+
+    2. Add ``'social_auth.context_processors.social_auth_by_type_backends'`` to your ``TEMPLATE_CONTEXT_PREPROCESSORS``. Yes, this means you probably have to go look them up in Django's documentation so that you don't 
+       override the defaults (why isn't this in there by default?) but that's OK.
+
+    3. Then comes a big block of settings. I usually put these at the end::
+
+        # SOCIAL AUTH SETTINGS
+        TWITTER_CONSUMER_KEY = 'your-key-here'
+        TWITTER_CONSUMER_SECRET = 'your-secret-here'
+        FACEBOOK_APP_ID = 'your-id-here'
+        FACEBOOK_API_SECRET = 'your-secrete-here'
+        SOCIAL_AUTH_ENABLED_BACKENDS = ('facebook', 'twitter')
+        SOCIAL_AUTH_COMPLETE_URL_NAME = 'socialauth_complete'
+        SOCIAL_AUTH_ASSOCIATE_URL_NAME = 'associate_complete'
+        SOCIAL_AUTH_DEFAULT_USERNAME = lambda u: slugify(u) # you'll need to import slugify from 'django.template.defaultfilters'
+        SOCIAL_AUTH_EXTRA_DATA = False
+        SOCIAL_AUTH_CHANGE_SIGNAL_ONLY = True
+
+        AUTHENTICATION_BACKENDS = (
+            'social_auth.backends.twitter.TwitterBackend',
+            'social_auth.backends.facebook.FacebookBackend',
+            'django.contrib.auth.backends.ModelBackend',
+        )
+
+        LOGIN_URL = '/login/'
+        LOGIN_REDIRECT_URL = '/'
+        LOGIN_ERROR_URL = '/login-error/'
+
+    4. Next, edit ``urls.py`` and add in ``url(r'', include('social_auth.urls'))``.
+
+    5. You'll want to set up some HTML links for people to login through::
+
+        <li><a href="{% url socialauth_begin 'twitter' %}">Login with Twitter</a></li>
+        <li><a href="{% url socialauth_begin 'facebook' %}">Login with Facebook</a></li>
+
+3. Explanations of a few bits
+-----------------------------
+
+    In the 3rd step above, you can configure a few things differently if you want.
+
+    1. ``SOCIAL_AUTH_ENABLED_BACKENDS`` needs to match the backends that you add to ``AUTHENTICATION_BACKENDS``. This lets you only load the backends you need.
+    2. Sadly, ``SOCIAL_AUTH_COMPLETE_URL_NAME`` and ``SOCIAL_AUTH_ASSOCIATE_URL_NAME`` seem to be magic settings with the last release. Just set them to this and don't worry about it unless you want to.
+    3. ``SOCIAL_AUTH_DEFAULT_USERNAME`` lets you set up a default username. You'll get one from the social auth service but it may not be compatible with Django's username requirements, hence the use of ``slugify()``.  
+       You could also use ``string.alphabet`` and some randomness to make a string for them.
+    4. Lastly, ``SOCIAL_AUTH_CHANGE_SIGNAL_ONLY`` stops the 3rd party apps from overriding anything the user has now entered in their ``User`` instance. For example, Twitter returns a user's full name as Django's 
+       ``first_name``. This means if you let them set first & last name, Twitter will override it each time they login. The ``SOCIAL_AUTH_EXTRA_DATA`` setting tells the backends we don't want any extra data they send 
+       through. If, though, you **do** want the data, obviously turn this off.
+
+4. Extra stuff
+--------------
+
+    Not something I use often, but you can set up signals for after a user logs in/signs up::
+
+        from social_auth.signals import pre_update
+        from social_auth.backends.twitter import TwitterBackend
+
+        def twitter_user_update(sender, user, response, details, **kwargs):
+            profile, create = Profile.objects.get_or_create(user=user)
+            profile.image = response['profile_image_url']
+
+            tokens = response['access_token'].split('&')
+            profile.oauth_token_secret = tokens[0].split('=')[-1]
+            profile.oauth_token = tokens[1].split('=')[-1]
+
+            if user.username != response['screen_name']:
+                redirect = Redirect.objects.get(new_path=profile.get_absolute_url())
+            else:
+                redirect = False
+
+            profile.user.username = response['screen_name']
+            if create:
+                profile.point = generate_point(lat=0, lng=0)
+            profile.save()
+            user.username = response['screen_name']
+            user.save()
+
+            if redirect:
+                redirect.new_path = profile.get_absolute_url()
+                redirect.save()
+
+            return True
+
+        pre_update.connect(twitter_user_update, sender=TwitterBackend)
+
+    This should be pretty self-explanatory if you're used to using signals in Django. This one, each time a user logs in, overrides their username and saves their tokens so we can post to Twitter as them.
+
+If you have any questions, hit me up on Twitter as @kennethlove

File docs/index.rst

 Notes, duh!
 
 DjangoCon 2011
------------
+--------------
 
 .. toctree::
-   :maxdepth: 1
-   
-   from_designer_to_djangoer
-   confessions_of_joe_developer
-   testing_the_developer_strikes_back
-   itch_scratching
-   django_package_thunderdome
-   real_world_django_deployment_with_chef
-   building_web_apis_in_django_with_tastypie
-   bottlenecks
-   best_practices_for_frontend_django_developers
-   designers_make_it_go_to_eleven
-   advanced_forms
-   teaching_django
+    :maxdepth: 1
 
-   lightning_talks
-   class_based_views
-   
+    from_designer_to_djangoer
+    confessions_of_joe_developer
+    testing_the_developer_strikes_back
+    itch_scratching
+    django_package_thunderdome
+    real_world_django_deployment_with_chef
+    building_web_apis_in_django_with_tastypie
+    bottlenecks
+    best_practices_for_frontend_django_developers
+    designers_make_it_go_to_eleven
+    advanced_forms
+    teaching_django
+
+    lightning_talks
+    class_based_views
+
+Other
+-----
+
+.. toctree::
+    :maxdepth: 1
+
+    django_social_auth