This fourth part of the Sun OpenSSO Enterprise Technical Overview contains information on implementing the Web Services Stack, identity services, and web services security. It contains the following chapters:
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.
OpenSSO Enterprise provides client interfaces for authentication, authorization, session, identity management and auditing in Java, in C (C++) and in HTTP(S)/XML. These interfaces are used by web and Java EE policy agents as well as custom applications developed externally. Now, OpenSSO Enterprise also delivers web services that expose these identity functions as simple web services. This chapter contains information on the following topics:
A web service is a black-box component that can be accessed using exposed endpoints. OpenSSO Enterprise uses this concept to expose the following security and identity related functions as Identity Web Services:
authenticate (user credential verification)
authorize (an authenticated identity's access permission)
attributes (an authenticated identity's profile)
log (record and audit actions)
Identity Web Services allow developers to easily invoke these functions without any knowledge of OpenSSO Enterprise, resolving the problems of enabling web service discovery and invocation, security, privacy and ease-of-deployment. Keeping Identity Web Services simple allows an application developer to consume them by pointing an integrated development environment (IDE) to the service's URL and allowing it to generate the stub code that wraps a call to the service. Identity Web Services are supported on:
Identity Web Services does not require the Client SDK or deployment of an agent or proxy to protect a resource.
Within Identity Web Services the user enters authentication credentials using a JavaServer Pages (JSP). The user data is then forwarded to the composite application which authenticates the web service request. The application may then authorize the operation and obtain the user's profile. See Identity Web Service Styles for more information.
OpenSSO Enterprise Identity Web Services have been developed in two styles. The decision on which style to use is the initial choice when designing your application. The styles are:
The SOAP and Web Services Description Language (WSDL) style is the traditional approach preferred by the service-oriented architecture (SOA) business intelligence community. See SOAP and WSDL.
The REpresentational State Transfer (REST) style is a newer approach preferred by the Web 2.0 community. (A REST service is referred to as RESTful.) See REST.
developers.sun.com has an excellent three part article called Securing Applications with Identity Services which contains IDE configuration information and procedures.
SOAP, WSDL, and XML Schema have become the standard for exchanging XML-based messages among applications. To implement this style, the IDE must obtain the WSDL, generate the client stubs, and set up the JavaServer Pages (JSP) for the Identity Web Services. Once completed, the SOAP Identity Web Services are accessible with the following URLs:
This style may be appropriate when:
A formal contract must be established to describe the interface that the web service offers. A WSDL is needed to describe the web service interfaces including details such as messages, operations, bindings, and location.
The architecture must address complex requirements including security, financial transactions, provider trust and the like.
The architecture needs to handle asynchronous processing and invocation. The infrastructure provided by standards such as WSRM and APIs such as JAX-WS can be leveraged out of the box.
The internet is comprised of resources. Clients may access resources with a URL. When requested, a representation of the resource (an HTML page) is returned. The result of the user clicking a link on the page is that another resource is accessed (possibly an image, video, or another HTML page). Each new representation places the client into a state that is different from the previous state. Thus, the client application changes state with each accessed resource representation. REST is a design architecture in which a web service is viewed as a resource identified by a URL. The web service client then accesses it using a globally defined set of remote methods that describe the action to be performed. REST is not a standard; you can only understand it, and design web services in the REST style. REST does, though, use standards including:
Resource representations (XML, HTML, GIF, JPEG, and others)
MIME types (text/xml, text/html, image/gif, image/jpeg, and others)
RESTful services are accessed using a generic interface; in OpenSSO Enterprise it is the GET, POST, PUT, and DELETE HTTP methods. The RESTful Identity Web Service is accessible at http://host_machine.domain:8080/opensso/identity. Because these web services are exposed using the HTTP methods, they can be accessed from a browser. This style may be appropriate when:
The web services are completely stateless. A good test is to consider whether the interaction can survive a restart of the server.
Bandwidth needs to be limited. REST is particularly useful for limited-profile devices such as PDAs and mobile phones, where the XML payload must be restricted.
Aggregation into existing web sites is needed. Web services can be exposed with XML and consumed by HTML without significantly reinventing the existing web site architecture.
OpenSSO Enterprise REST interfaces currently support only username and password authentication.
In an Identity Web Service interaction, the user interacts with an application which then calls either of the Identity Web Services to authenticate and authorize the identity, create personalized services, and log the actions. When contacted at the respective URL, OpenSSO Enterprise obtains the user profile from the appropriate identity repository for authentication and the policy configuration from the appropriate configuration data store, and writes the actions to the configured log file. Figure 13–1 illustrates the components of the Identity Web Services.
OpenSSO Enterprise implements security for web services as well as a Security Token Service to issue and validate security tokens to any third party clients. The Security Token Service can be used in tandem with Web Services Security or as a stand-alone component. This chapter contains the following sections.
A web service exposes some type of functionality using a platform-independent interface. Enterprises use platform-independent interfaces as a mechanism for allowing their applications to cross network boundaries and communicate with those of their partners, customers and suppliers. Web services are accessed by sending a request to one of the service's defined endpoints but the built-in openness of the web services technologies creates security risks. The following security requirements have been identified and must be supported to insure that the communications between a web service provider (WSP) and a web service client (WSC) are not compromised.
Data integrity and confidentiality during transport
Authentication of the sending entity
Initially, securing web services communications was addressed on the transport level, relying on securing the HTTP transmissions themselves using Secure Sockets Layer (SSL). This is not adequate though when access to an application is requested through an intermediary. The solution to this is to encrypt the entire request using message level security before it leaves the WSC. In message level security, authentication and authorization information in the form of a token is contained within the SOAP header, allowing the request or response to securely pass through multiple intermediaries before reaching its intended receiver. Figure 14–1 depicts message level security.
Additionally, policy enforcement points are distributed throughout the environment and access to resources and services is mainly over HTTP.
The OpenSSO Enterprise Web Services Security functionality can be used in a variety of platforms and containers for different purposes. These can range from providing single sign-on and federation support for web applications to securing web applications using security agents deployed on the appropriate web container. Here are the web services security functions that OpenSSO Enterprise provides.
Identify and authenticate the principal.
Generate and exchange security tokens in a trusted environment.
Preserve the identity through multiple intermediaries and across domain boundaries.
Maintain privacy and integrity of identity data.
Log the outcome.
Basically, the JCP, W3C, and OASIS are developing specifications related to web services security. WS-I creates profiles that recommend what to implement from various specifications and provides direction on how to implement the specifications. The Liberty Alliance Project provides a framework for building interoperable identity services, using specifications such as WS-Security (OASIS), SOAP, Security Assertions Markup Language SAML (OASIS) and XML (W3C). The following sections briefly discuss the specifications and profiles being developed by each organization.
There are a number of web services security specifications, guidelines, and tools that have been implemented to develop these Web Services Security features for OpenSSO Enterprise. The following sections have more general information on these specifications.
Web Services Interoperability Technology (WSIT) is an open source implementation of many of the web services specifications (commonly referred to as WS-*). The project was started by Sun Microsystems, and consists of Java API that allow developers to create web service clients and services that enables operations between the Java platform and clients and servers developed with the WS-* specifications. WSIT provides implementation of the following specifications for interoperability with .NET 3.0.
WS-Reliable Messaging Policy
WS-Security 1.0 and 1.1
Web service specifications are referred to collectively as WS-* although there is neither a single managed set of specifications that this consistently refers to nor one recognized body that owns all the specifications. WS-* is a general nod to the fact that many specifications use WS as their prefix.
Sun is working closely with Microsoft to ensure interoperability of web services enterprise technologies such as message optimization, reliable messaging, and security. The initial release of the Web Services Interoperability Technologies (WSIT) is a product of this joint effort. WSIT is an implementation of a number of open web services specifications to support enterprise features such as message optimization, reliable messaging, security, bootstrapping and configuration. More information can be found in this WSIT tutorial on java.sun.com.
The WS-Security specification is now developed by the Organization for Advancement of Structured Information Standards (OASIS) after being submitted to the standards body by IBM, Microsoft, and VeriSign in 2002. The specification defines how to sign a SOAP message and describes enhancements that provide message integrity, message confidentiality, and message authentication. It also defines:
An extensible, general-purpose mechanism for associating security tokens with message content.
How to encode binary security tokens.
A framework for XML-based tokens.
How to include opaque encrypted keys.
The WS-Security specification is designed to be used together with other WS-* specifications to provide tools for secure and reliable web services transactions. For example, WS-Policy does not provide a solution for negotiating web services in and of itself; it is used in conjunction with other specifications to accommodate a wide variety of policy exchange models. WS-Trust, on the other hand, uses the secure messaging mechanisms of WS-Security to define extensions for security token exchange within different trust domains. For more information, see the Web Services Security page on the OASIS web site.
Web Services Trust Language (WS-Trust) uses the secure messaging mechanisms of WS-Security to define additional extensions for security token exchange and to enable the issuance and dissemination of credentials within different trust domains. WS-Trust is used to develop the Security Token Service. For more information, see Security Token Service.
The Liberty Alliance Project establishes open technical specifications that support a broad range of web services, driving the specifications for services such as Personal Profile Service and the Employee Profile Service. In order to build these identity web services, the Liberty Alliance Project provides a framework for identity federation and a framework for adjunct web services such as a registration service and a discovery service. For more general information on the Liberty Alliance Project, see Using the Liberty ID-FF and the Liberty Alliance Project specifications.
The Java Community Process (JCP) primarily guides the development and approval of Java technical specifications, one of which is the Java Specification Request (JSR) 196. JSR 196 is a draft of the Java Authentication Service Provider Interface for Containers that defines a standard service provider interface (SPI) with which a message level security agent can be developed for Java EE containers on either the client side or the server side.
A server side agent can be used to verify security tokens or signatures on incoming requests and extract principal data or assertions before adding them to the client security context.
A client side agent can be used to add security tokens to outgoing requests, sign messages, and interact with the trusted authority to locate targeted web service providers.
The JSR–196 SPI is structured so that the security processes can be delegated to an agent at any of four interaction points (that represent the methods of the corresponding ClientAuthModule and ServerAuthModule SPI). These point are illustrated in Figure 14–2.
When a WSC and WSP are both deployed in a Java EE web container protected by JSR–196 security agents, the initial request from the WSC is intercepted by the agent on the client side which then queries a trusted authority (for example, the Discovery Service) to retrieve the necessary authorization credentials to secure to the request. The secured request is then passed to the WSP. The agent on the provider side receives the request to validate the authorization credentials. If validation is successful, the request is exposed to the web service and a response is created using the sender's credentials and the application specific request. The response is then intercepted by the agent on the provider side to secure and return it to the WSC. Upon receiving the response, the agent on the client side validates it and dispatches it to the client browser. The JSR 196 draft specification is available at http://www.jcp.org/en/jsr/detail?id=196.
OpenSSO Enterprise can provide web services security for client applications that built using the SOAP with Attachments API for Java (SAAJ) and Java API for XML Web Services (JAX-WS). For SAAJ applications, the OpenSSO Enterprise Client SDK can be used to explicitly secure and validate the outbound and inbound messages between the WSC and WSP. For JAX-WS applications, web services security can be enforced at the web container level with container-provided security plug-ins or handlers.
The JSR–196 specification is a security plug-in SPI supported by the Sun Java System Application Server. Handlers are interceptors that can plugged into the JAX-WS 2.0 runtime environment for additional processing of inbound and outbound messages.
The following sections have more information.
The architectural strategy behind the Web Services Security framework is to model security agents on authentication and authorization SPI provided by the web container and to use a WSIT infrastructure for WS-Trust, WS-Policy and WS-I BSP security token implementations. Security agents secure web service requests and validate web service responses by inserting (or extracting) security tokens into (or out of) SOAP messages at the WSC and the WSP. This abstracts security from the application and allows customers to standardize security across multiple containers. Figure 14–3 illustrates this.
The Web Services Security framework supports the following tokens.
Tokens that can be authenticated:
Tokens that can be issued:
UserName (generated with the Security Token Service or locally at the WSC)
X509 (generated with the Security Token Service or locally at the WSC)
SAML 1.1 (generated with the Security Token Service or locally at the WSC)
SAML 2.0 (generated with the Security Token Service or locally at the WSC)
Kerberos (generated locally at the WSC)
In general, securing web services involves establishing trust between a WSC and a WSP. Towards this end, OpenSSO Enterprise provides security agents to verify (and extract data from) security tokens on incoming requests and to add security information (tokens and signatures) to outgoing responses. It also provides a Security Token Service to handle security tokens, and a number of Java interfaces. The following sections contain more information on these components.
OpenSSO Enterprise can be configured for use as a Security Token Service, as a web services security provider, and as both. Messages used to transfer security tokens between communicating web services clients and providers are exchanged with SOAP. The following use case and deployment architecture is not intended to cover all potential scenarios.
A company employee has a user account in the A identity system and wants to access an internal calendar application which invokes a remote calendar web service to provide it's features. Sufficient identity and attribute information on behalf of the user must be supplied by the internal calendar application to the remote calendar web service in a secure manner. This figure illustrates how this use case could be configured. A detailed process flow follows.
The application and web service are in the same domain and both are deployed using Sun Java System Application Server and a security agent.
The authenticated employee uses the A Portal to invoke the internal calendar application and, at some point, accesses a link requiring it to make a web service call to the remote calendar web service on behalf of the authenticated user.
The internal calendar application is acting as a WSC.
The security agent protecting the internal calendar application intercepts the outbound SOAP message, connects to a token authority (in this case, the Security Token Service), determines the security mechanisms of the WSP, obtains the appropriate security token(s), and secures the request by inserting the tokens (in the form of a SAML assertion) into the SOAP request headers.
The security agent forwards the secured SOAP message to the remote calendar web service acting as the WSP.
The security agent protecting the remote calendar web service intercepts the inbound SOAP message.
The security agent protecting the remote calendar web service retrieves and validates the security information and, upon successful validation, forwards the request to the remote calendar web service.
The calendar web service sends back a response.
The security agent protecting the remote calendar web service intercepts the outbound SOAP message and digitally signs the request with its private key.
The security agent protecting the internal calendar application intercepts the inbound signed SOAP message, validates the signature, and, upon successful validation, forwards the request to the application.
The calendar application consumes the results and presents the employee with the appropriate response.
For identity-based web services specifically (a calendar service for example), the WSP would have to trust the WSC to authenticate the user, or the WSC would have to include the user's credentials as part of the web service request. The distinguishing factor is that identity-based web services authenticate both the WSC and the user's identity. The user must be authenticated so that the WSC can send the user's token to the WSP in a SOAP security header.
Because of the use of tokens in Web Services Security, there is a need for a centralized token service; the Security Token Service serves this purpose for OpenSSO Enterprise. The Security Token Service was developed from the WS-Trust protocol which defines extensions to the WS-Security specification for issuing and exchanging security tokens and establishing and accessing the presence of trust relationships. The Security Token Service is hosted as a servlet endpoint and coordinates security based interactions between a WSC and a WSP. The Security Token Service is a standalone service that any third party client can use without implementing Web Services Security. The Security Token Service:
Issues, renews, cancels, and validates security tokens.
Allows customers to write their own plug-ins for different token implementations and for different token validations.
Provides a WS—Trust based API for client and application access. For more information, see Web Services Security and Security Token Service Interfaces.
Provides security tokens including Kerberos, Web Services-Interoperability Basic Service Profile (WS-I BSP), and Resource Access Control Facility (RACF).
When a WSC makes a call to the WSP, it first connects with the Security Token Service to determine the security mechanism and optionally obtain the security tokens expected by the WSP. (Alternately, the WSP could register its acceptable security mechanisms with the Security Token Service and, before validating the incoming SOAP request, could check with the Security Token Service to determine its security mechanisms.) Figure 14–5 illustrates the internal architecture of the Security Token Service.
When an authenticated WSC (carrying credentials that confirm either the identity of the end user or the application) requests a token for access to a WSP, the Security Token Service verifies the credentials and, in response, issues a security token that provides proof that the WSC has been authenticated. The WSC presents the security token to the WSP which verifies that the token was issued by a trusted Security Token Service. Figure 14–6 illustrates the design of the Security Token Service.
Tokens that can be authenticated with the Security Token Service:
Tokens that can be issued with the Security Token Service:
End user tokens that can be converted or validated out of the box:
OpenSSO Enterprise SSOToken to SAML 1.1 or SAML 2.0 token
SAML 1.1 or SAML 2.0 token to OpenSSO Enterprise SSOToken
Additionally, end user tokens can be converted or validated after customization. In this case, the new token is an On Behalf Of token (WS-Trust protocol element) carried in the WS-Trust request as part of the SOAP body and not as an authentication token carried as part of the SOAP header. Custom tokens can also be created and sent On Behalf Of an end user token for conversion or validation by Security Token Service. To do this, implement the com.sun.identity.wss.sts.ClientUserToken interface and put the implemented class name in AMConfig.properties on the client side and the global Security Token Service configuration using the OpenSSO console.
You can configure a WSC's agent profile to retrieve tokens from the Security Token Service (using the WS-Trust protocol) or from the Discovery Service (using the Liberty Alliance Project protocol). Based on this configuration, either the Security Token Service client API or the Discovery Service client API (both available through the Client SDK) will take over. For more information, see the Sun OpenSSO Enterprise 8.0 Administration Guide.
Security agents (or web service security providers based on the JSR-196 specification) provide message level security, and support Liberty Alliance Project security tokens, Web Services-Interoperability Basic Security Profiles (WS-I BSP) tokens, and proprietary OpenSSO Enterprise session tokens. The agents use an instance of OpenSSO Enterprise for agent configuration data storage as well as authentication decisions. Web services requests and responses are passed to the appropriate authentication module using standard Java representations based on the transmission protocol. The following security agents are currently supported.
In previous Sun documentation, this agent was referred to as an authentication agent.
The HTTP security agent protects the endpoints of a web service that uses HTTP for communication. After the HTTP agent is deployed in a web container on the WSP side, all HTTP requests for access to web services protected by it are redirected to the login and authentication URLs defined in the OpenSSO Enterprise configuration data on the WSC side. The configurable properties are:
For this release, the HTTP security agents are used primarily for bootstrapping. Future releases will protect web applications.
Figure 14–7 illustrates the interactions described in the procedure below it.
A WSC (user with a browser) makes a request to access a web service protected by an HTTP security agent.
The security agent intercepts the request and redirects it (via the browser) to OpenSSO Enterprise for authentication.
Upon successful authentication, a response is returned to the web service, carrying a token as part of the Java EE Subject.
This token is used to bootstrap the appropriate Liberty ID-WSF security profile. If the response is successfully authenticated, the request is granted.
The functionality of the HTTP security agent is similar to that of the Java EE policy agent when used in SSO ONLY mode. This is a non restrictive mode that uses only the OpenSSO Enterprise Authentication Service to authenticate users attempting access. For more information on Java EE policy agents, see the Sun OpenSSO Enterprise Policy Agent 3.0 User’s Guide for J2EE Agents.
The SOAP security agent secures SOAP messages between a WSC and a WSP. It can be configured for use as a security provider on either the WSC server or the WSP server. This initial release encapsulates the Liberty Identity Web Services Framework (Liberty ID-WSF) SOAP Binding Specification (as implemented by OpenSSO Enterprise) and supports the following tokens.
In a scenario where security is enabled using Liberty Alliance Project tokens, the HTTP client requests (via the WSC) access to a service. The HTTP security agent redirects the request to the OpenSSO Enterprise Authentication Service for authentication and to determine the security mechanism registered by the WSP and obtain the security tokens expected. After a successful authentication, the WSC provides a SOAP body while the SOAP security agent on the WSC side inserts the security header and a token. The message is then signed before the request is sent to the WSP.
When received by the SOAP security agent on the WSP side, the signature and security token in the SOAP request are verified before forwarding the request on to the WSP itself. The WSP then processes it and returns a response, signed by the SOAP security agent on the WSP side, back to the WSC. The SOAP security agent on the WSC side then verifies the signature before forwarding the response on to the WSC. Figure 14–8 illustrates these interactions.
The following Liberty Alliance Project security tokens are supported in this release:
A secure web service uses a PKI (public key infrastructure) in which the WSC supplies a public key as the means for identifying the requester and accomplishing authentication with the web service provider. Authentication with the web service provider using processing rules defined by the Liberty Alliance Project.
A secure web service uses the Security Assertion Markup Language (SAML) SAML Bearer token confirmation method. The WSC supplies a SAML assertion with public key information as the means for authenticating the requester to the web service provider. A second signature binds the assertion to the SOAP message This is accomplished using processing rules defined by the Liberty Alliance Project
A secure web service uses the SAML holder-of-key confirmation method. The WSC adds a SAML assertion and a digital signature to a SOAP header. A sender certificate or public key is also provided with the signature. This is accomplished using processing rules defined by the Liberty Alliance Project.
In a scenario where security is enabled using Web Services-Interoperability Basic Security Profile (WS-I BSP) tokens, the HTTP client (browser) requests (via the WSC) access to a service. The SOAP security agent redirects the request to the OpenSSO Enterprise Authentication Service for authentication and to determine the security mechanism registered by the WSP and obtain the expected security tokens. After a successful authentication, the WSC provides a SOAP body while the SOAP security agent on the WSC side inserts the security header and a token. The message is then signed before the request is sent to the WSP.
When received by the SOAP security agent on the WSP side, the signature and security token in the SOAP request are verified before forwarding the request on to the WSP itself. The WSP then processes it and returns a response, signed by the SOAP security agent on the WSP side, back to the WSC. The SOAP security agent on the WSC side then verifies the signature before forwarding the response on to the WSC. Figure 14–9 illustrates the interactions as described.
The following WS-I BSP security tokens are supported in this release.
A secure web service requires a user name, password and, optionally, a signed the request. The web service consumer supplies a username token as the means for identifying the requester and a password, shared secret, or password equivalent to authenticate the identity to the web service provider.
A secure web service uses a PKI (public key infrastructure) in which the web service consumer supplies a public key as the means for identifying the requester and accomplishing authentication with to the web service provider.
A secure web service uses the SAML holder-of-key confirmation method. The web service consumer supplies a SAML assertion with public key information as the means for authenticating the requester to the web service provider. A second signature binds the assertion to the SOAP payload.
A secure web service uses the SAML sender-vouches confirmation method. The web service consumer adds a SAML assertion and a digital signature to a SOAP header. A sender certificate or public key is also provided with the signature.
The main dependencies and interactions of the Security Token Service and security agents in a web services security scenario are with the interfaces of the OpenSSO Enterprise Client SDK. This includes the following:
Security agents bootstrap the Security Token Service or the Liberty Alliance Project Discovery Service using the Client SDK.
The OpenSSO Enterprise Discovery Service can be leveraged with the Client SDK so consumers can continue to use it's end point for web services security token utilities, resource offerings and WSP end points. A configuration on the client side would choose either the WS-Trust orLiberty Alliance Project protocol for web services security token management.
The Client SDK implements XML signing and XML encryption for SOAP requests and responses.
The Client SDK generates the proprietary SSOToken based on security token credentials provided to the WSP. It also sets the SSOToken into the container Subject for further authorization processing.
The Client SDK implements caching for the security tokens generated by the Security Token Service or the Liberty Alliance Project Discovery Service. This improves performance when requesting security tokens.
The Client SDK implements complete processing (including token insertion, extraction and validation) of SOAP requests and responses.
The Web Services Security framework and the Security Token Service include the following Java packages as part of the Client SDK
com.sun.identity.wss.provider provides administrative interfaces for configuration of the WSC and WSP with their respective security mechanisms and Security Token Service configuration. They are called by the security agent during run time, and also by applications that would like to secure messages. On the WSC side, they are called to secure the web service request and to validate any response from the WSP. Similarly, there are interfaces for this functionality on the WSP side. When a WSC is configured to communicate with the Security Token Service, security mechanisms and security tokens would be obtained from it. When a WSP is configured to communicate with the Security Token Service, its resource offering would be published at the Security Token Service.
A WSC and a WSP can be associated with more than one Security Token Service.
com.sun.identity.wss.security provides classes that create, manage and represent security tokens and their processing. This SPI can plug in new security token implementations to the Security Token Service.
com.sun.identity.wss.sts contains classes for getting security tokens from the Security Token Service end point and converting an end user token from one format to another (for instance, converting to the OpenSSO Enterprise proprietary SSOToken in order to validate it against the Authentication Service and Policy Service). It also contains an SPI to issue different security tokens, attribute provider and authorization provider.