Sun OpenSSO Enterprise 8.0 Developer's Guide

Chapter 9 Implementing Web Services

OpenSSO Enterprise contains web services that can be used to extend the functionality of your federated environment. Additionally, new web services can be developed. This chapter covers the following topics:

Developing New Web Services

Any web service that is plugged into the OpenSSO Enterprise Liberty ID-WSF framework must register a key and an implementation of the com.sun.identity.liberty.ws.soapbinding.RequestHandler interface with the SOAP Binding Service. (For example, the Liberty Personal Profile Service is registered with the key idpp and the class com.sun.identity.liberty.ws.idpp.PPRequestHandler.) The Key value becomes part of the URL for the web service's endpoint (as in protocol://host:port/deploymenturi/Liberty/key). The implemented class allows the web service to retrieve the request (containing the authenticated principal and the authenticated security mechanism along with the entire SOAP message) from the client. The web service processes the request and generates a response. This section contains the process you would use to add a new Liberty ID-WSF web service to the OpenSSO Enterprise framework. Instructions for some of these steps are beyond the scope of this guide. The process has been divided into two tasks:

To Host a Custom Service

Before You Begin

The XML Schema Definition (XSD) file written to define the new service is the starting point for developing the service's server-side code.

Write an XML service schema for the new web service and Java classes to parse and process the XML messages.

The following sample schema defines a stock quote web service. The QuoteRequest and QuoteResponse elements define the parameters for the request and response that are inserted in the SOAP Body of the request and response, respectively. You will need to have QuoteRequest.java and QuoteResponse.java to parse and process the XML messages.

<?xml version="1.0" encoding="UTF-8" ?> 
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
  xmlns="urn:com:sun:liberty:sample:stockticker"
  targetNamespace="urn:com:sun:liberty:sample:stockticker">
  <xs:annotation>
      <xs:documentation>
         This is a sample stock ticker web service protocol
      </xs:documentation>
  </xs:annotation>

  <xs:element name="QuoteRequest" type="QuoteRequestType"/>
  <xs:complexType name="QuoteRequestType">
    <xs:sequence>
        <xs:element name = "ResourceID" type="xs:string" minOccurs="0"/>
        <xs:element name = "Symbol" type="xs:string" minOccours="1"/>
    </xs:sequence>
  </xs:complexType>

  <xs:complexType name="PriceType">
      <xs:sequence>
          <xs:element name="Last" type="xs:integer"/>
          <xs:element name="Open" type="xs:integer"/>
          <xs:element name="DayRange" type="xs:string"/>
          <xs:element name="Change" type="xs:string"/>
          <xs:element name="PrevClose" type="xs:integer"/>
      </xs:sequence>
  </xs:complexType>

  <xs:element name="QuoteResponse" type="QuoteResponseType"/>
  <xs:complexType name="QuoteResponseType">
    <xs:sequence>
        <xs:element name="Symbol" type="xs:string"/>
        <xs:element name="Time" type="xs:dateTime"/>
        <xs:element name="Delay" type="xs:dateTime" minOccurs="0"/>
        <xs:element name="Price" type="PriceType"/>
        <xs:element name="Volume" type="xs:integer"/>
    </xs:sequence>
  </xs:complexType>

</xs:schema>

Provide an implementation for one of the following interfaces based on the type of web service being developed.
- com.sun.identity.liberty.ws.soapbinding.RequestHandler for developing and deploying a general web service.
- com.sun.identity.liberty.ws.dst.service.DSTRequestHandler for developing and deploying an identity data service type web service based on the Liberty Alliance Project Identity Service Interface Specifications (Liberty ID-SIS).
In OpenSSO Enterprise, each web service must implement one of these interfaces to accept incoming message requests and return outgoing message responses. The following sample implements the com.sun.identity.liberty.ws.soapbinding.RequestHandler interface for the stock quote web service. com.sun.identity.liberty.ws.soapbinding.Message is the API used to construct requests and responses.
```
public class StockTickerService implements RequestHandler {
        :
         //implement business logic

         public Message processRequest(Message msg) throws 
                       SOAPFaultException, Exception {
                :
                SSOToken token = (SSOToken)msg.getToken();
                List responseBody = processSOAPBody(msg.getBodies());
                :
                Message response = new Message();
                response.setBodies(responseBody);
 
                return response;
          }
          :
          //more business logic

}
```

Compile the Java source code.

Be sure to include openfedlib.jar in your classpath.

Add the previously created classes to the web container classpath and restart the web container on which OpenSSO Enterprise is deployed.

Click the Web Services tab.

Under Web Services, click the SOAP Binding Service tab to register the new implementation with the SOAP Binding Service.

Click New under the Request Handler List global attribute.

Enter a name for the implementation in the Key field.

This value will be used as part of the service endpoint URL for the web service. For example, if the value is stock, the endpoint URL to access the stock quote web service will be:
http://host:port/deploy_uri/Liberty/stock

Enter the name of the implementation class previously created in the Class field.

(Optional) Enter a SOAP Action in the SOAP Action field.

Click Save to save the configuration.

The request handler will be displayed under the Request Handler List.

Click on the Access Control tab to begin the process of publishing the web service to the Discovery Service.

The Discovery Service is a registry of web services. It matches the properties in a request with the properties in its registry and returns the appropriate service location. See Discovery Service for more information.

Click the name of the realm to which you want to add the web service.

Click the Services tab to access the realm's services.

Click Discovery Service to create a new resource offering.

If the Discovery Service has not yet been added:
1. Click Add.
  
  A list of available services is displayed.
2. Select Discovery Service and click Next to add the service.
  
  The list of added services is displayed including the link to the Discovery Service.

Click Add on the Discovery Resource Offering screen.

(Optional) Enter a description of the resource offering in the Description field on the New Resource Offering page.

Type a URI for the value of the Service Type attribute.

This URI defines the type of service. It is recommended that the value of this attribute be the targetNamespace URI defined in the abstract WSDL description for the service. An example of a valid URI is urn:com:sun:liberty:sample:stockticker.

Type a URI for the value of the Provider ID attribute.

The value of this attribute contains the URI of the provider of the service instance. This information is useful for resolving trust metadata needed to invoke the service instance. A single physical provider may have multiple provider IDs.

Note –
The provider represented by the URI in the Provider ID attribute must also have an entry in the ResourceIDMapper attribute. For more information, see Classes For ResourceIDMapper Plug-in in Sun OpenSSO Enterprise 8.0 Administration Guide.

Click New Description to define the Service Description.

