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ço web
- Serviços web diretos: use uma consulta de URL para solicitar o WSDL de uma tabela.
- Conjuntos para importação de serviço web SOAP: use tabelas de importação e mapas de transformação para automatizar as solicitações de serviço web para tabelas.
- Serviços web SOAP com script: use JavaScript personalizado para executar solicitações de serviços web SOAP.
WSDL
Todas as tabelas e conjuntos para importação geram dinamicamente documentos XML de WSDL (Web Service Definition Language, Linguagem de definição de serviço web) que descrevem seu esquema de tabela e as operações disponíveis.
https://myinstance.service-now.com/incident.do?WSDL
Todos os WSDLs gerados e atendidos dinamicamente ServiceNow acessíveis via HTTP estão disponíveis para uso sob os termos definidos no acordo de licença da Iniciativa de código aberto OSI - Licença Apache, versão 2.0.
Suporte à solicitação SOAP de longa duração
O Now Platform oferece suporte a solicitações SOAP de longa execução, evitando tempos limites de soquete devido à inatividade da conexão de rede enquanto as solicitações estão em andamento.
Essa funcionalidade melhora a eficiência do ODBC Driver ao solicitar um grande número de registros, fazer consultas agregadas ou usar expressões de ordem que exigem classificação.
Por padrão, o sistema fornece proteção de tempo limite para clientes de serviços web fornecidos por ServiceNow, como o ODBC Driver e o MID Server. Você pode adicionar proteção de tempo limite aos seus serviços web personalizados com as 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 307-Temporário faz com que os clientes de serviços 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 que o cliente de serviços web especificou originalmente. O uso de Redirecionamentos Temporários 307 está em conformidade com WS-I.
- O valor de glide.soapprocessor.allow_long_running_threads é verdadeiro.
- A solicitação inclui um parâmetro de URL redirectSupported=true.
- A solicitação reconhece a sessão (compatível com 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 sobre o protocolo HTTPS e listas de controle de acesso (ACLs) 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 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 na tabela Filas [ecc_queue]. |
| soap_query | Pode consultar informações de 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 para importação e importações. Necessário para acesso à tabela Linha do conjunto de importação [sys_import_set_row]. |
| import_transformer | Pode gerenciar mapas de transformação do conjunto de importação e executar transformações. Necessário para acesso à tabela Linha do conjunto de importação [sys_import_set_row]. |
Requisitos de função de serviços 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 a autenticação básica do usuário associado à instância para cada solicitação de mensagem WSDL ou SOAP, os administradores podem definir a propriedade glide.basicauth.required como verdadeira.
Quando habilitadas, cada solicitação de WSDL e SOAP deve conter um cabeçalho de "Autorização", conforme especificado no protocolo de Autenticação básica.
Como as solicitações de serviços web não são interativas, o cabeçalho de autorização é sempre necessário durante uma solicitação.
O fornecimento de informações de autenticação básica com cada solicitação (necessário 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 web. Por exemplo, ao criar um registro de incidente, o campo de 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 a assinatura de solicitações SOAP ao consumir um serviço web externo
- Especifique os requisitos de autenticação que as solicitações SOAP devem atender ao se comunicarem pelo WS-Security.
Para saber mais sobre a política de acesso SOAP, consulte Políticas de acesso SOAP API.
Certificados necessários para solicitações SOAP assinadas
Para assinar solicitações SOAP para comunicações de WS-Security, os seguintes certificados são necessários:
- Certificado X.509 do solicitante
- Certificado de CA X.509 da autoridade de certificação que assinou o certificado do solicitante
Política de segurança padrão de 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. A propriedade do sistema glide.soap.default_security_policy especifica o nome da política de segurança SOAP que a instância usa ao impor a WSS (Web Services-Security) para solicitações de entrada.
| Campo | Descrição |
|---|---|
| Tipo | Cadeia de caracteres |
| Valor padrão | Política de segurança padrão |
| Local | Adicionar uma propriedade do sistema à 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 para a instância. Ele revisa o cabeçalho WS-Security para determinar a validade da mensagem de entrada. As solicitações afetadas por ataques, como um ataque intermediário, têm um cabeçalho WS-Security inválido e são bloqueadas.
Perfis de WS-Security
Um perfil de segurança WS determina como uma mensagem de serviços web é autenticada quando a segurança WS está habilitada. Os seguintes mecanismos 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. A verificação do 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 de WS-Security lista os perfis de WS-Security que estão em vigor no momento.
Registro em log de erros de WS-Security
A propriedade do sistema glide.processor.debug.SOAPProcessor permite que mensagens de erro sobre segurança de WS 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 o processamento SOAP, como verificações de certificado e armazenamento de chaves.
| Campo | Descrição |
|---|---|
| Tipo | verdadeiro | falso |
| Valor padrão | falso |
| Local | Adicionar uma propriedade do sistema à 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 a estrutura de autenticação X.509 conforme definido pela especificação Segurança de serviços web: SOAP Message Security.
Carregue o certificado e faça referência a ele no campo Certificado X509. Se for uma sessão vinculada, selecione o usuário para representar quando a autenticação WS-Security for bem-sucedida.
Perfil de Token do nome de usuário do WSS
Ao especificar o perfil de token X.509, você também pode fornecer um UsernameToken na solicitação SOAP.
Um UsernameToken é usado como um meio de identificar o solicitante por "nome de usuário" e, opcionalmente, usando uma senha, segredo compartilhado ou senha equivalente, para autenticar essa identidade.
Existem duas maneiras de autenticar um UsernameToken.
- Autentique 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 campo Usuário especificado para corresponder ao valor de UserName. O sistema usa o valor de 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.
- Autentique com as credenciais de usuário especificadas.
Figura 6. Autenticar com credenciais de usuário especificadas Autentique usando credenciais de login não relacionadas a 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 Web determina somente se um usuário está autorizado a acessar a instância com uma conexão SOAP. Depois de 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 de entrada muda esse comportamento e requer que os usuários atendam aos requisitos do Gerenciador de segurança contextual para acessar recursos da instância de serviços web.
Com esta propriedade habilitada, somente usuários que tenham a função SOAP apropriada e também atendam às condições de ACL para 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 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 o ServiceNow ODBC Driver. As sessões SOAP estão incluídas na lista de sessões de usuário em . As URLs ?SOAP identificam sessões SOAP.
Propriedades da sessão SOAP
Certas 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 após atingir o tempo limite, a instância estabelecerá uma nova sessão. Esta propriedade aceita valores de 5 a 1200 segundos (20 minutos).
|