Configurar uma conexão ITSM REST genérica

A Segura® Platform pode exigir um ticket do seu ITSM antes de conceder acesso privilegiado. Quando o seu ITSM não tem uma integração dedicada, use este tipo de conexão. Você descreve o endpoint, a autenticação e como ler a resposta; a plataforma passa a validar tickets contra ele sem nenhum desenvolvimento.

Requisitos

• Um perfil de administrador. Somente administradores podem criar, editar, testar e desativar conexões ITSM.
• Um ITSM que exponha seus tickets por uma API REST ou OData e responda em JSON. Respostas em XML não são suportadas.
• A URL base dessa API, servida por HTTPS.
• Dados de autenticação para um dos métodos suportados: OAuth 2.0 Client Credentials, API key, token de sessão ou token composto.
• O número de um ticket real para testar a configuração.

Passos

O formulário é um assistente com seis abas: Geral, Autenticação, Consulta,
Comportamento, Fallback e Revisão.

1. Na Segura® Platform, na barra de navegação, passe o mouse sobre o Menu de produtos e selecione Configurações.

2. No menu lateral, selecione Integrações > ITSM > Conexões ITSM.

3. No relatório Conexões ITSM, na barra superior, clique em + Adicionar.

4. Na tela Cadastro de integração com sistema de ticket, selecione Generic REST.

5. Na aba Geral, preencha os campos a seguir:

   • Nome da conexão *: identifica a conexão na Segura® Platform e precisa ser único. Os solicitantes também veem esse nome ao escolher uma origem ITSM no momento do acesso.
   • URL da instância *: a URL base da API do ITSM. Precisa começar com https://. A plataforma recusa HTTP puro, inclusive em ambientes de laboratório e homologação.
   • Status: ative para disponibilizar a conexão para validação.
   • Conector padrão do tenant: ative para que esta seja a conexão usada quando o solicitante não escolhe nenhuma e nenhuma política de acesso define uma. Apenas uma conexão por tenant pode ser a padrão.
   • Descrição: texto livre para seu próprio controle. Não afeta a validação.

6. Clique em Continuar.

7. Na aba Autenticação, selecione o Método de autenticação *. As opções são OAuth 2.0 Client Credentials, API key, Session token e token composto. Basic (usuário e senha) também aparece na lista, mas está desabilitado e não pode ser selecionado em uma conexão REST genérica.

8. Preencha os campos exibidos pelo método selecionado:

   • OAuth 2.0 Client Credentials: Client ID e Client Secret. Preencha URL do token (opcional) quando um servidor de identidade separado emitir os tokens, como Microsoft Entra ID, Keycloak ou Okta, e Scope (opcional) quando o provedor exigir que a requisição declare para que serve o token. Use Envio das credenciais para enviar as credenciais no corpo da requisição ou em um cabeçalho HTTP.
   • API key: Secret para a chave em si e Header de autenticação para o cabeçalho que a transporta.
   • Session token: Rota de login para o endpoint que emite o token e Campo do token na resposta para a posição do token na resposta.
   • token composto: Template do valor, que monta a credencial a partir de suas partes.

9. Clique em Continuar.

10. Na aba Consulta, descreva como a plataforma encontra o ticket:

    • método HTTP: GET ou POST.
    • Template da consulta *: a requisição que recupera o ticket. Escreva {ticket_id} onde entra o número do ticket, por exemplo tickets?filter=number eq '{ticket_id}'. {ticket_id} é o único placeholder disponível.
    • Template do corpo (POST): o payload JSON a enviar. Aparece somente quando o método é POST.
    • Caminho da lista na resposta: o caminho até o nó que carrega os registros do ticket, por exemplo value ou result.

11. Em Regra de aprovação, defina quando um ticket conta como aprovado:

    • Resposta não-vazia aprova: qualquer registro retornado pela consulta aprova a solicitação.
    • Campo igual ao valor: preencha Campo de aprovação com o campo da resposta que carrega o estado de aprovação e Valor aprovado com o valor que significa aprovado.