For each resource offering, at least one service description must be created.
1. Select the values for the Security Mechanism ID attribute to define how a web service client can authenticate to a web service provider.
  
  This field lists the security mechanisms that the service instance supports. Select the security mechanisms that you want to add and click Add. To prioritize the list, select the mechanism and click Move Up or Move Down.
2. Type a value for the End Point URL.
  
  This value is the URL to access the new web service. For this example, it might be:
  http://SERVER_HOST:SERVER_PORT/SERVER_DEPLOY_URI/Liberty/stock
3. (Optional) Type a value for the SOAP Action.
  
  This value is the equivalent of the wsdlsoap:soapAction attribute of the wsdlsoap:operation element in the service's concrete WSDL-based description.
4. Click OK to complete the configuration.

Check the Options box if there are no options or add a URI to the Options List to specify options for the resource offering.

This field lists the options that are available for the resource offering. Options provide hints to a potential requestor about the availability of certain data or operations to a particular offering. The set of possible URIs are defined by the service type, not the Discovery Service. If no option is specified, the service instance does not display any available options. For a standard set of options, see the Liberty ID-SIS Personal Profile Service Specification.

Select a directive for the resource offering.

Directives are special entries defined in SOAP headers that can be used to enforce policy-related decisions. You can choose from the following:
- GenerateBearerToken specifies that a bearer token be generated.
- AuthenticateRequester must be used with any service description that use SAML for message authentication.
- EncryptResourceID specifies that the Discovery Service encrypt the resource ID.
- AuthenticateSessionContext is specified when a Discovery Service provider includes a SAML assertion containing a SessionContextStatement in any future QueryResponse messages.
- AuthorizeRequester is specified when a Discovery Service provider wants to include a SAML assertion containing a ResourceAccessStatement in any future QueryResponse messages.
If you want to associate a directive with one or more service descriptions, select the check box for that Description ID. If no service descriptions are selected, the directive is applied to all description elements in the resource offering.

Click OK.

Logout from the console.

To Invoke the Custom Service

Web service clients can access the custom web service by discovering the web service's end point and using the required credentials. This information is stored by the OpenSSO Enterprise Discovery Service. There are two ways in which a client can authenticate to OpenSSO Enterprise in order to access the Discovery Service:

The Liberty ID-FF is generally used if it's a browser-based application and the web service client is a federation enabled service provider.
The OpenSSO Enterprise Authentication Service (based on the Liberty ID-WSF) is used for remote web services clients with pure SOAP-based authentication capabilities.

In the following procedure, we use the Liberty ID-WSF client API to invoke the web service.

Note –

The code in this procedure is used to demonstrate the usage of the Liberty ID-WSF client API. More information can be found in the Sun OpenSSO Enterprise 8.0 Java API Reference.

Write code to authenticate the WSC to the Liberty ID-WSF Authentication Service of OpenSSO Enterprise.

The sample code below will allow access to the Discovery Service. It is a client-side program to be run inside the WSC application.

public class StockClient {
              :
    public SASLResponse authenticate(
        String userName,
        String password,
        String authurl) throws Exception {

        SASLRequest saslReq =
                        new SASLRequest(AuthnSvcConstants.MECHANISM_PLAIN);
        saslReq.setAuthzID(userName);

        SASLResponse saslResp = AuthnSvcClient.sendRequest(saslReq, authurl);
        String statusCode = saslResp.getStatusCode();
        if (!statusCode.equals(SASLResponse.CONTINUE)) {
                return null;
        }

        String serverMechanism = saslResp.getServerMechanism();
        saslReq  = new SASLRequest(serverMechanism);
        String dataStr = userName + "\0" + userName + "\0" + password;
        saslReq.setData(dataStr.getBytes("UTF-8"));
        saslReq.setRefToMessageID(saslResp.getMessageID());
        saslResp = AuthnSvcClient.sendRequest(saslReq, authurl);
        statusCode = saslResp.getStatusCode();
        if (!statusCode.equals(SASLResponse.OK)) {
            return null;
        }

        return saslResp;
    }
                    :

           }

Add code that will extract the Discovery Service information from the Authentication Response.

The following additional code would be added to what was developed in the previous step.
```
ResourceOffering discoro = saslResp.getResourceOffering();
          List credentials = authnResponse.getCredentials();
```

Add code to query the Discovery Service for the web service's resource offering by using the Discovery Service resource offering and the credentials that are required to access it.

The following additional code would be added to what was previously developed.

RequestedService rs = new RequestedService(null,
                   "urn:com:sun:liberty:sample:stockticker");
              List rss = new ArrayList();
              rss.add(rs);

             Query  discoQuery = new Query(discoro.getResourceID(), rss);

             DiscoveryClient discoClient = null;
            
             discoClient = new DiscoveryClient(secAssertion, serviceURL, null);
         
             QueryResponse queryResponse = discoClient.getResourceOffering(discoQuery);

The discovery response contains the service's resource offering and the credentials required to access the service.

quotes contains the response body (the stock quote). You would use the OpenSSO Enterprise SOAP API to get the body elements.

 List offerings = discoResponse.getResourceOffering();
          ResourceOffering stockro = (ResourceOffering)offerings.get(0);

          List credentials = discoResponse.getCredentials();

          SecurityAssertion secAssertion = null;
          if(credentials != null && !credentials.isEmpty()) {
             secAssertion = (SecurityAssertion)credentials.get(0);
          }

          String serviceURL = ((Description)stockro.getServiceInstance().
                   getDescription().get(0)).getEndpoint();

          QuoteRequest req = new QuoteRequest(symbol,
               stockro.getResourceID().getResourceID());
          Element elem =  XMLUtils.toDOMDocument(
              req.toString(), debug).getDocumentElement();

          List list = new ArrayList();
          list.add(elem);

          Message msg = new Message(null, secAssertion);
          msg.setSOAPBodies(list);

          Message response = Client.sendRequest(msg, serviceURL, null, null);
          List quotes = response.getBodies();

Setting Up Liberty ID-WSF 1.1 Profiles

OpenSSO Enterprise automatically detects which version of the Liberty ID-WSF profiles is being used. If OpenSSO Enterprise is the web services provider (WSP), it detects the version from the incoming SOAP message. If OpenSSO Enterprise is the WSC, it uses the version the WSP has registered with the Discovery Service. If the WSP can not detect the version from the incoming SOAP message or the WSC can not communicate with the Discovery Service, the version defined in the com.sun.identity.liberty.wsf.version property in the OpenSSO Enterprise configuration data store will be used. Following are the steps to configure OpenSSO Enterprise to use Liberty ID-WSF 1.1 profiles.

To Configure OpenSSO Enterprise to Use Liberty ID-WSF 1.1 Profiles

