POST | Adicionar políticas de acesso a um grupo de usuários

Descrição

Vincule uma ou mais políticas de acesso a um grupo de usuários. Cada vínculo carrega a política de acesso, o perfil que ele concede aos membros do grupo e seu nível de aprovação.

A requisição é idempotente. Quando já existe um vínculo ativo com a mesma política de acesso, a plataforma o atualiza no lugar em vez de criar um segundo, então uma requisição que altera apenas o perfil ou o nível pode ser enviada sobre um vínculo existente.

A aplicação pode vincular apenas políticas de acesso PAM liberadas para sua autorização no A2A. A regra também vale para uma autorização com o Super admin habilitado. Qualquer outra política de acesso recebe a mesma resposta de uma política que não existe, então a resposta nunca revela se ela existe.

Uma requisição que inclui qualquer política de acesso fora desse escopo não grava nada, mesmo quando os demais vínculos são válidos. Se a aplicação não tiver uma autorização ativa no A2A, ela não pode vincular nenhuma política de acesso.

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 API v2.
Um token de acesso OAuth 2.0 válido. Para mais informações, acesse Como autenticar uma aplicação A2A.
As políticas de acesso referenciadas em access_group_id devem existir previamente. Para criar uma, acesse POST | Criar política de acesso.
Cada política de acesso deve ser uma política de acesso PAM ativa, liberada para a autorização da aplicação no A2A. Para mais informações, acesse Como gerenciar autorizações no A2A API v2.

Requisição

POST /api/v2/iam/user-groups/{id}/access-policies

Parâmetros de path

Parâmetro	Tipo	Obrigatório	Descrição
`id`	integer	Sim	Código de identificação único do grupo de usuários.

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
`bindings`	array[object]	Sim	Vínculos a criar ou atualizar. O array deve conter pelo menos um valor.
`bindings[].access_group_id`	integer	Sim	Código de identificação único da política de acesso a vincular.
`bindings[].profile`	string	Sim	Papel que o vínculo concede aos membros do grupo. Valores permitidos: `user`, `approver`, `user_approver`.
`bindings[].level`	integer	Sim	Nível de aprovação do vínculo. Valores permitidos: `1`, `2`, `3`.

Atenção

access_group_id e level devem ser enviados como integers JSON. As respostas retornam os códigos de identificação como strings, como "5" em access_group.id, então converta o valor antes de reenviá-lo. Um valor em string retorna 422 com o código api.validation.required_field.

Exemplo de requisição

POST {{url}}/api/v2/iam/user-groups/7/access-policies

Corpo

{
  "bindings": [
    {
      "access_group_id": 1,
      "profile": "user",
      "level": 1
    },
    {
      "access_group_id": 2,
      "profile": "approver",
      "level": 2
    }
  ]
}

Resposta

HTTP/1.1 201 Created
Location: /api/v2/iam/user-groups/7/access-policies
X-Request-Id: 7f3c1a90-2c4e-4b1a-9f5e-0a2b7c9d1e34

Exemplo de corpo de resposta

{
  "data": {
    "binding_ids": ["200", "201"]
  },
  "meta": {
    "links": {
      "self": "/api/v2/iam/user-groups/7/access-policies"
    }
  }
}

Campos do corpo de resposta

Campo	Tipo	Descrição
`data`	object	Os vínculos criados ou atualizados.
`data.binding_ids`	array[string]	Códigos de identificação dos vínculos. Guarde esses valores, eles identificam um vínculo no momento de removê-lo.
`meta`	object	Metadados do recurso.
`meta.links.self`	string	Caminho do sub-recurso de políticas de acesso.

Erros

Código HTTP	Mensagem	Possível causa	Solução
`401`	`api.auth.unauthorized`	O token de acesso está ausente, inválido ou expirou.	Solicite um novo token de acesso.
`404`	`api.resource.not_found`	O grupo de usuários não existe ou está fora do escopo da autorização. Uma política de acesso fora do escopo nunca retorna `404`; ela retorna `422`.	Verifique o código de identificação do grupo de usuários e o escopo da autorização.
`422`	`api.validation.required_field`	O corpo não carrega `bindings`, falta um dos campos de um vínculo, ou `access_group_id` foi enviado como string.	Adicione o campo ausente, ou envie `access_group_id` como integer, e reenvie a requisição.
`422`	`api.validation.invalid_type`	Um item de `bindings` não é um objeto.	Envie cada vínculo como um objeto e reenvie a requisição.
`422`	`api.validation.invalid_reference`	Um `access_group_id` não existe, não é uma política de acesso PAM, ou não está liberado para a autorização da aplicação no A2A. A mensagem é `One or more access policies not found.`, com uma entrada em `details` para cada `access_group_id` rejeitado. Nada é gravado.	Verifique os códigos e as políticas de acesso liberadas para a autorização, e reenvie a requisição.
`422`	`api.validation.access_policy.not_bindable`	Uma política de acesso liberada para a autorização da aplicação está inativa. Só podem ser vinculadas políticas de acesso PAM ativas e liberadas para a autorização. A mensagem é `One or more access policies cannot be bound to a user group: inactive, or of a type the user group screen does not offer.`	Ative a política de acesso e reenvie a requisição.
`422`	`api.enum.invalid_value`	O `profile` está fora da lista permitida, ou o `level` não é o integer `1`, `2` ou `3`.	Verifique os valores permitidos e reenvie a requisição.
`429`	`api.rate_limit_exceeded`	O limite de requisições foi excedido.	Aguarde o número de segundos retornado no cabeçalho `Retry-After` e tente novamente.

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