Настройка SAML

1. Введение

Аутентификация SAML основана на OneloginSamlBundle для Symfony. SuiteCRM поддерживает базовую конфигурацию пакета. Таким образом, большая часть настроек будет аналогична настройкам пакета OneloginSamlBundle.

На данный момент устаревшие настройки SAML игнорируются. Поддержка устаревших настроек планируется в будущем.

2. Ограничения

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

Кроме того, привязка сообщений к службе выхода в настоящее время не поддерживается.

3. Известные проблемы

По истечении сессии пользователь может быть перенаправлен на стандартную страницу ввода логина/пароля SuiteCRM, вместо приглашения ввода учётных данных SAML. Для решения проблемы пользователю необходимо очистить файлы cookie и снова перейти по URL-адресу SuiteCRM.

Проблема будет устранена в будущих версиях системы.

4. Включение аутентификации SAML

Для включения аутентификации SAML в файле .env.local пропишите следующее:

AUTH_TYPE=saml

5. Настройка аутентификации

SuiteCRM предоставляет доступ к некоторым параметрам OneloginSamlBundle, указывая стандартные значения этих параметров в файле .env. Файл .env содержит значения по умолчанию для всех доступных переменных системы. Если вы хотите переопределить те или иные значения - укажите новые значения параметров в файле .env.local.

###> SAML CONFIG ###
SAML_USERNAME_ATTRIBUTE=uid
SAML_USE_ATTRIBUTE_FRIENDLY_NAME=true
###< SAML CONFIG ###

5.1. Описание параметров

SAML_USERNAME_ATTRIBUTE

Атрибут SAML, используемый в качестве логина в SuiteCRM. Значение, полученное в запросе SAML для SAML_USERNAME_ATTRIBUTE, должно совпадать со значением поля user_name таблицы users используемого экземпляра SuiteCRM.

Пример:

  • Вы хотите войти в систему как пользователь jane.doe

  • Поле user_name в таблице пользователей SuiteCRM содержит значение jane.doe

Значение, установленное для SAML_USERNAME_ATTRIBUTE, должно быть любым свойством из запроса SAML, который предоставляет имя пользователя jane.doe.

SAML_USE_ATTRIBUTE_FRIENDLY_NAME

Следует ли использовать понятное имя, отправленное в запросе SAML.

Пример:

###> SAML CONFIG ###
SAML_USERNAME_ATTRIBUTE=username
SAML_USE_ATTRIBUTE_FRIENDLY_NAME=false
###< SAML CONFIG ###

5.2. Настройка SAML

Как уже упоминалось выше, SuiteCRM использует пакет OneloginSamlBundle. Следовательно, используемые системой настройки точно такие же, как и в OneloginSamlBundle.

За более детальной информацией обратитесь к следующим документам:

При добавлении настроек в SuiteCRM их необходимо поместить в папку /extensions/<your-extensions>/config. Лучше всего взять за основу и скопировать стандартный файл настроек, находящийся в одной из подпапок корневой папки config. Например, файл config/packages/hslavich_onelogin_saml.yaml копируем в extensions/custom/config/packages/hslavich_onelogin_saml.yaml

Пример c описанием параметров

Следующий пример настроек был взят из системы, которая использовала ссылку keycloak в качестве IDP. Некоторые из значений IDP взяты из этого примера, что НЕ означает, что все IDP используют подобные значения.

Следующий пример сопровождается комментариями с описанием соответствующего параметра.

hslavich_onelogin_saml:
  # Basic settings

  idp:
    # entity id of your idp
    entityId: '<idp-entity-id>'  # e.g.: 'http://saml-idp-host/realms/master'


    singleSignOnService:
      # single sign on url your IDP
      url: '<idp-sso-url>' # e.g.: 'http://saml-idp-host/realms/master/protocol/saml'
      binding: 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect'

    singleLogoutService:
      # single logout service url of your IDP
      url: '<idp-slo-url>' # e.g.: 'http://saml-idp-host/realms/master/protocol/saml'
      binding: 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect'

    # IDP certificate
    x509cert: '<idp-certificate-string> # e.g. 'MIICmzCCAYMCBgGC1LTnr ... ='


  # The SP in this case is your SuiteCRM instance
  sp:

    # SP entity id. Use your SuiteCRM instance url
    entityId: '<sp-entity-id-use-suitecrm-url> # e.g. 'https://<your-suitecrm-instance>'

    assertionConsumerService:
      # The path to SuiteCRM's acs service
      url: 'https://<your-suitecrm-instance>/saml/acs'
      binding: 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST'

    singleLogoutService:
      # The path to SuiteCRM's SAML logout service
      url: 'https://<your-suitecrm-instance>/saml/logout'
      binding: 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect'

    # SuiteCRM's private key for SAML (sp)
    privateKey: '<sp-private-key>' # e.g. 'MIIEoAIBAAKCAQEAx ...'

    # SuiteCRM's certificate for SAML (sp)
    x509cert: '<sp-cert>' # e.g. 'MIIC1zCCAb8CBgGC1awPM ... ='


  # Optional settings

  # SuiteCRM's base url for SAML
  baseurl: 'https://<your-suitecrm-instance>/saml'

  ######
  # NOTE : The values for the following settings will depend on how the IDP is setup
  ######
  strict: true
  debug: true
  security:
    nameIdEncrypted: false
    authnRequestsSigned: true
    logoutRequestSigned: true
    logoutResponseSigned: false
    wantMessagesSigned: false
    wantAssertionsSigned: false
    wantNameIdEncrypted: false
    requestedAuthnContext: false
    signMetadata: false
    wantXMLValidation: true
    signatureAlgorithm: 'http://www.w3.org/2001/04/xmldsig-more#rsa-sha256'
    digestAlgorithm: 'http://www.w3.org/2001/04/xmlenc#sha256'
  contactPerson:
    technical:
      givenName: 'Tech User'
      emailAddress: 'techuser@example.com'
    support:
      givenName: 'Support User'
      emailAddress: 'supportuser@example.com'
  organization:
    en:
      name: 'Example'
      displayname: 'Example'
      url: 'http://example.com'

