SAML¶

Требуемая зависимость¶

Для использования этого бэкенда необходимо установить python-saml 2.2.0 или выше, при использовании Python 3 необходимо установить python3-saml 1.2.1 или выше.

Требуемая конфигурация¶

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

• SOCIAL_AUTH_SAML_SP_ENTITY_ID: Идентификатор сущности SAML для вашего приложения. Это должен быть URL-адрес, включающий принадлежащее вам доменное имя. Не имеет значения, на что указывает URL. Пример: http://saml.yoursite.com

• SOCIAL_AUTH_SAML_SP_PUBLIC_CERT: Строка сертификата X.509 для пары ключей, которую будет использовать ваше приложение. Вы можете сгенерировать новую самоподписанную пару ключей с помощью:

  openssl req -new -x509 -days 3652 -nodes -out saml.crt -keyout saml.key
  

  Содержимое saml.crt должно быть использовано в качестве значения этой настройки (вы можете опустить первую и последнюю строки, которые не требуются).

• SOCIAL_AUTH_SAML_SP_PRIVATE_KEY: Закрытый ключ, который будет использоваться вашим приложением. Если вы использовали пример команды openssl, приведенный выше, установите это значение в содержимое saml.key (опять же, вы можете опустить первую и последнюю строки).

• SOCIAL_AUTH_SAML_ORG_INFO: Словарь, содержащий информацию о вашем приложении. Вы должны указать значения как минимум для английского языка. Для каждого языка необходимо указать name (не показывать пользователю), displayname (показывать пользователю) и URL. См. следующий пример:

  {
      "en-US": {
          "name": "example",
          "displayname": "Example Inc.",
          "url": "http://example.com",
      }
  }
  

• SOCIAL_AUTH_SAML_TECHNICAL_CONTACT: Словарь с двумя значениями, givenName и emailAddress, описывающий имя и email технического контакта, ответственного за ваше приложение. Пример:

  {
      "givenName": "Tech Gal",
      "emailAddress": "technical@example.com"
  }
  

• SOCIAL_AUTH_SAML_SUPPORT_CONTACT: Словарь с двумя значениями, givenName и emailAddress, описывающими имя и email контактного лица службы поддержки вашего приложения. Пример:

  {
      "givenName": "Support Guy",
      "emailAddress": "support@example.com",
  }
  

• SOCIAL_AUTH_SAML_ENABLED_IDPS: Самый важный параметр. Перечислите ID сущности, SSO URL и сертификат открытого ключа x.509 для каждого провайдера, которого ваше приложение хочет поддерживать. SSO URL должен поддерживать привязку HTTP-Redirect. Вы можете получить эти значения из метаданных XML провайдера. Вот пример для TestShib (значения взяты из метаданных TestShib):

  {
      "testshib": {
          "entity_id": "https://idp.testshib.org/idp/shibboleth",
          "url": "https://idp.testshib.org/idp/profile/SAML2/Redirect/SSO",
          "x509cert": "MIIEDjCCAvagAwIBAgIBADA ... 8Bbnl+ev0peYzxFyF5sQA==",
      }
  }
  

  Каждый IDP может определить ключи конфигурации, чтобы избежать необходимости использовать унифицированные имена ресурсов (т.е. urn:oid:0.9.2342.19200300.100.1.3 для адреса электронной почты) в качестве атрибутов для отображения данных пользователя, необходимых для завершения создания учетной записи. Значения, связанные с ключами attr_*, соответствуют ключам, указанным в качестве атрибутов в IDP.

  Продолжая пример с «тестшибом»:

  {
      "testshib": {
          "entity_id": "https://idp.testshib.org/idp/shibboleth",
          "url": "https://idp.testshib.org/idp/profile/SAML2/Redirect/SSO",
          "x509cert": "MIIEDjCCAvagAwIBAgIBADA ... 8Bbnl+ev0peYzxFyF5sQA==",
          "attr_user_permanent_id": "email",
          "attr_first_name": "first_name",
          "attr_last_name": "last_name",
          "attr_username": "email",
          "attr_email": "email",
      }
  }
  

  В этом примере attr_user_permanent_id и attr_email установлены на адрес электронной почты, переданный в ключе атрибута „email“.

  Примечание: testshib не предоставляет электронную почту в качестве атрибута. Это было протестировано с использованием Okta и G Suite (ранее Google Apps for Business).

Основное использование¶

• Установите все необходимые переменные конфигурации, описанные выше.

