SOAP Web Services
O SOAP (Simple Object Access Protocol) é um protocolo baseado em XML para acessar serviços da Web em HTTP.
Provedor de serviços da Web
- Serviços web diretos : Use uma consulta de URL para solicitar o WSDL de uma tabela.
- Conjuntos de importação de serviço web SOAP : Use tabelas de importação e mapas de transformação para automatizar solicitações de serviço web para tabelas.
- SOAP Web Services com script : Use JavaScript personalizado para executar solicitações de serviços web SOAP.
WSDL
Todas as tabelas e conjuntos de importação geram dinamicamente documentos XML WSDL (Web Service Definition Language) que descrevem o esquema de tabela e as operações disponíveis.
https://myinstance.service-now.com/incident.do?WSDL
Todos gerados e atendidos dinamicamente ServiceNow WSDLs acessíveis via HTTP estão disponíveis para uso sob os termos definidos no acordo de licença OSI - Apache License, Versão 2,0 da Iniciativa de código aberto.
Suporte a solicitações SOAP de longa execução
. ServiceNow AI Platform Oferece suporte a solicitações SOAP de longa execução, evitando tempos limite de soquete devido à inatividade da conexão de rede enquanto as solicitações estão em andamento.
Esta funcionalidade melhora a eficiência do driver ODBC ao solicitar um grande número de registros, fazer consultas agregadas ou usar expressões de ordenação que exigem classificação.
Por padrão, o sistema fornece proteção de tempo limite para clientes de serviços da Web fornecidos por ServiceNow Como o driver ODBC e o MID Server. Você pode adicionar proteção de tempo limite aos seus serviços web personalizados com propriedades do sistema.
Proteção de tempo limite
Os clientes de serviços Web recebem um redirecionamento temporário 307 para manter sessões longas ativas e evitar um tempo limite devido à inatividade do soquete. Um redirecionamento temporário 307 faz com que os clientes de serviços da Web que oferecem suporte ao código de status repitam sua última solicitação para o local especificado no cabeçalho do local HTTP. O valor do cabeçalho do local é o mesmo URL especificado originalmente pelo cliente de serviços web. O uso de redirecionamentos temporários 307 é compatível com WS-I.
- O valor de glide.soapprocessor.allow_long_running_threadsverdadeiro.
- A solicitação inclui um redirectSupported=trueParâmetro de URL.
- A solicitação reconhece a sessão (oferece suporte a cookies HTTP).
- O número de redirecionamentos não excedeu o valor definido por glide.soap.max_redirects.
Segurança de serviços web SOAP
Uma instância impõe a segurança do serviço web usando uma combinação de desafio/resposta de autenticação básica pelo protocolo HTTPS e ACLs (Access Control Lists, listas de controle de acesso) no nível do sistema usando segurança contextual. Os administradores podem controlar quais recursos do sistema os usuários de serviços web podem acessar concedendo a eles uma das funções SOAP.
Funções SOAP
Para usar os serviços web SOAP, você deve ter a função apropriada para a operação que deseja executar. Além disso, você deve ter todas as outras funções necessárias para acessar as tabelas de destino.
| Função | Descrição |
|---|---|
| soap | Pode executar todas as operações SOAP. |
| soap_create | Pode inserir novos registros. |
| soap_delete | Pode excluir registros existentes. |
| soap_ecc | Pode consultar, inserir e excluir registros nas Filas [ecc_queue] tabela. |
| soap_query | Pode consultar informações do registro. |
| soap_query_update | Pode consultar informações de registro e atualizar registros. |
| soap_script | Pode executar scripts que especificam um endpoint .do. Esta função é necessária para executar serviços web com script. |
| soap_update | Pode atualizar registros. |
| import_admin | Pode gerenciar todos os aspectos de conjuntos de importação e importações. Necessário para acessar a tabela Linha do conjunto de importação [sys_import_set_row]. |
| import_transformer | Pode gerenciar mapas de transformação de conjunto de importação e executar transformações. Necessário para acessar a tabela Linha do conjunto de importação [sys_import_set_row]. |
Requisitos de função de serviços da Web padrão
Por padrão, um conjunto de regras de ACL de processador exige que os usuários tenham a função soap_query para fazer solicitações de esquema WSDL, XSD e XML.
Se você quiser mudar esses requisitos de função, poderá desativar as regras de ACL.
Autenticação básica
Para impor autenticação básica para o usuário associado à instância para cada solicitação de mensagem WSDL ou SOAP, os administradores podem definir a propriedade glide.basicauth.obrigatório . verdadeiro .
Cada solicitação WSDL e SOAP deve conter um cabeçalho "Autorização", conforme especificado em Autenticação básica protocolo.
Como as solicitações de serviços da Web não são interativas, o Autorização o cabeçalho é sempre necessário durante uma solicitação.
Fornecer informações básicas de autenticação com cada solicitação (seja necessária ou não) tem a vantagem adicional de que o usuário fornecido nas credenciais de autenticação básica pode ser associado à invocação de serviço da Web. Por exemplo, ao criar um registro de incidente, o campo diário lista o ID do usuário contido no cabeçalho de autenticação básica em vez do usuário convidado padrão.
Políticas de segurança SOAP
- Habilitar ou desabilitar solicitações SOAP de assinatura ao consumir um serviço web externo
- Especifique os requisitos de autenticação que as solicitações SOAP devem atender ao se comunicar por WS-Security.
Para saber mais sobre a política de acesso SOAP, consulte Políticas de acesso à API SOAP .
Certificados necessários para solicitações SOAP assinadas
Para assinar solicitações SOAP para comunicações WS-Security, os seguintes certificados são necessários:
- Certificado X.509 do solicitante
- X.509 Certificado CA da autoridade de certificação que assinou o certificado do solicitante
Política de segurança padrão SOAP
Os administradores podem especificar a política de segurança SOAP que uma instância usa com a propriedade do sistema glide.soap.default_security_policy . . glide.soap.default_security_policy A propriedade do sistema especifica o nome da política de segurança SOAP que a instância usa ao impor Serviços Web-Segurança (WSS) para solicitações de entrada.
| Campo | Descrição |
|---|---|
| Tipo | Cadeia de caracteres |
| Valor padrão | Política de segurança padrão |
| Local | Adicione uma propriedade do sistema Para a tabela Propriedades do sistema [sys_properties] |
WS-Security
- Verifique se as mensagens SOAP são originadas de um remetente conhecido
- Verifique se as mensagens SOAP não foram alteradas em trânsito
O WS-Security deve funcionar com autenticação básica. Quando uma instância recebe uma mensagem SOAP, ela revisa o cabeçalho de autenticação básica para determinar se o usuário SOAP tem direitos sobre a instância. Revisa o cabeçalho WS-Security para determinar a validade da mensagem de entrada. As solicitações afetadas por ataques, como um ataque man-in-the-middle, têm um cabeçalho WS-Security inválido e são bloqueadas.
Perfis WS-Security
Um perfil WS-security determina como uma mensagem de serviços web é autenticada quando o WS-security está habilitado. Os mecanismos a seguir podem ser usados para autenticar solicitações de serviços web:
| Mecanismo de autenticação | Descrição |
|---|---|
| Verificação de certificado | Verifica o certificado associado à solicitação. Verificar o certificado da solicitação requer o carregamento do certificado e da autoridade de certificação do solicitante. |
| Credenciais do usuário | Autentica a solicitação de serviços web verificando as credenciais do usuário associadas à solicitação. Este tipo de autenticação pode verificar se as credenciais da solicitação correspondem às credenciais de um usuário existente ou se as credenciais da solicitação correspondem a um nome de usuário e senha fornecidos no registro de perfil. |
O módulo Perfis WS-Security lista os perfis WS-Security que estão em vigor no momento.
Registro em log de erros do WS-Security
. glide.processor.debug.SOAPProcessor A propriedade do sistema permite que mensagens de erro sobre WS-security sejam exibidas no log de transações.
A propriedade do sistema glide.processor.debug.SOAPProcessor Habilita (verdadeiro) ou desabilita (falso) mensagens de depuração para processamento SOAP, como verificações de certificado e armazenamento de chaves.
| Campo | Descrição |
|---|---|
| Tipo | verdadeiro | falso |
| Valor padrão | falso |
| Local | Adicione uma propriedade do sistema Para a tabela Propriedades do sistema [sys_properties] |
Perfil de token WSS X.509
- nome do assunto
- nome do emissor
- número de série
- intervalo de validade
Use Estrutura de autenticação X.509 conforme definido por Segurança de serviços da Web: Especificação de segurança de mensagens SOAP .
Carregue o certificado e faça referência a ele no Certificado X509 campo. Se for uma sessão vinculada, selecione o usuário para representar quando a autenticação WS-Security for bem-sucedida.
Perfil UsernameToken do WSS
Ao especificar o perfil de token X.509, você também pode fornecer um UsernameToken na solicitação SOAP.
UsernameToken é usado como um meio de identificar o solicitante por "nome de usuário" e, opcionalmente, usar uma senha, segredo compartilhado ou senha equivalente para autenticar essa identidade.
Há duas maneiras de autenticar um UsernameToken.
- Autenticar com credenciais de usuário existentes.
Figura 5. Autenticar com credenciais de usuário existentes Use o nome de usuário da solicitação SOAP de entrada para pesquisar um usuário pelo especificado Usuário campo para corresponder a. Nome de usuário valor. O sistema usa o valor da senha no UsernameToken de entrada para autenticar a solicitação. Quando a opção Vincular sessão é selecionada, o usuário autenticado com êxito é usado para a sessão.
- Autenticar com credenciais de usuário especificadas.
Figura 6. Autenticar com credenciais de usuário especificadas Autentique usando credenciais de login não relacionadas aos usuários na tabela Usuário. Quando a opção Vincular sessão é selecionada, o usuário especificado no campo Executar como usuário é usado para a sessão.
Segurança estrita para serviços web
Por padrão, a autenticação básica para serviços da Web determina somente se um usuário está autorizado a acessar a instância com uma conexão SOAP. Uma vez autorizado, qualquer usuário pode acessar qualquer tabela publicada como um serviço web.
A propriedade do sistema Impor segurança estrita nas solicitações SOAP recebidas muda esse comportamento e requer que os usuários atendam Contextual Security Manager requisitos para acessar recursos da instância de serviços da web.
Com esta propriedade habilitada, somente usuários que têm a função SOAP apropriada e também atendem às condições da ACL, a tabela e a operação podem executar essa operação a partir de uma conexão SOAP.
Autenticação mútua para serviços web
A autenticação mútua é compatível com serviços web de saída.
Gestão e emissão de relatórios de sessão SOAP
Uma sessão SOAP é uma sessão do Glide estabelecida com uma instância por qualquer cliente SOAP externo, como uma aplicação cliente de serviços web, um ServiceNow MID Server ou ServiceNow Driver ODBC. As sessões SOAP estão incluídas na lista de sessões do usuário em . . ?SOAP As URLs identificam sessões SOAP.
Propriedades da sessão SOAP
Determinadas propriedades controlam como as sessões SOAP são mantidas.
| Propriedade | Descrição |
|---|---|
| glide.soap.invalidate_session_timeout | Duração, em segundos, que uma sessão ativa permanece aberta. Depois que essa duração é atingida, a instância desativa a sessão e recupera todos os recursos do sistema. Se o cliente enviar outra solicitação depois que a duração do tempo limite for atingida, a instância estabelecerá uma nova sessão. Esta propriedade aceita valores de 5 a 1200 segundos (20 minutos).
|