Django Framework¶

Установка¶

От pypi:

$ pip install social-auth-app-django

И для MongoEngine ORM:

$ pip install social-auth-app-django-mongoengine

Зарегистрируйте приложение¶

Django built-in app поставляется с двумя ORM, один для стандартного Django ORM и другой для MongoEngine ORM.

Добавьте приложение к настройке INSTALLED_APPS, для ORM по умолчанию:

INSTALLED_APPS = (
    ...
    'social_django',
    ...
)

И для MongoEngine ORM:

INSTALLED_APPS = (
    ...
    'social_django_mongoengine',
    ...
)

Также убедитесь, что определили настройки хранилища MongoEngine:

SOCIAL_AUTH_STORAGE = 'social_django_mongoengine.models.DjangoStorage'

База данных¶

(For Django 1.7 and higher) you need to sync the database to create needed models once you added social_django to your installed apps:

./manage.py migrate

При использовании PostgreSQL рекомендуется использовать встроенное поле JSONB для хранения извлеченных extra_data. Чтобы включить его, определите настройку:

SOCIAL_AUTH_POSTGRES_JSONFIELD = True

Бэкенды аутентификации¶

Добавьте желаемые бэкенды аутентификации в настройку AUTHENTICATION_BACKENDS в Django:

AUTHENTICATION_BACKENDS = (
    'social_core.backends.open_id.OpenIdAuth',
    'social_core.backends.google.GoogleOpenId',
    'social_core.backends.google.GoogleOAuth2',
    'social_core.backends.google.GoogleOAuth',
    'social_core.backends.twitter.TwitterOAuth',
    'social_core.backends.yahoo.YahooOpenId',
    ...
    'django.contrib.auth.backends.ModelBackend',
)

Учтите, что бэкенды должны быть определены в AUTHENTICATION_BACKENDS, иначе Django не выберет их при попытке аутентификации пользователя.

Не пропустите django.contrib.auth.backends.ModelBackend при использовании приложения django.contrib.auth, иначе пользователи не смогут войти в систему по методу имя пользователя / пароль.

Записи URL-адресов¶

Добавить записи URL-адресов:

urlpatterns = patterns('',
    ...
    url('', include('social_django.urls', namespace='social'))
    ...
)

В случае, если вам нужно пользовательское пространство имен, этот параметр также необходим:

SOCIAL_AUTH_URL_NAMESPACE = 'social'

Шаблоны¶

Пример использования бэкенда google-oauth2 в шаблоне:

<a href="{% url "social:begin" "google-oauth2" %}">Google+</a>

Контекстные процессоры шаблонов¶

Существует контекстный процессор, который будет добавлять данные бэкендов и ассоциаций в контекст шаблона:

TEMPLATES = [
    {
        ...
        'OPTIONS': {
            ...
            'context_processors': [
                ...
                'social_django.context_processors.backends',
                'social_django.context_processors.login_redirect',
                ...
            ]
        }
    }
]

backends контекстный процессор загрузит в контекст ключ backends с тремя записями на нем:

associated

Это список UserSocialAuth экземпляров, связанных с текущим вошедшим пользователем. Будет пустым, если текущего пользователя нет.

not_associated

Список доступных имен бэкендов, еще не связанных с текущим пользователем. Если пользователь не вошел в систему, это будет список всех доступных бэкендов.

backends

Список всех доступных имен бэкендов.

Индивидуальная конфигурация¶

Вы можете добавить (или убрать) несколько функций на конвейере социальных аутентификаций.

По умолчанию в social_django есть несколько конвейеров:

social_details - Получение информации о пользователе и возвращение ее в простом формате для последующего создания экземпляра пользователя. В некоторых случаях информация уже является частью ответа auth от провайдера, но иногда она может попасть в API провайдера.

social_uid - Получение социального uid от того сервиса, через который мы проводим аутентификацию. uid - это уникальный идентификатор данного пользователя в провайдере.

auth_allowed - Проверяет, что текущий процесс авторизации действителен в рамках текущего проекта, здесь применяются белые списки электронной почты и доменов (если они определены).

social_user - Проверяет, связан ли текущий social-account с сайтом.

get_username- Придумать имя пользователя для этого человека, добавляет случайную строку в конце, если есть коллизия.

create_user - Создать учетную запись пользователя, если она еще не найдена.

associate_user - Создать запись, которая ассоциирует социальный аккаунт с данным пользователем.

extra_data - Заполнить поле extra_data в социальной записи значениями, указанными в настройках (и значениями по умолчанию, такими как access_token и т.д.).

user_details - Обновление записи пользователя с любой измененной информацией из службы авторизации.

Некоторые другие конвейеры также доступны для использования, но не включены по умолчанию:

associate_by_email - ассоциировать текущий аут с пользователем с таким же адресом электронной почты в БД. Обс: Этот элемент конвейера не является на 100% безопасным, если вы не знаете, что провайдеры включили проверку электронной почты на своей стороне, иначе пользователь может попытаться завладеть учетной записью другого пользователя, используя тот же (не подтвержденный) адрес электронной почты на каком-либо провайдере.

Пример использования:

SOCIAL_AUTH_PIPELINE = (
    'social_core.pipeline.social_auth.social_details',
    'social_core.pipeline.social_auth.social_uid',
    'social_core.pipeline.social_auth.social_user',
    'social_core.pipeline.user.get_username',
    'social_core.pipeline.social_auth.associate_by_email',
    'social_core.pipeline.user.create_user',
    'social_core.pipeline.social_auth.associate_user',
    'social_core.pipeline.social_auth.load_extra_data',
    'social_core.pipeline.user.user_details',
)

ORMs¶

Как было сказано выше, встроенное приложение Django поддерживает ORM по умолчанию и MongoEngine ORM.

При использовании MongoEngine убедитесь, что вы выполнили инструкции для MongoEngine Django integration, поскольку теперь вы используете эту модель пользователя. Бэкэнд MongoEngine_ был разработан и протестирован с версией 0.6.10 MongoEngine_.

Реализации альтернативных моделей хранения в настоящее время следуют жесткому шаблону моделей, которые ведут себя почти или идентично моделям Django ORM. В настоящее время они не отделены от этого шаблона никаким уровнем абстракции. Если вы хотите реализовать свою собственную альтернативу, пожалуйста, обратитесь за руководством к модулям social_django.models и << 1 >>>.

JSON field support¶

Django 3.1 introduces JSONField support for all backends and adds a deprecation warning.

These are the related settings to enabling this integration:

• SOCIAL_AUTH_JSONFIELD_ENABLED (boolean)

  Same behavior, setting name updated to match JSONField being supported by all systems:

  SOCIAL_AUTH_POSTGRES_JSONFIELD = True  # Before
  SOCIAL_AUTH_JSONFIELD_ENABLED = True  # After
  

• SOCIAL_AUTH_JSONFIELD_CUSTOM (import path) Allows specifying an import string. This gives better control to setting a custom JSONField.

  For django systems < 3.1 (technically <4), you can set the old JSONField to maintain behavior with earlier social-app-django releases:

  SOCIAL_AUTH_JSONFIELD_CUSTOM = 'django.contrib.postgres.fields.JSONField'
  

  For sites running or upgrading to django 3.1+, then can set this so the new value:

  SOCIAL_AUTH_JSONFIELD_CUSTOM = 'django.db.models.JSONField'
  

• Deprecating setting: SOCIAL_AUTH_POSTGRES_JSONFIELD (bool) Rename this to SOCIAL_AUTH_JSONFIELD_ENABLED. The setting will be deprecated in a future release.

Исключения Среднее программное обеспечение¶

Предоставляется базовое промежуточное ПО, которое обрабатывает SocialAuthBaseException, предоставляя сообщение пользователю через фреймворк сообщений Django, а затем отвечая перенаправлением на URL, определенный в одном из методов промежуточного ПО.

Промежуточное программное обеспечение находится по адресу social_django.middleware.SocialAuthExceptionMiddleware. Любой метод может быть переопределен, но для простоты рекомендуется использовать эти два:

get_message(request, exception)
get_redirect_uri(request, exception)

По умолчанию сообщением является сообщение об исключении, а URL для перенаправления - местоположение, указанное параметром LOGIN_ERROR_URL.

Если действительный бэкенд был обнаружен декоратором strategy(), он будет доступен в request.strategy.backend, а process_exception() будет использовать его для построения URL перенаправления в зависимости от бэкенда, но вернется к умолчанию, если он не определен.

Обработка исключений отключена, если любой из этих параметров имеет значение True:

<backend name>_SOCIAL_AUTH_RAISE_EXCEPTIONS = True
SOCIAL_AUTH_RAISE_EXCEPTIONS = True
RAISE_EXCEPTIONS = True
DEBUG = True

Место назначения перенаправления получит два параметра GET:

message = ''

Сообщение о возникшем исключении, в некоторых случаях это сообщение, возвращаемое провайдером в процессе аутентификации.

backend = ''

Имя бэкенда, который был использован, если это был действительный бэкенд.

Промежуточное ПО попытается использовать встроенное в Django приложение messages для хранения сообщения об исключении и пометит его social-auth и именем бэкенда. Если приложение не включено, или произошла ошибка MessageFailure, приложение по умолчанию будет использовать формат URL, описанный выше.

Администратор Django¶

Приложение по умолчанию (не MongoEngine) содержит модуль admin.py, который будет автоматически обнаружен обычным механизмом.

Но, в силу природы приложения, которое зависит от существования модели пользователя, легко впасть в рекурсивный импорт, в результате чего приложение не загрузится. Это происходит потому, что модуль администратора будет создавать набор полей для заполнения свойства search_fields для поиска связанных пользователей в административном интерфейсе, но для этого необходимо получить модель пользователя, которая может быть не определена в это время.

Чтобы избежать этой проблемы, задайте следующий параметр для обхода ошибки импорта:

SOCIAL_AUTH_ADMIN_USER_SEARCH_FIELDS = ['field1', 'field2']

Например:

SOCIAL_AUTH_ADMIN_USER_SEARCH_FIELDS = ['username', 'first_name', 'email']

Перечисленные поля должны быть полями пользовательских моделей.

Также можно определить больше полей поиска, не связанных напрямую с моделью пользователя, задав следующие параметры:

SOCIAL_AUTH_ADMIN_SEARCH_FIELDS = ['field1', 'field2']