В указанном примере не прописаны все возможные параметры. Полное описание всех параметров доступно по следующим ссылкам:

5.3. Использование секретов в Symfony

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

Секреты Symfony позволяют нам безопасно хранить все конфиденциальные значения, зашифрованные в хранилище (vault). Кроме того, эти значения также могут быть определены для отдельного окружения.

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

Для добавления секретов сначала выполните действия, описанные в документе Symfony’s documentation: How to Keep Sensitive Information Secret.

Пример:

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

  1. Добавьте секрет для закрытого ключа поставщика услуг (SP)

    Из корневой папки системы выполните команду php bin/console secrets:set SAML_SP_PRIVATE_KEY и после приглашения укажите ключ.

  2. Добавьте секрет для сертификата SP

    Из корневой папки системы выполните команду php bin/console secrets:set SAML_SP_CERT и после приглашения укажите сертификат.

  3. Отредактируйте файл hslavich_onelogin_saml.yaml

    Наконец, измените пользовательскую копию файла hslavich_onelogin_saml.yaml, прописав в нём необходимые значения.

    Следующий пример — всего лишь фрагмент вышеуказанного файла:

    hslavich_onelogin_saml:
    
      # ...
    
      # The sp in this case is your SuiteCRM instance
      sp:
    
         ...
    
        # SuiteCRM's private key for SAML (sp)
        privateKey: '%env(SAML_SP_PRIVATE_KEY)%'
    
        # SuiteCRM's certificate for SAML (sp)
        x509cert: '%env(SAML_SP_CERT)%'
    
        # ...
  4. При необходимости добавьте другие настройки в секреты

    Есть и другие значения, которые вы можете добавить к секретам, такие как сертификат IDP или fingerprint.

  5. Очистите кеш Symfony

5.4. Альтернативы секретам Symfony

Если вы не хотите использовать секреты Symfony и предпочитаете более простую альтернативу, можно использовать следующую ссылку: env variables.

Возьмём тот же пример, что мы рассматривали выше в разделе Использование секретов в Symfony.

hslavich_onelogin_saml:

  # ...

  # The sp in this case is your SuiteCRM instance
  sp:

    # ...

    # SuiteCRM's private key for SAML (sp)
    privateKey: '%env(SAML_SP_PRIVATE_KEY)%'

    # SuiteCRM's certificate for SAML (sp)
    x509cert: '%env(SAML_SP_CERT)%'

    # ...

Использование значений из .env.local

В вышеприведённом примере privateKey и x509cert уже указывают на переменные SAML_SP_PRIVATE_KEY и SAML_SP_CERT соответственно.

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

Пример:

# ...

SAML_SP_PRIVATE_KEY='MIIEoAIBAAKCAQEAx ...'
SAML_SP_CERT='MIIC1zCCAb8CBgGC1awPM ... ='

# ...

После внесения изменений не забудьте очистить кеш Symfony.

Чтение значений из файлов

Также возможно чтение значений из файлов: Symfony documentation: env variables.

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

  1. Отредактируйте пользовательский файл настроек

    Отредактируйте пользовательскую копию файла hslavich_onelogin_saml.yaml для чтения сертификата x509cert из файла:

    hslavich_onelogin_saml:
    
      # ...
    
      # The sp in this case is your SuiteCRM instance
      sp:
    
        # ...
    
        # SuiteCRM's certificate for SAML (sp)
        x509cert: '%env(file:SAML_SP_CERT_FILE)%'
    
        # ...
  2. Укажите путь до сертификата в файле .env.local:

    # ...
    
    SAML_SP_CERT_FILE='extensions/custom/config/packages/sp_cert.crt'
    
    # ...
  3. Очистите кеш Symfony

