CommuniGate Pro: Программы Помощники

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

Протокол Интерфейса Внешнего Аутентификатора основывается на обычном Протоколе Помощников.

В этом руководстве описывается Версия 7 Интерфейса Внешнего Аутентификатора.

Когда пользователь должен быть аутентифицирован при помощи незащищённого (clear text) метода, Сервер отправляет следующую команду:
nnnnnn VRFY (mode) name@domain password [loginAddress]
где:

nnnnnn: это уникальный последовательный номер этого запроса
mode: имя услуги (IMAP, POP, FTP и т.д.), которая требует проведения этой операции аутентификации.
Этот параметр может отсутствовать, если запрос был получен от безымянного компонента Сервера.
Если имя услуги указывается, то оно заключается в скобки.
name: имя пользователя
domain: имя домена пользователя
password: проверяемая парольная строка. Если пароль содержит специальные символы, то он кодируется так же, как Строка в кавычках.
loginAddress: сетевой адрес, с которого входит пользователь.
Этот параметр может отсутствовать, если пароль проверяется внутренним компонентом Сервера.
Если параметр указывается, то он заключается в квадратные скобки.

Если пользователь должен быть аутентифицирован при помощи безопасного SASL метода, то отправляется следующая команда:
nnnnnn SASL(method) (mode) name@domain password key [loginAddress]
где:

method: имя безопасного SASL метода (CRAM-MD5, APOP)
key: строка challenge, отправляемая почтовой программе клиента. Если в challenge содержится специальный символ, он кодируется так же, как Строка в кавычках

Если пароль принимается, то Внешний Аутентификатор должен вернуть положительный ответ:
nnnnnn OK

Если пароль не принимается, то должен возвращаться отрицательный ответ:
nnnnnn ERROR optional-error-message

Если пароль принимается и есть аутентификационный ответ, который должен быть возвращён клиенту, то положительный ответ должен возвращаться как строка в кавычках:
nnnnnn RETURN "authentication-response"

проверка SASL пароля требует, что бы в программе Внешнего Аутентификатора все SASL методы и алгоритмы поддерживались корректно. Как альтернатива, программа Внешнего Аутентификатора может возвращать пароль пользователя в открытом виде, заставляя Сервер проверять пароль и расчитывать аутентификационные ответы. Пароль пользователя в открытом виде должен возвращаться как строка в кавычках:
nnnnnn PLAIN "plain-text-password"

Пример сессии (I: - команда сервера, отправленная на стандартный ввод программы, O: - ответы программы, записанные в её стандартный вывод):

I: 00001 INTF 1 O: 00001 INTF 1 I: 00010 VRFY user1@domain1.com dsyui134 O: 00010 OK I: 00011 VRFY (IMAP) user2@domain2.com jskj23#45 [10.0.3.4] O: 00011 ERROR incorrect password I: 00012 SASL(CRAM-MD6) user4@domain2.com hdkj547812329394055 <pop-23456@mydomain.com> [10.0.1.4] I: 00013 VRFY (IMAP) user2@domain2.com "jskj23\"45" O: 00013 OK O: 00012 ERROR unsupported SASL method I: 00014 SASL(DIGEST-MD5) user4@domain2.com 012345 "user:qop:zz:mmm:uri" [10.0.1.4] O: 00014 RETURN "0123456789AAAA" I: 00015 SASL(DIGEST-MD5) user4@domain2.com 012345 "user:qop:zz:mmm:uri" [10.0.1.4] O: 00015 PLAIN "my$$password"

Программы Внешней Аутентификации могут также использоваться для обработки неизвестных имён. Например, программа может осуществлять поиск в внешней базе данных, проверяя, существует ли в этой базе данных пользователь, создавать Пользователя, Псевдоним, Группу, Список Рассылки или Переадресатор используя CLI/APICommuniGate Pro и возвращать Серверу положительный ответ. В этом случае CommuniGate Pro повторно попытается открыть объект с указанным именем в этом домене.

