What it does
-----------------
This is a application to enable authentication via various third party sites.
In particular it allows logging in via

Twitter
Gmail
Facebook
Yahoo(Essentially openid)
OpenId

How it works
-------------------
1. For all providers(except Facebook) there are two urls and views. (start and done)
2. Start sets up the required tokens, and redirects and hands off to the correct
provider.
3. Provider handles authentication on their ends, and hands off to Us, providing
authorization tokens.
4. In done, we check if the user with these details already exists, if yes, we
log them in. Otherwise we create a new user, and log them in.

For all of these, we use standard django authenication system, with custom
auth_backends, hence all existing views, and decorators as @login_required
will work as expected.

API References
http://openid.net/developers/
http://developer.yahoo.com/openid/
http://code.google.com/apis/accounts/docs/OpenID.html
http://apiwiki.twitter.com/OAuth-FAQ
http://developers.facebook.com/connect.php

Limitations
--------------
As with all APIs, we are limited by the amout of data which the API provider
provides us. For example, both Yahoo and Google provide extremely limited data
about the autheticated subscriber. Twitter and Facebook provide a lot of details,
but not the email. Different Openid providers are free to provide [different
amounts of data](http://openid.net/specs/openid-simple-registration-extension-1_0.html).

Implementation
----------------
1. Install required libraries.

  `pip install python-openid python-yadis oauth`

2. Add `socialauth` to `INSTALLED_APPS`

3. Include required urls

  `(r'^accounts/', include('socialauth.urls')),`

  Urls
  ---------

  /login/ Login page. Has all the login options
  /openid_login/ AND /openid_login/done/
  /yahoo_login/ AND /yahoo_login/done/
  /gmail_login/ AND /gmail_login/done/
  /twitter_login/ AND /twitter_login/done/
  /facebook_login/done/ We dont have a start url here, as the starting tokens are
  set in a popup, as per FB Connect recommendations.

4. Add required settings

   OPENID_REDIRECT_NEXT = '/accounts/openid/done/'
   OPENID_SREG = {"requred": "nickname, email", "optional":"postcode, country", "policy_url": ""}
   OPENID_AX = [{"type_uri": "email", "count": 1, "required": False, "alias": "email"}, {"type_uri": "fullname", "count":1 , "required": False, "alias": "fullname"}]
   TWITTER_CONSUMER_KEY = ''
   TWITTER_CONSUMER_SECRET = ''
   FACEBOOK_API_KEY = ''
   FACEBOOK_API_SECRET = ''
   LOGIN_REDIRECT_URL = '/login/done/'

   The API Keys are available from

   http://www.facebook.com/developers/createapp.php 
   https://developer.yahoo.com/dashboard/createKey.html
   https://www.google.com/accounts/ManageDomains
   http://twitter.com/oauth_clients 

5. Set the authentication_backends to the providers you are using.

   AUTHENTICATION_BACKENDS = ('django.contrib.auth.backends.ModelBackend',
                               'socialauth.auth_backends.OpenIdBackend',
                               'socialauth.auth_backends.TwitterBackend',
                               'socialauth.auth_backends.FacebookBackend',
                             )

6. If using them, set the token callback urls correctly for Twitter and Facebook.