POST | Criar sincronização de grupo LDAP

Descrição

Crie uma sincronização de grupo LDAP na plataforma Segura™. Uma única requisição vincula um grupo do Active Directory, identificado por um distinguished name e um filtro LDAP, a um grupo de usuários, atribui as roles de ACL que seus membros recebem e, opcionalmente, configura o bloco Domum.

A sincronização é criada no estado ativo. Criá-la não importa nenhum usuário: execute POST | Executar sincronização de grupo LDAP para iniciar a primeira importação.

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.
Um token de acesso OAuth 2.0 válido. Para mais informações, acesse Como autenticar uma aplicação no A2A.
O servidor LDAP, o grupo de usuários e quaisquer roles referenciadas na requisição já devem existir e estar ativos.
O módulo de licença cote deve estar ativo para enviar o bloco domum.

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-group-syncs

Cabeçalhos

Cabeçalho	Obrigatório	Descrição
`Content-Type`	Sim	Deve ser `application/json`.

Atenção

Este endpoint não suporta o header Idempotency-Key. Reenviar uma requisição cria uma segunda sincronização. Verifique se o recurso já existe com GET | Listar todas as sincronizações de grupos LDAP antes de reenviar.

Corpo da requisição

O corpo carrega dois objetos. group_sync contém a sincronização em si, e domum contém a integração opcional com o Domum.

`group_sync`

Campo	Tipo	Obrigatório	Descrição
`name`	string	Sim	Nome da sincronização. Máximo de 100 caracteres.
`server_id`	int	Sim	Código de identificação do servidor LDAP. O servidor deve existir e estar ativo.
`user_group_id`	int	Sim	Código de identificação do grupo de usuários que recebe os usuários sincronizados. O grupo deve existir e estar ativo.
`synchronization_enabled`	boolean	Sim	Indica se a sincronização está habilitada para rodar.
`overwrite_user_accesses`	boolean	Sim	Indica se a sincronização sobrescreve os acessos já atribuídos a um usuário. Requer que `synchronization_enabled` seja `true`.
`force_roles`	boolean	Não	Indica se a sincronização remove do usuário qualquer role que o grupo do Active Directory não concede mais. Padrão: `true`.
`automatic_sync`	boolean	Não	Indica se a plataforma executa a sincronização em sua própria agenda. Padrão: `false`.
`dn`	string	Sim	Distinguished name base pesquisado no diretório. Máximo de 255 caracteres.
`ad_username_attribute`	string	Sim	Atributo do Active Directory lido como o nome de usuário. Máximo de 255 caracteres.
`ad_name_attribute`	string	Não	Atributo do Active Directory lido como o nome completo. Valores permitidos: `name`, `displayname`, `samaccountname`, `null`. Os valores são em minúsculas.
`department_id`	int	Não	Código de identificação do departamento atribuído aos usuários sincronizados. Aceita `null`.
`ad_query`	string	Sim	Filtro LDAP que seleciona os grupos a sincronizar. Máximo de 2048 caracteres.
`role_ids`	array de int	Não	Códigos de identificação das roles de ACL atribuídas aos usuários sincronizados.

`domum`

Envie este objeto apenas quando o módulo de licença cote estiver ativo. Sem a licença, a requisição retorna 422 api.feature.unavailable.

Campo	Tipo	Obrigatório	Descrição
`enabled`	boolean	Sim	Indica se os usuários sincronizados recebem acesso no Domum.
`type`	string	Sim	Perfil de acesso concedido no Domum. Valores permitidos: `full_users`, `limited_users`.
`vendor_id`	int	Condicional	Código de identificação do fornecedor ou grupo interno. Obrigatório quando `enabled` é `true`.

Exemplo de requisição `POST` `{{url}}/api/v2/iam/ldap-group-syncs`

Corpo