Don't use the Liberty ID-FF sample as it does not configure a signing key.
If both machines are in the same domain, change the cookie name on one of them to avoid cookie conflict.

Install OpenSSO Enterprise on two different machines.

Test the installations by logging in to the console at http://server:port/opensso/UI/Login.

Configure one instance of OpenSSO Enterprise as a Liberty ID-FF identity provider.
1. Login to the OpenSSO Enterprise console.
2. Click the Federation tab.
3. Click New under Entity Providers.
  
  The Create IDFF Entity Provider page is displayed.
4. Enter a value for the Entity Identifier attribute on the Create IDFF Entity Provider page.
5. Under Identity Provider, enter values for Meta Alias, Signing Certificate Alias, and Encryption Certificate Alias and click Create to create the identity provider metadata.
6. Using ssoadm.jsp, export the identity provider metadata.

Configure the second instance of OpenSSO Enterprise as a Liberty ID-FF service provider.
1. Login to the OpenSSO Enterprise console.
2. Click the Federation tab.
3. Click New under Entity Providers.
  
  The Create IDFF Entity Provider page is displayed.
4. Enter a value for the Entity Identifier attribute on the Create IDFF Entity Provider page.
5. Under Service Provider, enter values for Meta Alias, Signing Certificate Alias, and Encryption Certificate Alias and click Create to create the service provider metadata.
6. Using ssoadm.jsp, export the service provider metadata.

Exchange the standard metadata files and import the identity provider metadata onto the service provider machine and the service provider metadata onto the identity provider machine.

Create a circle of trust that includes the Entity Identifier for both providers on each machine.

Login to the instance of OpenSSO Enterprise acting as the identity provider.
1. Click the Web Services tab.
2. Click the Discovery Service tab.
3. Scroll down to Resource Offerings for Bootstrapping.
4. Click urn:liberty:disco:2003-08.
  
  The Edit Resource Offerings page is displayed.
5. Remove the default value of Service Type.
6. Add urn:liberty:security:2005-02:null:X509.
7. Change the value of the Provider ID attribute to the entity identifier of the identity provider.
8. Click Save.
  
  The Discovery Service page is displayed.
9. Scroll down to the Classes for ResourceID Mapper Plug-in attribute.
10. Click the link that is the value of the Provider ID.
  
  The Edit Resource ID Mapping page is displayed.
11. Change the value of the Provider ID attribute to the entity identifier of the identity provider.
12. Click Save.
  
  The Discovery Service page is displayed.
13. Click the Configuration tab.
14. Click the Global tab.
15. Click the Liberty ID-WSF Security Service link.
  
  The Liberty ID-WSF Security Service page is displayed.
16. Enter test as the value for the following attributes and click Save.
  - Default WSC Certificate alias
  - Trusted Authority signing certificate alias
  - Trusted CA signing certificate aliases
  Note –
  test is the default self-signed certificate shipped with OpenSSO Enterprise. Use your own key and CA name for your customized deployment.
17. Log out of the console and restart the identity provider instance to allow the changes to take effect.

Login to the instance of OpenSSO Enterprise acting as the service provider.
1. Click the Web Services tab.
2. Under the Personal Profile tab, change the value of the Provider ID attribute to the entity identifier of the service provider and click Save.
3. Click the SOAP Binding Service tab.
4. Scroll down, enable 1.1 as the value of the Liberty Identity Web Services Version attribute and click Save.
5. Click the Configuration tab.
6. Click the Global tab.
7. Click the Liberty ID-WSF Security Service link.
  
  The Liberty ID-WSF Security Service page is displayed.
8. Enter test as the value for the following attributes and click Save.
  - Default WSC Certificate alias
  - Trusted Authority signing certificate alias
  - Trusted CA signing certificate aliases
  Note –
  test is the default self-signed certificate shipped with OpenSSO Enterprise. Use your own key and CA name for your customized deployment.
9. Log out of the console and restart the service provider instance to allow the changes to take effect.

To Test the Liberty ID-WSF 1.1 Configuration

Deploy the OpenSSO Enterprise client WAR on a third web container.
- Use opensso-client-jdk15.war for web containers running the Java Development Kit (JDK) 1.5 and above.
- Use opensso-client-jdk14.war for web containers running JDK 1.4.

Configure the client sample and then configure the WSC sample.

Find AMConfig.properties for the Client SDK under the user_home/OpenSSOClient directory.

For example, path_to_client_sample_deployment_AMConfig.properties

Edit the following properties in AMConfig.properties.
- com.sun.identity.liberty.ws.wsc.certalias=test
- com.sun.identity.liberty.ws.ta.certalias=test
- com.sun.identity.liberty.ws.trustedca.certalias=test
Note –
test is the default self-signed certificate shipped with OpenSSO Enterprise. Use your own key and CA name for your customized deployment.

Restart the Client SDK web container and follow the client SDK sample README to run the sample.

All Liberty ID-WSF traffic is using version 1.1 now. You can validate this by looking at the XML message; the name space for the SOAP binding should be urn:liberty:sb:2004-04 as opposed to urn:liberty:sb: 2003-08 for version 1.0.

Common Application Programming Interfaces

The following list describes the API common to all Liberty-based OpenSSO Enterprise service components and services.

Common Interfaces

This section summarizes classes that can be used by all Liberty-based OpenSSO Enterprise web service components, as well as interfaces common to all Liberty-based OpenSSO Enterprise web services. The packages that contain the classes and interfaces are:

`com.sun.identity.liberty.ws.common` Package

This package includes the Status class common to all Liberty-based OpenSSO Enterprise web service components. It represents a common status object. For more information, including methods and their syntax and parameters, see the Sun OpenSSO Enterprise 8.0 Java API Reference.

`com.sun.identity.liberty.ws.interfaces` Package

This package includes interfaces that can be implemented to add their corresponding functionality to each Liberty-based OpenSSO Enterprise web service.

Table 9–1 com.sun.identity.liberty.ws.interfaces Interfaces


