Sun Java System Access Manager 7.1 Federation and SAML Administration Guide

PAOS Binding

Access Manager has implemented the optional Liberty Reverse HTTP Binding for SOAP Specification. This specification defines a message exchange protocol that permits an HTTP client to be a SOAP responder. HTTP clients are no longer necessarily equipped with HTTP servers. For example, mobile terminals and personal computers contain web browsers yet they do not operate HTTP servers. These clients, though, can use their browsers to interact with an identity service, possibly a personal profile service or a calendar service. These identity services could also be beneficial when the client devices interact with an HTTP server. The use of PAOS makes it possible to exchange information between user agent-hosted services and remote servers. This is why the reverse HTTP for SOAP binding is also known as PAOS; the spelling of SOAP is reversed.

Comparison of PAOS and SOAP

In a typical SOAP binding, an HTTP client interacts with an identity service through a client request and a server response. For example, a cell phone user (client) can contact the phone service provider (service) to retrieve stock quotes and weather information. The service verifies the user’s identity and responds with the requested information.

In a reverse HTTP for SOAP binding, the phone service provider plays the client role, and the cell phone client plays the server role. The initial SOAP request from the server is actually bound to an HTTP response. The subsequent response from the client is bound to a request.

PAOS Binding API

The Access Manager implementation of PAOS binding includes a Java package named com.sun.identity.liberty.ws.paos. This package provides classes to parse a PAOS header, make a PAOS request, and receive a PAOS response.

Note –

This API is used by PAOS clients on the HTTP server side. An API for PAOS servers on the HTTP client side would be developed by the manufacturers of the HTTP client side products, for example, cell phone manufacturers.

The following table describes the available classes in com.sun.identity.liberty.ws.paos. For more detailed API documentation, see the Java API Reference in /AccessManager-base/SUNWam/docs or on docs.sun.com.

Table 11–8 PAOS Binding Classes


Class	Description
`PAOSHeader`	Used by a web application on the HTTP server side to parse a PAOS header in an HTTP request from the user agent side.
`PAOSRequest`	Used by a web application on the HTTP server side to construct a PAOS request message and send it via an HTTP response to the user agent side. Note – `PAOSRequest` is made available in `PAOSResponse` to provide correlation, if needed, by API users.
`PAOSResponse`	Used by a web application on the HTTP server side to receive and parse a PAOS response using an HTTP request from the user agent side.
`PAOSException`	Represents an error occurring while processing a SOAP request and response.

For more information, including methods and their syntax and parameters, see the Java API Reference in /AccessManager-base/SUNWam/docs or on docs.sun.com.

PAOS Binding Sample

A sample that demonstrates PAOS service interaction between an HTTP client and server is provided in the /AccessManager-base/SUNWam/samples/phase2/paos directory. The PAOS client is a servlet, and the PAOS server is a stand-alone Java program. Instructions on how to run the sample can be found in the Readme.html or Readme.txt file. Both files are included in the paos directory. The following code example is the PAOS client servlet.

Example 11–1 PAOS Client Servlet From PAOS Sample

import java.util.*;
import java.io.*;

import javax.servlet.*;
import javax.servlet.http.*;

import com.sun.identity.liberty.ws.paos.*;

import com.sun.identity.liberty.ws.idpp.jaxb.*;

public class PAOSClientServlet extends HttpServlet {

  public void doGet(HttpServletRequest req, HttpServletResponse res)
    throws ServletException, IOException {

      PAOSHeader paosHeader = null;
      try {
    paosHeader = new PAOSHeader(req);
      } catch (PAOSException pe1) {
    pe1.printStackTrace();

    String msg = "No PAOS header\\n";
    res.setContentType("text/plain");
    res.setContentLength(1+msg.length());
    PrintWriter out = new PrintWriter(res.getOutputStream());
    out.println(msg);
    out.close();

    throw new ServletException(pe1.getMessage());
      }

      HashMap servicesAndOptions = paosHeader.getServicesAndOptions();

      Set services = servicesAndOptions.keySet();

      String thisURL = req.getRequestURL().toString();
      String[] queryItems = { "/IDPP/Demographics/Birthday" };
      PAOSRequest paosReq = null;
      try {
    paosReq = new PAOSRequest(thisURL,
                  (String)(services.iterator().next()),
                  thisURL,
                  queryItems);
      } catch (PAOSException pe2) {
    pe2.printStackTrace();
    throw new ServletException(pe2.getMessage());
      }
      System.out.println("PAOS request to User Agent side --------------->");
      System.out.println(paosReq.toString());
      paosReq.send(res, true);
  }

  public void doPost(HttpServletRequest req, HttpServletResponse res)
    throws ServletException, IOException {

      PAOSResponse paosRes = null;
      try {
    paosRes = new PAOSResponse(req);
      } catch (PAOSException pe) {
    pe.printStackTrace();
    throw new ServletException(pe.getMessage());
      }

      System.out.println("PAOS response from User Agent side -------------->");
      System.out.println(paosRes.toString());

      System.out.println("Data output after parsing -------------->");

      String dataStr = null;
      try {
    dataStr = paosRes.getPPResponseStr();
      } catch (PAOSException paose) {
    paose.printStackTrace();
    throw new ServletException(paose.getMessage());
      }
      System.out.println(dataStr);

      String msg = "Got the data: \\n" + dataStr;

      res.setContentType("text/plain");
      res.setContentLength(1+msg.length());

      PrintWriter out = new PrintWriter(res.getOutputStream());

      out.println(msg);

      out.close();
  }
}

See Appendix A, Liberty-based and SAML Samples for information about all the sample code and files included with Access Manager.