Конфигурация¶

Настройка приложения¶

После установки приложения (проверьте раздел Установка) определите следующие настройки, чтобы включить поведение приложения. Также ознакомьтесь с подробными инструкциями в разделах, посвященных каждому фреймворку.

Имя настройки¶

Почти все настройки имеют префикс SOCIAL_AUTH_, есть некоторые исключения для фреймворка Django, например AUTHENTICATION_BACKENDS.

All settings can be defined per-backend by adding the backend name to the setting name, like SOCIAL_AUTH_TWITTER_LOGIN_URL. Settings discovery is done by reducing the name starting with the backend setting, then the app setting, and finally the global setting, for example:

SOCIAL_AUTH_TWITTER_LOGIN_URL
SOCIAL_AUTH_LOGIN_URL
LOGIN_URL

Имя бэкенда генерируется из атрибута name класса бэкенда путем поднятия его в верхнем регистре и замены - на _.

Ключи и секреты¶

• Set up needed OAuth keys (see OAuth section for details):

  SOCIAL_AUTH_TWITTER_KEY = 'foobar'
  SOCIAL_AUTH_TWITTER_SECRET = 'bazqux'
  

OpenID backends don’t require keys usually, but some need some API Key to call any API on the provider. Check Backends sections for details.

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

Зарегистрируйте бэкенды, которые вы планируете использовать, на фреймворке Django используйте обычные настройки AUTHENTICATION_BACKENDS, для других определите SOCIAL_AUTH_AUTHENTICATION_BACKENDS:

SOCIAL_AUTH_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',
    ...
)

Параметры URL-адресов¶

Эти URL используются на разных этапах процесса аутентификации, одни для успешных результатов, другие - для ошибок.

SOCIAL_AUTH_LOGIN_REDIRECT_URL = '/logged-in/'

Используется для перенаправления пользователя после успешного завершения процесса аутентификации. Используется значение ?next=/foo, если оно присутствовало

SOCIAL_AUTH_LOGIN_ERROR_URL = '/login-error/'

URL, на который будет перенаправлен пользователь в случае ошибки

SOCIAL_AUTH_LOGIN_URL = '/login-url/'

Используется как запасной вариант для LOGIN_ERROR_URL.

SOCIAL_AUTH_NEW_USER_REDIRECT_URL = '/new-users-redirect-url/'

Используется для перенаправления новых зарегистрированных пользователей, будет использоваться вместо SOCIAL_AUTH_LOGIN_REDIRECT_URL, если определено. Обратите внимание, что ?next=/foo добавляется, если присутствует, если вы хотите, чтобы новые пользователи переходили к следующему, вам придется сделать это самостоятельно.

SOCIAL_AUTH_NEW_ASSOCIATION_REDIRECT_URL = '/new-association-redirect-url/'

Как SOCIAL_AUTH_NEW_USER_REDIRECT_URL, но для новых ассоциированных учетных записей (пользователь уже вошел в систему). Используется вместо SOCIAL_AUTH_LOGIN_REDIRECT_URL

SOCIAL_AUTH_DISCONNECT_REDIRECT_URL = '/account-disconnected-redirect-url/'

Пользователь будет перенаправлен на этот URL при отключении социального аккаунта

SOCIAL_AUTH_INACTIVE_USER_URL = '/inactive-user/'

Неактивные пользователи могут быть перенаправлены на этот URL при попытке аутентификации.

Успешные URL будут по умолчанию иметь значение SOCIAL_AUTH_LOGIN_URL, в то время как URL с ошибками будут возвращаться к значению SOCIAL_AUTH_LOGIN_ERROR_URL.

Модель пользователя¶

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

SOCIAL_AUTH_USER_MODEL = 'foo.bar.User'

<<< Модель User должна иметь поля username и << 2 >>>, они обязательны.

Также рекомендуется использовать булевы флаги is_authenticated и is_active, которые при необходимости могут быть методами (должны возвращать True или False). Если в модели их нет, то предполагается значение True.

Изменение длины некоторых полей¶

Некоторые базы данных накладывают ограничения на индексные столбцы (например, MySQL InnoDB). Эти ограничения не будут хорошо работать с некоторыми полями UserSocialAuth. Чтобы избежать таких ошибок, определите некоторые из следующих параметров.

SOCIAL_AUTH_UID_LENGTH = <int>

Используется для определения максимальной длины поля uid. Значение 223 должно работать при использовании MySQL InnoDB, которая накладывает ограничение в 767 байт (при условии кодировки UTF-8).

SOCIAL_AUTH_NONCE_SERVER_URL_LENGTH = <int>

Модель Nonce имеет уникальное ограничение по сравнению с ('server_url', 'timestamp', 'salt'), соль имеет максимальную длину 40, поэтому длина server_url должна быть настроена с помощью этой настройки.