Interface	Description
`Authorizer`	This interface, once implemented, can be used by each Liberty-based web service component for access control. Note – The `com.sun.identity.liberty.ws.disco.plugins.DefaultDiscoAuthorizer` class is the implementation of this interface for the Discovery Service. The `com.sun.identity.liberty.ws.idpp.plugin.IDPPAuthorizer` class is the implementation for the Liberty Personal Profile Service. The `Authorizer` interface enables a web service to check whether a web service consumer (WSC) is allowed to access the requested resource. When a WSC contacts a web service provider (WSP), the WSC conveys a sender identity and an invocation identity. Note that the invocation identity is always the subject of the SAML assertion. These conveyances enable the WSP to make an authorization decision based on one or both identities. The OpenSSO Enterprise Policy Service performs the authorization based on defined policies.
`ResourceIDMapper`	This interface is used to map a user DN to the resource identifier associated with it. OpenSSO Enterprise provides implementations of this interface. `com.sun.identity.liberty.ws.disco.plugins.Default64ResourceIDMapper` assumes the Resource ID format to be: `providerID` + "/" + `the Base64 encoded userIDs`. `com.sun.identity.liberty.ws.disco.plugins.DefaultHexResourceIDMapper` assumes the Resource ID format to be: `providerID` + "/" + `the hex string of userID`. `com.sun.identity.liberty.ws.idpp.plugin.IDPPResourceIDMapper` assumes the Resource ID format to be: `providerID` + "/" + `the Base64 encoded userIDs`. A different implementation of the interface may be developed. The implementation class should be given to the provider that hosts the Discovery Service. The mapping between the `providerID` and the implementation class can be configured through the Classes For ResourceIDMapper Plugin attribute.
`ServiceInstanceUpdate`	Interface used to include a SOAP header (`ServiceInstanceUpdateHeader`) when sending a SOAP response.

For more information, including methods and their syntax and parameters, see the Sun OpenSSO Enterprise 8.0 Java API Reference.

Common Security API

The Liberty-based security APIs are included in the com.sun.identity.liberty.ws.security package and the com.sun.identity.liberty.ws.common.wsse package.

`com.sun.identity.liberty.ws.security` Package

The com.sun.identity.liberty.ws.security package includes the SecurityTokenProvider interface for managing Web Service Security (WSS) type tokens and the SecurityAttributePlugin interface for inserting security attributes (using an AttributeStatement) into the assertion during the Discovery Service token generation. The following table describes the classes used to manage Liberty-based security mechanisms.

Table 9–2 com.sun.identity.liberty.ws.security Classes


Class	Description
`ProxySubject`	Represents the identity of a proxy, the confirmation key, and confirmation obligation the proxy must possess and demonstrate for authentication purposes.
`ResourceAccessStatement`	Conveys information regarding the accessing entities and the resource for which access is being attempted.
`SecurityAssertion`	Provides an extension to the Assertion class to support ID-WSF `ResourceAccessStatement` and `SessionContextStatement`.
`SecurityTokenManager`	An entry class for the security package `com.sun.identity.liberty.ws.security`. You can call its methods to generate X.509 and SAML tokens for message authentication or authorization. It is designed as a provider model, so different implementations can be plugged in if the default implementation does not meet your requirements.
`SessionContext`	Represents the session status of an entity to another system entity.
`SessionContextStatement`	Conveys the session status of an entity to another system entity within the body of an `<saml:assertion>` element.
`SessionSubject`	Represents a Liberty subject with its associated session status.

For more information, including methods and their syntax and parameters, see the Sun OpenSSO Enterprise 8.0 Java API Reference.

`com.sun.identity.liberty.ws.common.wsse` Package

This package includes BinarySecurityToken which provides an interface to parse and create the X.509 Security Token in accordance with the Liberty ID-WSF Security Mechanisms. Both WSS X.509 and SAML tokens are supported. For more information, including methods and their syntax and parameters, see the Sun OpenSSO Enterprise 8.0 Java API Reference.

Authentication Web Service

The SOAP specifications define an XML-based messaging paradigm, but do not specify any particular security mechanisms. Particularly, they do not describe user authentication using SOAP messages. To rectify this, the Liberty-based Authentication Web Service was implemented based on the Liberty ID-WSF Authentication Service and Single Sign-On Service Specification. The specification defines a protocol that adds the Simple Authentication and Security Layer (SASL) authentication functionality to the SOAP binding described in the Liberty ID-WSF SOAP Binding Specification and SOAP Binding Service. The Liberty-based Authentication Web Service is for provider-to-provider authentication.

Note –

The specification also contains an XML schema that defines the authentication protocol. More information can be found in Schema Files and Service Definition Documents.

Authentication Web Service Default Implementation

The Authentication Web Service attributes are global; the value of this attribute is carried across the OpenSSO Enterprise configuration and inherited by every realm. The attributes for the Authentication Web Service are defined in the amAuthnSvc.xml service file. The Mechanism Handlers List attribute stores information about the SASL mechanisms that are supported by the Authentication Web Service and contains two parameters.

`key` Parameter

The required key defines the SASL mechanism supported by the Authentication Web Service.

`class` Parameter

The required class specifies the name of the implemented class for the SASL mechanism. Two authentication mechanisms are supported by the following default implementations:

Table 9–3 Default Implementations for Authentication Mechanism


Class	Description
`com.sun.identity.liberty.ws.authnsvc.mechanism.PlainMechanismHandler`	This class is the default implementation for the PLAIN authentication mechanism. It maps user identifiers and passwords in the PLAIN mechanism to the user identifiers and passwords in the LDAP authentication module under the root organization.
`com.sun.identity.liberty.ws.authnsvc.mechanism.CramMD5MechanismHandler`	This class is the default implementation for the CRAM-MD5 authentication mechanism.

The Authentication Web Service layer provides an interface that must be implemented for each SASL mechanism to process the requested message and return a response.

Authentication Web Service Packages

The Authentication Web Service provides programmatic interfaces to allow clients to interact with it. The following sections provide short descriptions of these packages. For more detailed information, see the Sun OpenSSO Enterprise 8.0 Java API Reference. The authentication-related packages include:

`com.sun.identity.liberty.ws.authnsvc` Package

This package provides web service clients with a method to request authentication credentials from the Authentication Web Service and receive responses back from it using the Simple Authentication and Security Layer (SASL).

`com.sun.identity.liberty.ws.authnsvc.mechanism` Package

This package provides an interface that must be implemented for each different SASL mechanism to enable authentication using them. Each SASL mechanism will correspond to one implementation that will process incoming SASL requests and generate outgoing SASL responses.

`com.sun.identity.liberty.ws.authnsvc.protocol` Package

This package provides classes that correspond to the request and response elements defined in the Liberty XSD schema that accompanies the Liberty ID-WSF Authentication Service Specification.

Access the Authentication Web Service

The URL to gain access to the Authentication Web Service is:

http://SERVER_HOST:SERVER_PORT/SERVER_DEPLOY_URI/Liberty/authnsvc

This URL is normally used by the OpenSSO Enterprise client API to access the service. For example, the OpenSSO Enterprise public client, com.sun.identity.liberty.ws.authnsvc.AuthnSvcClient uses this URL to authenticate principals with OpenSSO Enterprise.

