test

Sun OpenSSO Enterprise 8.0 Technical Overview

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.