Django Framework¶
Django framework has a little more support since this application was derived from django-social-auth. Here are some details on configuring this application on Django.
Register the application¶
The Django built-in app comes with two ORMs, one for default Django ORM and another for MongoEngine ORM.
Add the application to INSTALLED_APPS
setting, for default ORM:
INSTALLED_APPS = (
...
'social.apps.django_app.default',
...
)
And for MongoEngine ORM:
INSTALLED_APPS = (
...
'social.apps.django_app.me',
...
)
Also ensure to define the MongoEngine storage setting:
SOCIAL_AUTH_STORAGE = 'social.apps.django_app.me.models.DjangoStorage'
Database¶
(For Django 1.7 and higher) sync database to create needed models:
./manage.py migrate
If you’re still using South, you’ll need override SOUTH_MIGRATION_MODULES:
SOUTH_MIGRATION_MODULES = {
'default': 'social.apps.django_app.default.south_migrations'
}
Note that Django’s app labels take the last part of the import, so
in this case social.apps.django_app.default
becomes default
here.
Sync database to create needed models:
./manage.py syncdb
Authentication backends¶
Add desired authentication backends to Django’s AUTHENTICATION_BACKENDS setting:
AUTHENTICATION_BACKENDS = (
'social.backends.open_id.OpenIdAuth',
'social.backends.google.GoogleOpenId',
'social.backends.google.GoogleOAuth2',
'social.backends.google.GoogleOAuth',
'social.backends.twitter.TwitterOAuth',
'social.backends.yahoo.YahooOpenId',
...
'django.contrib.auth.backends.ModelBackend',
)
Take into account that backends must be defined in AUTHENTICATION_BACKENDS or Django won’t pick them when trying to authenticate the user.
Don’t miss django.contrib.auth.backends.ModelBackend
if using django.contrib.auth
application or users won’t be able to login by username / password method.
URLs entries¶
Add URLs entries:
urlpatterns = patterns('',
...
url('', include('social.apps.django_app.urls', namespace='social'))
...
)
In case you need a custom namespace, this setting is also needed:
SOCIAL_AUTH_URL_NAMESPACE = 'social'
Template Context Processors¶
There’s a context processor that will add backends and associations data to template context:
TEMPLATE_CONTEXT_PROCESSORS = (
...
'social.apps.django_app.context_processors.backends',
'social.apps.django_app.context_processors.login_redirect',
...
)
backends
context processor will load a backends
key in the context with
three entries on it:
associated
- It’s a list of
UserSocialAuth
instances related with the currently logged in user. Will be empty if there’s no current user. not_associated
- A list of available backend names not associated with the current user yet. If there’s no user logged in, it will be a list of all available backends.
backends
- A list of all available backend names.
ORMs¶
As detailed above the built-in Django application supports default ORM and MongoEngine ORM.
When using MongoEngine make sure you’ve followed the instructions for MongoEngine Django integration, as you’re now utilizing that user model. The MongoEngine_ backend was developed and tested with version 0.6.10 of MongoEngine_.
Alternate storage models implementations currently follow a tight pattern of
models that behave near or identical to Django ORM models. It is currently
not decoupled from this pattern by any abstraction layer. If you would like
to implement your own alternate, please see the
social.apps.django_app.default.models
and
social.apps.django_app.me.models
modules for guidance.
Exceptions Middleware¶
A base middleware is provided that handles SocialAuthBaseException
by
providing a message to the user via the Django messages framework, and then
responding with a redirect to a URL defined in one of the middleware methods.
The middleware is at social.apps.django_app.middleware.SocialAuthExceptionMiddleware
.
Any method can be overridden, but for simplicity these two are recommended:
get_message(request, exception)
get_redirect_uri(request, exception)
By default, the message is the exception message and the URL for the redirect
is the location specified by the LOGIN_ERROR_URL
setting.
If a valid backend was detected by strategy()
decorator, it will be
available at request.strategy.backend
and process_exception()
will
use it to build a backend-dependent redirect URL but fallback to default if not
defined.
Exception processing is disabled if any of this settings is defined with a
True
value:
<backend name>_SOCIAL_AUTH_RAISE_EXCEPTIONS = True
SOCIAL_AUTH_RAISE_EXCEPTIONS = True
RAISE_EXCEPTIONS = True
DEBUG = True
The redirect destination will get two GET
parameters:
message = ''
- Message from the exception raised, in some cases it’s the message returned by the provider during the auth process.
backend = ''
- Backend name that was used, if it was a valid backend.
Django Admin¶
The default application (not the MongoEngine one) contains an admin.py
module that will be auto-discovered by the usual mechanism.
But, by the nature of the application which depends on the existence of a user
model, it’s easy to fall in a recursive import ordering making the application
fail to load. This happens because the admin module will build a set of fields
to populate the search_fields
property to search for related users in the
administration UI, but this requires the user model to be retrieved which might
not be defined at that time.
To avoid this issue define the following setting to circumvent the import error:
SOCIAL_AUTH_ADMIN_USER_SEARCH_FIELDS = ['field1', 'field2']
For example:
SOCIAL_AUTH_ADMIN_USER_SEARCH_FIELDS = ['username', 'first_name', 'email']
The fields listed must be user models fields.