6. Использование собственной аутентификации

Даже при использовании SAML система позволяет использовать собственную аутентификацию с использованием пароля, установленного в SuiteCRM для указанного пользователя.

Для этого войдите в систему, используя следующий URL: https://<your-suitecrm-instance>/auth.

После успешного входа в систему пользователь будет перенаправлен на https://<your-suitecrm-instance>/.

Обратите внимание, что при выходе из системы вы будете перенаправлены на страницу входа SAML, а не на собственную страницу ввода логина/пароля SuiteCRM.

6.1. Параметр external_auth_only config

Возможность входа в SuiteCRM с использованием собственного логина будет зависеть от значения параметра external_auth_only, прописанного в профиле пользователя:

Если в настройках пользователя параметр external_auth_only (см. соответствующее поле таблицы users в базе данных) установлен в значение 1 (или true), пользователь не сможет войти в систему, используя учётные данные SuiteCRM.

С другой стороны, если для external_auth_only установлено значение 0 (или false), пользователь сможет попытаться войти в систему, при условии, что у него установлен пароль в SuiteCRM.

7. Настройка автоматического создания пользователя

По умолчанию при использовании SAML автоматическое создание пользователей отключено.

Если этот параметр отключён, то учётные записи пользователей, использующих SAML, должны быть созданы до того как они попытаются войти в систему.

Если параметр включён - он автоматически создаст пользователя из SAML, если он ещё не существует в SuiteCRM.

Обратите внимание, что у созданного таким образом пользователя не будет установлен пароль, а параметр external_auth_only (см. соответствующее поле таблицы users в базе данных) по умолчанию будет установлен в значение 1 (или true).

Для автоматического создания пользователя в файле .env.local пропишите следующее:

SAML_AUTO_CREATE=enabled

При включении автоматического создания пользователя вам также необходимо определить, как информация о пользователе из SAML должна сопоставляться с пользователем в SuiteCRM.

Настройки по умолчанию для этого сопоставления указаны в файле config/services/saml/saml.yaml.

Для настройки параметров необходимо скопировать указанный файл в папку extensions, например, extensions/<your-package>/config/services/saml/saml.yaml.

parameters:
  saml.autocreate.attributes_map:

7.1. Описание параметров

saml.autocreate.attributes_map

Определяет способ сопоставления полей SAML с полями пользователя.

Ключи — это имена полей в SAML, а значения — имена полей в SuiteCRM.

Пример

Файл: extensions/<your-package>/config/services/saml/saml.yaml

parameters:
  saml.autocreate.attributes_map:
    email: email1
    'urn:oid:2.5.4.4': last_name
    'urn:oid:2.5.4.42': first_name

Чтобы проверить значения, отправленные из SAML, вы можете открыть файл logs/auth.log, в котором будет записан процесс создания пользователя. Этот файл заполняется, когда вы пытаетесь войти в систему. Поэтому, сначала попробуйте войти под пользователем, которого нет в системе, и только потом проверяйте логи.

Запись будет выглядеть следующим образом: App\Security\Saml\AppSamlUserFactory | createUser attributes. Эта запись также должна содержать информацию в формате json с атрибутами, которые SuiteCRM получает от IDP.

Взглянув на следующий фрагмент из журнала, можно увидеть, что:

  • Фамилия Doe соответствует ключу urn:oid:2.5.4.4

  • Имя Jeremy соответствует ключу urn:oid:2.5.4.42

  • Электронная почта jeremy.doe@example.com соответствует ключу email

[2022-09-15 09:23:53] auth.INFO: App\Security\Saml\AppSamlUserFactory | createUser username: jeremy.doe [] []
[2022-09-15 09:23:53] auth.INFO: App\Security\Saml\AppSamlUserFactory | createUser attributes | {"urn:oid:2.5.4.4":["Doe"],"urn:oid:2.5.4.42":["Jeremy"],"username":["jeremy.doe"],"email":["jeremy.doe@example.com"],"Role":["view-profile","offline_access","manage-account","manage-account-links","uma_authorization","default-roles-master"]} [] []

8. Очистка кеша Symfony

После внесения любых изменений в файлы .env и ldap.yaml необходимо очистить кеш Symfony.

Из корневой папки системы выполните:

bin/console cache:clear

Либо удалите содержимое папки /<path-to-your-suite8-project>/cache.

Apache / php должны иметь доступ на чтение и запись в папку /<path-to-your-suite8-project>/cache.
Это не относится к папке /<path-to-your-suite8-project>/public/legacy/cache - не удаляйте её содержимое.

9. Дополнительная информация

Дополнительная информация о настройке SAML находится на страницах:

Обязательно убедитесь, что информация, указанная по ссылке, актуальна для версии Symfony, используемой в установленной версии SuiteCRM.

Content is available under GNU Free Documentation License 1.3 or later unless otherwise noted.