SOCIAL_AUTH_ASSOCIATION_SERVER_URL_LENGTH = <int> или SOCIAL_AUTH_ASSOCIATION_HANDLE_LENGTH = <int>

Модель Association имеет уникальное ограничение по сравнению с ('server_url', 'handle'), длина обоих полей может быть изменена с помощью этих настроек.

Генерация имени пользователя¶

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

UUID добавляется к именам пользователей в случае коллизий. Здесь приведены некоторые настройки для управления генерацией имен пользователей.

SOCIAL_AUTH_UUID_LENGTH = 16

Контролирует длину UUID, добавляемого к именам пользователей.

SOCIAL_AUTH_USERNAME_IS_FULL_EMAIL = True

Если вы хотите использовать полный адрес электронной почты в качестве username, определите этот параметр.

SOCIAL_AUTH_SLUGIFY_USERNAMES = False

For those that prefer slugged usernames, the get_username pipeline can apply a slug transformation (code borrowed from Django project) by defining this setting to True. The feature is disabled by default to not force this option to all projects.

SOCIAL_AUTH_CLEAN_USERNAMES = True

По умолчанию a set of regular expressions применяется к именам пользователей, чтобы очистить их от обычных нежелательных символов, таких как пробелы. Установите значение False, чтобы отключить это поведение.

SOCIAL_AUTH_CLEAN_USERNAME_FUNCTION = None

Иногда требуется дополнительная очистка имен пользователей, чтобы они правильно вписывались в проект. Эта настройка используется для указания на функцию, которая будет вызвана с текущим значением имени пользователя, полученный результат будет использован в качестве нового имени пользователя. Этот метод может быть вызван несколько раз в случае коллизии. Значение настройки должно быть в формате пути импорта.

Дополнительные аргументы в процессах аутентификации¶

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

Вы можете отправлять дополнительные параметры в процессе авторизации, определяя настройки для каждого бэкенда, например, чтобы запросить Facebook показать страницу мобильной авторизации, определите:

SOCIAL_AUTH_FACEBOOK_AUTH_EXTRA_ARGUMENTS = {'display': 'touch'}

Для других провайдеров просто задайте настройки в форме:

SOCIAL_AUTH_<uppercase backend name>_AUTH_EXTRA_ARGUMENTS = {...}

Кроме того, вы можете отправлять дополнительные параметры в процессе обработки маркера запроса, определяя настройки таким же образом, как описано выше, но с другим суффиксом:

SOCIAL_AUTH_<uppercase backend name>_REQUEST_TOKEN_EXTRA_ARGUMENTS = {...}

Основная информация запрашивается у различных провайдеров для создания целостного экземпляра пользователя (с именем и фамилией, электронной почтой и полным именем), это может быть слишком навязчивым для некоторых сайтов, которые хотят запрашивать у пользователей минимум данных. Можно отменить значения, запрашиваемые по умолчанию, определив любой из следующих параметров для провайдеров Open Id:

SOCIAL_AUTH_<BACKEND_NAME>_IGNORE_DEFAULT_AX_ATTRS = True
SOCIAL_AUTH_<BACKEND_NAME>_AX_SCHEMA_ATTRS = [
    (schema, alias)
]

Для бэкендов OAuth:

SOCIAL_AUTH_<BACKEND_NAME>_IGNORE_DEFAULT_SCOPE = True
SOCIAL_AUTH_<BACKEND_NAME>_SCOPE = [
    ...
]

Обработка перенаправлений и urlopen¶

Приложение выполняет несколько перенаправлений и вызовов API. Следующие настройки позволяют немного изменить их поведение.

SOCIAL_AUTH_SANITIZE_REDIRECTS = False

Процесс авторизации завершается перенаправлением, по умолчанию оно выполняется со значением SOCIAL_AUTH_LOGIN_REDIRECT_URL, но может быть отменено с помощью аргумента next GET. Если этот параметр имеет значение True, приложение будет варьировать домен конечного URL и перенаправлять на него, только если он находится на том же домене.

SOCIAL_AUTH_ALLOWED_REDIRECT_HOSTS = ['foo', 'bar']

To allow redirection to certain domains while keeping the more restrictive SOCIAL_AUTH_SANITIZE_REDIRECTS = True setting. This will redirect to the next GET argument if the hostname is on the list, otherwise it defaults to the value of SOCIAL_AUTH_LOGIN_REDIRECT_URL.

SOCIAL_AUTH_REDIRECT_IS_HTTPS = False