Для проверки неизвестного имени, Сервер отправляет следующие команды:
nnnnnn NEW name@domain relayType
где:

relayType: [MAIL] - если команда отправляется в процессе операции маршрутизации почты,
[SIGNAL] если команда отправляется в процессе операции маршрутизации сигналов,
[ACCESS] - если команда отправляется в процессе операции маршрутизации доступа.
name@domain: полный адрес неизвестного локального объекта.

Если программа отправляет ответ OK, то Сервер снова пытается найти объект name в Домене domain.

Если программа отправляет ответ ROUTED address, то Сервер берёт полученный address и перезапускает процедуру Маршрутизации с этим адресом. Маршрутизируемый адрес получает атрибут "can Relay", за исключением ситуации, если он был указан с префиксом [NORELAY].

Если программа отправляет ответ FAILURE, то Маршрутизатор Сервера возвращает код "временной внутренней ошибки" (этот код заставляет SMTP модуль вернуть код ошибки 4xx, а не код постоянной ошибки 5xx).

Если программа отправляет любой другой ответ, то Маршрутизатор Сервера возвращает ошибку "неизвестный пользователь".

Пример сессии:

I: 00010 NEW user1@domain1.com [MAIL] O: 00010 ERROR this account is not known I: 00011 NEW user2@domain2.com [MAIL] I: 00012 NEW user3@domain2.com [ACCESS] O: 00012 OK O: 00011 ROUTED [NORELAY] userX@domain2.com

Установка Домена "Обратиться к Внешней Программе" указывает серверу использовать программу Внешнего Аутентификатора при обработке неизвестного имени.

Программа Внешней Аутентификации может использоваться для помощи при Маршрутизации адреса. Если адрес направляется в домен @external, то "локальная часть" адреса передаётся Программе Внешней Аутентификации при помощи команды ROUTE:
nnnnnn ROUTE <address> relayType
где:

relayType: [MAIL] - если команда отправляется в процессе операции маршрутизации почты,
[SIGNAL] если команда отправляется в процессе операции маршрутизации сигналов,
[ACCESS] - если команда отправляется в процессе операции маршрутизации доступа.
address: локальная часть адреса с доменной частью external.

Если программа отправляет ответ ROUTED address, то Сервер берёт полученный address и перезапускает процедуру Маршрутизации с этим адресом. Маршрутизируемый адрес получает атрибут "can Relay", если он был указан с префиксом [RELAY].

Если программа отправляет любой другой ответ, то Маршрутизатор Сервера возвращает ошибку "не могу провести маршрутизацию адреса".

Пример сессии:

I: 00010 ROUTE <user1> [MAIL] O: 00010 ERROR this account is blocked I: 00011 ROUTE <user2%domain1.dom> [MAIL] I: 00012 ROUTE <"user3##name"%domain2.dom> [SIGNAL] O: 00012 FAILURE internal error O: 00011 ROUTED [RELAY] userX@domain100.dom

Внешние Фильтры Сообщений

Программы - Внешние Фильтры Сообщений используются для фильтрования содержимого (от вирусов и спама).

Протокол Интерфейса Внешнего Фильтра основывается на обычном Протоколе Помощников.
В этом разделе описывается Версия 3 Протокола Внешнего Фильтра.

