Controles LDAP

Controles são objetos especiais que podem ser enviados junto com uma requisição LDAP para alterar o comportamento do servidor LDAP durante a realização da requisição. Pode também haver controles enviados pelo servidor junto com a resposta para fornecer mais informação, normalmente para responder a um objeto de controle da requisição.

Nota:

Nem todos os controles são suportados por todos os servidores LDAP. Para saber quais controles são suportados por um servidor, é necessário consultar o DSE raiz lendo-se um DN vazio com o filtro (objectClass=*).

Exemplo #1 Testando suporte ao controle de resultados paginados

<?php

// $ds é um identificador válido de ligação a um servidor de diretório

$result = ldap_read($ds, '', '(objectClass=*)', ['supportedControl']);
if (!in_array(LDAP_CONTROL_PAGEDRESULTS, ldap_get_entries($ds, $result)[0]['supportedcontrol'])) {
die("Este servidor não suporte controle de resultados paginados.");
}

?>

A partir do PHP 7.3, pode-se enviar controle com a requisição em todas as funções de requisição usando o parâmetro controls. Quando uma versão "ext" de uma função existir, deve-se usá-la se for desejado acessar o objeto de resposta completa e ser capaz de analisar controles de resposta a partir dele usando ldap_parse_result().

controls deve ser um array contendo um array para cada controle a enviar, contendo as seguintes chaves:

oid (string)

O OID do controle. Deve-se usar constantes LDAP_CONTROL_* para isto. Consulte as constantes LDAP.

iscritical (bool)

Se um controle for observado como crítico, a requisição falhará se o constrole não for suportado pelo servidor, ou se houver falha em sua aplicação. Observe que alguns controles devem ser sempre marcados como críticos como citado na RFC que os introduz. O padrão é false.

value (mixed)

Se aplicável, o valor do controle. Leia a seguir para mais informação.

A maior parte dos valores de controle são enviados ao servidor com codificação BER. O usuário pode aplicar a codificação BER por conta própria, ou pode-se passar um array com as chaves corretas de forma que a codificação é feita automaticamente. Controles que suportam ser passados como um array são:

• LDAP_CONTROL_PAGEDRESULTS Chaves esperadas são [size] e [cookie]

• LDAP_CONTROL_ASSERT Chave esperada é filter

• LDAP_CONTROL_VALUESRETURNFILTER Chave esperada é filter

• LDAP_CONTROL_PRE_READ Chave esperada é attrs

• LDAP_CONTROL_POST_READ Chave esperada é attrs

• LDAP_CONTROL_SORTREQUEST Espera um array de arrays com chaves attr, [oid], [reverse].

• LDAP_CONTROL_VLVREQUEST Chaves esperadas são before, after, attrvalue|(offset, count), [context]

Os controles a seguir não precisam de nenhum valor:

• LDAP_CONTROL_PASSWORDPOLICYREQUEST

• LDAP_CONTROL_MANAGEDSAIT

• LDAP_CONTROL_DONTUSECOPY

O controle LDAP_CONTROL_PROXY_AUTHZ é um caso especial já que não é esperado que seu valor seja codificado com BER, por usso pode-se usar diretamente uma string para seu valor.

Quando controles são analisados por ldap_parse_result(), valores são convertidos em array se suportado. Isto é suportado para:

• LDAP_CONTROL_PASSWORDPOLICYRESPONSE Chaves são expire, grace, [error]

• LDAP_CONTROL_PAGEDRESULTS Chaves são size, cookie

• LDAP_CONTROL_PRE_READ Chaves são dn e nomes de atributo LDAP

• LDAP_CONTROL_POST_READ Chaves são dn e nomes de atributo LDAP

• LDAP_CONTROL_SORTRESPONSE Chaves são errcode, [attribute]

• LDAP_CONTROL_VLVRESPONSE Chaves são target, count, errcode, context