В проектах за обратным прокси, использующих HTTPS, URI перенаправления могут иметь неправильную схему (http:// вместо https://), если запрос не содержит соответствующих заголовков, что может привести к ошибкам в процессе аутентификации. Для принудительного использования HTTPS в конечных URI установите этот параметр в значение True.

SOCIAL_AUTH_URLOPEN_TIMEOUT = 30

Любой вызов urllib2.urlopen будет выполняться со значением таймаута по умолчанию, чтобы изменить его, не влияя на глобальный таймаут сокета, определите этот параметр (значение указывает секунды таймаута).

urllib2.urlopen использует значение socket.getdefaulttimeout() по умолчанию, поэтому установка socket.setdefaulttimeout(...) будет влиять на urlopen, если эта установка не определена, в противном случае эта установка имеет приоритет. Также это может повлиять на другие места в Django.

Аргумент timeout был введен в python 2.6 в соответствии с urllib2 documentation.

Белые списки¶

Регистрация может быть ограничена набором пользователей, идентифицированных по их адресу электронной почты или доменному имени. Для внесения в белый список достаточно установить любой из этих параметров:

SOCIAL_AUTH_<BACKEND_NAME>_WHITELISTED_DOMAINS = ['foo.com', 'bar.com']

Введите список доменных имен, которые должны быть внесены в белый список. Любой пользователь, имеющий адрес электронной почты на любом из разрешенных доменов, успешно войдет в систему, в противном случае будет выдано сообщение AuthForbidden.

SOCIAL_AUTH_<BACKEND_NAME>_WHITELISTED_EMAILS = ['me@foo.com', 'you@bar.com']

Введите список адресов электронной почты, которые должны быть внесены в белый список. Любой пользователь с адресом электронной почты из этого списка успешно войдет в систему, в противном случае будет выдано сообщение AuthForbidden.

Различные настройки¶

SOCIAL_AUTH_PROTECTED_USER_FIELDS = ['email',]

Во время процесса конвейера dict с именем details будет заполнен значениями, необходимыми для создания экземпляра пользователя, но он также используется для обновления экземпляра пользователя. Любое значение в нем будет проверено как атрибут в экземпляре пользователя (сначала выполнив hasattr(user, name)). Обычно есть атрибуты, которые нельзя обновлять (например, username, id, email и т.д.), эти поля должны быть protect. Установите имя любого поля, требующего protect в этом параметре, и оно не будет обновляться.

SOCIAL_AUTH_IMMUTABLE_USER_FIELDS = ['email',]

Set any field name that requires protection in this setting, and it won’t be updated after inital population. This setting is similar to SOCIAL_AUTH_PROTECTED_USER_FIELDS in that they both do not allow changes of the data - however this one allows it to be set if no prior value exists. An example use case might be an application that seeds data from a social plaform but allows the users to override it locally.

SOCIAL_AUTH_SESSION_EXPIRATION = False

По умолчанию время истечения сессии пользователя будет задано вашим веб-фреймворком (в Django, например, оно задается с помощью SESSION_COOKIE_AGE). Некоторые провайдеры возвращают время жизни токена доступа, который хранится в UserSocialAuth.extra_data под ключом expires. Изменение этого параметра на True отменит настройку длины сессии вашего веб-фреймворка и установит длину сессии пользователя в соответствии со значением expires, полученным от поставщика услуг доступа.

SOCIAL_AUTH_OPENID_PAPE_MAX_AUTH_AGE = <int value>

Включите поддержку расширения OpenID PAPE, определив этот параметр.

SOCIAL_AUTH_FIELDS_STORED_IN_SESSION = ['foo',]

Если вы хотите хранить дополнительные параметры из POST или GET в сессии, как это было сделано для параметра next, определите эту настройку с именами параметров.

В этом случае значение поля foo будет сохранено, когда пользователь перейдет по ссылке <a href="{% url socialauth_begin 'github' %}?foo=bar">...</a>.

SOCIAL_AUTH_PASSWORDLESS = False

Когда эта настройка True и social_core.pipeline.mail.send_validation включена, это позволяет реализовать passwordless authentication mechanism. Пример такой реализации можно найти в psa-passwordless.

SOCIAL_AUTH_USER_AGENT = None

Определяет значение заголовка User-Agent, отправляемое при каждом запросе к поставщику услуг. Используется в сочетании с бэкендом, который устанавливает свойство SEND_USER_AGENT в True. Значение по умолчанию - строка social-auth-<version>.

Отключение счета¶

Отключение является побочной операцией и должно выполняться только методом POST, некоторые CSRF-защиты приветствуются (и применяются в приложении Django). Убедитесь, что любой вызов /disconnect/<backend>/ или /disconnect/<backend>/<id>/ выполняется методом POST.

SOCIAL_AUTH_REVOKE_TOKENS_ON_DISCONNECT = False

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