Data Services

A data service is a web service that supports the query and modification of data regarding a principal. An example of a data service is a web service that hosts and exposes a principal's profile information, such as name, address and phone number. A query is when a web service consumer (WSC) requests and receives the data (in XML format). A modify is when a WSC sends new information to update the data. The Liberty Alliance Project has defined the Liberty ID-WSF Data Services Template Specification (Liberty ID-WSF-DST) as the standard protocol for the query and modification of data profiles exposed by a data service. Using this specification, the Liberty Alliance Project has developed additional specifications for other types of data services: personal profile service, geolocation service, contact service, and calendar service). Of these data services, OpenSSO Enterprise has implemented the Liberty Personal Profile Service.

Liberty Personal Profile Service

The Liberty Personal Profile Service is a default OpenSSO Enterprise identity service. It can be queried for identity data and its attributes can be updated.

For access to occur, the hosting provider of the Liberty Personal Profile Service needs to be registered with the Discovery Service on behalf of each identity principal. To register a service with the Discovery Service, update a resource offering for that service. For more information, see Discovery Service.

The URL to gain access to the Liberty Personal Profile Service is:

http://SERVER_HOST:SERVER_PORT/SERVER_DEPLOY_URI/Liberty/idpp

This URL is normally used by the OpenSSO Enterprise client API to access the service. For example, the OpenSSO Enterprise public Data Service Template client, com.sun.identity.liberty.ws.dst.DSTClient uses this URL to query and modify an identity's personal profile attributes stored in OpenSSO Enterprise.

Data Services Template Packages

OpenSSO Enterprise contains two packages based on the Liberty ID-WSF-DST. They are:

For more detailed API documentation, including methods and their syntax and parameters, see the Sun OpenSSO Enterprise 8.0 Java API Reference.

`com.sun.identity.liberty.ws.dst` Package

The following table summarizes the classes in the Data Services Template client API that are included in the com.sun.identity.liberty.ws.dst package.

Table 9–4 Data Service Client APIs


Class	Description
`DSTClient`	Provides common functions for the Data Services Templates query and modify options.
`DSTData`	Provides a wrapper for any data entry.
`DSTModification`	Represents a Data Services Template modification operation.
`DSTModify`	Represents a Data Services Template modify request.
`DSTModifyResponse`	Represents a Data Services Template response to a DST modify request.
`DSTQuery`	Represents a Data Services Template query request.
`DSTQueryItem`	Wrapper for one query item.
`DSTQueryResponse`	Represents a Data Services Template query response.
`DSTUtils`	Provides utility methods used by the DST layer.

`com.sun.identity.liberty.ws.dst.service` Package

This package provides a handler class that can be used by any generic identity data service that is built using the Liberty Alliance ID-SIS Specifications.

Note –

The Liberty Personal Profile Service is built using the Liberty ID-SIS Personal Profile Service Specification, based on the Liberty Alliance ID-SIS Specifications.

The DSTRequestHandler class is used to process query or modify requests sent to an identity data service. It is an implementation of the interface com.sun.identity.liberty.ws.soapbinding.RequestHandler. For more detailed API documentation, see the Sun OpenSSO Enterprise 8.0 Java API Reference.

Discovery Service

OpenSSO Enterprise contains a Discovery Service defined by the Liberty Alliance Project specifications. The Discovery Service allows a requesting entity to dynamically determine a principal’s registered identity service. It might also function as a security token service, issuing security tokens to the requester that can then be used in the request to the discovered identity service. The following sections contain more information.

Generating Security Tokens

In general, a discovery service and an identity provider are hosted on the same machine. Because the identity provider hosting the Discovery Service might be fulfilling other roles for an identity (such as a Policy Decision Point or an Authentication Authority), it can be configured to provide the requesting entity with security tokens. The Discovery Service can include a security token (inserted into a SOAP message header) in a DiscoveryLookup response. The token can then be used as a credential to invoke the service returned with it.

Note –

For information regarding the deployment of the Client SDK, see Chapter 14, Using the Client SDK.

To Configure the Discovery Service to Generate Security Tokens

Generate the keystore and certificate aliases for the machines that are hosting the Discovery Service, the WSP and the WSC.

OpenSSO Enterprise uses a Java keystore for storing the public and private keys so, if this is a new deployment, you might need to generate one using keytool, the key and certificate management utility supplied with the Java Platform, Standard Edition. In short, keytool generates key pairs as separate key entries (one for a public key and the other for its associated private key). It wraps the public key into an X.509 self-signed certificate (one for which the issuer/signer is the same as the subject), and stores it as a single-element certificate chain. Additionally, the private key is stored separately, protected by a password, and associated with the certificate chain for the corresponding public key. All public and private keystore entries are accessed via unique aliases.

Update the values of the key-related properties for the appropriate deployed instances of OpenSSO Enterprise.

Note –
The same property might have already been edited depending on the deployment scenario.
1. For the web services provider and web services client deployed on OpenSSO Enterprise:
  1. Login to the OpenSSO Enterprise console.
  2. Click the Configuration tab.
  3. Click the Global tab.
  4. Click the Liberty ID-WSF Security Service link.
    
    The Liberty ID-WSF Security Service page is displayed.
  5. Enter test as the value for the following attributes and click Save.
    - Default WSC Certificate alias
    - Trusted Authority signing certificate alias
    - Trusted CA signing certificate aliases
    Note –
    test is the default self-signed certificate shipped with OpenSSO Enterprise. Use your own key and CA name for your customized deployment. If you want to use a different keystore location, under the Configuration tab click Servers and Sites. Click the link of the appropriate server instance. Under the Security tab click Inheritance Settings and do the following:
    - Uncheck the Keystore File box.
    - Optionally, uncheck the Private Key Password File box and the Keystore Password File box.
    Click Save and Back to Server Profile. Click the Keystore link and enter the location of the Keystore File. (If you change the password for the Private Key or Keystore, you need to encode the new password using the ampassword command or encode.jsp before putting it into the corresponding password file.)
  6. Log out of the console and restart the instance to allow the changes to take effect.
2. For the web services provider and web services client deployed on the same machine as the OpenSSO Enterprise Client SDK update the values of the following key-related properties in the AMConfig.properties:
  - com.sun.identity.saml.xmlsig.keystore defines the location of the keystore file.
  - com.sun.identity.saml.xmlsig.storepass defines the location of the file that contains the password used to access the keystore file.
  - com.sun.identity.saml.xmlsig.keypass defines the location of the file that contains the password used to protect the private key of a generated key pair.
  - com.sun.identity.liberty.ws.wsc.certalias defines the certificate alias used for signing the WSP protocol responses.
  - com.sun.identity.liberty.ws.trustedca.certaliases defines the certificate alias and the Provider ID list on which the WSP is trusting.

