GET | Listar todos os servidores LDAP

Descrição

Liste os perfis de conexão de servidor LDAP/AD cadastrados na plataforma Segura™. A resposta é paginada e aceita projeção de campos, filtros e ordenação.

Este endpoint retorna um resumo de cada servidor. Para ler todos os atributos de um servidor, acesse GET | Listar um servidor LDAP por [id].

Pré-requisitos

Uma aplicação com a autorização Users concedida pelo administrador no A2A. Para mais informações, acesse Como gerenciar autorizações no A2A.
Um token de acesso OAuth 2.0 válido. Para mais informações, acesse Como autenticar uma aplicação A2A.

Requisição

GET /api/v2/iam/ldap-servers

Parâmetros de query

Campo	Tipo	Obrigatório	Descrição
`page`	integer	Não	Página a retornar. Padrão: `1`.
`limit`	integer	Não	Número de servidores por página. Padrão: `50`. Máximo: `200`.
`sort_by`	string	Não	Lista de campos e direções separada por vírgula. Veja Ordenação.
`fields`	string	Não	Lista de campos a retornar, separada por vírgula. Valores permitidos: `id`, `host`, `port`, `active`, `use_ssl`, `order`, `domain`.
`search`	string	Não	Busca livre em `host`, `dn_base` e `account_domain_name`.
`ldap_server.host`	string	Não	Retorna os servidores com este host.
`ldap_server.port`	integer	Não	Retorna os servidores nesta porta.
`ldap_server.active`	boolean	Não	Retorna os servidores ativos ou inativos.
`ldap_server.use_ssl`	boolean	Não	Retorna os servidores com LDAPS habilitado ou desabilitado.
`ldap_server.domain_id`	integer	Não	Retorna os servidores deste domínio.
`ldap_server.bind_credential_id`	integer	Não	Retorna os servidores que fazem bind com esta credencial PAM.
`ldap_server.network_connector_id`	integer	Não	Retorna os servidores alcançados por este network connector.

Atenção

Os campos de filtro e ordenação carregam o prefixo ldap_server.. As formas curtas, como ?active=true ou ?sort_by=host:asc, não fazem parte do contrato: um filtro com o nome curto retorna 400 api.request.bad_request e um campo de ordenação curto retorna 422.

Operadores de filtro

ldap_server.host também aceita um sufixo que altera a forma como o valor é comparado. Sem sufixo, a comparação é exata.

Sufixo	Exemplo	Descrição
`_contains`	`?ldap_server.host_contains=example`	O host contém o valor.
`_starts_with`	`?ldap_server.host_starts_with=ad.`	O host começa com o valor.
`_ends_with`	`?ldap_server.host_ends_with=.com`	O host termina com o valor.

Ordenação

sort_by recebe uma lista separada por vírgula, cada segmento com um campo e uma direção separados por dois-pontos, como ldap_server.order:asc. A direção é asc ou desc.

Campos ordenáveis: id, ldap_server.host, ldap_server.port, ldap_server.active, ldap_server.use_ssl, ldap_server.order, ldap_server.created_at, ldap_server.updated_at.

Exemplo de requisição

GET {{url}}/api/v2/iam/ldap-servers?ldap_server.active=true&sort_by=ldap_server.order:asc&page=1&limit=50

Resposta

HTTP/1.1 200 OK

Exemplo de corpo da resposta

{
    "data": [
        {
            "id": 7,
            "host": "ad.example.com",
            "port": 389,
            "active": true,
            "use_ssl": false,
            "order": 1,
            "domain": { "id": 5, "name": "EXAMPLE.COM" }
        },
        {
            "id": 9,
            "host": "ad.private.example.com",
            "port": 636,
            "active": true,
            "use_ssl": true,
            "order": 2,
            "domain": null
        }
    ],
    "meta": {
        "pagination": { "page": 1, "limit": 50, "total_items": 2, "total_pages": 1 },
        "links": {
            "self": "/api/v2/iam/ldap-servers?ldap_server.active=true&sort_by=ldap_server.order:asc&page=1&limit=50"
        }
    }
}

Campos do corpo da resposta

Campo	Tipo	Descrição
`data`	array of objects	Servidores que atendem à requisição.
`data[].id`	integer	Código de identificação único do servidor, atribuído pela Segura™.
`data[].host`	string	Hostname ou endereço IP do servidor de diretório.
`data[].port`	integer	Porta em que o diretório escuta.
`data[].active`	boolean	Indica se o servidor está ativo.
`data[].use_ssl`	boolean	Indica se o LDAPS está habilitado.
`data[].order`	integer	Ordem de avaliação na cadeia de autenticação.
`data[].domain`	object	Domínio ao qual o servidor pertence. Retorna `null` quando o nome de domínio armazenado não corresponde a nenhum domínio cadastrado.
`data[].domain.id`	integer	Código de identificação do domínio.
`data[].domain.name`	string	Nome do domínio.
`meta`	object	Metadados da resposta.
`meta.pagination`	object	Estado de paginação da resposta.
`meta.pagination.page`	integer	Página retornada.
`meta.pagination.limit`	integer	Número de servidores por página.
`meta.pagination.total_items`	integer	Número total de servidores que atendem à requisição.
`meta.pagination.total_pages`	integer	Número total de páginas.
`meta.links`	object	Links de navegação para a listagem.
`meta.links.self`	string	Caminho da requisição.

Info

A listagem retorna um resumo de cada servidor, com os campos no mesmo nível dentro de cada item. O endpoint de detalhe retorna todos os atributos, aninhados sob ldap_server. Acesse GET | Listar um servidor LDAP por [id] para o formato completo.

A partir da versão 4.2.10, a resposta retorna id e o id de cada objeto aninhado como string, por exemplo "7". O corpo das requisições continua recebendo esses valores como inteiros.

Erros

Código HTTP	Mensagem	Causa possível	Solução
`400`	`api.request.bad_request`	A requisição carrega um parâmetro de query desconhecido, como um filtro sem o prefixo `ldap_server.`.	Verifique o nome do parâmetro e reenvie a requisição.
`401`	`api.auth.unauthorized`	O token de acesso está ausente ou expirou.	Solicite um novo token de acesso.
`422`	`api.sort.invalid_field`	`sort_by` nomeia um campo que não é ordenável.	Envie um dos campos indicados na seção Ordenação.
`422`	`api.sort.invalid_direction`	Um segmento de `sort_by` carrega uma direção diferente de `asc` ou `desc`.	Corrija a direção e reenvie a requisição.
`429`	`api.rate_limit.exceeded`	O limite de requisições foi excedido.	Reduza a frequência de requisições e tente novamente.

Para mensagens de erros de autenticação e a política de 403 versus 404, acesse API v2 - Convenções e comportamentos compartilhados.