test

Sun OpenSSO Enterprise 8.0 Technical Overview

Part IV The Web Services Stack, Identity Services, and Web Services Security

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:

Chapter 12 Accessing the Web Services Stack

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.

About 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.

Figure 12–1 Web Services Stack Design

Design of Web Services Stack in OpenSSO Enterprise

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.

Web Services Stack Architecture

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–2 Web Services Stack Architecture

This figure illustrates the Web Services Stack architecture in OpenSSO Enterprise.

Web Services Stack Process

Figure 12–3 provides a high-level view of the process between the various components in the Web Services Stack. In this example:

Figure 12–3 Web Services Stack Process

Illustration depicting the web services stack process.

  1. The user attempts to access a resource hosted on the service provider server.

  2. The service provider redirects the user to the identity provider for authentication.

  3. The identity provider authenticates the user successfully and sends the single sign-on assertion to the requesting service provider.

  4. The service provider verifies the assertion and the user is issued a session token.

  5. The service provider redirects the user to the requested resource.

  6. 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.

  7. 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.

  8. 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.

  9. 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.

  10. 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.

  11. 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.

Using the Web Services Stack

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.

With SAML v2 or Liberty ID-FF

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.

Figure 12–4 Web Services Stack Using SAML v2

Web Services Stack using SAML v2

With the Authentication Web Service

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.

Figure 12–5 Web Services Stack Using Authentication Web Service

Web Services Stack using Authentication Web Service

Implemented Services

Information on the services implemented in the Web Services Stack is in the following sections:

Additional information can be found in the Sun OpenSSO Enterprise 8.0 Administration Guide and the Sun OpenSSO Enterprise 8.0 Developer’s Guide.

Authentication Web Service

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.

Note –

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.

Authentication Web Service Process

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.

  1. 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.

  2. The Authentication Web Service responds by asserting the method to use and, if applicable, initiating a challenge.

    Note –

    If the Authentication Web Service does not support any of the cited methods, it responds by aborting the exchange.

  3. The WSC responds with the necessary credentials for the chosen method of authentication.

  4. 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.

Authentication Web Service API

The Authentication Web Service includes the following Java programming packages:

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.

Which Authentication Service to Use?

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:

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.

Note –

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.

  1. The user attempts access to a service provider (not necessarily hosted by OpenSSO Enterprise).

  2. 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.

    Note –

    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)

  3. After inspecting its configuration, the Authentication Web Service sends back a response indicating that it supports Certificate and PLAIN authentication.

  4. The service provider decides on PLAIN authentication and prompts the user for an identifier and password.

  5. The service provider receives the user identifier and password and sends it to the identity provider.

  6. The identity provider passes the credentials to the locally hosted LDAP Authentication module using the proprietary OpenSSO Enterprise Authentication Service Java API.

  7. The LDAP Authentication module verifies the credentials by accessing the user's personal profile (hosted by a third-party product).

  8. 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.

  9. 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.

Discovery 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.)

Note –

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.

Discovery Service Process

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.

Figure 12–6 Discovery Service Process

Discovery Service process

  1. 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:

    1. Within a browser, the user types the URL for a service provider.

    2. The service provider collects the user’s credentials and redirects the information to the identity provider for authentication.

    3. If the credentials are verified, the user is authenticated.

    4. 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.

  2. After authentication, the user now requests access to services hosted by another service provider in the circle of trust.

  3. 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.

  4. 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.

  5. 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.

  6. 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.

  7. 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.

Discovery Service Architecture

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.

Note –

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.

Figure 12–7 Discovery Service Architecture

Illustration depicting the architecture of the Discovery Service.

Discovery Service API

The Discovery Service includes the following Java programming packages:

For more information, see the Sun OpenSSO Enterprise 8.0 Java API Reference and the Sun OpenSSO Enterprise 8.0 Developer’s Guide.

SOAP Binding 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.

Note –

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.

SOAP Binding Service Components

The following sections contain information on some programming components of the SOAP Binding Service.

SOAPReceiver Servlet

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.

RequestHandler Interface

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.

SOAP Binding Service Process

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.

Note –

Before invoking a corresponding service, the SOAP framework might also do the following:

SOAP Binding Service API

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.

Liberty Personal Profile Service

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.

Note –

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.

Liberty Personal Profile Service Design

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.

Figure 12–8 Data Service Template as Building Block of Data Services

Illustration showing how data service template is framework for data services.

Note –

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.

Liberty Personal Profile Service Process

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.

