--- title: "POST | Criar servidor LDAP" slug: "api-v2-post-create-ldap-server" updated: 2026-11-03T14:57:57Z published: 2026-11-03T14:57:57Z canonical: "docs.senhasegura.io/api-v2-post-create-ldap-server" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.senhasegura.io/llms.txt > Use this file to discover all available pages before exploring further. # POST | Criar servidor LDAP ## Descrição Crie um perfil de conexão de servidor LDAP/AD na plataforma Segura™. Uma única requisição define o host e a porta, a credencial PAM usada no bind, a DN base, o formato da conta, a ordem de avaliação na cadeia de autenticação e os parâmetros de consulta de grupo. O servidor é criado no estado ativo e entra imediatamente na cadeia de autenticação. É o mesmo registro que a interface web gerencia em **Settings** > **Authentication** > **LDAP/AD**: um servidor criado aqui aparece lá, e vice-versa. --- ## Pré-requisitos - Uma aplicação com a autorização **Users** concedida pelo administrador no A2A, com a permissão do recurso definida como **Leitura e escrita**. Para mais informações, acesse [Como gerenciar autorizações no A2A](/v4-2/docs/how-to-manage-authorizations-in-a2a). - Um token de acesso OAuth 2.0 válido. Para mais informações, acesse [Como autenticar uma aplicação A2A](/v4-2/docs/how-to-authenticate-an-application-in-a2a). - Um domínio cadastrado na plataforma, para referenciar em `domain_id`. - Uma credencial PAM contendo a conta de bind, para referenciar em `bind_credential_id`. Info Um token de acesso carrega apenas as autorizações que existiam no momento em que foi gerado. Depois que o administrador habilitar a autorização **Users**, gere um novo token para a aplicação: um token existente não passa a ter a nova autorização. --- ## Requisição `POST` `/api/v2/iam/ldap-servers` ### Cabeçalhos | Cabeçalho | Obrigatório | Descrição | | --- | --- | --- | | `Content-Type` | Sim | Deve ser `application/json`. | ### Corpo da requisição | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `host` | string | Sim | Hostname ou endereço IP do servidor de diretório. Máximo de 200 caracteres. | | `port` | integer | Sim | Porta em que o diretório escuta. Valores permitidos: `1` a `65535`. | | `dn_base` | string | Sim | DN base para buscas de usuário. Máximo de 255 caracteres. | | `use_ssl` | boolean | Sim | Habilita o LDAPS. | | `member_is_dn` | boolean | Sim | Indica que o atributo de membro retorna uma DN completa. | | `bind_requires_dn` | boolean | Sim | Indica que o diretório exige uma DN para o bind. | | `account_form` | string | Sim | Formato de usuário esperado pelo diretório. Valores permitidos: `dn`, `username`, `backslash`, `principal`, `null`. | | `order` | integer | Sim | Ordem de avaliação na cadeia de autenticação. O valor menor é avaliado primeiro. Deve ser único entre os servidores ativos. | | `domain_id` | integer | Sim | Código de identificação do domínio ao qual o servidor pertence. | | `bind_credential_id` | integer | Sim | Código de identificação da credencial PAM usada no bind. | | `use_credential_domain` | boolean | Sim | Usa o domínio da credencial de bind em vez do domínio próprio do servidor. A credencial deve ter um domínio. | | `ignore_disabled_expired` | boolean | Sim | Ignora contas expiradas durante a sincronização de grupo. | | `network_connector_id` | integer | Não | Código de identificação do agente de network connector usado para alcançar o servidor. Retorna `null` quando o servidor é alcançado diretamente. | | `account_filter_format` | string | Não | Filtro LDAP customizado usado para localizar uma conta, em que `%s` é o placeholder do nome de usuário. Máximo de 100 caracteres. | | `username_attribute` | string | Não | Atributo do diretório que contém o nome de usuário. Padrão: `uid`. Máximo de 30 caracteres. | | `dn_bind` | string | Não | Caminho base usado na operação de bind. Máximo de 200 caracteres. | | `group` | string | Não | Restringe a autenticação aos membros deste grupo. Máximo de 200 caracteres. | | `group_dn` | string | Não | DN base para buscas de grupo. Máximo de 200 caracteres. | | `group_attribute` | string | Não | Atributo do diretório que contém o nome do grupo. Máximo de 200 caracteres. | | `group_scope` | string | Não | Escopo da busca de grupo. Valores permitidos: `subtree`, `onelevel`, `base`, `null`. | | `group_filter` | string | Não | Filtro LDAP aplicado ao buscar grupos. Máximo de 200 caracteres. | | `member_attribute` | string | Não | Atributo do grupo que lista seus membros. Máximo de 200 caracteres. | Atenção `bind_credential_id` é obrigatório. A API faz o bind no diretório por meio de uma credencial PAM e não aceita um nome de usuário e senha enviados no corpo da requisição. Três campos não podem ser enviados. O estado `active` é alterado por meio de [POST | Ativar servidor LDAP](/v4-2/docs/api-v2-post-activate-ldap-server) e [POST | Desativar servidor LDAP](/v4-2/docs/api-v2-post-deactivate-ldap-server), e `account_domain_name` e `account_domain_name_short` são derivados do domínio referenciado em `domain_id`. Enviar qualquer um dos três retorna `422 patch.field.not.allowed`. --- ### Exemplo de requisição `POST` `{{url}}/api/v2/iam/ldap-servers` #### Corpo ``` { "host": "ad.example.com", "port": 389, "dn_base": "CN=Users,DC=example,DC=com", "use_ssl": false, "member_is_dn": false, "bind_requires_dn": false, "account_form": "principal", "order": 1, "domain_id": 5, "bind_credential_id": 102, "use_credential_domain": false, "ignore_disabled_expired": false } ``` --- ## Resposta ``` HTTP/1.1 201 Created Location: /api/v2/iam/ldap-servers/7 ``` O cabeçalho `Location` contém o caminho do servidor criado. Info Na versão 4.2.7, a resposta `201` não carrega um cabeçalho `ETag`. A partir da versão 4.2.10, ela carrega, e você pode usar esse valor diretamente em `If-Match`. Envie uma requisição [GET | Listar um servidor LDAP por [id]](/v4-2/docs/api-v2-get-list-an-ldap-server) para o caminho em `Location` para ler a versão atual do servidor, que [PUT | Atualizar servidor LDAP por [id]](/v4-2/docs/api-v2-put-update-ldap-server) e [PATCH | Atualizar parcialmente servidor LDAP por [id]](/v4-2/docs/api-v2-patch-update-ldap-server) exigem no cabeçalho `If-Match`. ### 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": "svc-ldap@example.com", "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 | Campo | Tipo | Descrição | | --- | --- | --- | | `data` | object | O servidor LDAP criado. | | `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. Um servidor criado sempre 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. | | `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. | | `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 criado. | | `meta.links.self` | string | Caminho do servidor criado. | | `meta.actions` | object | Ações disponíveis para o servidor em seu estado atual. Um servidor criado como ativo oferece `test-connection` e `deactivate`. | 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. --- ## 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. | Remova o 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. | | `403` | `api.auth.forbidden` | A autorização não tem permissão para gerenciar servidores LDAP. | Peça ao administrador para verificar a autorização **Users** no A2A e gerar um novo token. | | `422` | `api.validation.required_field` | Um campo obrigatório está ausente do corpo da requisição. | Adicione o campo ausente e reenvie a requisição. | | `422` | `api.validation.invalid_type` | Um campo recebeu um valor de tipo incorreto. | Verifique o tipo esperado para o campo e reenvie a requisição. | | `422` | `api.validation.port.out_of_range` | `port` está fora do intervalo de `1` a `65535`. | Envie uma porta dentro do intervalo. | | `422` | `api.validation.order.duplicate` | Outro servidor ativo já usa este valor de `order`. | Envie um valor diferente ou desative o servidor que usa esse valor. | | `422` | `api.validation.invalid_reference` | O domínio, a credencial ou o network connector referenciado não existe. | Verifique os códigos de identificação enviados em `domain_id`, `bind_credential_id` e `network_connector_id`. | | `422` | `api.enum.invalid_value` | `account_form` ou `group_scope` recebeu um valor fora da lista permitida. | Verifique os valores permitidos para o campo e reenvie a requisição. | | `422` | `patch.field.not.allowed` | O corpo carrega um campo somente leitura, como `active`, `account_domain_name` ou `account_domain_name_short`. | Remova o 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. | ### Exemplo de resposta de erro `422` outro servidor ativo já usa o valor de `order`: ``` { "code": "api.validation.order.duplicate", "message": "Another active LDAP server already uses this order.", "details": [ { "field": "order", "code": "api.validation.order.duplicate" } ] } ``` Para mensagens de erros de autenticação e a política de `403` versus `404`, acesse [API v2 - Convenções e comportamentos compartilhados](/v4-2/docs/api-v2-conventions-and-shared-behaviors).