• Сгенерируйте метаданные SAML XML для вашего приложения. Лучший способ сделать это - создать новый view/page/URL в вашем приложении, который будет вызывать метод бэкенда generate_metadata_xml(). Вот пример того, как это сделать в Django:

  def saml_metadata_view(request):
      complete_url = reverse('social:complete', args=("saml", ))
      saml_backend = load_backend(
          load_strategy(request),
          "saml",
          redirect_uri=complete_url,
      )
      metadata, errors = saml_backend.generate_metadata_xml()
      if not errors:
          return HttpResponse(content=metadata, content_type='text/xml')
  

• Загрузите метаданные для вашего приложения, созданные вышеописанным способом, и отправьте их каждому поставщику идентификации (IdP), который вы хотите использовать. Каждый IdP должен установить и настроить ваши метаданные в своей системе, прежде чем они начнут работать.

• Теперь все готово! Чтобы пользователи могли войти в систему с помощью любого заданного IdP, нужно дать им ссылку на URL python-social-auth «begin»/»auth» и включить параметр запроса idp, указывающий имя используемого IdP. Это необходимо, поскольку бэкенд поддерживает несколько IdP. Имена IdP являются ключами, используемыми в параметре SOCIAL_AUTH_SAML_ENABLED_IDPS.

  Пример Django:

  # In view:
  context['testshib_url'] = u"{base}?{params}".format(
      base=reverse('social:begin', kwargs={'backend': 'saml'}),
      params=urllib.urlencode({'next': '/home', 'idp': 'testshib'})
  )
  # In template:
  <a href="{{ testshib_url }}">TestShib Login</a>
  # Result:
  <a href="/login/saml/?next=%2Fhome&amp;idp=testshib">TestShib Login</a>
  

• Рекомендуется тестирование с помощью провайдера TestShib, так как известно, что он работает хорошо.

Расширенные настройки¶

• SOCIAL_AUTH_SAML_SP_EXTRA: Это может быть задано в виде диктанта, и любые указанные здесь пары ключ/значение будут переданы в настройку python-saml базовой конфигурации библиотеки sp. Подробности см. в документации python-saml.

  To publish a rollover certificate in advance of changing, use SOCIAL_AUTH_SAML_SP_EXTRA to set ['sp']['x509certNew'] of python-saml:

  {
      "x509certNew": "MIIEDjCCAvagAwIBAgIBADA ... 8Bbnl+ev0peYzxFyF5sQA==",
  }
  

• SOCIAL_AUTH_SAML_SECURITY_CONFIG: Этот параметр можно задать в виде диктанта, и все указанные здесь пары ключ/значение будут переданы в базовый параметр python-saml конфигурации библиотеки security. Два полезных ключа, которые вы можете задать, это metadataCacheDuration и metadataValidUntil, которые управляют временем истечения срока действия ваших метаданных XML. По умолчанию используется срок кэширования 10 дней, что означает, что IdP разрешено кэшировать ваши метаданные до 10 дней, но не дольше. metadataCacheDuration должно быть указано в виде строки продолжительности ISO 8601 (например, P1D для одного дня).

• SOCIAL_AUTH_SAML_EXTRA_DATA: Это может быть установлено в список кортежей, аналогично настройкам бэкенда OAuth. Он сопоставляет атрибуты IDP с атрибутами extra_data. Каждый атрибут будет списком значений (даже если только 1 значение) в соответствии с тем, как python-saml обрабатывает атрибуты:

  SOCIAL_AUTH_SAML_EXTRA_DATA = [('attribute_name', 'extra_data_name_for_attribute'),
                               ('department', 'department'),
                               ('manager_full_name', 'manager_full_name')]
  

Расширенное использование¶

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

• get_idp(self, idp_name): Учитывая имя IdP, верните экземпляр SAMLIdentityProvider с деталями IdP. Переопределите этот метод, если вы хотите использовать какой-либо другой метод для настройки доступных поставщиков идентификационных данных, например, получить их во время выполнения с другого сервера или использовать список поставщиков из федерации Shibboleth.

• _check_entitlements(self, idp, attributes): Этот метод вызывается в процессе входа в систему, и именно здесь вы можете принять решение о принятии или отклонении пользователя на основе его SAML-атрибутов. Например, вы можете ограничить доступ к вашему приложению, чтобы принимать только пользователей, принадлежащих к определенному отделу. Проверив переданный параметр атрибутов, ничего не делайте, чтобы разрешить пользователю войти в систему, или поднимите значение social_core.exceptions.AuthForbidden, чтобы отклонить пользователя.