Figure 12–9 Liberty Personal Profile Service Process

Diagram illustrating the process of modifying or requesting personal profile attributes.

  1. A WSC uses the Data Services Template API uses SOAP to post a query or a modify request to the Liberty Personal Profile Service.

  2. 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.

  3. 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.

  4. 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.

Note –

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.

Data Services API

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:

For more information, see the Sun OpenSSO Enterprise 8.0 Java API Reference and the Sun OpenSSO Enterprise 8.0 Developer’s Guide.

Chapter 13 Delivering Identity Web Services

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:

About Identity Web Services

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:

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:

Note –

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.

Identity Web Service Styles

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:

Note –

developers.sun.com has an excellent three part article called Securing Applications with Identity Services which contains IDE configuration information and procedures.

SOAP and WSDL

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:

REST

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:

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:

Note –

OpenSSO Enterprise REST interfaces currently support only username and password authentication.

Identity Web Services Architecture

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.

Figure 13–1 Components within the Identity Services Interactions

Components within the Identity Services interactions

Chapter 14 Securing Web Services and the Security Token Service

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.

About Web Services Security

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.

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.

Figure 14–1 Message Level Security

Illustration of security context in message level security

Note –

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.

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

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.

Note –

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.

WS-Security Specification

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:

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.

WS-Trust Specification

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.

Liberty Alliance Project Specifications

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.

JSR-196 Specification

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.

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.

Figure 14–2 Four Security Process Points

The four points in the interaction between a web service client and web service provider where security processes can be added.

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.

Web Services Security in OpenSSO Enterprise

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.

Note –

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.

Web Services Security Internal Architecture

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.

Figure 14–3 Architecture of Web Services Security Components

Interactions and architecture of the Web Services Security framework

The Web Services Security framework supports the following tokens.

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.

Web Services Security Deployment Architecture

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.

Note –

The application and web service are in the same domain and both are deployed using Sun Java System Application Server and a security agent.

Figure 14–4 Web Service Security Deployment Architecture

Web Service Security Deployment Architecture

  1. 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.

    Note –

    The internal calendar application is acting as a WSC.

  2. 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.

  3. The security agent forwards the secured SOAP message to the remote calendar web service acting as the WSP.

  4. The security agent protecting the remote calendar web service intercepts the inbound SOAP message.

  5. 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.

  6. The calendar web service sends back a response.

  7. The security agent protecting the remote calendar web service intercepts the outbound SOAP message and digitally signs the request with its private key.

  8. 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.

  9. 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.

Security Token Service

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:

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.

Figure 14–5 Security Token Service Architecture

Design 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.

Figure 14–6 Security Token Service Design

Design of the Security Token Service

The Security Token Service supports the following tokens.

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.

Note –

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

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.

Note –

In previous Sun documentation, this agent was referred to as an authentication agent.

HTTP Security 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:

Note –

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.

Figure 14–7 HTTP Security Agent Process

HTTP security agent protecting HTTP requests to, and responses from, service providers

  1. A WSC (user with a browser) makes a request to access a web service protected by an HTTP security agent.

  2. The security agent intercepts the request and redirects it (via the browser) to OpenSSO Enterprise for authentication.

  3. 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.

Note –

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.

SOAP Security Agent

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.

Supported Liberty Alliance Project Security 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.

Figure 14–8 SOAP Security Agent Process for Liberty Alliance Project Security Tokens

SOAP security agent protecting communications between clients and service providers

The following Liberty Alliance Project security tokens are supported in this release:

X.509

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.

BearerToken

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

SAMLToken

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.

Supported Web Services-Interoperability Basic Security Profile Security Tokens

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.

Figure 14–9 SOAP Provider Agent Process for WS-I BSP Security Tokens

Illustration of interactions between WSC and WSP with deployed SOAP Provider agents for WS-I BSP security tokens

The following WS-I BSP security tokens are supported in this release.

User Name

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.

X.509

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.

SAML-Holder-Of-Key

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.

SAML-SenderVouches

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.

Web Services Security and Security Token Service Interfaces

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:

The Web Services Security framework and the Security Token Service include the following Java packages as part of the Client SDK

For more information, see the Sun OpenSSO Enterprise 8.0 Java API Reference and the Sun OpenSSO Enterprise 8.0 Developer’s Guide.

com.sun.identity.wss.provider

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.

Tip –

A WSC and a WSP can be associated with more than one Security Token Service.

com.sun.identity.wss.security

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

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.