Web Services IV: SOAP Handlers

SOAP Handlers

O SOAP é um vocabulário XML para mensagens de Web Services, e é independente do protocolo de transporte.
Uma mensagem SOAP transporta dados no body e pode acrescentar headers. Estão também disponíveis exemplos de programação para a construção e envio de mensagens XML.

Os SOAP handlers são o mecanismo da biblioteca de Web Services para Java, JAX-WS, que permite intercetar e aceder diretamente às mensagens SOAP que saem ou entram de um cliente ou servidor. Atente à seguinte figura. Do lado do cliente, os handlers são chamados a seguir ao stub e antes da mensagem seguir pela rede. Do lado do servidor, os handlers são chamados após a mensagem chegar da rede, e antes do tie.

Como programar um handler?

Um handler é uma classe Java que implementa a interface javax.xml.ws.handler.soap.SOAPHandler.
O método handleMessage() é invocado de cada vez que uma mensagem entra (inbound) ou sai (outbound). O resultado do método handleMessage() determina de que forma prossegue o processamento da mensagem. Resumidamente: se retornar true, o processamento prossegue; se atirar uma java.lang.RuntimeException, é devolvida uma SOAP fault.

Como especificar que handlers devem ser chamados?

Para indicar que handlers devem ser chamados, é necessária editar um ficheiro que define a cadeia de processamento.
Existe uma configuração independente para o cliente e outra para o servidor.

A forma mais habitual de parametrizar os handlers, se necessário, é colocar variáveis static na respetiva classe.
Por exemplo, pode criar-se um parâmetro para indicar a chave criptográfica a usar.

 

---

Exemplo de handlers

Um exemplo de handlers tem três módulos: a biblioteca, o cliente, e o servidor.
A biblioteca de handlers contém as classes partilhadas pelos outros dois (não faz sentido ter classes copiadas entre cliente e servidor).

Biblioteca ws-handlers
- contém:

• LogHandler - imprime mensagens SOAP para System.out
• PrettyLogHandler - semelhante ao anterior, mas indenta o XML para uma leitura mais fácil
• EndpointAddressHandler - imprime o endereço de destino da mensagem
• MessageContextHandler - imprime todas as variáveis de contexto para System.out para se poder ver quais são e quais os seus valores
• HeaderHandler - mostra como acrescentar um Header à mensagem SOAP

• HeaderHandlerTest - usa mocks para testar localmente um handler

- para usar:

• fazer mvn install para compilar e instalar o módulo no repositório local do Maven
• acrescentar a dependência para example:ws-handlers:1.0-SNAPSHOT no pom.xml do projeto que vai usar os Handlers
• editar/acrescentar o ficheiro de configuração dos handlers no projeto que os vai usar

O exemplo seguinte demonstra a forma como os handlers acedem às mensagens XML dos Web Services utilizando o LogHandler.

• Web Service hello-ws_handlers
  - A configuração é feita através de um ficheiro e de uma anotação.
• Web Service client hello-ws-cli_handlers
  - a definição de handlers no cliente é feita através de um ficheiro de configuração.

Para experimentar o exemplo:

• cd hello-ws_handlers
• mvn clean compile exec:java

• cd hello-ws-cli_handlers
• mvn clean compile exec:java

As mensagens SOAP transmitidas deverão ser impressas para a consola.

O exemplo pode ser também usado para experimentar os outros handlers, basta editar os ficheiros de configuração das cadeias de processamento.
Sugere-se, por exemplo, experimentar o MessageContextHandler para imprimir para a consola o contexto de processamento da mensagem.

 

---

Exercício

Terceira parte do projeto

Na aula passada vimos como se utiliza a biblioteca e o servidor Kerberos para implementar as partes cliente e servidor do protocolo sem que existisse real comunicação entre os dois, i.e. tudo se passava no mesmo processo.
Hoje vamos implementar o protocolo aproveitando as mensagens SOAP que já são trocadas entre o binas-ws-cli e o binas-ws.

Configuração dos handlers no servidor e no cliente

Começar por adicionar a biblioteca ws-handlers ao projeto binas.

1. Editar o pom.xml para que o groupId passe a conter o identificador do grupo CXX.
2. Compilar e instalar o módulo:
   • cd ws-handlers
   • mvn clean install
   Sempre que se atualizar o código dos handlers será necessário reinstalar.

Prosseguir com o binas-ws:

1. Adicionar a dependência para a biblioteca ws-handlers no pom.xml.
2. Na pasta src/main/resources adicionar ficheiro binas-ws_handler-chain.xml com configuração da cadeia de interceção.
   O LogHandler deve ser chamado no início e no fim da cadeia. Alternativamente, pode ser usado o PrettyLogHandler.
3. Adicionar a seguinte anotação ao PortImpl:
   

   @HandlerChain(file = "/binas-ws_handler-chain.xml")
   

   Para ver ficheiros de configuração semelhantes, consultar o servidor do exemplo acima.
4. Lançar o servidor.
• cd binas-ws
• mvn compile exec:java
5. Usar o cliente para chamar o test_ping.
• cd binas-ws-cli
• mvn compile exec:java
6. Agora, ao receber mensagens, estas serão capturadas e impressas para a consola do servidor.

Concluir com o binas-ws-cli:

1. Adicionar também a dependência para a biblioteca ws-handlers ao pom.xml.
2. Criar os ficheiros de configuração da cadeia de handlers na pasta src/jaxws
   Para ver ficheiros de configuração semelhantes, consultar o cliente do exemplo acima.
3. Configurar a cadeia de handlers, acrescentando o LogHandler no início e no fim da cadeia.
4. Para verificar se a configuração ficou bem feita, fazer uma chamada à operação test_ping e confirmar que as mensagens são também capturadas e impressas na consola do lado do cliente.

Neste ponto, o cliente e o servidor têm as suas mensagens SOAP a ser capturadas e impressas para a consola.

 

Implementação dos mecanismos de segurança

Vai ser necessário criar dois handlers para interagir com o servidor Kerberos:

• KerberosClientHandler
• KerberosServerHandler

Para a interação com o Kerberos, deve-se reaproveitar o código produzido no laboratório anterior, colocado agora nos handlers e estendido com os passos referidos em destaque.

Parte cliente:

1. Antes de enviar uma mensagem, o cliente autentica-se e recebe chave de sessão e ticket.
2. Deve abrir a chave de sessão (Kcs) com a sua chave (Kc).
3. Depois deve colocar o ticket num cabeçalho de uma mensagem SOAP para seguir para o servidor.
4. Deve criar um autenticador também para enviar num outro cabeçalho.

Parte servidor:

1. A mensagem deve ser intercetada à chegada, receber e abrir o ticket com a sua chave (Ks) e validá-lo.
2. Depois deve abrir o autenticador com a chave de sessão (Kcs) e validá-lo.
3. A mensagem de resposta deve ter devolver um RequestTime para o cliente

 

O que falta fazer?

Vai ser necessário ter mais handlers para os restantes mecanismos de segurança pedidos no projeto:

• BinasAuthorizationHandler
• MACHandler

Para cada requisito de segurança referido no enunciado do projeto:

• Identificar que alterações são necessárias às mensagens SOAP.
• O que se deve fazer à saída da mensagem?
• O que se deve fazer à chegada?
• O que fazer quando a mensagem não corresponde ao esperado?
  return true para continuar, ou atirar RuntimeException para devolver mensagem de erro?
• Implementar e testar de forma gradual.

 

Bom trabalho!

 

---