---
title: "Configurações da conexão ITSM REST genérica"
slug: "reference-generic-rest-itsm-connector-settings"
updated: 2026-11-06T02:19:05Z
published: 2026-11-06T02:19:05Z
canonical: "docs.senhasegura.io/reference-generic-rest-itsm-connector-settings"
---

> ## 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.

# Configurações da conexão ITSM REST genérica

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](/v4-2/docs/pt/how-to-configure-a-generic-rest-itsm-integration-in-segura).

## Caminho para acesso

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. 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**, **token composto** e **Basic (usuário e senha)**. A aba **Revisão** exibe apenas os campos do método selecionado. |

### 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.

Info

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. |

### Basic (usuário e senha)

A plataforma envia o usuário e a senha em um cabeçalho HTTP padrão de autenticação Basic a cada consulta de ticket.

| Item | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| **Usuário** | Campo de texto | Sim | Usuário da conta do ITSM com a qual a plataforma se autentica. Não pode ficar vazio nem conter dois-pontos (`:`). |
| **Senha** | Campo de texto | Sim, em uma conexão nova | Senha dessa conta. Ela fica armazenada no cofre e nunca aparece na aba **Revisão**, na trilha de auditoria nem nos logs. Editar uma conexão sem digitá-la novamente mantém o valor armazenado. |

Info

A plataforma envia o usuário e a senha a cada requisição. Prefira **OAuth 2.0 Client Credentials** ou **API key** quando o ITSM oferecer suporte a eles.

## 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:

1. **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.
2. **A origem que o solicitante seleciona** no formulário de justificativa, oferecida somente quando o grupo de acesso não está fixado.
3. **A conexão com Tenant default connector** ativado.
4. **A única conexão ativa**, quando existe exatamente uma e nenhuma padrão está definida.
5. **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.

Atenção

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.

## Tópicos relacionados

- [Configurar uma conexão ITSM REST genérica](/v4-2/docs/pt/how-to-configure-a-generic-rest-itsm-integration-in-segura)
- [Configurações de validação de ticket do ServiceNow](/v4-2/docs/pt/reference-itsm-ticket-validation-settings)
- [Sobre a integração ITSM da Segura™](/v4-2/docs/pt/about-senhaseguras-itsm-integration)