test

Sun Java System Access Manager 7.1 Federation and SAML Administration Guide

Discovery Service Overview

All web services are defined by a Web Services Description Language (WSDL) file that describes the type of data the service contains, the available ways said data can be exchanged, the operations that can be performed using the data, a protocol that can be used to perform the operations, and a URL (or endpoint) for access to the service. Additionally, the WSDL file itself is assigned a unique resource identifier (URI) that is used to locate it. The file is then published and the URI is placed in a Universal Description, Discovery and Integration (UDDI) repository so it can be found by potential users. Thus, the web service can now be discovered. According to the Web Services Glossary, discovery of a web service is the act of locating a WSDL file for it. Typically, there are one or more web services on a network so, a discovery service is required to keep track of them.

Access Manager implements the Liberty ID-WSF Discovery Service Specification for its Discovery Service. The Discovery Service is a registry for identity-based web services. An identity-based web service presents an interface to access a type of data that is considered a part of a principal's online identity. For example, a payment web service might contain an individual's credit card information and would allow payments to be made using this information. When a web service consumer (WSC) queries the Discovery Service for a web service provider that allows access to a particular user's credit card information, the Discovery Service matches the properties in the request against the properties of it's registered services and returns the appropriate resource offering.

Note –

A resource offering defines an association between a type of identity data and a URI to the WSDL definition that provides information about obtaining access to the data. For more information on resource offerings, see Storing Resource Offerings.

This overview contains the following sections:

Discovery Service WSDL

A WSDL document is written in the eXtensible Markup Language (XML) and describes a web service. It specifies the location of the service and the operations the service exposes.

Note –

The WSDL specification can be found at http://www.w3.org/TR/wsdl.

The portType property in the Liberty ID-WSF Discovery Service WSDL file defines the Discovery Service operations.

Following is a reproduction of liberty-idwsf-disco-svc-v1.2.wsdl, the Liberty ID-WSF Discovery Service WSDL file.

Example 8–1 Abstract WSDL for Liberty ID-WSF Discovery Service Specification


<?xml version="1.0"?>
<definitions name="disco-svc" 
  targetNamespace="urn:liberty:disco:2003-08" 
  xmlns:typens="urn:liberty:disco:2003-08" 
  xmlns="http://schemas.xmlsoap.org/wsdl/" 
  xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
  xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" 
  xmlns:sb="urn:liberty:sb:2003-08"
  xmlns:disco="urn:liberty:disco:2003-08">

  <!-- Abstract WSDL for Liberty Discovery Service Specification -->

      <xsd:documentation>

        XML Schema from Liberty Discovery Service Specification.

        ### NOTICE ###

        Copyright (c) 2004-2005 Liberty Alliance participants, see
        http://www.projectliberty.org/specs/idwsf_1_1_copyrights.php

      </xsd:documentation>

  <types>
    <xsd:schema>
      <xsd:import schemaLocation="liberty-idwsf-disco-svc-exts-v1.2.xsd"/>
      <xsd:import schemaLocation="liberty-idwsf-soap-binding-exts-v1.2.xsd"/>
      <xsd:import schemaLocation="liberty-idwsf-soap-binding-v1.2.xsd"/>
    </xsd:schema>
  </types>

  <message name="Query">
    <part name="body" element="disco:Query"/>
  </message>

  <message name="QueryResponse">
    <part name="body" element="disco:QueryResponse"/>
  </message>

  <message name="Modify">
    <part name="body" element="disco:Modify"/>
  </message>

  <message name="ModifyResponse">
    <part name="body" element="disco:ModifyResponse"/>
  </message>

  <message name="CorrelationHeader">
    <part name="Correlation" element="typens:Correlation"/>
  </message>

  <portType name="DiscoveryPort">

    <operation name="DiscoveryLookup">
      <input message="typens:Query"/>
      <output message="typens:QueryResponse"/>
    </operation>

    <operation name="DiscoveryUpdate">
      <input message="typens:Modify"/>
      <output message="typens:ModifyResponse"/>
    </operation>

  </portType>

  <!--
  An example of a binding and service that can be used with this
  abstract service description is provided below.
  -->

  <binding name="DiscoveryBinding" type="typens:DiscoveryPort">

    <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
    
    <operation name="DiscoveryLookup">
      <soap:operation soapAction="http://example.com/DiscoveryLookup"/>

      <input>
        <soap:header message="typens:CorrelationHeader" part="Correlation" use="literal"/>
        <soap:body use="literal"/>
      </input>

      <output>
        <soap:header message="typens:CorrelationHeader" part="Correlation" use="literal"/>      
        <soap:body use="literal"/>
      </output>

    </operation>
    
    <operation name="DiscoveryUpdate">
      <soap:operation soapAction="http://example.com/DiscoveryUpdate"/>

      <input>
        <soap:header message="typens:CorrelationHeader" part="Correlation" use="literal"/>
        <soap:body use="literal"/>
      </input>

      <output>
        <soap:header message="typens:CorrelationHeader" part="Correlation" use="literal"/>
        <soap:body use="literal"/>
      </output>

    </operation>

  </binding>

  <service name="DiscoveryService">

    <port name="DiscoveryPort" binding="typens:DiscoveryBinding">
      
      <!-- Modify with the REAL SOAP endpoint -->
      
      <soap:address location="http://example.com/discovery"/>
      
    </port>

  </service>

</definitions>

amDisco XML Service Files

The Discovery Service is defined by the XML service file amDisco.xml. This file defines the attributes for the Discovery Service. All of the attributes in the Discovery Service can be managed through either the Access Manager Console or this file.

Note –

For more information about service files, see the Sun Java System Access Manager 7.1 Administration Guide. For more information about Discovery Service attributes, see Discovery Service Attributes.

A second XML file, amDisco_add.xml is in /AccessManager-base/SUNWam/upgrade/services50_sunIdentityServerDiscoveryService/10_20/data. This file is used for upgrading Identity Server 6.2 to Access Manager 7.1. It lists the changes to the amDisco.xml file since the earlier release.

Discovery Service Architecture

Java applications use the client API (discussed in Client APIs in com.sun.identity.liberty.ws.disco) to form requests sent to the Discovery Service and to parse the responses received back from it. Requests are initially received by a SOAP receiver which constructs the SOAP message that incorporates the client request.

Note –

The SOAP Binding Service defines how to send and receive messages using SOAP, an XML-based messaging protocol. The SOAP receiver is a servlet that constructs the message using these definitions. For more information, see Chapter 9, SOAP Binding Service.

The SOAP message is then routed to the Discovery Service which parses the resource identifier from it. This identifier is used to find a matching user distinguished name (DN). The necessary information is then culled from the corresponding profile, a response is generated, and the response is sent back to the SOAP receiver. The SOAP receiver then sends the response back to the client. The following figure illustrates this architecture. The Discovery Service Process has more information on how the Discovery Service works.

Figure 8–1 Discovery Service Architecture

Illustration depicting the architecture of the Discovery Service.