In OpenSSO Enterprise, the Federation Services framework enables the secure exchange of authentication and authorization information by providing an interface for creating, modifying, and deleting circles of trust and configuring service providers and identity providers (both remote and hosted types) as entity providers. The implemented Web Services Stack defines a supporting framework for these Federation Services. This chapter contains information on the Web Services Stack.
Web services are distributed applications developed using open technologies such as eXtensible Markup Language (XML), SOAP, and HyperText Transfer Protocol (HTTP). Enterprises use these technologies as a mechanism for allowing their applications to cross network boundaries and communicate with those of their partners, customers and suppliers. Towards this end, OpenSSO Enterprise implements the Liberty Alliance Project Identity-Web Service Framework (Liberty ID-WSF) 1.1 specifications, designed to operate in concert with the Liberty Alliance Project Identity-Federation Framework (Liberty ID-FF). The implementation of the Liberty ID-WSF 1.1 specifications uses a servlet framework into which identity-based web services can be plugged and leveraged for security. Tools and API are also provided for identity providers to develop new web services and for service providers to consume both default and custom web services. Furthermore, OpenSSO Enterprise provides the necessary hooks to integrate an existing enterprise infrastructure with the Liberty Alliance Project—based infrastructure. Figure 12–1 illustrates the design of the Liberty ID-WSF framework.
Any custom web service developed with the Liberty ID-WSF must register with the SOAP Binding Service which provides validation of SOAP messages and generates the OpenSSO Enterprise session token for client authorization. Bootstrapping of the Web Services Stack is accomplished by using the Discovery Service to find a resource offering for an authenticated user. (A resource offering defines an association between a type of identity data and a URI to a WSDL file that provides information about obtaining access to the data. The web service provider must also register the web service's resource offering with the Discovery Service before offering services.) OpenSSO Enterprise supports bootstrapping using SAML v2, Liberty ID-FF, or the Authentication Web Service.
The Web Services Stack defines an architecture in which SOAP over HTTP(S) is used as the transport layer protocol. As well, custom web services can be plugged into it. All web services in OpenSSO Enterprise (whether proprietary or custom) are front-ended by a servlet endpoint called the SOAPReceiver. The SOAPReceiver validates digital signatures or encryptions from incoming SOAP request messages and authenticates the remote web services client. From a high-level, a user requests a specific service which passes the request to the SOAPReceiver which, in turn, passes it to the Liberty Personal Profile Service (or a custom web service). Figure 12–2 illustrates the architecture of the Web Services Stack and how a web service client (WSC) communicates with the web service provider (WSP).
Figure 12–3 provides a high-level view of the process between the various components in the Web Services Stack. In this example:
The web browser represents a user.
The service provider also acts as a WSC, invoking a web service on behalf of the user. The service provider relies on the identity provider for authentication.
The identity provider acts as an authentication provider by authenticating the user. It also acts as a trusted authority, issuing security tokens through the Discovery Service.
The WSP serves requests from web services clients such as the Liberty Personal Profile Service.
The process assumes that the user, the identity provider, and the service provider have already been federated.
The user attempts to access a resource hosted on the service provider server.
The service provider redirects the user to the identity provider for authentication.
The identity provider authenticates the user successfully and sends the single sign-on assertion to the requesting service provider.
The service provider verifies the assertion and the user is issued a session token.
The service provider redirects the user to the requested resource.
The user requests access to another service hosted on the WSC server.
For example, it might need that value of an attribute from the user’s Liberty Personal Profile Service.
The WSC sends a query to the Discovery Service to determine where the user’s Liberty Personal Profile Service instance is hosted.
The WSC bootstraps the Discovery Service with the resource offering from the assertion obtained earlier.
The Discovery Service returns a response to the WSC containing the endpoint for the user’s Liberty Personal Profile Service instance and a security token that the WSC can use to access it.
The WSC sends a query to the Liberty Personal Profile Service instance.
The query asks for the user’s personal profile attributes, such as home phone number. The required authentication mechanism specified in the Liberty Personal Profile Service resource offering must be followed.
The Liberty Personal Profile Service instance authenticates and validates authorization for the requested user or the WSC, or both.
If user interaction is required for some attributes, the Interaction Service will be invoked to query the user for consents or for attribute values. The Liberty Personal Profile Service instance returns a response to the WSC after collecting all required data.
The WSC processes the Liberty Personal Profile Service response, and renders the service pages containing the information.
For detailed information about all these components, see the Sun OpenSSO Enterprise 8.0 Administration Guide.
The Web Services Stack authenticates the user and obtains bootstrapping information for the requested application. For client applications accessed from a desktop, the user can be authenticated using the Authentication Web Service. (For example, a Java® Swing client application can authenticate the user, obtain profile data, and pass it on for online transactions.) For browser-based applications, the user can be authenticated using the SAML v2 single sign-on profiles or Liberty ID-FF. The following sections describe how the Web Services Stack can be implemented.
For more information on configuring the Web Services Stack, see Chapter 9, Implementing Web Services, in Sun OpenSSO Enterprise 8.0 Developer’s Guide and Chapter 9, Identity Web Services, in Sun OpenSSO Enterprise 8.0 Administration Guide.
OpenSSO Enterprise can be a deployed as a service provider or an identity provider and provide identity authentication using the SAML v2 or Liberty ID-FF protocols, implemented by the Federation Services, to bootstrap into the Web Services Stack framework. The SAML v2 process is illustrated in Figure 12–4.
OpenSSO Enterprise can also provide identity authentication using the Authentication Web Service to bootstrap into the Web Services Stack framework. This process is illustrated in Figure 12–5.
Information on the services implemented in the Web Services Stack is in the following sections:
The Authentication Web Service is for provider-to-provider authentication. SOAP defines an XML-based messaging paradigm, but not security mechanisms for message protection; particularly, they do not describe user authentication. To secure SOAP messages, the 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. Upon successful authentication, the final Simple Authentication and Security Layer (SASL) response contains the resource offering for the Discovery Service.
The Authentication Web Service is configured using the XML service file amAuthnSvc.xml and can be managed using the OpenSSO Enterprise console or this XML file. Additional administration information can be found in the Sun OpenSSO Enterprise 8.0 Administration Guide.
The following sections contain more general information.
The exchange of authentication information between a web service consumer (WSC) and web service provider (WSP) is accomplished using SOAP-bound messages. The messages are a series of client requests and server responses specific to the defined SASL mechanism (or mode of authentication). The authentication exchange can involve an arbitrary number of round trips, dictated by the particular SASL mechanism employed. The WSC might have knowledge of the supported SASL mechanisms, or it might send the server its own list of mechanisms and allow the server to choose one. (The list of supported mechanisms can be found at SASL Mechanisms.) After receiving a request for authentication (or any response from the WSC), the WSP may issue additional challenges or indicate authentication failure or success. The sequence between the WSC and the Authentication Web Service (a WSP) is as follows.
The authentication exchange begins when a WSC sends a SASL authentication request to the Authentication Web Service on behalf of a principal. The request message contains an identifier for the principal and indicates one or more SASL mechanisms from which the service can choose.
The Authentication Web Service responds by asserting the method to use and, if applicable, initiating a challenge.
If the Authentication Web Service does not support any of the cited methods, it responds by aborting the exchange.
The WSC responds with the necessary credentials for the chosen method of authentication.
The Authentication Web Service replies by approving or denying the authentication. If approved, the response includes the credentials the WSC needs to invoke other web services, such as the Discovery Service.
The Authentication Web Service includes the following Java programming packages:
com.sun.identity.liberty.ws.authnsvc is a client API for external Java applications to send SASL requests and receive SASL responses.
com.sun.identity.liberty.ws.authnsvc.mechanism defines an interface to handle different SASL mechanisms.
com.sun.identity.liberty.ws.authnsvc.protocol contains classes that represent the SASL request and response.
Together, the packages are used to initiate the authentication process and communicate authentication credentials to the Authentication Web Service. For more information, see the Sun OpenSSO Enterprise 8.0 Java API Reference and the Sun OpenSSO Enterprise 8.0 Developer’s Guide.
The Authentication Web Service is not to be confused with the proprietary OpenSSO Enterprise Authentication Service. Architecturally, the Authentication Web Service sits on top of the OpenSSO Enterprise Authentication Service and the Web Services Stack framework. You might use the Authentication Web Service if you are a service provider and want to use a standards-based mechanism to authenticate users. Following are two use cases where the Authentication Web Service is preferable to the proprietary OpenSSO Enterprise Authentication Service:
A service provider relies on a remote identity provider (not necessarily using OpenSSO Enterprise) for authentication.
An enterprise in a service-oriented architecture (SOA) environment wants to use non-proprietary mechanisms to authenticate users and web services clients before accessing a protected web service.
In addition to providing an authentication service to verify credentials (for example, user ID and password), the Authentication Web Service provides the WSC with bootstrap information that contains the endpoint and credentials needed to access the Discovery Service. The WSC can ignore the bootstrap or use it to access other web services, such as the authenticated user's personal profile or calendar.
An authenticated enterprise might also use the bootstrap information to access a partner in a business-to-business environment.
Following is a scenario that shows how the Authentication Web Service interacts with the OpenSSO Enterprise Authentication Service. The WSC delegates all authentication to the identity provider and prefers PLAIN authentication which accepts a user identifier and password.
The user attempts access to a service provider (not necessarily hosted by OpenSSO Enterprise).
When the service provider (acting as a WSC) finds that the user is not authenticated, it invokes the identity provider Authentication Web Service by sending a SOAP request.
It is assumed that the identity provider is hosted by OpenSSO Enterprise where the OpenSSO Enterprise Authentication Service is configured for Certificate and LDAP authentication and the Authentication Web Service has mapped LDAP to its own PLAIN authentication mechanism)
After inspecting its configuration, the Authentication Web Service sends back a response indicating that it supports Certificate and PLAIN authentication.
The service provider decides on PLAIN authentication and prompts the user for an identifier and password.
The service provider receives the user identifier and password and sends it to the identity provider.
The identity provider passes the credentials to the locally hosted LDAP Authentication module using the proprietary OpenSSO Enterprise Authentication Service Java API.
The LDAP Authentication module verifies the credentials by accessing the user's personal profile (hosted by a third-party product).
The Authentication Web Service is notified of the verification and sends a response to the service provider indicating successful authentication. If configured to do so, it also includes bootstrap information formatted using XML and containing the Discovery Service endpoint and a token to invoke it.
The service provider parses the response, verifies that it is a successful authentication, and provides the service to the user.
At some point the service provider might need to access the user's personal profile. To do this, it will use the bootstrap information received during this process to contact the Discovery Service and find where the profile is stored. The Discovery Service returns a resource offering (containing a token and the location of an endpoint), and the service provider uses that to invoke the Liberty Personal Profile Service.
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 in a Universal Description, Discovery and Integration (UDDI) repository. 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. OpenSSO Enterprise implements the Liberty ID-WSF Discovery Service Specification for its Discovery Service. When a WSC queries the Discovery Service for a WSP that allows access to a particular user's credit card information, the Discovery Service matches the properties in the request against the properties of its registered services and returns the appropriate resource offering (which defines an association between a type of identity data and a URI to the WSDL definition for obtaining access to the data.)
The Discovery Service is configured using the XML service file amDisco.xml and can be managed using the OpenSSO Enterprise console or this XML file. Additional administration information can be found in the Sun OpenSSO Enterprise 8.0 Administration Guide.
The following sections contain additional information on the Discovery Service.
Figure 12–6 provides an overview of the interactions between the parties in a web services environment using the Discovery Service. In this scenario, the identity provider hosts the Discovery Service and the process assumes that the Discovery Service is not generating security tokens.
The user logs in to an identity provider, is authenticated, and completes the federation process, enabling single sign-on with other members of the circle of trust. More specifically:
Within a browser, the user types the URL for a service provider.
The service provider collects the user’s credentials and redirects the information to the identity provider for authentication.
If the credentials are verified, the user is authenticated.
Assuming the identity provider is the center of a circle of trust, it will notify the authenticated user of the option to federate any local identities created with circle of trust member organizations. The user would then accept or decline this invitation to federate. If the user accepts this option to federate, single sign-on is enabled. By accepting the invitation, the user will be given the option to federate to a member organization’s web site at each login.
After authentication, the user now requests access to services hosted by another service provider in the circle of trust.
The service provider, acting as a WSC, sends a DiscoveryLookup query to the Discovery Service looking for a pointer to the user's identity provider.
The service provider is able to bootstrap the Discovery Service using the end point reference culled from the authentication statement.
The Discovery Service returns a DiscoveryLookup response to the service provider that points to the instance of the requested identity provider.
The response contains the resource offering for the user’s Liberty Personal Profile Service.
The service provider then sends a query (using the Data Services Template Specification) to the Liberty Personal Profile Service.
The required authentication mechanism specified in the Liberty Personal Profile Service resource offering must be followed.
The Liberty Personal Profile Service authenticates and validates authorization, or policy, or both for the requested user and service provider, and returns a Data Services Template response.
If user interaction is required for some attributes, the Interaction Service will be invoked to query the user for consents or attribute values. The Data Services Template would then be returned after all required data is collected.
The service provider processes the Liberty Personal Profile Service response and renders HTML pages based on the original request and user authorization.
A user's actual account information is not exchanged during federation. Thus, the identifier displayed on each provider site will be based on the respective local identity profile.
Remote Java applications use the Client SDK to form requests sent to the Discovery Service and to parse the responses received back from it. Requests are initially received by the SOAPReceiver, a servlet which constructs the SOAP message that incorporates the client request.
The SOAP Binding Service defines how to send and receive messages using SOAP, an XML-based messaging protocol. For more information, see SOAP Binding Service in Sun OpenSSO Enterprise 8.0 Administration Guide.
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 returned to the SOAPReceiver which sends the response back to the client. Figure 12–7 illustrates this architecture.
The Discovery Service includes the following Java programming packages:
com.sun.identity.liberty.ws.disco is a client API that provides interfaces to communicate with the Discovery Service.
com.sun.identity.liberty.ws.disco.plugins defines an interface that can be used to develop plug-ins. The package also contains some default plug-ins.
com.sun.identity.liberty.ws.interfaces contains 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.
The Web Services Stack uses SOAP messages to convey identity data between providers. OpenSSO Enterprise has implemented the Liberty ID-WSF SOAP Binding Specification (Liberty ID-WSF-SBS) as the method of transport for this purpose. The specification defines SOAP as the binding to HTTP, which is itself layered onto the TCP/IP stack. The SOAP Binding Service is a set of Java API used by the developer to send and receive SOAP messages.
The SOAP Binding Service is configured using the XML service file amSOAPBinding.xml and can be managed using the OpenSSO Enterprise console or this XML file. Additional administration information can be found in the Sun OpenSSO Enterprise 8.0 Administration Guide.
The following sections contain additional information on the SOAP Binding Service.
The following sections contain information on some programming components of the SOAP Binding Service.
The SOAPReceiver servlet receives a Message object from a 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.
com.sun.identity.liberty.ws.soapbinding.RequestHandler is an interface that must be implemented on the server side by any Liberty-based web service using the SOAP Binding Service. For more information, see the Sun OpenSSO Enterprise 8.0 Java API Reference and the Sun OpenSSO Enterprise 8.0 Developer’s Guide.
In the SOAP Binding Service process, an identity service invokes the Message class (contained in the Client SDK) to construct a request. (As clients of the SOAP Binding Service, the Discovery Service, the Liberty Personal Profile Service (and the sample Employee Profile Service), and the Authentication Web Service all use the SOAP Binding Service client-side API.) The Message object will contain any default or non-default SOAP headers as well as the SOAP body containing the request(s). Once generated, the WSC invokes the sendRequest method and sends the Message object to the SOAPReceiver which receives the Message, verifies the signature, and constructs its own Message object. The SOAPReceiver then invokes the appropriate Request Handler class to send this second message to the corresponding service for a response.
The web service processes the second message, generates a response, and sends that response back to the SOAPReceiver which, in turn, returns the response back to the WSC for processing.
Before invoking a corresponding service, the SOAP framework might also do the following:
Authenticate the sender identity to verify the credentials of a WSC peer, probably by verifying its client certificate.
Authenticate the invoking identity to verify the credentials of a WSC on behalf of a user to verify whether the user has been authenticated. This depends on the security authentication profile.
Granular authorization to authorize the WSC before processing a service request.
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. For more information, see the Sun OpenSSO Enterprise 8.0 Java API Reference and the Sun OpenSSO Enterprise 8.0 Developer’s Guide.
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 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 identity profiles exposed by a data service. The Liberty ID-Service Interface Specification Personal Profile Service Specification (Liberty ID-SIS-PP) describes a data service that provides an identity’s basic profile information, such as full name, contact details, and financial information. This data service is intended to be the least common denominator for holding consumer-based information about a principal. OpenSSO Enterprise has implemented these specifications and developed the Liberty Personal Profile Service which can be queried for identity data and its attributes can be updated.
The Liberty Personal Profile Service is configured using the XML service file amLibertyPersonalProfile.xml and can be managed using the OpenSSO Enterprise console or this XML file. Additional administration information can be found in the Sun OpenSSO Enterprise 8.0 Administration Guide.
The following sections contain additional information on the Liberty Personal Profile Service.
The Liberty ID-WSF-DST specifies a base layer that can be extended by any instance of a data service. An example of a data service is an identity service, such as an online corporate directory. When you want to contact a colleague, you conduct a search based on the individual’s name, and the data service returns information associated with that person's identity. The information might include the individual’s office location and phone number, as well as job title or department name. For proper implementation, all data services must be built on top of the Liberty ID-WSF-DST because it provides the data model and message interfaces. Figure 12–8 illustrates how OpenSSO Enterprise uses the Liberty ID-WSF-DST as the framework for the Liberty Personal Profile Service and other custom data services.
For more information on the data services specification, see the Liberty ID-WSF Data Services Template Specification. For more information on the personal profile specifications, see the Liberty ID-SIS Personal Profile Service Specification.
The invocation of a personal profile begins when a WSC posts a query or a modify request to the Liberty Personal Profile Service on behalf of a user. Figure 12–9 illustrates the invocation process of the Liberty Personal Profile Service.
A WSC uses the Data Services Template API uses SOAP to post a query or a modify request to the Liberty Personal Profile Service.
The SOAP request is received by the SOAPReceiver servlet provided by the SOAP Binding Service.
The SOAPReceiver invokes either the Discovery Service, the Authentication Web Service, or the Liberty Personal Profile Service, depending on the service key transmitted as part of the URL. The SOAP Binding Service might also authenticate the client identity. For more information, see SOAPReceiver Servlet.
The Liberty Personal Profile Service implements the DSTRequestHandler to process the request.
The request is processed based on the type (query or modify) and the query expression. Processing might entail the authorization of a WSC using the OpenSSO Enterprise Policy Service, or it might entail using the Interaction Service for interacting with the user before sending data to the WSC.
The Liberty Personal Profile Service builds a service response, adds credentials (if they are required), and sends the response back to the WSC.
For a response to a query request, the Liberty Personal Profile Service builds a personal profile container (as defined by the specification). It is formatted in XML and based on the Query Select expression. The Liberty Personal Profile Service attribute values are extracted from the data store by making use of the attribute mapper. The attribute mapper is defined by the XML service file, and the attribute values will be used while building the XML container. The Liberty Personal Profile Service then applies xpath queries on the XML and provides us with the resultant XML data node.
For a response to a modify request, the Liberty Personal Profile Service parses the Modifiable Select expression and updates the new data from the new data node in the request.
For initial access, 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 the resource offering for that service. For more information, see the Sun OpenSSO Enterprise 8.0 Administration Guide.
OpenSSO Enterprise data services are built using a Java package called com.sun.identity.liberty.ws.dst. OpenSSO Enterprise provides this package for developing custom services based on the Liberty ID-WSF-DST. Additional information about these interfaces can be found in the Sun OpenSSO Enterprise 8.0 Java API Reference.
OpenSSO Enterprise contains two packages based on the Liberty ID-WSF-DST. They are:
com.sun.identity.liberty.ws.dst provides classes for the Client SDK.
com.sun.identity.liberty.ws.dst.service provides a handler class that can be used by any data service that is built using the Liberty 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.