-==================
Django Social Auth
==================
You can check this documentation on `Read the Docs`_ too.
-----
+.. contents:: Table of Contents
+
Demo
----
+
There's a demo at http://social.matiasaguirre.net/.
Note: It lacks some backends support at the moment.
-
---------
Features
--------
+
This application provides user registration and login using social sites
credentials, some features are:
- Extensible pipeline to handle authentication/association mechanism
-------------
Dependencies
------------
+
Dependencies that **must** be meet to use the application:
- OpenId_ support depends on python-openid_
- Several backends demands application registration on their corresponding
sites.
-
-------------
Installation
------------
$ cd django-social-auth
$ sudo python setup.py install
-
--------------
Configuration
-------------
+
- Add social_auth to ``PYTHONPATH`` and installed applications::
INSTALLED_APPS = (
It's default value is ``DEBUG``, so you need to set it to ``False`` to avoid
tracebacks when ``DEBUG = True``.
-
------------------------
Authentication Pipeline
-----------------------
* ``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
+
+ - 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.
workflow will be cut and the value returned immediately, this is useful to
return ``HttpReponse`` instances like ``HttpResponseRedirect``.
-----------------
Partial Pipeline
----------------
Check the `example application`_ to check a basic usage.
-
----------------
Deprecated bits
---------------
SOCIAL_AUTH_ASSOCIATE_BY_MAIL
--------------
Usage example
-------------
FACEBOOK_APP_ID = 'real id here'
FACEBOOK_API_SECRET = 'real secret here'
--------
Signals
-------
+
A ``pre_update`` signal is sent when user data is about to be updated with new
values from authorization service provider, this apply to new users and already
existent ones. This is useful to update custom user fields or `User Profiles`_,
socialauth_registered.connect(new_users_handler, sender=None)
+Backends
+--------
-------
OpenId
-------
+^^^^^^
+
OpenId_ support is simpler to implement than OAuth_. Google and Yahoo
providers are supported by default, others are supported by POST method
providing endpoint URL.
Settings must be a list of tuples mapping value name in response and value
alias used to store.
-
------
OAuth
------
+^^^^^
+
OAuth_ communication demands a set of keys exchange to validate the client
authenticity prior to user approbation. Twitter, Facebook and Orkut
facilitates these keys by application registration, Google works the same,
Settings must be a list of tuples mapping value name in response and value
alias used to store.
-
--------
Twitter
--------
+^^^^^^^
+
Twitter offers per application keys named ``Consumer Key`` and ``Consumer Secret``.
To enable Twitter these two keys are needed. Further documentation at
`Twitter development resources`_:
Client type instead of the Browser. Almost any dummy value will work if
you plan some test.
-
---------
Facebook
---------
+^^^^^^^^
+
Facebook works similar to Twitter but it's simpler to setup and redirect URL
is passed as a parameter when issuing an authorization. Further documentation
at `Facebook development resources`_:
testing. Instead I define http://myapp.com and setup a mapping on /etc/hosts
or use dnsmasq_.
-
------
Orkut
------
+^^^^^
+
Orkut offers per application keys named ``Consumer Key`` and ``Consumer Secret``.
To enable Orkut these two keys are needed.
ORKUT_EXTRA_SCOPES = [...]
-
-------------
Google OAuth
-------------
+^^^^^^^^^^^^
+
Google provides ``Consumer Key`` and ``Consumer Secret`` keys to registered
applications, but also allows unregistered application to use their authorization
system with, but beware that this method will display a security banner to the
Check which applications can be included in their `Google Data Protocol Directory`_
-
--------------
Google OAuth2
--------------
+^^^^^^^^^^^^^
+
Recently Google launched OAuth2 support following the definition at `OAuth2 draft`.
It works in a similar way to plain OAuth mechanism, but developers **must** register
an application and apply for a set of keys. Check `Google OAuth2`_ document for details.
Check which applications can be included in their `Google Data Protocol Directory`_
-
---------
LinkedIn
---------
+^^^^^^^^
+
LinkedIn setup is similar to any other OAuth service. To request extra fields
using `LinkedIn fields selectors`_ just define the setting::
By default ``id``, ``first-name`` and ``last-name`` are requested and stored.
-
-------
GitHub
-------
+^^^^^^
+
GitHub works similar to Facebook (OAuth).
- Register a new application at `GitHub Developers`_, set your site domain as
GITHUB_EXTENDED_PERMISSIONS = [...]
-
--------
Dropbox
--------
+^^^^^^^
+
Dropbox uses OAuth v1.0 for authentication.
- Register a new application at `Dropbox Developers`_, and
DROPBOX_APP_ID = ''
DROPBOX_API_SECRET = ''
-
-------
Flickr
-------
+^^^^^^
+
Flickr uses OAuth v1.0 for authentication.
- Register a new application at the `Flickr App Garden`_, and
FLICKR_APP_ID = ''
FLICKR_API_SECRET = ''
-
----------
BrowserID
----------
+^^^^^^^^^
+
Support for BrowserID_ is possible by posting the ``assertion`` code to
``/complete/browserid/`` URL.
Check the second "Use Case" for an implementation example.
-
----------
Instagram
----------
+^^^^^^^^^
+
Instagram uses OAuth v2 for Authentication
- Register a new application at the `Instagram API`_, and
INSTAGRAM_CLIENT_ID = ''
INSTAGRAM_CLIENT_SECRET = ''
-*Note:*
-Instagram only allows one callback url so you'll have to change your urls.py to
-accomodate both ``/complete`` and ``/associate`` routes, for example by having
-a single ``/associate`` url which takes a ``?complete=true`` parameter for the
-cases when you want to complete rather than associate.
+.. note::
+ Instagram only allows one callback url so you'll have to change your urls.py to
+ accomodate both ``/complete`` and ``/associate`` routes, for example by having
+ a single ``/associate`` url which takes a ``?complete=true`` parameter for the
+ cases when you want to complete rather than associate.
--------
Testing
-------
+
To test the app just run::
./manage.py test social_auth
cd contrib/tests
./runtests.py
----------
Use Cases
---------
Some particular use cases are listed below.
)
2. Include a similar snippet in your page to make BrowserID_ work::
+
<!-- Include BrowserID JavaScript -->
<script src="https://browserid.org/include.js" type="text/javascript"></script>
});
</script>
-
--------------
Miscellaneous
-------------
+
Join to django-social-auth_ community on Convore_ and bring any questions or
suggestions that will improve this app.
-
If defining a custom user model, do not import social_auth from any models.py
that would finally import from the models.py that defines your User class or it
will make your project fail with a recursive import because social_auth uses
get_model() to retrieve your User.
-
There's an ongoing movement to create a list of third party backends on
djangopackages.com_, so, if somebody doesn't want it's backend in the
``contrib`` directory but still wants to share, just split it in a separated
package and link it there.
-
-----
Bugs
----
-Maybe several, please create `issues in github`_
+Maybe several, please create `issues in github`_
-------------
Contributors
------------
+
Attributions to whom deserves:
- caioariede_ (Caio Ariede):
- Instagram support
-----------
Copyrights
----------
+
Base work is copyrighted by:
- django-twitter-oauth::
projects / django-social-auth.git / commitdiff