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 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.
- Serviços Web SOAP 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 de WSDL (Web Service Definition Language, Linguagem de definição de serviço da 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 ServiceNow acessíveis via HTTP estão disponíveis para uso de acordo com 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 processamento.
Esta funcionalidade melhora a eficiência do ODBC Driver ao solicitar um grande número de registros, fazer consultas agregadas ou usar a ordem por expressões 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 ODBC Driver e o MID Server. Você pode adicionar proteção de tempo limite aos seus serviços Web personalizados com propriedades do sistema.
Proteção por tempo limite
Os clientes de serviços Web recebem um redirecionamento temporário 307 para manter as 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 compatíveis com o 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 da Web especificou originalmente. O uso de redirecionamentos temporários 307 é compatível 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 SOAP Web Services
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 da Web podem acessar, concedendo a eles uma das funções SOAP.
Funções SOAP
Para usar SOAP Web Services, 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 |
|---|---|
| Sabão | 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 da 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 acesso à tabela Linha do conjunto de importação [sys_import_set_row]. |
| import_transformer | Pode gerenciar mapas de transformações 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 da web padrão
Por padrão, um conjunto de regras de ACL do 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 ao usuário associado à instância para cada solicitação de mensagem WSDL ou SOAP, os administradores podem definir a propriedade glide.basicauth.required como verdadeiro.
Quando habilitada, cada solicitação 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 da Web não são interativas, o cabeçalho Autorização é sempre necessário durante uma solicitação.
Fornecer informações de autenticação básica com cada solicitação (se for 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 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 Web Services-Security (WSS) 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 se originam de um remetente conhecido
- Verifique se as mensagens SOAP não foram alteradas em trânsito
O WS-Security deve funcionar com a 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 WS-security determina como uma mensagem de serviços da web é autenticada quando a WS-security está habilitada. Os seguintes mecanismos podem ser usados para autenticar solicitações de serviços da 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 da 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 do perfil. |
O módulo Perfis de WS-Security lista os perfis de WS-Security que estão em vigor.
Registro em log de erros de WS-Security
A propriedade do sistema glide.processor.debug.SOAPProcessor 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 | 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 Web Services Security: 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 a ser representado quando a autenticação WS-Security for bem-sucedida.
Perfil de UsernameToken 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 as credenciais de usuário existentes.
Figura 5. Autenticar com credenciais de usuário existentes Use o nome de usuário da solicitação SOAP recebida 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 as 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 da 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. 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 recebidas muda esse comportamento e requer que os usuários atendam aos requisitos do Contextual Security Manager para acessar recursos de instância de serviços da Web.
Com esta propriedade habilitada, somente usuários que tenham a função SOAP apropriada e também atendam às condições da 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 da web
A autenticação mútua é compatível com serviços da Web de saída.
Gerenciamento e relatório de sessões 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 da Web, um ServiceNow MID Server ou o ServiceNow ODBC Driver. As sessões SOAP estão incluídas na lista de sessões do usuário em . Os URLs ?SOAP identificam as 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 a duração do tempo limite ser atingida, a instância estabelecerá uma nova sessão. Esta propriedade aceita valores de 5 a 1200 segundos (20 minutos).
|