mod_auth_mellon#

Описание#

mod_auth_mellon предназначен для реализации аутентификации на основе протокола SAML (Security Assertion Markup Language). SAML — это открытый стандарт на основе XML, предназначенный для обмена данными аутентификации и авторизации между различными системами. Он позволяет пользователям входить в несколько приложений, используя всего один логин и пароль, что упрощает процесс аутентификации.

mod_auth_mellon позволяет интегрировать веб-сервер с системами единого входа (например, Active Directory) и другими провайдерами удостоверений (IdP - Identity Provider).

Примечание

Для корректной работы модуля могут понадобиться:

утилита pkgconf - помогает находить и использовать библиотеки при сборке программного обеспечения (подробнее - на странице справочника man pkgconf);
OpenSSL (подробнее - в разделе «База знаний» → «Утилита openssl»);
библиотека для выполнения HTTP-запросов libcURL;
библиотека для работы с протоколом SAML 2.0 lasso;
модули mod_authn_core и mod_authz_user.

Пример конфигурации#

Пример конфигурации, настроенной с помощью модуля mod_auth_mellon для защиты ресурса /protected:

<Location /protected>
    # Тип аутентификации
    AuthType "Mellon"

    # Файл метаданных IdP
    MellonIdPMetadataFile /etc/httpd/mellon/idp-metadata.xml
    
    # Файл с закрытым ключом SP (Service Provider)
    MellonSPPrivateKeyFile /etc/httpd/mellon/sp-private-key.pem

    # Файл с сертификатом SP
    MellonSPCertFile /etc/httpd/mellon/sp-cert.pem
    
    # Доступ к ресурсу разрешен только аутентифицированным пользователям
    Require valid-user
</Location>

Директивы#

Список директив модуля представлен в таблице ниже. Также работой модуля управляют стандартные директивы Require valid-user и AuthType "Mellon".

