django_social_auth.egg-info/
social_auth.egg-info/
env/
+doc/_build
--- /dev/null
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS =
+SPHINXBUILD = sphinx-build
+PAPER =
+BUILDDIR = _build
+
+# Internal variables.
+PAPEROPT_a4 = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest
+
+help:
+ @echo "Please use \`make <target>' where <target> is one of"
+ @echo " html to make standalone HTML files"
+ @echo " dirhtml to make HTML files named index.html in directories"
+ @echo " singlehtml to make a single large HTML file"
+ @echo " pickle to make pickle files"
+ @echo " json to make JSON files"
+ @echo " htmlhelp to make HTML files and a HTML help project"
+ @echo " qthelp to make HTML files and a qthelp project"
+ @echo " devhelp to make HTML files and a Devhelp project"
+ @echo " epub to make an epub"
+ @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+ @echo " latexpdf to make LaTeX files and run them through pdflatex"
+ @echo " text to make text files"
+ @echo " man to make manual pages"
+ @echo " changes to make an overview of all changed/added/deprecated items"
+ @echo " linkcheck to check all external links for integrity"
+ @echo " doctest to run all doctests embedded in the documentation (if enabled)"
+
+clean:
+ -rm -rf $(BUILDDIR)/*
+
+html:
+ $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+ @echo
+ @echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+dirhtml:
+ $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+ @echo
+ @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+singlehtml:
+ $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+ @echo
+ @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
+
+pickle:
+ $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+ @echo
+ @echo "Build finished; now you can process the pickle files."
+
+json:
+ $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+ @echo
+ @echo "Build finished; now you can process the JSON files."
+
+htmlhelp:
+ $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+ @echo
+ @echo "Build finished; now you can run HTML Help Workshop with the" \
+ ".hhp project file in $(BUILDDIR)/htmlhelp."
+
+qthelp:
+ $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+ @echo
+ @echo "Build finished; now you can run "qcollectiongenerator" with the" \
+ ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+ @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/DjangoSocialAuth.qhcp"
+ @echo "To view the help file:"
+ @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/DjangoSocialAuth.qhc"
+
+devhelp:
+ $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
+ @echo
+ @echo "Build finished."
+ @echo "To view the help file:"
+ @echo "# mkdir -p $$HOME/.local/share/devhelp/DjangoSocialAuth"
+ @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/DjangoSocialAuth"
+ @echo "# devhelp"
+
+epub:
+ $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
+ @echo
+ @echo "Build finished. The epub file is in $(BUILDDIR)/epub."
+
+latex:
+ $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+ @echo
+ @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+ @echo "Run \`make' in that directory to run these through (pdf)latex" \
+ "(use \`make latexpdf' here to do that automatically)."
+
+latexpdf:
+ $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+ @echo "Running LaTeX files through pdflatex..."
+ make -C $(BUILDDIR)/latex all-pdf
+ @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+text:
+ $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
+ @echo
+ @echo "Build finished. The text files are in $(BUILDDIR)/text."
+
+man:
+ $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
+ @echo
+ @echo "Build finished. The manual pages are in $(BUILDDIR)/man."
+
+changes:
+ $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+ @echo
+ @echo "The overview file is in $(BUILDDIR)/changes."
+
+linkcheck:
+ $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+ @echo
+ @echo "Link check complete; look for any errors in the above output " \
+ "or in $(BUILDDIR)/linkcheck/output.txt."
+
+doctest:
+ $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+ @echo "Testing of doctests in the sources finished, look at the " \
+ "results in $(BUILDDIR)/doctest/output.txt."
--- /dev/null
+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`_:
+
+- Register a new application at `Facebook App Creation`_, and
+
+- fill **App Id** and **App Secret** values in values::
+
+ FACEBOOK_APP_ID
+ FACEBOOK_API_SECRET
+
+- also it's possible to define extra permissions with::
+
+ FACEBOOK_EXTENDED_PERMISSIONS = [...]
+
+If you define a redirect URL in Facebook setup page, be sure to not
+define http://127.0.0.1:8000 or http://localhost:8000 because it won't
+work when testing. Instead I define http://myapp.com and setup a mapping
+on /etc/hosts or use dnsmasq_.
+
+
+.. _dnsmasq: http://www.thekelleys.org.uk/dnsmasq/doc.html
+.. _Facebook development resources: http://developers.facebook.com/docs/authentication/
+.. _Facebook App Creation: http://developers.facebook.com/setup/
--- /dev/null
+Google
+======
+
+This section describes how to setup the different services provided by
+Google.
+
+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 user telling that the application
+is not trusted.
+
+Check `Google OAuth`_ and make your choice.
+
+- fill **Consumer Key** and **Consumer Secret** values::
+
+ GOOGLE_CONSUMER_KEY
+ GOOGLE_CONSUMER_SECRET
+
+anonymous values will be used if not configured as described in their
+`OAuth reference`_
+
+
+- configure the display name to be used in the *grant permissions* dialog
+ that Google will display to users in::
+
+ GOOGLE_DISPLAY_NAME = ''
+
+ shows 'Social Auth' by default, but that might not suite your application.
+
+- setup any needed extra scope in::
+
+ GOOGLE_OAUTH_EXTRA_SCOPE = [...]
+
+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.
+
+**Note**:
+ This support is experimental as Google implementation may change and
+ OAuth2 is still a draft.
+
+To enable OAuth2 support:
+
+- fill **Client Key** and **Client Secret** settings, these values can be obtained
+ easily as described on `OAuth2 Registering`_ doc::
+
+ GOOGLE_OAUTH2_CLIENT_KEY = ''
+ GOOGLE_OAUTH2_CLIENT_SECRET = ''
+
+- scopes are shared between OAuth mechanisms::
+
+ GOOGLE_OAUTH_EXTRA_SCOPE = [...]
+
+Check which applications can be included in their `Google Data Protocol Directory`_
+
+
+Orkut
+-----
+
+Orkut offers per application keys named **Consumer Key** and
+**Consumer Secret**. To enable Orkut these two keys are needed.
+
+Check `Google support`_ and `Orkut API`_ for details on getting
+your consumer_key and consumer_secret keys.
+
+- fill **Consumer Key** and **Consumer Secret** values::
+
+ ORKUT_CONSUMER_KEY
+ ORKUT_CONSUMER_SECRET
+
+- add any needed extra data to::
+
+ ORKUT_EXTRA_DATA = ''
+
+- configure extra scopes in::
+
+ ORKUT_EXTRA_SCOPES = [...]
+
+
+.. _Google support: http://www.google.com/support/a/bin/answer.py?hl=en&answer=162105
+.. _Orkut API: http://code.google.com/apis/orkut/docs/rest/developers_guide_protocol.html#Authenticating
+.. _Google OpenID: http://code.google.com/apis/accounts/docs/OpenID.html
+.. _Google OAuth: http://code.google.com/apis/accounts/docs/OAuth.html
+.. _Google OAuth2: http://code.google.com/apis/accounts/docs/OAuth2.html
+.. _OAuth2 Registering: http://code.google.com/apis/accounts/docs/OAuth2.html#Registering
+.. _Google Data Protocol Directory: http://code.google.com/apis/gdata/docs/directory.html
+.. _OAuth2 draft: http://tools.ietf.org/html/draft-ietf-oauth-v2-10
+.. _OAuth reference: http://code.google.com/apis/accounts/docs/OAuth_ref.html#SigningOAuth
+.. _Orkut OAuth: http://code.google.com/apis/orkut/docs/rest/developers_guide_protocol.html#Authenticating
--- /dev/null
+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,
+but provides the option for unregistered applications.
+
+Check next sections for details.
+
+OAuth_ backends also can store extra data in UserSocialAuth.extra_data field
+by defining a set of values names to retrieve from service response.
+
+Settings is per backend and it's name is dynamically checked using uppercase
+backend name as prefix::
+
+ <uppercase backend name>_EXTRA_DATA
+
+Example::
+
+ FACEBOOK_EXTRA_DATA = [(..., ...)]
+
+Settings must be a list of tuples mapping value name in response and value
+alias used to store.
+
+
+.. _OAuth: http://oauth.net/
--- /dev/null
+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.
+
+OpenId_ backends can store extra data in UserSocialAuth.extra_data field
+by defining a set of values names to retrieve from any of the used schemas,
+pettributeExchange and SimpleRegistration. As their keywords differ we need
+two settings.
+
+Settings is per backend, so we have two possible values for each one. Name
+is dynamically checked using uppercase backend name as prefix::
+
+ <uppercase backend name>_SREG_EXTRA_DATA
+ <uppercase backend name>_AX_EXTRA_DATA
+
+Example::
+
+ GOOGLE_SREG_EXTRA_DATA = [(..., ...)]
+ GOOGLE_AX_EXTRA_DATA = [(..., ...)]
+
+Settings must be a list of tuples mapping value name in response and value
+alias used to store.
+
+.. _OpenId: http://openid.net/
+.. _OAuth: http://oauth.net/
--- /dev/null
+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`_:
+
+- Register a new application at `Twitter App Creation`_,
+
+- mark the **Yes, use Twitter for login** checkbox, and
+
+- fill **Consumer Key** and **Consumer Secret** values::
+
+ TWITTER_CONSUMER_KEY
+ TWITTER_CONSUMER_SECRET
+
+- You need to specify an URL callback or the application will be marked as
+ Client type instead of the Browser. Almost any dummy value will work if
+ you plan some test.
+
+.. _Twitter development resources: http://dev.twitter.com/pages/auth
+.. _Twitter App Creation: http://twitter.com/apps/new
--- /dev/null
+Bugs
+====
+Maybe several, please report `issues in github`_
+
+.. _issues in github: https://github.com/omab/django-social-auth/issues
--- /dev/null
+# -*- coding: utf-8 -*-
+#
+# Django Social Auth documentation build configuration file, created by
+# sphinx-quickstart on Sun Mar 20 23:07:14 2011.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#sys.path.insert(0, os.path.abspath('.'))
+
+# -- General configuration -----------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be extensions
+# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx', 'sphinx.ext.todo', 'sphinx.ext.viewcode']
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The encoding of source files.
+#source_encoding = 'utf-8-sig'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'Django Social Auth'
+copyright = u'2011, Matías Aguirre'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = '0.3.8'
+# The full version, including alpha/beta/rc tags.
+release = '0.3.8'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#language = None
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+#today_fmt = '%B %d, %Y'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = ['_build']
+
+# The reST default role (used for this markup: `text`) to use for all documents.
+#default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# A list of ignored prefixes for module index sorting.
+#modindex_common_prefix = []
+
+
+# -- Options for HTML output ---------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages. See the documentation for
+# a list of builtin themes.
+html_theme = 'default'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further. For a list of options available for each theme, see the
+# documentation.
+#html_theme_options = {}
+
+# Add any paths that contain custom themes here, relative to this directory.
+#html_theme_path = []
+
+# The name for this set of Sphinx documents. If None, it defaults to
+# "<project> v<release> documentation".
+#html_title = None
+
+# A shorter title for the navigation bar. Default is the same as html_title.
+#html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+#html_logo = None
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+#html_favicon = None
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+#html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+#html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+
+# If false, no module index is generated.
+#html_domain_indices = True
+
+# If false, no index is generated.
+#html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+#html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+#html_show_sourcelink = True
+
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
+#html_show_sphinx = True
+
+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
+#html_show_copyright = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it. The value of this option must be the
+# base URL from which the finished HTML is served.
+#html_use_opensearch = ''
+
+# This is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = None
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'DjangoSocialAuthdoc'
+
+
+# -- Options for LaTeX output --------------------------------------------------
+
+# The paper size ('letter' or 'a4').
+#latex_paper_size = 'letter'
+
+# The font size ('10pt', '11pt' or '12pt').
+#latex_font_size = '10pt'
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, documentclass [howto/manual]).
+latex_documents = [
+ ('index', 'DjangoSocialAuth.tex', u'Django Social Auth Documentation',
+ u'Matías Aguirre', 'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+#latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+#latex_use_parts = False
+
+# If true, show page references after internal links.
+#latex_show_pagerefs = False
+
+# If true, show URL addresses after external links.
+#latex_show_urls = False
+
+# Additional stuff for the LaTeX preamble.
+#latex_preamble = ''
+
+# Documents to append as an appendix to all manuals.
+#latex_appendices = []
+
+# If false, no module index is generated.
+#latex_domain_indices = True
+
+
+# -- Options for manual page output --------------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+ ('index', 'djangosocialauth', u'Django Social Auth Documentation',
+ [u'Matías Aguirre'], 1)
+]
+
+
+# Example configuration for intersphinx: refer to the Python standard library.
+intersphinx_mapping = {'http://docs.python.org/': None}
--- /dev/null
+Configuration
+=============
+
+- Add social_auth to PYTHONPATH and installed applications::
+
+ INSTALLED_APPS = (
+ ...
+ 'social_auth'
+ )
+
+- Add desired authentication backends to AUTHENTICATION_BACKENDS_ setting::
+
+ AUTHENTICATION_BACKENDS = (
+ 'social_auth.backends.twitter.TwitterBackend',
+ 'social_auth.backends.facebook.FacebookBackend',
+ 'social_auth.backends.google.GoogleOAuthBackend',
+ 'social_auth.backends.google.GoogleOAuth2Backend',
+ 'social_auth.backends.google.GoogleBackend',
+ 'social_auth.backends.yahoo.YahooBackend',
+ 'social_auth.backends.contrib.linkedin.LinkedinBackend',
+ 'social_auth.backends.contrib.LiveJournalBackend',
+ 'social_auth.backends.contrib.orkut.OrkutBackend',
+ 'social_auth.backends.OpenIDBackend',
+ 'django.contrib.auth.backends.ModelBackend',
+ )
+
+ Note: this was introduced in a recent change and it's not backward
+ compatible, take into account that saved sessions won't be able to login
+ because the backend string stored in session (like backends.TwitterBackend)
+ won't match the new paths.
+
+- The application will try to import custom backends from the sources defined in::
+
+ SOCIAL_AUTH_IMPORT_BACKENDS = (
+ 'myproy.social_auth_extra_services',
+ )
+
+ This way it's easier to add new providers, check the already defined ones
+ in social_auth.backends for examples.
+
+ Take into account that backends **must** be defined in AUTHENTICATION_BACKENDS_
+ or Django won't pick them when trying to authenticate the user.
+
+- Setup Twitter, Facebook, Orkut and Google OAuth keys (see OAuth_ section
+ for details)::
+
+ TWITTER_CONSUMER_KEY = ''
+ TWITTER_CONSUMER_SECRET = ''
+ FACEBOOK_APP_ID = ''
+ FACEBOOK_API_SECRET = ''
+ LINKEDIN_CONSUMER_KEY = ''
+ LINKEDIN_CONSUMER_SECRET = ''
+ ORKUT_CONSUMER_KEY = ''
+ ORKUT_CONSUMER_SECRET = ''
+ GOOGLE_CONSUMER_KEY = ''
+ GOOGLE_CONSUMER_SECRET = ''
+
+- Setup login URLs::
+
+ LOGIN_URL = '/login-form/'
+ LOGIN_REDIRECT_URL = '/logged-in/'
+ LOGIN_ERROR_URL = '/login-error/'
+
+ Check Django documentation at `Login URL`_ and `Login redirect URL`_
+
+ In case of authentication error, the message can be stored in session
+ if the following setting is defined::
+
+ SOCIAL_AUTH_ERROR_KEY = 'social_errors'
+
+ This defines the desired session key where last error message should be
+ stored. It's disabled by default.
+
+- Configure authentication and association complete URL names to avoid
+ possible clashes::
+
+ SOCIAL_AUTH_COMPLETE_URL_NAME = 'complete'
+ SOCIAL_AUTH_ASSOCIATE_URL_NAME = 'associate_complete'
+
+- Add URLs entries::
+
+ urlpatterns = patterns('',
+ ...
+ url(r'', include('social_auth.urls')),
+ ...
+ )
+
+- Sync database to create needed models::
+
+ ./manage.py syncdb
+
+- Not mandatory, but recommended::
+
+ SOCIAL_AUTH_DEFAULT_USERNAME = 'new_social_auth_user'
+
+ or::
+
+ import random
+ SOCIAL_AUTH_DEFAULT_USERNAME = lambda: random.choice(['Darth Vader', 'Obi-Wan Kenobi', 'R2-D2', 'C-3PO', 'Yoda'])
+
+ or::
+
+ from django.template.defaultfilter import slugify
+ SOCIAL_AUTH_USERNAME_FIXER = lambda u: slugify(u)
+
+ in case your user layout needs to purify username on some weird way.
+
+ Final user name will have an integer suffix in case it's already taken.
+
+- Backends will store extra values from response by default, set this to False
+ to avoid such behavior::
+
+ SOCIAL_AUTH_EXTRA_DATA = False
+
+ Also more extra values will be stored if defined, details about this setting
+ are listed below on OpenId and OAuth sections.
+
+ Session expiration time is an special value, it's recommended to define::
+
+ SOCIAL_AUTH_EXPIRATION = 'expires'
+
+ to and use such setting name where expiration times are returned. View that
+ completes login process will set session expiration time using this name if
+ it's present or 'expires' by default. Expiration time saving can be disabled
+ setting::
+
+ SOCIAL_AUTH_SESSION_EXPIRATION = False
+
+- It's possible to override the used User model if needed::
+
+ SOCIAL_AUTH_USER_MODEL = 'myapp.CustomUser'
+
+ This class **must** have a custom `Model Manager`_ with a create_user method
+ that resembles the one on `auth.UserManager`_.
+
+ Also, it's highly recommended that this class define the following fields::
+
+ username = CharField(...)
+ last_login = DateTimeField(blank=True)
+ is_active = BooleanField(...)
+
+ and the method::
+
+ is_authenticated():
+ ...
+
+ These are needed to ensure a better django-auth integration, in other case
+ `login_required`_ won't be usable. A warning is displayed if any of these are
+ missing. By default `auth.User`_ is used.
+
+ Check example application for implementation details, but first, please take
+ a look to `User Profiles`_, it might be what you were looking for.
+
+.. _Model Manager: http://docs.djangoproject.com/en/dev/topics/db/managers/#managers
+.. _Login URL: http://docs.djangoproject.com/en/dev/ref/settings/?from=olddocs#login-url
+.. _Login redirect URL: http://docs.djangoproject.com/en/dev/ref/settings/?from=olddocs#login-redirect-url
+.. _AUTHENTICATION_BACKENDS: http://docs.djangoproject.com/en/dev/ref/settings/?from=olddocs#authentication-backends
+.. _auth.User: http://code.djangoproject.com/browser/django/trunk/django/contrib/auth/models.py#L186
+.. _auth.UserManager: http://code.djangoproject.com/browser/django/trunk/django/contrib/auth/models.py#L114
+.. _login_required: http://code.djangoproject.com/browser/django/trunk/django/contrib/auth/decorators.py#L39
+.. _User Profiles: http://www.djangobook.com/en/1.0/chapter12/#cn222
+.. _OAuth: http://oauth.net/
--- /dev/null
+Contributions
+=============
+
+Attributions to whom deserves:
+
+caioariede_ (Caio Ariede):
+ * Improvements and Orkut support
+
+krvss_ (Stas Kravets):
+ * Initial setup.py configuration
+
+jezdez_ (Jannis Leidel):
+ * Improvements and documentation update
+
+alfredo_ (Alfredo Ramirez)
+ * Facebook and Doc improvements
+
+mattucf_ (Matt Brown)
+ * Twitter and OAuth improvements
+
+Quard_ (Vadym Zakovinko)
+ * LinkedIn support
+
+micrypt_ (Seyi Ogunyemi)
+ * python-oauth2_ migration
+
+djm_ (Darian Moody)
+ * Improvements
+
+bernardokyotoku_ (Bernardo Kyotoku)
+ * Improvements
+
+maraujop_ (Miguel Araujo)
+ * Improvements
+
+.. _caioariede: https://github.com/caioariede
+.. _krvss: https://github.com/krvss
+.. _jezdez: https://github.com/jezdez
+.. _alfredo: https://github.com/alfredo
+.. _mattucf: https://github.com/mattucf
+.. _Quard: https://github.com/Quard
+.. _micrypt: https://github.com/micrypt
+.. _djm: https://github.com/djm
+.. _bernardokyotoku: https://github.com/bernardokyotoku
+.. _maraujop: https://github.com/maraujop
+.. _python-oauth2: https://github.com/simplegeo/python-oauth2
--- /dev/null
+Demo
+====
+There's a demo at http://social.matiasaguirre.net/.
+
+**Note**: It lacks Orkut support at the moment.
--- /dev/null
+.. Django Social Auth documentation master file, created by
+ sphinx-quickstart on Sun Mar 20 23:07:14 2011.
+ You can adapt this file completely to your liking, but it should at least
+ contain the root `toctree` directive.
+
+Welcome to Django Social Auth's documentation!
+==============================================
+
+Django Social Auth is an easy to setup social authentication/authorization
+mechanism for Django projects.
+
+Contents:
+
+.. toctree::
+ :maxdepth: 2
+
+ intro
+ demo
+ installing
+ configuration
+
+ backends/openid
+ backends/oauth
+ backends/google
+ backends/facebook
+ backends/twitter
+
+ signals
+ contributions
+ testing
+ bugs
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
--- /dev/null
+
+Installation
+============
+
+------------
+Dependencies
+------------
+Dependencies that **must** be meet to use the application:
+
+- OpenId_ support depends on python-openid_
+
+- OAuth_ support depends on python-oauth2_
+
+- Twitter and Facebook support demands an application registration
+ on their corresponding sites.
+
+
+----------
+Get a copy
+----------
+
+From pypi_::
+
+ $ pip install django-social-auth
+
+or::
+
+ $ easy_install django-social-auth
+
+or clone from github_::
+
+ $ git clone git://github.com/omab/django-social-auth.git
+
+and add social_auth to PYTHONPATH::
+
+ $ export PYTHONPATH=$PYTHONPATH:$(pwd)/django-social-auth/
+
+or::
+
+ $ cd django-social-auth
+ $ sudo python setup.py install
+
+
+.. _OpenId: http://openid.net/
+.. _OAuth: http://oauth.net/
+.. _pypi: http://pypi.python.org/pypi/django-social-auth/
+.. _github: https://github.com/omab/django-social-auth
+.. _python-openid: http://pypi.python.org/pypi/python-openid/
+.. _python-oauth2: https://github.com/simplegeo/python-oauth2
--- /dev/null
+Introduction
+============
+
+Django Social Auth is an easy to setup social authentication/authorization
+mechanism for Django projects.
+
+Crafted using base code from django-twitter-oauth_ and django-openid-auth_,
+implements a common interface to define new authentication providers from
+third parties.
+
+
+--------
+Features
+--------
+This application provides user registration and login using social sites
+credentials, some features are:
+
+- Registration and Login using social sites using the following providers
+ at the moment:
+
+ * `Google OpenID`_
+ * `Google OAuth`_
+ * `Google OAuth2`_
+ * `Yahoo OpenID`_
+ * OpenId_ like myOpenID_
+ * `Twitter OAuth`_
+ * `Facebook OAuth`_
+
+ Some contributions added support for:
+
+ * `LiveJournal OpenID`_
+ * `Orkut OAuth`_
+ * `Linkedin OAuth`_
+
+- Basic user data population and signaling, to allows custom fields values
+ from providers response
+
+- Multiple social accounts association to single users
+
+- Custom User model override if needed (`auth.User`_ by default)
+
+.. _auth.User: http://code.djangoproject.com/browser/django/trunk/django/contrib/auth/models.py#L186
+.. _OpenId: http://openid.net/
+.. _OAuth: http://oauth.net/
+.. _django-twitter-oauth: https://github.com/henriklied/django-twitter-oauth
+.. _django-openid-auth: https://launchpad.net/django-openid-auth
+.. _Google OpenID: http://code.google.com/apis/accounts/docs/OpenID.html
+.. _Google OAuth: http://code.google.com/apis/accounts/docs/OAuth.html
+.. _Google OAuth2: http://code.google.com/apis/accounts/docs/OAuth2.html
+.. _Yahoo OpenID: http://openid.yahoo.com/
+.. _Twitter OAuth: http://dev.twitter.com/pages/oauth_faq
+.. _Facebook OAuth: http://developers.facebook.com/docs/authentication/
+.. _Linkedin OAuth: https://www.linkedin.com/secure/developer
+.. _Orkut OAuth: http://code.google.com/apis/orkut/docs/rest/developers_guide_protocol.html#Authenticating
+.. _myOpenID: https://www.myopenid.com/
+.. _LiveJournal OpenID: http://www.livejournal.com/support/faqbrowse.bml?faqid=283
--- /dev/null
+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`_,
+for example, to store user gender, location, etc. Example::
+
+ from social_auth.signals import pre_update
+ from social_auth.backends.facebook import FacebookBackend
+
+ def facebook_extra_values(sender, user, response, details, **kwargs):
+ user.gender = response.get('gender')
+ return True
+
+ pre_update.connect(facebook_extra_values, sender=FacebookBackend)
+
+New data updating is made automatically but could be disabled and left only to
+signal handler if this setting value is set to True::
+
+ SOCIAL_AUTH_CHANGE_SIGNAL_ONLY = False
+
+Take into account that when defining a custom User model and declaring signal
+handler in models.py, the imports and handler definition *must* be made after
+the custom User model is defined or circular imports issues will be raised.
+
+
+.. _User Profiles: http://www.djangobook.com/en/1.0/chapter12/#cn222
--- /dev/null
+Testing
+=======
+Django-social-auth aims to be a fully tested project, some partial test are
+present at the moment and others are being worked.
+
+To test the app just run::
+
+ ./manage.py test social_auth
+
+This will run a bunch of tests, so far only login process is tested, more
+will come eventually.
+
+User accounts on the different sites are needed to run test, here's how it's
+configured::
+
+ TEST_TWITTER_USER = 'testing_account'
+ TEST_TWITTER_PASSWORD = 'password_for_testing_account'
projects / django-social-auth.git / commitdiff