{
    "group_sync": {
        "name": "Infrastructure operators",
        "server_id": 10,
        "user_group_id": 7,
        "synchronization_enabled": true,
        "overwrite_user_accesses": false,
        "force_roles": true,
        "automatic_sync": false,
        "dn": "OU=Operators,DC=example,DC=com",
        "ad_username_attribute": "sAMAccountName",
        "ad_name_attribute": "displayname",
        "ad_query": "(&(objectClass=group)(cn=ops-*))",
        "role_ids": [1, 3]
    },
    "domum": {
        "enabled": true,
        "type": "limited_users",
        "vendor_id": 22
    }
}

Resposta

HTTP/1.1 201 Created
Location: /api/v2/iam/ldap-group-syncs/501
ETag: "174f80fa9c3b4d2e"

O header Location carrega o caminho da sincronização criada e o header ETag carrega sua versão atual. Guarde o valor do ETag; PUT | Atualizar sincronização de grupo LDAP por [id], PATCH | Atualizar parcialmente sincronização de grupo LDAP por [id] e DELETE | Excluir sincronização de grupo LDAP por [id] o utilizam no header If-Match para detectar alterações concorrentes.

Exemplo de corpo da resposta

{
    "data": {
        "id": "501",
        "group_sync": {
            "name": "Infrastructure operators",
            "active": true,
            "server": { "id": "10" },
            "user_group": { "id": "7" },
            "synchronization_enabled": true,
            "overwrite_user_accesses": false,
            "force_roles": true,
            "automatic_sync": false,
            "dn": "OU=Operators,DC=example,DC=com",
            "ad_username_attribute": "sAMAccountName",
            "ad_name_attribute": "displayname",
            "department": null,
            "ad_query": "(&(objectClass=group)(cn=ops-*))",
            "roles": [{ "id": 1 }, { "id": 3 }]
        },
        "domum": {
            "enabled": true,
            "type": "limited_users",
            "vendor": { "id": 22 }
        }
    },
    "meta": {
        "links": { "self": "/api/v2/iam/ldap-group-syncs/501" },
        "actions": {
            "sync": "/api/v2/iam/ldap-group-syncs/501/sync",
            "deactivate": "/api/v2/iam/ldap-group-syncs/501/deactivate"
        }
    }
}

Campos do corpo da resposta

Campo	Tipo	Descrição
`data`	object	A sincronização criada.
`meta`	object	Links e as ações disponíveis para o recurso em seu estado atual.

`data`

Campo	Tipo	Descrição
→`id`	string	Código de identificação único da sincronização, atribuído pela Segura™.
→`group_sync`	object	As configurações da sincronização.
→`domum`	object	As configurações do Domum. Retornado apenas quando o módulo de licença `cote` está ativo.

`data.group_sync`

Campo	Tipo	Descrição
→→`name`	string	Nome da sincronização.
→→`active`	boolean	Indica se a sincronização está ativa. Uma nova sincronização é sempre criada como `true`.
→→`server`	object	O servidor LDAP, como `{ "id": <string> }`. A requisição envia `server_id`.
→→`user_group`	object	O grupo de usuários, como `{ "id": <string> }`. A requisição envia `user_group_id`.
→→`synchronization_enabled`	boolean	Indica se a sincronização está habilitada para rodar.
→→`overwrite_user_accesses`	boolean	Indica se a sincronização sobrescreve os acessos já atribuídos a um usuário.
→→`force_roles`	boolean	Indica se a sincronização remove roles que o grupo do Active Directory não concede mais.
→→`automatic_sync`	boolean	Indica se a plataforma executa a sincronização em sua própria agenda.
→→`dn`	string	Distinguished name base pesquisado no diretório.
→→`ad_username_attribute`	string	Atributo do Active Directory lido como o nome de usuário.
→→`ad_name_attribute`	string	Atributo do Active Directory lido como o nome completo. Retorna `null` quando o atributo enviado não é suportado.
→→`department`	object	O departamento atribuído aos usuários sincronizados. Retorna `null` quando não definido.
→→`ad_query`	string	Filtro LDAP que seleciona os grupos a sincronizar.
→→`roles`	array de objetos	As roles de ACL atribuídas, cada uma como `{ "id": <int> }`. A requisição envia `role_ids`.