Программа должна обрабатывать запросы Внешнего Фильтра:
seqNum FILE fileName
где fileName является именем файла, который программа должна сканировать.
Если обработка сообщения должна продолжаться, то строка с ответом должна иметь следующий формат:
seqNum OK
Если обработка сообщения должна продолжаться, но внешний фильтр желает добавить к сообщению поле заголовка, то строка с ответом должна иметь следующий формат:
seqNum ADDHEADER header-field-text
где header-field-text является текстовой строкой с одним или несколькими полями заголовков в RFC822. Этот текст (опционально - из нескольких строк) должен быть помещен в строку ответа в формате Строка
Если сообщение должно быть отвергнуто, то строка с ответом должна иметь следующий формат:
seqNum ERROR report
где report - текстовая строка, объясняющая, почему сообщение было отвергнуто. Этот текст (опционально - из нескольких строк) должен быть помещен в строку ответа в формате Строка
Если сообщение должно быть выкинуто, то строка с ответом должна иметь следующий формат:
seqNum DISCARD
Если обработка сообщения должна отложена (из-за лицензионных ограничений, например), то строка с ответом должна иметь следующий формат:
seqNum REJECTED report
где report - текстовая строка, объясняющая, почему обработка сообщения должна быть отложена.
Если программа получает запрос, который она не может обработать, то она должна возвращать ответ FAILURE:
seqNum FAILURE

где seqNum - идентификатор запроса.
Если программа отправила ответ FAILURE или любой другой ответ, то Сервер помещает запись в Журнал работы Сервера и обрабатывает его как ответ OK.
Программа ДОЛЖНА быть готова обрабатывать несколько запросов одновременно (используя несколько нитей). Так как Программа Внешнего Фильтра используется вместе с используется с Правилами, Общими для Сервера (и обрабатывается компонентом Сервера Установка в Очередь), то программа должна быть готова обрабатывать N параллельных запросов, где N - число процессоров (нитей) компонента Установка в Очередь.
Программа МОЖЕТ быть реализована с использованием одной нити - так, что она будет читать следующий запрос только после того, как ею был обработан предыдущий. Однако, такой дизайн может существенно уменьшить производительность всего Сервера: пока программа Внешнего Фильтра сканирует большое сообщение, другие сообщения не могут быть установлены в очередь.

Если внешняя программа заканчивает свою работу аварийно, то CommuniGate Pro приостанавливает процесс Установки в Очередь до тех пор, пока внешняя программа не будет перезапущена.

Внешние Помощники RADIUS

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

Протокол Интерфейса Внешнего RADIUS основывается на обычном Протоколе Помощников.
В этом руководстве описывается Версия 2 Интерфейса Внешнего RADIUS.

Если Внешняя программа RADIUS включена, то она используется после того, как пароль пользователя прошёл проверку. Сервер отправляет ей следующие команды:
nnnnnn LOGIN name@domain attributes settings
где:

nnnnnn: это уникальный последовательный номер этого запроса
name: имя Пользователя
domain: имя Домена Пользователя
attributes: словарь со всеми затребованными атрибутами.
settings: словарь, в котором содержатся установки Пользователя.

Если запрос на вход принимается, то программа - Помощник должна вернуть положительный ответ:
nnnnnn ACCEPT attributes
где:

nnnnnn: последовательный номер запроса
attributes: словарь с атрибутами, добавляемыми в ответ RADIUS.

Если пароль не принимается, то должен возвращаться отрицательный ответ:
nnnnnn REJECT optional-error-message

Если Внешняя программа RADIUS включена, то она используется для обработки запросов Start, Stop и Interim-Update. Сервер отправляет следующие команды:
nnnnnn ACCNT command name@domain attributes
где:

nnnnnn: это уникальный последовательный номер этого запроса
command: команда (started, ended, updated)
name: имя Пользователя
domain: имя Домена Пользователя
attributes: словарь с требуемыми атрибутами.

Программа - Помощник должна возвращать положительный ответ:
nnnnnn OK
где:

nnnnnn: последовательный номер запроса

Атрибуты в словаре должны использовать цифровые значения как ключи (например, 27 для Session-Timeout).

