Управляющие объекты протокола LDAP

Управляющие объекты — специальные объекты, которые, если нужно, передают вместе с LDAP-запросом, чтобы изменить поведение LDAP-сервера на время исполнения запроса. Вместе с ответом сервер может также отправлять управляющие объекты, обычно чтобы сообщить дополнительную информацию в ответ на управляющий объект из запроса.

Замечание:

Не каждый LDAP-сервер поддерживает все управляющие объекты. Чтобы определить, какие управляющие объекты поддерживает сервер, запрашивают корневую запись DSE путём чтения пустого dn-имени с фильтром (objectClass=*).

Пример #1 Тестирование поддержки управления пагинацией результата

<?php

// $ds — допустимый идентификатор соединения с сервером каталогов

$result = ldap_read($ds, '', '(objectClass=*)', ['supportedControl']);
if (!in_array(LDAP_CONTROL_PAGEDRESULTS, ldap_get_entries($ds, $result)[0]['supportedcontrol'])) {
die("Этот сервер не поддерживает управление пагинацией");
}

?>

Начиная с PHP 7.3 управляющие объекты отправляют в запросе через параметр controls функций запроса. Разработчик должен работать с расширенной версией функции, если ext-вариант функции существует, если нужно получить доступ к полному объекту ответа и разбору функцией ldap_parse_result() управляющих объектов из объекта ответа.

Параметр controls должен содержать массив, который содержит массив со следующими ключами для каждого управляющего объекта, который будет отправлен:

oid (string)

OID-идентификатор управляющего объекта. Параметр принимает константы, имена которых начинаются на LDAP_CONTROL_. Смотрите раздел «Константы LDAP».

iscritical (bool)

Запрос завершится ошибкой, если управляющий объект пометили как критичный, а сервер не поддерживает такой управляющий объект, либо если объект невозможно применить. Обратите внимание, что отдельные объекты требуется помечать критичными в кажом запросе, как отмечает стандарт RFC, который представляет управляющий объект. Значение по умолчанию — false.

value (mixed)

Значение управляющего объекта, если нужно. Подробнее о доступных значениях описание расскажет в абзаце, который идёт ниже.

Бо́льшая часть значений управляющих объектов отсылается на сервер закодированными по правилам BER. Разработчики BER-кодируют значения сами или вместо этого передают массив с корректными ключами, и тогда значения закодирует PHP. Поддерживаемые управляющие объекты:

• LDAP_CONTROL_PAGEDRESULTS Ожидаемые ключи [size] и [cookie]

• LDAP_CONTROL_ASSERT Ожидаемый ключ — filter

• LDAP_CONTROL_VALUESRETURNFILTER Ожидаемый ключ — filter

• LDAP_CONTROL_PRE_READ Ожидаемый ключ — attrs

• LDAP_CONTROL_POST_READ Ожидаемый ключ — attrs

• LDAP_CONTROL_SORTREQUEST Ожидается массив массивов с ключами: attr, [oid], [reverse].

• LDAP_CONTROL_VLVREQUEST Ожидаемые ключи: before, after, attrvalue|(offset, count), [context]

Для следующих управляющих объектов значения не нужны:

• LDAP_CONTROL_PASSWORDPOLICYREQUEST

• LDAP_CONTROL_MANAGEDSAIT

• LDAP_CONTROL_DONTUSECOPY

Объект LDAP_CONTROL_PROXY_AUTHZ — уникальный случай, поскольку его значение не нужно кодировать по правилам BER, так что указывают обыкновенную строку.

Функция ldap_parse_result() преобразовывает значения в массив, если поддерживается, когда анализирует управляющие объекты. Это поддерживается для следующих элементов:

• LDAP_CONTROL_PASSWORDPOLICYRESPONSE Ключи: expire, grace, [error]

• LDAP_CONTROL_PAGEDRESULTS Ключи: size, cookie

• LDAP_CONTROL_PRE_READ Ключи: dn и имена атрибутов LDAP

• LDAP_CONTROL_POST_READ Ключи: dn и имена атрибутов LDAP

• LDAP_CONTROL_SORTRESPONSE Ключи: errcode, [attribute]

• LDAP_CONTROL_VLVRESPONSE Ключи: target, count, errcode, context