`data.domum`

Campo	Tipo	Descrição
→→`enabled`	boolean	Indica se os usuários sincronizados recebem acesso no Domum.
→→`type`	string	Perfil de acesso concedido no Domum. Retorna `full_users` ou `limited_users`.
→→`vendor`	object	O fornecedor ou grupo interno, como `{ "id": <int> }`. A requisição envia `vendor_id`.

Atenção

Enviar ad_name_attribute com um valor que a plataforma reconhece mas não suporta retorna 201 Created e armazena null. Verifique o valor de ad_name_attribute na resposta para confirmar se o atributo foi aceito.

Erros

Código HTTP	Mensagem	Causa possível	Solução
`400`	`api.request.malformed`	O corpo não é um JSON válido.	Verifique a sintaxe do JSON e reenvie a requisição.
`403`	`api.permission.denied`	A aplicação não tem permissão para este recurso.	Peça ao administrador para verificar a autorização Users da aplicação no A2A.
`422`	`api.validation.required_field`	Um campo obrigatório está ausente ou é `null`.	Envie todos os campos obrigatórios listados nas tabelas de corpo da requisição.
`422`	`api.validation.invalid_type`	Um campo tem o tipo primitivo incorreto.	Verifique a coluna `Tipo` nas tabelas de corpo da requisição.
`422`	`api.validation.length_exceeded`	Uma string é mais longa do que a coluna permite.	Reduza o valor ao máximo documentado para o campo.
`422`	`api.validation.invalid_reference`	`server_id`, `user_group_id`, `department_id`, uma entrada em `role_ids` ou `domum.vendor_id` não existe.	Confirme que os recursos referenciados existem antes de reenviar a requisição.
`422`	`api.validation.server.inactive`	`server_id` aponta para um servidor LDAP inativo.	Ative o servidor, ou referencie um servidor ativo.
`422`	`api.validation.user_group.inactive`	`user_group_id` aponta para um grupo de usuários inativo.	Ative o grupo, ou referencie um grupo ativo.
`422`	`api.validation.overwrite.requires_sync_enabled`	`overwrite_user_accesses` é `true` enquanto `synchronization_enabled` é `false`.	Defina `synchronization_enabled` como `true`, ou defina `overwrite_user_accesses` como `false`.
`422`	`api.validation.unknown_field`	O corpo carrega uma chave que não faz parte do esquema do recurso.	Remova a chave. Verifique se o corpo usa os objetos `group_sync` e `domum`.
`422`	`api.enum.invalid_value`	`ad_name_attribute` ou `domum.type` está fora dos valores permitidos.	Envie um dos valores permitidos listados nas tabelas de corpo da requisição.
`422`	`api.feature.unavailable`	O bloco `domum` foi enviado sem o módulo de licença `cote`.	Remova o bloco `domum`, ou peça ao administrador para licenciar o módulo.
`422`	`ldap_group_sync.domum.vendor_required`	`domum.enabled` é `true` sem `domum.vendor_id`.	Envie `domum.vendor_id`.
`429`	`rate_limit_exceeded`	A aplicação excedeu sua cota de requisições.	Aguarde o período indicado no header `Retry-After` e reenvie a requisição.

Erros de autenticação

Mensagem	Causa possível	Solução
`Client authentication failed.`	Falha na autenticação da aplicação com o servidor Segura.	Verifique os parâmetros de autenticação (`Access Token URL`, `Client ID` e `Client secret`) e solicite um novo token de acesso.
`Invalid signature`	Falha no reconhecimento da URL da aplicação cliente.	Verifique a URL da aplicação cliente e reenvie a requisição.
`No route matched with those values.`	Header de autorização ausente na requisição da API.	Solicite um novo token de acesso.
`Request timed out.`	A requisição excedeu o limite de tempo.	Verifique a conectividade entre a origem da requisição e o servidor Segura.