12. Para negar acesso fora de uma janela de validade, preencha os campos a seguir:

    • Campo de início da validade e Campo de fim da validade: os campos da resposta que guardam o início e o fim da janela. Preencha os dois ou nenhum.
    • Fuso horário da validação *: o fuso horário usado para ler esses campos. A Segura® Platform armazena datas em UTC e converte com essa configuração, então o resultado pode divergir do
      relógio local de quem testa perto da virada do dia.
    • Formato de data *: o formato que o ITSM retorna. Selecione Outro formato... para informar uma máscara em Formato personalizado. Com um formato apenas de data, o fim da janela é inclusivo até 23:59:59 daquele dia.

13. Para verificar quem pediu o acesso e o que está sendo acessado, ative a regra correspondente e informe o campo da resposta que carrega o valor:

    • Exigir solicitante = usuário e depois preencha Campo do solicitante (resposta).
    • Exigir alvo = dispositivo/conta e depois preencha Campo do alvo (resposta). O valor precisa corresponder ao endereço IP ou hostname do dispositivo, ou ao nome de usuário da credencial.
    Info

    Deixe Exigir alvo = dispositivo/conta desativado quando nenhum campo da resposta do ITSM carregar um host. Um campo que traga outra coisa, como o nome de um site ou de um prédio, nunca corresponde a um dispositivo nem a uma credencial, então toda solicitação seria negada.

14. Quando o estado de aprovação não vem junto com o ticket, ative 2ª chamada de aprovação e preencha Rota da 2ª chamada, Campo de aprovação (2ª chamada) e Valor aprovado (2ª chamada).

15. Clique em Continuar.

16. Na aba Comportamento, ajuste os parâmetros de rede:

    • Timeout de conexão (segundos): quanto tempo esperar para estabelecer a conexão. Padrão: 10.
    • Timeout de leitura (segundos): quanto tempo esperar pela resposta do ITSM. Padrão: 30.
    • Máximo de tentativas: quantas vezes tentar novamente após uma falha de comunicação. Padrão: 3.
    • TTL do cache de validação (segundos): por quanto tempo um resultado de validação é reaproveitado antes de a plataforma consultar o ITSM outra vez. Padrão: 60.
    • Intervalo do health check (minutos): com que frequência a sonda de saúde executa. Padrão: 5.

17. Clique em Continuar.

18. Na aba Fallback, selecione o comportamento a aplicar quando o ITSM não puder ser alcançado:

    • Negar acesso quando o ITSM estiver inacessível: nenhum acesso é concedido. Recomendado.
    • Permitir apenas acesso emergencial (break-glass): o acesso é concedido somente pelo procedimento de emergência.
    • Permitir acesso e registrar para auditoria posterior: o acesso é concedido e o evento fica registrado para revisão.

19. Clique em Continuar.

20. Volte à aba Consulta e teste a configuração antes de salvar:

    • Ticket de teste: o número de um ticket real.
    • Usuário de teste (solicitante): o nome de usuário a testar, quando a regra de solicitante está ativa.
    • IP de amostra (teste) e Usuário-alvo de amostra (teste): os valores a testar, quando a regra de alvo está ativa.
    • Clique em Testar conexão.

21. Leia o resultado. Uma caixa verde Would APPROVE this ticket indica que a consulta teve sucesso e todas as condições foram atendidas. Uma caixa vermelha Would DENY this ticket indica que a requisição retornou dados, mas uma verificação falhou, por exemplo um solicitante que não corresponde. O teste executa a mesma pipeline de uma validação real, incluindo a segunda chamada de aprovação quando configurada, mas não salva nada e não gera nenhuma entrada de log.

22. Vá até a aba Revisão, confira a configuração e clique em Salvar.

Disponibilizar a conexão para uso

Uma conexão salva é usada conforme cada solicitação resolve a sua origem. Além de Conector padrão do tenant na aba Geral, você pode fixar uma conexão em uma única política de
acesso: na aba Aprovadores da política, selecione-a no campo Conexão ITSM. Isso tem precedência sobre o padrão do tenant para essa política.

Tópicos relacionados

• Configurações da conexão ITSM REST genérica
• Sobre a integração ITSM da Segura®