Директивы `mod_auth_mellon`#
Синтаксис	Значение по умолчанию	Контекст	Описание
`MellonCacheSize <number>`	`MellonCacheSize 100`	`server config`	Устанавливает максимальное количество одновременно активных сессий, хранящихся в кеше. По достижении этого предела `mod_auth_mellon` начинает удалять сессии, использованные максимально давно
`MellonCacheEntrySize <number>`	`MellonCacheEntrySize 196608`	`server config`	Устанавливает максимальный размер для одной записи сессии в байтах. По достижении этого предела `mod_auth_mellon` не сможет сохранить больше данных в сессии и вернет ошибку. Минимальный размер записи составляет `65536` байт; значения ниже будут игнорироваться, и будет использоваться минимальный размер
`MellonLockFile <file_path>`	`MellonLockFile "/var/run/mod_auth_mellon.lock"`	`server config`	Указывает полный путь к файлу, используемому для синхронизации доступа к данным сессии. Путь должен использоваться только одним экземпляром веб-сервера одновременно
`MellonPostDirectory <directory-path>`	Нет	`server config`	Указывает полный путь к каталогу, в котором сохраняются POST-запросы во время аутентификации. Этот каталог должен быть доступен для записи пользователю веб-сервера и не должен быть доступен для записи (или чтения) другими пользователями
`MellonPostTTL <seconds>`	`MellonPostTTL 900`	`server config`	Устанавливает задержку в секундах перед тем, как сохраненный POST-запрос может быть очищен
`MellonPostSize <bytes>`	`MellonPostSize 1048576`	`server config`	Устанавливает максимальный размер для сохраненных POST-запросов
`MellonPostCount <number>`	`MellonPostCount 100`	`server config`	Устанавливает максимальное количество сохраненных POST-запросов
`MellonDiagnosticsFile <file\|pipe>`	`MellonDiagnosticsFile logs/mellon_diagnostics`	`server config`, `virtual host`	Указывает файл для записи диагностической информации. Это может быть либо имя файла, либо канал. Если это имя файла, то результирующий путь будет относительным к `ServerRoot`. Если значение предшествует символу канала `\|`, то за ним должен следовать путь к программе, которая будет получать информацию журнала на стандартный ввод
`MellonDiagnosticsEnable On\|Off`	`MellonDiagnosticsEnable Off`	`server config`, `virtual host`	Управляет выводом диагностической информации
`MellonEnable off\|info\|auth`	`MellonEnable "off"`	`directory`	Включает `mod_auth_mellon` в конкретной директории. Имеет три возможных значения: `off` - `mod_auth_mellon` не будет выполнять никаких действий по заданному пути; `info` - если пользователь авторизован для доступа к ресурсу, то окружение будет заполнено информацией о пользователе. Если пользователь не авторизован, окружение не будет заполнено, но доступ не будет запрещен. Это можно использовать для настройки параметров SSO Mellon на верхнем уровне сайта, а затем использовать `auth` для защиты отдельных путей в других частях сайта; `auth` - окружение будет заполнено информацией о пользователе, если он авторизован. Если он аутентифицирован (вошел в систему), но не авторизован (в соответствии с директивами `MellonRequire` и `MellonCond`), будет возвращена ошибка `403 Forbidden`. Если он не аутентифицирован, его перенаправит на страницу входа IdP
`MellonDecoder <value>`	Нет	`directory`	(Устарела) Не выполняет никаких действий, но принимается для обратной совместимости
`MellonVariable <cookie-name>`	`MellonVariable "cookie"`	`directory`	Определяет выбор имени cookie, которое `mod_auth_mellon` должен использовать для запоминания идентификатора сессии. Если требуется, чтобы на одном и том же хосте работали разные сайты, необходимо выбрать уникальное имя для cookie для каждого сайта
`MellonSecureCookie On\|Off\|httponly\|secure`	`MellonSecureCookie Off`	`directory`	Определяет, должны ли cookie, устанавливаемые `mod_auth_mellon`, иметь флаги `HttpOnly` и `secure`. Если установлено значение `On`, оба флага будут установлены. Значения `httponly` или `secure` установят один соответствующий флаг
`MellonCookieDomain <domain>`	Зависит от запроса	`directory`	Позволяет указать домен для cookie, который будет устанавливать `mod_auth_mellon`. По умолчанию используется домен для полученного запроса (заголовок `Host`, если он присутствует, или `ServerName` декларации `VirtualHost`; если отсутствует, выполняется обратное разрешение на локальный IP)
`MellonCookiePath <path>`	`MellonCookiePath /`	`directory`	Указывает путь для cookie, который будет устанавливать `mod_auth_mellon`
`MellonCookieSameSite Strict\|Lax\|None`	Нет	`directory`	Позволяет управлять значением `SameSite`, используемым для аутентификационного cookie. При использовании `None` рекомендуется установить `MellonSecureCookie On`, чтобы избежать проблем совместимости с новыми браузерами. Если значение не задано, атрибут `SameSite` не устанавливается для cookie. В новых браузерах это может привести к тому, что `SameSite` по умолчанию будет установлен на `Lax`. Для теста cookie используется фиксированное значение `SameSite` `None`
`MellonUser <attribute>`	`MellonUser "NAME_ID"`	`directory`	Выбирает, какой атрибут следует использовать в качестве имени пользователя. Имя пользователя передается другим модулям веб-сервера и на веб-страницу, которую посещает пользователь. `NAME_ID` — это атрибут, который устанавливается на идентификатор, полученный от IdP. Если `MellonUser` ссылается на многозначный атрибут, может быть использовано любое одно значение из этого атрибута
`MellonIdP <attribute>`	Нет	`directory`	Выбирает, в какой атрибут следует записывать удаленный IdP `entityId`. Этот атрибут передается другим модулям веб-сервера и на веб-страницы, которые посещает пользователь
`MellonSetEnv <local_name> <IdP_name>`	Нет	`directory`	Позволяет сопоставлять имена атрибутов, полученные от IdP, с выбранными пользователем именами. Можно указать несколько раз
`MellonSetEnvNoPrefix <local_name> <IdP_name>`	Нет	`directory`	Позволяет сопоставлять имена атрибутов по аналогии с `MellonSetEnv`, за исключением того, что она не добавляет префикс `MELLON_` к создаваемой переменной окружения. Можно указать несколько раз
`MellonEnvPrefix <prefix>`	`MellonEnvPrefix "MELLON_"`	`directory`	Изменяет строку, с которой начинаются переменные, передаваемые от IdP. Можно установить любой необходимый префикс
`MellonMergeEnvVars On\|Off [<separator>]`	`MellonMergeEnvVars Off`	`directory`	Объединяет несколько значений переменных окружения, установленных с помощью `MellonSetEnv`, в одну переменную. Например, вместо поведения по умолчанию, при котором используются `MYENV_VAR_0`, `MYENV_VAR_1` и т.д., переменная будет выглядеть как `MYENV_VAR => val1;val2;val3`. Второй необязательный параметр указывает разделитель, чтобы переопределить разделитель по умолчанию (точка с запятой)
`MellonEnvVarsIndexStart 0\|1`	`MellonEnvVarsIndexStart 0`	`directory`	Указывает, с какого индекса должны начинаться переменные окружения для многозначных атрибутов: с `0` или `1`
`MellonEnvVarsSetCount On\|Off`	`MellonEnvVarsSetCount Off`	`directory`	Указывает, следует ли сохранять количество значений для любого заданного атрибута в переменной с суффиксом `_N`
`MellonRequire <attribute_name> <valid_values>`	Нет	`directory`	Позволяет ограничить доступ для пользователей с определенными атрибутами. Атрибуты получаются от IdP. Если не указаны директивы `MellonRequire`, любой пользователь, аутентифицированный IdP, получит доступ к сервису. Если указано несколько директив `MellonRequire`, все они должны совпадать. Последняя директива переопределяет предыдущие для одного и того же атрибута
`MellonCond <attribute_name> <value> [<options>]`	Нет	`directory`	Предоставляет ту же функциональность, что и `MellonRequire`, с дополнительными возможностями. Атрибуты получаются от IdP. В отличие от `MellonRequire` не допускает несколько значений. Если указан флаг `[REG]`, `<value>` интерпретируется как регулярное выражение. Поддерживаются форматы для подстановки строк. Дополнительные опции включают `OR`, `NOT`, `SUB`, `REG`, `NC`, `MAP`, и `REF`. Разрешено использовать несколько `MellonCond` для одного атрибута и смешивать `MellonCond` с `MellonRequire`
`MellonEndpointPath <path>`	`MellonEndpointPath "/mellon"`	`directory`	Указывает, какой каталог `mod_auth_mellon` должен считать содержащим эндпойнты SAML 2.0. Любой запрос к этому каталогу будет обрабатываться `mod_auth_mellon`. Путь должен быть полным (от корневого каталога веб-сервера) и являться подкаталогом указанного `<Location ...>`
`MellonDefaultLoginPath <path>`	`MellonDefaultLoginPath "/"`	`directory`	Указывает местоположение, в которое следует перенаправить пользователя после входа, инициированного IdP. По умолчанию это корневой каталог сайта
`MellonSessionLength <seconds>`	`MellonSessionLength 86400`	`directory`	Устанавливает максимальную продолжительность сессии в секундах. Фактическая продолжительность может быть меньше в зависимости от условий, полученных от IdP
`MellonSessionIdleTimeout <seconds>`	`MellonSessionIdleTimeout -1`	`directory`	Указывает время в секундах, в течение которого пользователь может оставаться неактивным, прежде чем сессия истечет. Этот параметр отключен по умолчанию для поддержания обратной совместимости
`MellonNoCookieErrorPage <url>`	Нет	`directory`	Указывает полный путь к странице, на которую `mod_auth_mellon` перенаправит пользователя, если он вернется от IdP без cookie с идентификатором сессии. Пользователь также может получить ошибку, если cookie потеряны между перенаправлением на страницу входа IdP и возвращением с нее. Если значение не установлено, то при отсутствии cookie `mod_auth_mellon` вернет ошибку `400 Bad Request`
`MellonSPMetadataFile <file_path>`	Нет	`directory`	Указывает полный путь к файлу, содержащему метаданные для поставщика услуг (SP). Является необязательной. Если установлена, метаданные будут использованы для конфигурации Mellon. Если XML содержит несколько сущностей, будет использована первая. Эти метаданные также будут опубликованы на эндпойнте метаданных Mellon
`MellonSPentityId <entityID>`	Устанавливается на URL метаданных Mellon	`directory`	Может быть использована для явной установки `entityID`, который Mellon будет представлять при аутентификации и автоматически сгенерированных метаданных. Если `entityID` не указан через `MellonSPMetadataFile` или `MellonSPentityId`, он будет установлен на URL метаданных Mellon
`MellonOrganizationName <name>`	Нет	`directory`	Устанавливает имя организации, которое будет использоваться в элементе `<Organization>` метаданных
`MellonOrganizationDisplayName [lang] <name>`	Нет	`directory`	Устанавливает отображаемое имя организации для указанного языка
`MellonOrganizationURL <url>`	Нет	`directory`	Устанавливает URL-адрес организации, который будет использоваться в элементе `<Organization>` метаданных
`MellonSPPrivateKeyFile <file_path>`	Нет	`directory`	Указывает файл `.pem`, который содержит закрытый ключ поставщика услуг (SP). Файл `.pem` не может быть зашифрован паролем. Закрытый ключ должен быть доступен для чтения только пользователю `root`
`MellonSPCertFile <file_path>`	Нет	`directory`	Указывает файл `.pem`, содержащий сертификат для поставщика услуг (SP). Эта директива является необязательной
`MellonIdPMetadataFile <file_path> [<validation_chain>]`	Нет	`directory`	Указывает полный путь к файлу, содержащему метаданные аутентификации для IdP. Эта директива обязательна. Можно указать необязательную цепочку проверки в качестве второго аргумента. Если она опущена, проверка метаданных не будет производиться. Можно настроить несколько метаданных IdP, указав XML-файл, содержащий дескрипторы для нескольких IdP, или повторив эту директиву для каждого IdP. Если включено несколько IdP, необходимо предоставить метод обнаружения для выбора правильного IdP для пользователя; если он не указан, Mellon вернется к первому в списке
`MellonIdPMetadataGlob <pattern>`	Нет	`directory`	Указывает шаблон `glob(3)`, который является альтернативой директиве `MellonIdPMetadataFile`. Позволяет указать несколько файлов метаданных IdP, соответствующих заданному шаблону
`MellonIdPCAFile <file_path>`	Нет	`directory`	Указывает полный путь к сертификату удостоверяющего центра (CA). Этот сертификат может быть использован вместо сертификата для IdP
`MellonIdPIgnore <entityId>`	Нет	`directory`	Указывает `entityId` IdP, которые не должны загружаться из метаданных XML-файлов. Это полезно, если определенный IdP вызывает ошибки. Можно указать несколько `entityId` через одну директиву `MellonIdPIgnore`, а также использовать несколько директив `MellonIdPIgnore`
`MellonDiscoveryURL <url>`	Нет	`directory`	Указывает URL для службы обнаружения IdP. Используется для выбора между несколькими настроенными IdP. При первоначальной аутентификации пользователя происходит перенаправление на URL обнаружения IdP с установленными аргументами: - `entityID` - URL SP `entityId`, где опубликованы метаданные; - `returnIDParam` - аргумент, который служба обнаружения IdP должна вернуть; - `return` - URL-адрес возврата, на который служба обнаружения IdP должна вернуть пользователя. Служба обнаружения IdP должна перенаправить пользователя на URL возврата с установленным `returnIDParam`, равным выбранному `entityId` IdP. Также см. параметры `MellonProbeDiscovery` ниже для альтернативного способа обработки обнаружения
`MellonProbeDiscoveryTimeout <seconds>`	Нет	`directory`	Устанавливает тайм-аут для службы обнаружения IdP, доступной на эндпойнте `probeDisco`. Это приведет к отправке SP HTTP GET-запросов на настроенный URL `ProviderID` IdP. Этот URL используется для публикации метаданных (не обязательно). Если IdP возвращает статус HTTP `200`, то IdP выбирается. Если URL `ProviderID` требует SSL, используется `MellonIdPCAFile` в качестве доверенной цепочки CA
`MellonProbeDiscoveryIdP <url>`	Нет	`directory`	Используется для ограничения списка IdP, запрашиваемых службой обнаружения IdP. Если обнаружение по запросу не удается и этот список предоставлен, возвращается ошибка HTTP `500`, вместо того чтобы продолжать с первым доступным IdP. Если директива не установлена, все настроенные IdP будут запрашиваться
`MellonSamlResponseDump On\|Off`	`MellonSamlResponseDump Off`	`directory`	Делает утверждение SAML-аутентификации доступным в переменной окружения `MELLON_SAML_RESPONSE`. Это утверждение содержит проверяемую подпись, которую можно проверить повторно
`MellonSessionDump On\|Off`	`MellonSessionDump Off`	`directory`	Делает сессию Lasso доступной в переменной окружения `MELLON_SESSION`
`MellonAuthnContextClassRef <URI>`	Нет	`directory`	Запрашивает конкретный уровень безопасности аутентификации через элемент `AuthnContextClassRef` в `AuthnRequest`. Она также требует соблюдения этого уровня при получении аутентификационного утверждения. Можно указать несколько значений. Если утверждение не имеет требуемого уровня безопасности, браузеру возвращается код состояния `HTTP Forbidden`
`MellonAuthnContextComparisonType exact\|minimum\|maximum\|better`	Нет	`directory`	Устанавливает атрибут `Comparison` в `AuthnRequest`
`MellonSubjectConfirmationDataAddressCheck On\|Off`	`MellonSubjectConfirmationDataAddressCheck On`	`directory`	Управляет проверкой IP-адреса клиента по сравнению с адресом, возвращаемым IdP в атрибуте `Address` узла `SubjectConfirmationData`. Это может быть полезно, если SP находится за обратным прокси или в какой-либо сложной сетевой топологии, из-за чего IP-адрес клиента отличается для IdP и SP
`MellonDoNotVerifyLogoutSignature <url>`	Нет	`directory`	Отключает проверку подписи при обмене сообщениями о выходе из системы с указанным IdP
`MellonPostReplay On\|Off`	`MellonPostReplay Off`	`directory`	Указывает, следует ли включить повторную отправку POST-запросов после аутентификации. Если `On`, POST-запросы, которые инициируют аутентификацию, будут сохранены до завершения аутентификации и затем повторно отправлены. Если `Off` - запросы будут преобразованы в обычные GET-запросы после аутентификации. Если эта директива включена, необходимо также установить `MellonPostDirectory` в конфигурации сервера
`MellonNoSuccessErrorPage <url>`	Нет	`directory`	Указывает страницу, на которую следует перенаправить пользователя, если IdP отправляет ошибку в ответ на запрос аутентификации. По умолчанию происходит не перенаправление, а отправка ошибки `401 Unauthorized`
`MellonECPSendIDPList On\|Off`	`MellonECPSendIDPList Off`	`directory`	Управляет тем, следует ли включать список IdP при отправке сообщения ECP PAOS `<AuthnRequest>` клиенту ECP
`MellonSendCacheControlHeader On\|Off`	`MellonSendCacheControlHeader On`	`directory`	Управляет тем, будет ли заголовок `Cache-control` отправляться в ответах
`MellonRedirectDomains <domain>`	`MellonRedirectDomains [self]`	`directory`	Задает список доменов, на которые разрешены перенаправления. Специальное имя `[self]` означает домен текущего запроса. Имена доменов могут также использовать подстановочные знаки
`MellonSignatureMethod rsa-sha1\|rsa-sha256\|rsa-sha384\|rsa-sha512`	`MellonSignatureMethod rsa-sha256`	`directory`	Управляет методом подписи, используемым для подписания SAML-сообщений, генерируемых Mellon