Следующие атрибуты интерпретируются как 32-битные целые значения и закодированы в словаре как числовые строки:
NAS-Port, Service-Type, Framed-Protocol, Framed-Routing, Framed-MTU, Framed-Compression, Login-Service, Login-TCP-Port, Framed-IPX-Network, Session-Timeout, Idle-Timeout, Termination-Action, Framed-AppleTalk-Link, Framed-AppleTalk-Network, Event-Timestamp, NAS-Port-Type, Port-Limit, ARAP-Zone-Access, Password-Retry, Prompt, Tunnel-Type, Tunnel-Medium-Type, Tunnel-Preference, Acct-Interim-Interval, Acct-Delay-Time, Acct-Input-Octets, Acct-Output-Octets, Acct-Authentic, Acct-Session-Time, Acct-Input-Packets, Acct-Output-Packets, Acct-Terminate-Cause, Acct-Link-Count, Acct-Input-Gigawords, Acct-Output-Gigawords.

Следующие атрибуты интерпретируются как 32-битные IP адреса и кодируются в словаре как строки вида aaa.bbb.ccc.ddd:
NAS-IP-Address, Framed-IP-Address, Framed-IP-Netmask, Login-IP-Host.

Следующие атрибуты игнорируются в ответах Помощника:
User-Name, User-Password, CHAP-Password, State, Proxy-State, EAP-Message, Message-Authenticator, Acct-Status-Type.

Все другие значения атрибутов кодируются либо как Строка, либо как Блок Данных. Сервер использует формат блока данных для тех значений атрибутов, которые содержат байты не из диапазона 0x20-0x7F.
Формат Блока Данных должен использоваться, если значение содержит байты с двоичными нулями.

Если атрибут имеет несколько значений, то значение атрибута кодируется как Массив.

Следующие атрибуты добавляются к атрибутам словаря, передаваемым Помощнику:

0: Идентификатор запроса протокола RADIUS. Он может использоваться для обнаружения переданных повторно пакетов (дублирующихся запросов).
secretKey (только в запросах на аутентификацию): значение строки с настройкой модуля RADIUS "общий секрет"
authData (только в запросах на аутентификацию): 16-байтный Блок Данных, содержащий часть "данных аутентификации" запроса RADIUS.

Зависимые от Производителя атрибуты представляются при помощи ключей с отрицательными цифровыми значениями. Абсолютное значение ключа является значением "VendorID". Для каждого VendorID, связанный с ним элемент является словарём. Ключи этого словаря являются зависимыми от Производителя "типами производителя", со связанными с ними "специфическими атрибутами". Значения "специфических атрибутов" могут хранится как Строка, Блоки Данных, Числа или Массивы Строк, Блоков Данных и/или Чисел.

I: 00001 INTF 1 O: 00001 OK 1 I: 00002 LOGIN user1@domain1.com {0=#15; 1="User1";4=10.0.0.1;32="NAS 1";31=4153837164;"-311"={9=#777;10="ZZZ";}; authData=[AbndghAbndgh1sjkjkss3T=]; secretKey=a123;} {RealName="User"; NATIP="192.168.1.3";} O: 00002 ACCEPT {8=192.168.1.3; 9=255.255.255.0; 13=(0,3);} I: 00003 LOGIN user1@domain1.com {0=#16; 1="uSEr1";32="NAS 2";31=415.5512.12; 8=192.168.1.3; authData=[Abnd278sjkljsljkjksFG=]; secretKey=a123;} {NATIP="10.0.1.114";} O: 00003 REJECT I: 00004 ACCNT started user1@domain1.com {0=#17;1="uSEr1";32="NAS 2";31=415.5512.12; 8=192.168.1.3;} O: 00004 OK

Обратите внимание: Сервер может отправлять несколько параллельных запросов для одного Пользователя.

Обратите внимание: Внешняя программа RADIUS вызывается, когда данные Пользователя открыты. В системе с Динамическим Кластером это означает, что Внешние программы RADIUS должны запускаться на Backend Серверах и такие Внешние программы RADIUS, запущенные на других Backend Серверах, никогда не получат одновременные запросы для одного и того же Пользователя.

Программы Помощники

Протокол Помощников

Внешняя Аутентификация

Внешние Фильтры Сообщений

Внешние Помощники RADIUS

Внешние Обработчики CDR