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

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

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

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

Когда пользователь должен быть аутентифицирован при помощи незащищённого (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"

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

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

name@domain

полное имя (адрес) требуемого Пользователя.

Программа должна возвращать пароль пользователя в открытом виде как строка в кавычках:
nnnnnn PLAIN "plain-text-password"
Если программа не может получить пароль в открытом виде, то она должна возвращать ответ FAILURE.

Программы Внешней Аутентификации могут также использоваться для обработки неизвестных имён. Например, программа может осуществлять поиск в внешней базе данных, проверяя, существует ли в этой базе данных пользователь, создавать Пользователя, Псевдоним, Группу, Список Рассылки или Переадресатор используя 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].

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

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

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

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

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

до создания Пользователя:

nnnnnn PRECREATE accountName@domainName accountType initialSettings
initialSettings является словарём.
Если эта операция заканчивается неуспешно, то Пользователь не создаётся.

после создания Пользователя:

nnnnnn POSTCREATE accountName@domainName accountType initialSettings
Если эта операция заканчивается неуспешно, то вновь созданный Пользователь удаляется.

до переименования Пользователя:

nnnnnn PRERENAME accountName@domainName newAccountName@newDomainName
Если эта операция заканчивается неуспешно, то Пользователь не переименовывается.

после переименования Пользователя:

nnnnnn POSTRENAME accountName@domainName newAccountName@newDomainName
Если эта операция заканчивается неуспешно, то Пользователь переименовывается обратно.

до удаления Пользователя:

nnnnnn PREDELETE accountName@domainName
Если эта операция заканчивается неуспешно, то Пользователь не удаляется.

после удаления Пользователя:

nnnnnn POSTDELETE accountName@domainName

до изменения Класса Лицензии Пользователя:

nnnnnn PRETYPECHANGE accountName@domainName newClass
Если эта операция заканчивается неуспешно, то Класс Лицензии Пользователя не изменяется.

после изменения Класса Лицензии Пользователя:

nnnnnn POSTTYPECHANGE accountName@domainName newClass

до обновления Установок Пользователя:

nnnnnn PREUPDATE accountName@domainName modifiedSettings
Если эта операция заканчивается неуспешно, то Установки Пользователя не изменяются.

после обновления Установок Пользователя:

nnnnnn POSTUPDATE accountName@domainName newSettings

до обновления пароля Пользователя:

nnnnnn PREPWDCHANGE accountName@domainName newPassword
Если эта операция заканчивается неуспешно, то пароль Пользователя не обновляется.

Пароль - это одна из Установок Пользователя; таким образом, за этой командой должна следовать команда PREUPDATE.

Программа должна либо отправить ответ OK, либо ответ FAILURE "errorCode".

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

Протокол Интерфейса Внешнего Фильтра основывается на обычном Протоколе Помощников.
В этом разделе описывается Версия 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 основывается на обычном Протоколе Помощников.
В этом руководстве описывается Версия 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: - команда сервера, отправленная на стандартный ввод программы, O: - ответы программы, записанные в её стандартный вывод):

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 Серверах, никогда не получат одновременные запросы для одного и того же Пользователя.

Программы - Внешние Обработчики CDR могут использоваться для обработки CDR (Call Detail Records, Детализированная Информация о Звонках), созданных компонентом Signal при попытках установления звонка и его дальнейшей обработке. Они также могут обрабатывать CDR записи, созданные CG/PL приложениями.

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

Когда включена программа Внешний Обработчик CDR, то модуль Signal генерирует CDR и отправляет их в эту программу.

При создании CDR Сервер отправляет следующие команды:
nnnnnn CDR cdr_data
где:

nnnnnn

это уникальный последовательный номер этого запроса

cdr_data

CDR данные в формате компонента Signal или в формате CG/PL приложения.

когда запись обработана, программа должна вернуть положительный ответ:
nnnnnn OK

Программы Внешней Рекламной Системы могут использоваться для обеспечения XIMSS клиентов "рекламными" данными (рекламной информацией, демонстрируемое клиентом пользователю).

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

Когда клиент запрашивает рекламное сообщение, Сервер отправляет следующие команды:
nnnnnn BANNER bannerType [ accountName@domainName ] [ INFO bannerSetting ] [ PREFS bannerPreference ] [ PARAM paramData ]
где:

nnnnnn

это уникальный последовательный номер этого запроса

bannerType

если строка с типом рекламного сообщения указана клиентским приложением (указано клиентское приложение и тип рекламного сообщения, например prontoEmailTop, myClientLeftBanner).

accountName@domainName

полное имя Пользователя, затребовавшего рекламное сообщение.

bannerSetting

(опционально) значение Установки Пользователя BannerInfo (Параметры Рекламы).

bannerPreference

(опционально) значение Настройки Пользователя BannerClass.

paramData

(опционально) текстовое представление объекта с параметрами, указанными клиентским приложением.

Когда запись обработана, программа должна вернуть положительный ответ:
nnnnnn RESULT resultData
где:

resultData

текстовое представление рекламной информации.

Программа также может вернуть блокирующий ответ:
nnnnnn BLOCK
Указанный bannerType добавляется в список "заблокированных" типов. Если клиент запрашивает рекламу "заблокированного" типа, то ему немедленно возвращается пустой ответ, при этом вызова программы Внешней Рекламной Системы не происходит.

Если программа Внешней Рекламной Системы не запущена, то любой запрос на рекламу возвращает пустой ответ.