GET | Listar um servidor LDAP por [id]

Descrição

Acesse todos os atributos de um perfil de conexão de servidor LDAP/AD na plataforma Segura™. A resposta carrega a versão atual do servidor no cabeçalho ETag, que os endpoints de atualização exigem, e as ações disponíveis para o servidor em seu estado atual.

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/{id}

Parâmetros de caminho

Campo	Tipo	Obrigatório	Descrição
`id`	integer	Sim	Código de identificação único do servidor LDAP. Nota: este valor é atribuído pela Segura™ em POST \| Criar servidor LDAP.

Parâmetros de query

Campo	Tipo	Obrigatório	Descrição
`fields`	string	Não	Lista de campos a retornar, separada por vírgula, como `id,ldap_server.host,ldap_server.active`.

Cabeçalhos

Cabeçalho	Obrigatório	Descrição
`If-None-Match`	Não	Versão que o cliente já possui. Quando corresponde à versão atual do servidor, a resposta é `304 Not Modified` sem corpo.

Exemplo de requisição

GET {{url}}/api/v2/iam/ldap-servers/7

Resposta

HTTP/1.1 200 OK
ETag: "a3f8c2e1d9b04567"

O cabeçalho ETag contém a versão atual do servidor. Guarde o valor: PUT | Atualizar servidor LDAP por [id] e PATCH | Atualizar parcialmente servidor LDAP por [id] o exigem no cabeçalho If-Match para detectar alterações concorrentes.

Exemplo de corpo da resposta

{
    "data": {
        "id": 7,
        "ldap_server": {
            "host": "ad.example.com",
            "port": 389,
            "dn_base": "CN=Users,DC=example,DC=com",
            "active": true,
            "use_ssl": false,
            "member_is_dn": false,
            "bind_requires_dn": false,
            "account_form": "principal",
            "order": 1,
            "domain": { "id": 5, "name": "EXAMPLE.COM" },
            "bind_credential": {
                "id": 102,
                "username": "[email protected]",
                "domain": { "id": 5, "name": "EXAMPLE.COM" }
            },
            "network_connector": null,
            "account_filter_format": null,
            "use_credential_domain": false,
            "ignore_disabled_expired": false,
            "username_attribute": null,
            "dn_bind": null,
            "account_domain_name": "EXAMPLE.COM",
            "account_domain_name_short": "EXAMPLE",
            "group": null,
            "group_dn": null,
            "group_attribute": null,
            "group_scope": null,
            "group_filter": null,
            "member_attribute": null,
            "created_at": "2026-05-08T22:42:34+00:00",
            "updated_at": "2026-05-08T22:42:34+00:00"
        }
    },
    "meta": {
        "links": { "self": "/api/v2/iam/ldap-servers/7" },
        "actions": {
            "test-connection": "/api/v2/iam/ldap-servers/7/test-connection",
            "deactivate": "/api/v2/iam/ldap-servers/7/deactivate"
        }
    }
}

Campos do corpo da resposta

Info

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.

Campo	Tipo	Descrição
`data`	object	O servidor LDAP.
`data.id`	integer	Código de identificação único do servidor, atribuído pela Segura™.
`data.ldap_server`	object	Atributos do servidor.
`data.ldap_server.host`	string	Hostname ou endereço IP do servidor de diretório.
`data.ldap_server.port`	integer	Porta em que o diretório escuta.
`data.ldap_server.dn_base`	string	DN base para buscas de usuário.
`data.ldap_server.active`	boolean	Indica se o servidor está ativo.
`data.ldap_server.use_ssl`	boolean	Indica se o LDAPS está habilitado.
`data.ldap_server.member_is_dn`	boolean	Indica que o atributo de membro retorna uma DN completa.
`data.ldap_server.bind_requires_dn`	boolean	Indica que o diretório exige uma DN para o bind.
`data.ldap_server.account_form`	string	Formato de usuário esperado pelo diretório. Retorna `dn`, `username`, `backslash`, `principal` ou `null`.
`data.ldap_server.order`	integer	Ordem de avaliação na cadeia de autenticação.
`data.ldap_server.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.ldap_server.domain.id`	integer	Código de identificação do domínio.
`data.ldap_server.domain.name`	string	Nome do domínio.
`data.ldap_server.bind_credential`	object	Credencial PAM usada no bind.
`data.ldap_server.bind_credential.id`	integer	Código de identificação da credencial.
`data.ldap_server.bind_credential.username`	string	Nome de usuário da credencial.
`data.ldap_server.bind_credential.domain`	object	Domínio da credencial.
`data.ldap_server.network_connector`	object	Agente de network connector usado para alcançar o servidor. Retorna `null` quando o servidor é alcançado diretamente.
`data.ldap_server.network_connector.id`	integer	Código de identificação do agente de network connector.
`data.ldap_server.network_connector.name`	string	Nome do agente de network connector.
`data.ldap_server.account_filter_format`	string	Filtro LDAP customizado usado para localizar uma conta.
`data.ldap_server.use_credential_domain`	boolean	Indica se o domínio da credencial de bind é usado.
`data.ldap_server.ignore_disabled_expired`	boolean	Indica se contas expiradas são ignoradas durante a sincronização de grupo.
`data.ldap_server.username_attribute`	string	Atributo do diretório que contém o nome de usuário.
`data.ldap_server.dn_bind`	string	Caminho base usado na operação de bind.
`data.ldap_server.account_domain_name`	string	Nome de domínio aplicado às contas. Derivado do domínio referenciado e somente leitura.
`data.ldap_server.account_domain_name_short`	string	Nome de domínio curto aplicado às contas. Derivado do domínio referenciado e somente leitura.
`data.ldap_server.group`	string	Grupo cujos membros têm permissão para autenticar.
`data.ldap_server.group_dn`	string	DN base para buscas de grupo.
`data.ldap_server.group_attribute`	string	Atributo do diretório que contém o nome do grupo.
`data.ldap_server.group_scope`	string	Escopo da busca de grupo. Retorna `subtree`, `onelevel`, `base` ou `null`.
`data.ldap_server.group_filter`	string	Filtro LDAP aplicado ao buscar grupos.
`data.ldap_server.member_attribute`	string	Atributo do grupo que lista seus membros.
`data.ldap_server.created_at`	datetime	Data e hora de criação do servidor, no formato ISO 8601.
`data.ldap_server.updated_at`	datetime	Data e hora da última alteração do servidor, no formato ISO 8601.
`meta`	object	Metadados do recurso.
`meta.links`	object	Links de navegação para o recurso.
`meta.links.self`	string	Caminho do servidor.
`meta.actions`	object	Ações disponíveis para o servidor em seu estado atual.

Atenção

meta.actions segue o estado do servidor. Um servidor ativo oferece test-connection e deactivate; um servidor inativo oferece test-connection e activate.

Um servidor desativado por meio de DELETE | Desativar servidor LDAP por [id] continua legível. A requisição retorna 200 OK com active definido como false, não 404 Not Found.

Erros

Código HTTP	Mensagem	Causa possível	Solução
`401`	`api.auth.unauthorized`	O token de acesso está ausente ou expirou.	Solicite um novo token de acesso.
`403`	`api.auth.forbidden`	A autorização não tem permissão para ler servidores LDAP.	Peça ao administrador para verificar a autorização Users no A2A e gerar um novo token.
`404`	`api.resource.not_found`	O servidor não existe.	Verifique o código de identificação enviado no caminho.
`422`	`api.validation.invalid_field`	`fields` nomeia um campo que não existe.	Verifique os nomes de campo 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.