Este documento apresenta informações sobre a conexão ITSM REST genérica, que permite à Segura® Platform validar tickets de acesso em qualquer ITSM que exponha uma API REST ou OData. Ele cobre os campos do formulário da conexão e o comportamento da validação depois que a conexão entra em uso. Mais informações em Configurar uma conexão ITSM REST genérica.
Caminho para acesso
- Na Segura® Platform, na barra de navegação, passe o mouse sobre o Menu de produtos e selecione Configurações.
- No menu lateral, selecione Integrações > ITSM > Conexões ITSM.
- Na barra superior, clique em + Adicionar e selecione Generic REST.
Geral
Identifica a conexão, aponta para a API do ITSM e define se ela é a padrão do tenant.
| Item | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| Nome da conexão | Campo de texto | Sim | Identifica a conexão na Segura® Platform e precisa ser único no tenant. Os solicitantes veem esse nome ao escolher uma origem ITSM no momento do acesso. |
| URL da instância | Campo de texto | Sim | URL base da API REST ou OData do ITSM. Precisa começar com https://. A plataforma recusa HTTP puro incondicionalmente, inclusive em ambientes de laboratório e homologação, e valida o formato da URL na própria tela. |
| Status | Botão toggle | Não | Disponibiliza a conexão para validação. Somente conexões ativas são usadas para validar tickets e somente conexões ativas aparecem no seletor de origem ITSM. |
| Conector padrão do tenant | Botão toggle | Não | Torna esta a conexão usada quando o solicitante não escolhe uma origem e nenhuma política de acesso define uma. Apenas uma conexão por tenant pode ter essa marcação. |
| Descrição | Campo de texto | Não | Texto livre para controle interno. Não afeta a validação. |
Autenticação
| Item | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| Método de autenticação | Menu suspenso | Sim | Define como a plataforma se autentica na API do ITSM e determina quais campos a aba exibe. 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. |
OAuth 2.0 Client Credentials
A plataforma solicita um token temporário uma vez e depois envia apenas esse token em cada consulta de ticket, renovando-o quando expira. Deixe Token URL e Scope em branco para manter o comportamento de uma instância no padrão ServiceNow, que emite tokens em um caminho fixo dentro da própria instância.
| Item | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| Client ID | Campo de texto | Sim | Identificador da aplicação registrada no provedor de token. |
| Client Secret | Campo de texto | Sim | Segredo dessa aplicação. Fica armazenado no cofre e nunca aparece na configuração salva. Editar uma conexão sem redigitá-lo mantém o valor armazenado. |
| URL do token (opcional) | Campo de texto | Não | Endereço que emite o token. Preencha quando um servidor de identidade separado emitir os tokens, como Microsoft Entra ID, Keycloak ou Okta, em vez da instância do ITSM. |
| Scope (opcional) | Campo de texto | Não | Declara para que serve o token. Alguns provedores recusam emitir o token quando a requisição não informa esse valor. |
| Envio das credenciais | Menu suspenso | Não | Define se o identificador e o segredo da aplicação vão no corpo da requisição ou em um cabeçalho HTTP. A especificação do OAuth permite as duas formas, e alguns provedores aceitam apenas uma. |
Quando o provedor não emite o token, a plataforma registra uma falha de autenticação nos logs de diagnóstico e reproduz a mensagem de erro do próprio provedor. Leia essa mensagem antes de suspeitar da configuração de consulta.
O fluxo resource owner password credentials do OAuth 2.0, em que a aplicação envia também o usuário e a senha de uma conta de serviço, não é suportado. Ele aparece em integrações antigas de ServiceNow e Ivanti, e as orientações modernas de OAuth o desencorajam. Um provedor que aceite apenas esse fluxo não pode ser usado com uma conexão REST genérica.
API key
| Item | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| Header de autenticação | Campo de texto | Sim | Nome do cabeçalho HTTP que transporta a chave. |
| Secret | Campo de texto | Sim | A própria chave de API. Fica armazenada no cofre. |
Session token
| Item | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| Rota de login | Campo de texto | Sim | Endpoint que emite o token de sessão, relativo à URL da instância. |
| Campo do token na resposta | Campo de texto | Sim | Caminho até o token na resposta do login. |
Token composto
| Item | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| Template do valor | Campo de texto | Sim | Modelo que monta o valor da credencial a partir de suas partes. O segredo real fica no cofre e é referenciado pelo modelo, em vez de armazenado na configuração. |
Consulta
Descreve a requisição que recupera o ticket e como ler a resposta.
Busca do ticket
| Item | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| método HTTP | Menu suspenso | Sim | Método usado na consulta do ticket. As opções são GET e POST. |
| Template da consulta | Campo de texto | Sim | Requisição que recupera o ticket, relativa à URL da instância. Escreva {ticket_id} onde entra o número do ticket. Exemplo: tickets?filter=number eq '{ticket_id}'. |
| Template do corpo (POST) | Campo de texto | Não | Payload JSON enviado com a requisição. Aparece somente quando HTTP method é POST. |
| Caminho da lista na resposta | Campo de texto | Não | Caminho até o nó que carrega os registros do ticket, aplicado antes da leitura de qualquer campo. Exemplo: value ou result. Deixe em branco quando o payload for um objeto plano na raiz. |
{ticket_id} é o único placeholder aceito por uma conexão REST genérica.
Aprovação
| Item | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| Regra de aprovação | Menu suspenso | Sim | Define quando um ticket retornado conta como aprovado. Resposta não-vazia aprova: qualquer registro retornado pela consulta aprova a solicitação. Campo igual ao valor: um campo da resposta precisa carregar um valor específico. |
| Campo de aprovação | Campo de texto | Condicional | Campo da resposta que carrega o estado de aprovação. Obrigatório quando Regra de aprovação é Campo igual ao valor. |
| Valor aprovado | Campo de texto | Condicional | Valor desse campo que significa aprovado. Obrigatório quando Regra de aprovação é Campo igual ao valor. |
| 2ª chamada de aprovação | Botão toggle | Não | Consulta um segundo endpoint para obter o estado de aprovação, para ITSMs que não o retornam junto com o ticket. |
| Rota da 2ª chamada | Campo de texto | Condicional | Endpoint da segunda chamada. Obrigatório quando 2ª chamada de aprovação está ativo. |
| Campo de aprovação (2ª chamada) | Campo de texto | Condicional | Campo da resposta da segunda chamada que carrega o estado de aprovação. |
| Valor aprovado (2ª chamada) | Campo de texto | Condicional | Valor desse campo que significa aprovado. |
Janela de validade
Nega o acesso fora de uma janela que o ITSM retorna com o ticket. Preencha os dois nomes de campo ou nenhum.
| Item | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| Campo de início da validade | Campo de texto | Não | Campo da resposta que guarda o início da janela. |
| Campo de fim da validade | Campo de texto | Não | Campo da resposta que guarda o fim da janela. |
| Fuso horário da validação | Menu suspenso (fuso horário IANA) | Sim | Fuso horário usado para ler os campos de data e hora da resposta. A Segura® Platform armazena datas em UTC e converte com essa configuração, então uma validação perto da virada do dia pode divergir do relógio local de quem testa. |
| Formato de data | Menu suspenso | Sim | Formato que o ITSM retorna nesses campos. Selecione Outro formato... para informar uma máscara em Formato personalizado. |
| Formato personalizado | Campo de texto | Condicional | Máscara de formato, por exemplo d.m.Y ou Y-m-d H:i:s. Obrigatório quando Formato de data é Outro formato.... |
Verificações de solicitante e alvo
Cada verificação é opcional e precisa do campo da resposta que carrega o valor.
| Item | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| Exigir solicitante = usuário | Botão toggle | Não | Compara o usuário da Segura® Platform com um campo do ticket. |
| Campo do solicitante (resposta) | Campo de texto | Condicional | Campo da resposta que guarda o solicitante. Obrigatório quando a chave está ativa. |
| Exigir alvo = dispositivo/conta | Botão toggle | Não | Compara o alvo do acesso com um campo do ticket. Deixe desativado quando nenhum campo da resposta carregar um host: um campo que traga outra coisa, como o nome de um site ou de um prédio, nunca corresponde, então toda solicitação é negada. |
| Campo do alvo (resposta) | Campo de texto | Condicional | Campo da resposta que guarda o alvo. Obrigatório quando a chave está ativa. O valor precisa corresponder ao endereço IP ou hostname do dispositivo, ou ao nome de usuário da credencial. |
Teste da conexão
Executa antes de salvar, na parte inferior da aba Consulta.
| Item | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| Ticket de teste | Campo de texto | Não | Número de um ticket real usado pelo teste e pela sonda de saúde periódica. Sem ele, a sonda mede apenas se o endpoint responde. Qualquer resposta HTTP conta como alcançável, então uma autenticação quebrada continua sendo reportada como saudável. |
| Usuário de teste (solicitante) | Campo de texto | Não | Nome de usuário que o teste usa quando a verificação de solicitante está ativa. |
| IP de amostra (teste) | Campo de texto | Não | Endereço IP que o teste usa quando a verificação de alvo está ativa. |
| Usuário-alvo de amostra (teste) | Campo de texto | Não | Nome de usuário de alvo que o teste usa quando a verificação de alvo está ativa. |
| Testar conexão | Botão | n/a | Executa a mesma pipeline de uma validação real, incluindo a segunda chamada de aprovação quando configurada. Não salva nada e não gera nenhuma entrada de log. O resultado aparece na própria tela: uma caixa verde Would APPROVE this ticket quando a consulta teve sucesso e todas as condições foram atendidas, ou uma caixa vermelha Would DENY this ticket quando a requisição retornou dados, mas uma verificação falhou. |
Comportamento
Parâmetros de rede da conexão. Todos têm um valor padrão, então a aba pode ser deixada como está.
| Item | Tipo | Padrão | Descrição |
|---|---|---|---|
| Timeout de conexão (segundos) | Campo numérico | 10 | Quanto tempo a plataforma espera para estabelecer a conexão. |
| Timeout de leitura (segundos) | Campo numérico | 30 | Quanto tempo a plataforma espera pela resposta do ITSM. |
| Máximo de tentativas | Campo numérico | 3 | Quantas vezes a plataforma tenta novamente após uma falha de comunicação. |
| TTL do cache de validação (segundos) | Campo numérico | 60 | Por quanto tempo um resultado de validação é reaproveitado antes de a plataforma consultar o ITSM outra vez. |
| Intervalo do health check (minutos) | Campo numérico | 5 | Com que frequência a sonda de saúde executa na conexão. |
Fallback
O que a plataforma faz quando o ITSM não pode ser alcançado.
| Item | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| Comportamento de fallback | Botão de opção | Sim | As opções são Negar acesso quando o ITSM estiver inacessível (nenhum acesso é concedido; a configuração recomendada), Permitir apenas acesso emergencial (break-glass) (acesso somente pelo procedimento de emergência) e Permitir acesso e registrar para auditoria posterior (o acesso é concedido e fica registrado para revisão). |
Não existe opção fail-open. Uma política de acesso pode sobrescrever essa escolha para si, em Comportamento de fallback (override) na aba Aprovadores.
Como a validação funciona
Verificações de validação
Cada verificação é fail-closed: uma verificação que não pode ser satisfeita nega o acesso em vez de deixar passar.
| Verificação | O que confirma |
|---|---|
| Janela de validade | A data e a hora atuais estão dentro da janela que o ticket retorna. |
| Aprovação | A resposta satisfaz a regra de aprovação da conexão. |
| Solicitante | O ticket nomeia o usuário que está pedindo o acesso. |
| Alvo | O ticket nomeia o dispositivo ou a conta que está sendo acessada. |
A Segura® Platform consulta o ITSM somente para leitura. Ela nunca abre, atualiza nem fecha um ticket.
Tratamento da resposta
| Item | Descrição |
|---|---|
| Formato da resposta | Apenas JSON. Respostas em XML não são suportadas. |
| Múltiplos registros | Quando a consulta retorna vários registros, a solicitação é aprovada se um único registro passar por todas as verificações ativas nele mesmo. Campos nunca são combinados entre registros. |
| Comparação de valores | As comparações de aprovação, solicitante e alvo ignoram diferenças de maiúsculas e minúsculas e espaços no início e no fim. |
| Nomes de campo | Nomes de campo retirados da resposta do ITSM são tratados como strings opacas e nunca são traduzidos. |
| Mensagem ao solicitante | Um solicitante negado vê uma mensagem genérica informando que o ticket é inválido ou não autorizado. Os detalhes da resposta do ITSM vão para o log de diagnóstico da conexão e não são exibidos ao solicitante. |
Não encontrado não é falha
Um ticket que o ITSM não retorna é um desfecho normal, não um erro. Somente uma falha aciona o comportamento de fallback:
| Resposta do ITSM | Resultado |
|---|---|
| Resposta vazia, 204, 400 ou 404 | Ticket não encontrado. Acesso negado. |
| 401, 403, 429, 5xx ou timeout | Falha. O comportamento de fallback é aplicado, e o log de diagnóstico registra a causa identificada. |
Janela de validade e fuso horário
A janela de validade é lida no fuso horário definido em Fuso horário da validação, não no fuso da appliance nem no do solicitante. Com um formato apenas de data, o fim da janela é inclusivo até 23:59:59 daquele dia, então um ticket válido até 28 de julho é negado somente em 29 de julho.
Cache de validação
Uma validação repetida do mesmo ticket dentro do TTL do cache de validação (segundos) reaproveita o resultado anterior em vez de consultar o ITSM outra vez. Vale conhecer duas consequências:
- A autorização pode ficar levemente defasada. Um ticket fechado ou revogado no ITSM durante a janela do cache continua sendo validado com o resultado em cache.
- O log de validação registra uma entrada por acesso, como sempre, mas o log de diagnóstico da conexão não registra linha nenhuma para um resultado em cache, porque nenhuma requisição saiu da plataforma. Uma aprovação sem linha de diagnóstico correspondente é esperada, não um registro faltando.
Qual conexão valida uma solicitação
Quando há mais de uma conexão ITSM ativa, uma conexão decide o desfecho e a resposta dela é final. A Segura® Platform resolve qual é a cada validação, nesta ordem:
- A conexão fixada para o grupo de acesso do solicitante. Quando o administrador fixa uma origem, ela prevalece sobre todo o resto: o solicitante não pode trocá-la, e uma origem enviada com a solicitação de qualquer forma é ignorada.
- A origem que o solicitante seleciona no formulário de justificativa, oferecida somente quando o grupo de acesso não está fixado.
- A conexão com Tenant default connector ativado.
- A única conexão ativa, quando existe exatamente uma e nenhuma padrão está definida.
- O modo de compatibilidade, quando nada acima resolve.
Observações sobre a seleção do solicitante:
- O seletor aparece somente no formulário de justificativa da web e somente quando há mais de uma conexão ativa. Sessões de proxy de terminal, EPM e chamadas de API sempre resolvem pela ordem automática acima.
- O seletor lista apenas conexões ativas, usando o nome que cada conexão recebeu.
- A seleção não fica gravada na justificativa. Vale apenas para aquela validação.
- Em um grupo de acesso que não está fixado, o solicitante pode selecionar qualquer conexão ativa, inclusive uma mais permissiva que a padrão. Para amarrar um grupo a uma única origem, fixe-a; para impedir que uma origem seja usada por qualquer pessoa, desative o Status dela.
- Se uma conexão for desativada depois de escolhida, o formulário de justificativa devolve um erro pedindo outra origem. Se uma conexão fixada for desativada, a fixação é ignorada e a resolução segue para o degrau seguinte.
Modo de compatibilidade
Enquanto houver mais de uma conexão ativa e nenhuma com Conector padrão do tenant ativado, a Segura® Platform valida o ticket contra todas as conexões ativas e concede o acesso quando qualquer uma aprova. A tela Conexões ITSM exibe um aviso persistente enquanto isso vale.
Isso preserva o desfecho de ambientes que operavam com várias conexões antes de existir a resolução de conexão, então nenhum ambiente muda de comportamento no upgrade sem uma ação do administrador. Ativar Conector padrão do tenant encerra o modo de compatibilidade; desativá-lo outra vez, com mais de uma conexão ativa, o restaura.
Definir uma conexão padrão pode mudar o desfecho de solicitações que o modo de compatibilidade costumava aprovar: um ticket que era válido em outra conexão passa a ser avaliado somente pela conexão que a resolução seleciona, e pode ser negado. Confirme qual origem deve decidir antes de definir a padrão.
Enquanto o modo de compatibilidade vale, um acesso produz uma requisição por conexão ativa, então os logs de diagnóstico registram uma linha por conexão. O log de validação continua registrando uma única entrada para o acesso.