Configure each identity provider and service provider as an entity using the Federation module.

This entails configuring each provider as an entity in a circle of trust.

Establish provider trust between the entities by creating an authentication domain using the Federation module.

See Part II, Federation, Web Services, and SAML Administration, in Sun OpenSSO Enterprise 8.0 Administration Guide.

Change the default value of the Provider ID for the Discovery Service on the machine where the Discovery Service is hosted to the value that reflects the previously loaded metadata.
1. Click the Web Services tab from the OpenSSO Enterprise Console.
2. Click the Discovery Service tab under Web Services.
3. Change the default value of the Provider ID from protocol://host:port/deployuri/Liberty/disco to the Entity ID of the identity provider.

Change the default value of the Provider ID for the Liberty Personal Profile Service on the machine where the Liberty Personal Profile Service is hosted to the value that reflects the previously loaded metadata.
1. Click the Web Services tab from the OpenSSO Enterprise Console.
2. Click the Liberty Personal Profile Service tab under Web Services.
3. Change the default value of the Provider ID from protocol://host:port/deployuri/Liberty/idpp to the Entity ID of the identity provider.

Register a resource offering for the WSP using either of the following methods.

Make sure that the appropriate directives are chosen.
- For SAML Bearer token use GenerateBearerToken or AuthenticateRequester.
- For SAML Token (Holder of key) use AuthenticateRequester or AuthorizeRequester.

Discovery Service Packages

OpenSSO Enterprise contains several Java packages that are used by the Discovery Service. They include:

com.sun.identity.liberty.ws.disco includes a client API that provides interfaces to communicate with the Discovery Service. See Client APIs in com.sun.identity.liberty.ws.disco.
com.sun.identity.liberty.ws.disco.plugins includes an interface that can be used to develop plug-ins. The package also contains some default plug-ins. See com.sun.identity.liberty.ws.disco.plugins.DiscoEntryHandler Interface.
com.sun.identity.liberty.ws.interfaces includes interfaces that can be used to implement functionality common to all Liberty-enabled identity services. Several implementations of these interfaces have been developed for the Discovery Service. See com.sun.identity.liberty.ws.interfaces.Authorizer Interface and com.sun.identity.liberty.ws.interfaces.ResourceIDMapper Interface.

Note –

Additional information is in the Sun OpenSSO Enterprise 8.0 Java API Reference.

Client APIs in `com.sun.identity.liberty.ws.disco`

The following table summarizes the client APIs in the package com.sun.identity.liberty.ws.disco. For more information, including methods and their syntax and parameters, see the Sun OpenSSO Enterprise 8.0 Java API Reference.

Table 9–5 Discovery Service Client APIs


Class	Description
`Description`	Represents a DescriptionType element of a service instance.
`Directive`	Represents a discovery service DirectiveType element.
`DiscoveryClient`	Provides methods to send Discovery Service queries and modifications.
`EncryptedResourceID`	Represents an EncryptionResourceID element for the Discovery Service.
`InsertEntry`	Represents an Insert Entry for Discovery Modify request.
`Modify`	Represents a discovery modify request.
`ModifyResponse`	Represents a discovery response to a modify request.
`Query`	Represents a discovery Query object.
`QueryResponse`	Represents a response to a discovery query request.
`RemoveEntry`	Represents a remove entry element for the discovery modify request.
`RequestedService`	Enables the requester to specify that all the resource offerings returned must be offered through a service instance that complies with one of the specified service types.
`ResourceID`	Represents a Discovery Service Resource ID.
`ResourceOffering`	Associates a resource with a service instance that provides access to that resource.
`ServiceInstance`	Describes a web service at a distinct protocol endpoint.

`com.sun.identity.liberty.ws.disco.plugins.DiscoEntryHandler` Interface

This interface is used to get and set discovery entries for a user. A number of default implementations are provided, but if you want to handle this function differently, implement this interface and set the implementing class as the value of the Entry Handler Plugin Class attribute as discussed in Entry Handler Plug-in Class in Sun OpenSSO Enterprise 8.0 Administration Guide. The default implementations of this interface are described in the following table.

Table 9–6 Implementations of com.sun.identity.liberty.ws.disco.plugins.DiscoEntryHandler


Class	Description
`UserDiscoEntryHandler`	Gets or modifies discovery entries stored in the user’s entry as a value of the `sunIdentityServerDiscoEntries` attribute. The `UserDiscoEntryHandler` implementation is used in business-to-consumer scenarios such as the Liberty Personal Profile Service.
`DynamicDiscoEntryHandler`	Gets discovery entries stored as a value of the `sunIdentityServerDynamicDiscoEntries` dynamic attribute in the Discovery Service. Modification of these entries is not supported and always returns `false`. The resource offering is saved in an organization or a role. The `DynamicDiscoEntryHandler` implementation is used in business-to-business scenarios such as the Liberty Employee Profile service.
`UserDynamicDiscoEntryHandler`	Gets a union of the discovery entries stored in the user entry `sunIdentityServerDiscoEntries` attribute and discovery entries stored in the Discovery Service `sunIdentityServerDynamicDiscoEntries` attribute. It modifies only discovery entries stored in the user entry. The `UserDynamicDiscoEntryHandler` implementation can be used in both business-to-consumer and business-to-business scenarios.

`com.sun.identity.liberty.ws.interfaces.Authorizer` Interface

This interface is used to enable an identity service to check the authorization of a WSC. The DefaultDiscoAuthorizer class is the default implementation of this interface. The class uses the OpenSSO Enterprise Policy Service for creating and applying policy definitions. Policy definitions for the Discovery Service are configured using the OpenSSO Enterprise Console.

Note –

The Policy Service looks for an SSOToken defined for Authenticated Users or Web Service Clients. For more information on this and the Policy Service in general, see the Sun OpenSSO Enterprise 8.0 Administration Guide.

To Configure Discovery Service Policy Definitions

In the OpenSSO Enterprise Console, click the Access Control tab.

Select the name of the realm in which the policy definitions will be configured.

Select Policies to access policy configurations.

Click New Policy to add a new policy definition.

Type a name for the policy.

(Optional) Enter a description for the policy.

(Optional) Select the check box next to Active.

Click New to add rules to the policy definition.

Select Discovery Service for the rule type and click Next.

Type a name for the rule.

Type a resource on which the rule acts.

The Resource Name field uses the form ServiceType + RESOURCE_SEPARATOR + ProviderID. For example, urn:liberty:id-sis-pp:2003-08;http://example.com.

Select an action and appropriate value for the rule.

Discovery Service policies can only look up or update data.

Click Finish to configure the rule.

The com.sun.identity.liberty.ws.interfaces.Authorizer interface can be implemented by any web service in OpenSSO Enterprise. For more information, see XXXXXCommon Service Interfaces and the Java API Reference in //OpenSSO-base/SUNWam/docs or on docs.sun.com.

Click New to add subjects to the policy definition.

Select the subject type and click Next.

Type a name for the group of subjects.

(Optional) Click the check box if this is an exclusive group.

Select the users and click to add them to the group.

Click Finish to return to the policy definition screen.

Click New to add conditions to the policy definition.

Select the condition type and click Next.

Type values for the displayed attributes.

For more information, see the Sun OpenSSO Enterprise 8.0 Administration Guide.

Click Finish to return to the policy definition screen.

Click New to add response providers to the policy definition.

Type a name for the response provider.

(Optional) Add values for the StaticAttribute.

(Optional) Add values for the DynamicAttribute.

Click Finish to return to the policy definition screen.

Click Create to finish the policy configuration.

`com.sun.identity.liberty.ws.interfaces.ResourceIDMapper` Interface

This interface is used to map a user ID to the resource identifier associated with it. OpenSSO Enterprise provides two implementations of this interface.

com.sun.identity.liberty.ws.disco.plugins.Default64ResourceIDMapper assumes the format to be providerID + "/" + the Base64 encoded userIDs
com.sun.identity.liberty.ws.disco.plugins.DefaultHexResourceIDMapper assumes the format to be providerID + "/" + the hex string of userIDs

A different implementation of the interface may be developed. The implementation class should be given to the provider that hosts the Discovery Service. The mapping between the providerID and the implementation class can be configured through the XXXXXClasses For ResourceIDMapper Plug-in attribute.

Note –

The com.sun.identity.liberty.ws.interfaces.ResourceIDMapper interface is common to all identity services in OpenSSO Enterprise not only the Discovery Service. For more information, see the Sun OpenSSO Enterprise 8.0 Java API Reference.

Access the Discovery Service

The URL to gain access to the Discovery Service is:

http://SERVER_HOST:SERVER_PORT/SERVER_DEPLOY_URI/Liberty/disco

This URL is normally used by the OpenSSO Enterprise client API to access the service. For example, the public Discovery Service client, com.sun.identity.liberty.ws.disco.DiscoveryClient uses this URL to query and modify the resource offerings of an identity.

SOAP Binding Service

OpenSSO Enterprise contains an implementation of the Liberty ID-WSF SOAP Binding Specification from the Liberty Alliance Project. The specification defines a transport layer for sending and receiving SOAP messages.

`SOAPReceiver` Servlet

The SOAPReceiver servlet receives a Message object from a web service client (WSC), verifies the signature, and constructs its own Message object for processing by OpenSSO Enterprise. The SOAPReceiver then invokes the correct request handler class to pass this second Message object on to the appropriate OpenSSO Enterprise service for a response. When the response is generated, the SOAPReceiver returns this Message object back to the WSC. More information can be found in the SOAP Binding Service in Sun OpenSSO Enterprise 8.0 Technical Overview.

SOAP Binding Service Package

The SOAP Binding Service includes a Java package named com.sun.identity.liberty.ws.soapbinding. This package provides classes to construct SOAP requests and responses and to change the contact point for the SOAP binding. The following table describes some of the available classes. For more detailed information, see the Sun OpenSSO Enterprise 8.0 Java API Reference.

Table 9–7 SOAP Binding Service API


Class	Description
`Client`	Provides a method with which a WSC can send a request to a WSP using a SOAP connection. It also returns the response.
`ConsentHeader`	Represents the SOAP element named `Consent`.
`CorrelationHeader`	Represents the SOAP element named `Correlation`. By default, `CorrelationHeader` will always be signed.
`ProcessingContextHeader`	Represents the SOAP element named `ProcessingContext`.
`ProviderHeader`	Represents the SOAP element named `Provider`.
`RequestHandler`	Defines an interface that needs to be implemented on the server side by each web service in order to receive a request from a WSC and generate a response. After implementing the class, it must be registered in the SOAP Binding Service so the SOAP framework knows where to forward incoming requests.
`Message`	Represents a SOAP message and is used by both the web service client and server to construct SOAP requests and responses. Each SOAP message has multiple headers and bodies. It may contain a certificate for client authentication, the IP address of a remote endpoint, and a SAML assertion used for signing.
`ServiceInstanceUpdateHeader`	Allows a service to change the endpoint on which requesters will contact it.
`ServiceInstanceUpdateHeader.Credential`	Allows a service to use a different security mechanism and credentials to access the requested resource.
`SOAPFault`	Represents the SOAP element named `SOAP Fault`.
`SOAPFaultDetail`	Represents the SOAP element named `Detail`, a child element of `SOAP Fault`.
`UsageDirectiveHeader`	Defines the SOAP element named `UsageDirective`.

See PAOS Binding for information on this reverse HTTP binding for SOAP.

Interaction Service

Providers of identity services often need to interact with the owner of a resource to get additional information, or to get their consent to expose data. The Liberty Alliance Project has defined the Liberty ID-WSF Interaction Service Specification to specify how these interactions can be carried out. Of the options defined in the specification, OpenSSO Enterprise has implemented the Interaction RequestRedirect Profile. In this profile, the WSP requests the connecting WSC to redirect the user agent (principal) to an interaction resource (URL) at the WSP. When the user agent sends an HTTP request to get the URL, the WSP has the opportunity to present one or more pages to the principal with questions for other information. After the WSP obtains the information it needs to serve the WSC, it redirects the user agent back to the WSC, which can now reissue its original request to the WSP.

Configuring the Interaction Service

While there is no XML service file for the Interaction Service, this service does have properties. The properties are configured upon installation in the configuration data store and are described in the following table.

Table 9–8 Interaction Service Properties


Property	Description
`com.sun.identity.liberty.interaction.wspRedirectHandler`	Points to the URL where the `WSPRedirectHandler` servlet is deployed. The servlet handles the service provider side of interactions for user redirects.
`com.sun.identity.liberty.interaction.wscSpecifiedInteractionChoice`	Indicates the level of interaction in which the WSC will participate if the WSC participates in user redirects. Possible values include `interactIfNeeded`, `doNotInteract`, and `doNotInteractForData`. The affirmative `interactIfNeeded` is the default.
`com.sun.identity.liberty.interaction.wscWillIncludeUserInteractionHeader`	Indicates whether the WSC will include a SOAP header to indicate certain preferences for interaction based on the Liberty specifications. The default value is `yes`.
`com.sun.identity.liberty.interaction.wscWillRedirect`	Indicates whether the WSC will participate in user redirections. The default value is `yes`.
`com.sun.identity.liberty.interaction.wscSpecifiedMaxInteractionTime`	Indicates the maximum length of time (in seconds) the WSC is willing to wait for the WSP to complete its portion of the interaction. The WSP will not initiate an interaction if the interaction is likely to take more time than . For example, the WSP receives a request where this property is set to a maximum 30 seconds. If the WSP property `com.sun.identity.liberty.interaction.wspRedirectTime` is set to 40 seconds, the WSP returns a SOAP fault (`timeNotSufficient`), indicating that the time is insufficient for interaction.
`com.sun.identity.liberty.interaction.wscWillEnforceHttpsCheck`	Indicates whether the WSC will enforce HTTPS in redirected URLs. The Liberty Alliance Project specifications state that, the value of this property is always `yes`, which indicates that the WSP will not redirect the user when the value of `redirectURL` (specified by the WSP) is not an HTTPS URL. The `false` value is primarily meant for ease of deployment in a phased manner.
`com.sun.identity.liberty.interaction.wspWillRedirect`	Initiates an interaction to get user consent for something or to collect additional data. This property indicates whether the WSP will redirect the user for consent. The default value is `yes`.
`com.sun.identity.liberty.interaction.wspWillRedirectForData`	Initiates an interaction to get user consent for something or to collect additional data. This property indicates whether the WSP will redirect the user to collect additional data. The default value is `yes`.
`com.sun.identity.liberty.interaction.wspRedirectTime`	Indicates the length of time (in seconds) that the WSP expects to take to complete an interaction and return control back to the WSC. For example, the WSP receives a request indicating that the WSC will wait a maximum 30 seconds (set in `com.sun.identity.liberty.interaction.wscSpecifiedMaxInteractionTime`) for interaction. If the `wspRedirectTime` is set to 40 seconds, the WSP returns a SOAP fault (`timeNotSufficient`), indicating that the time is insufficient for interaction.
`com.sun.identity.liberty.interaction.wspWillEnforceHttpsCheck`	Indicates whether the WSP will enforce a HTTPS `returnToURL` specified by the WSC. The Liberty Alliance Project specifications state that the value of this property is always `yes`. The `false` value is primarily meant for ease of deployment in a phased manner.
`com.sun.identity.liberty.interaction.wspWillEnforceReturnToHostEqualsRequestHost`	Indicates whether the WSP would enforce the address values of `returnToHost` and `requestHost` if they are the same. The Liberty Alliance Project specifications state that the value of this property is always `yes`. The `false` value is primarily meant for ease of deployment in a phased manner.
`com.sun.identity.liberty.interaction.htmlStyleSheetLocation`	Points to the location of the style sheet that is used to render the interaction page in HTML.
`com.sun.identity.liberty.interaction.wmlStyleSheetLocation`	Points to the location of the style sheet that is used to render the interaction page in WML.

Interaction Service API

The OpenSSO Enterprise Interaction Service includes a Java package named com.sun.identity.liberty.ws.interaction. WSCs and WSPs use the classes in this package to interact with a resource owner. The following table describes the classes.

Table 9–9 Interaction Service Classes


Class	Description
`InteractionManager`	Provides the interface and implementation for resource owner interaction.
`InteractionUtils`	Provides some utility methods related to resource owner interaction.

For more information, including methods and their syntax and parameters, see the Sun OpenSSO Enterprise 8.0 Java API Reference.

PAOS Binding

OpenSSO Enterprise 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 OpenSSO Enterprise 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 Sun OpenSSO Enterprise 8.0 Java API Reference.

Table 9–10 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.

Chapter 9 Implementing Web Services

Developing New Web Services

To Host a Custom Service

Before You Begin

To Invoke the Custom Service

Setting Up Liberty ID-WSF 1.1 Profiles

To Configure OpenSSO Enterprise to Use Liberty ID-WSF 1.1 Profiles

To Test the Liberty ID-WSF 1.1 Configuration

Common Application Programming Interfaces

Common Interfaces

com.sun.identity.liberty.ws.common Package

com.sun.identity.liberty.ws.interfaces Package

Common Security API

com.sun.identity.liberty.ws.security Package

com.sun.identity.liberty.ws.common.wsse Package

Authentication Web Service

Authentication Web Service Default Implementation

key Parameter

class Parameter

Authentication Web Service Packages

com.sun.identity.liberty.ws.authnsvc Package

com.sun.identity.liberty.ws.authnsvc.mechanism Package

com.sun.identity.liberty.ws.authnsvc.protocol Package

Access the Authentication Web Service

Data Services

Liberty Personal Profile Service

Data Services Template Packages

com.sun.identity.liberty.ws.dst Package

com.sun.identity.liberty.ws.dst.service Package

Discovery Service

Generating Security Tokens

To Configure the Discovery Service to Generate Security Tokens

Discovery Service Packages

Client APIs in com.sun.identity.liberty.ws.disco

com.sun.identity.liberty.ws.disco.plugins.DiscoEntryHandler Interface

com.sun.identity.liberty.ws.interfaces.Authorizer Interface

To Configure Discovery Service Policy Definitions

com.sun.identity.liberty.ws.interfaces.ResourceIDMapper Interface

Access the Discovery Service

SOAP Binding Service

SOAPReceiver Servlet

SOAP Binding Service Package

Interaction Service

Configuring the Interaction Service

Interaction Service API

PAOS Binding

Comparison of PAOS and SOAP

PAOS Binding API

`com.sun.identity.liberty.ws.common` Package

`com.sun.identity.liberty.ws.interfaces` Package

`com.sun.identity.liberty.ws.security` Package

`com.sun.identity.liberty.ws.common.wsse` Package

`key` Parameter

`class` Parameter

`com.sun.identity.liberty.ws.authnsvc` Package

`com.sun.identity.liberty.ws.authnsvc.mechanism` Package

`com.sun.identity.liberty.ws.authnsvc.protocol` Package

`com.sun.identity.liberty.ws.dst` Package

`com.sun.identity.liberty.ws.dst.service` Package

Client APIs in `com.sun.identity.liberty.ws.disco`

`com.sun.identity.liberty.ws.disco.plugins.DiscoEntryHandler` Interface

`com.sun.identity.liberty.ws.interfaces.Authorizer` Interface

`com.sun.identity.liberty.ws.interfaces.ResourceIDMapper` Interface

`SOAPReceiver` Servlet