Chapter 11 Securing Web Services Using the Security Token Service (WS-* Specifications)

A web service is an application that exposes some type of business or infrastructure functionality though a callable interface that is both language-neutral and platform-independent. A company's web-based phonebook is an example of such an application. This document provides information about how you can use OpenSSO Enterprise to protect your web-base applications and services from unauthorized use or attack.

The following topics are included in this chapter:

• About Web Services Security Models

• About OpenSSO Enterprise Web Services Security

• Analyzing the Deployment Architecture

• Understanding Typical Business Use Cases

• Considering Assumptions, Dependencies, and Constraints

• Evaluating Benefits and Tradeoffs

About Web Services Security Models

A web service exposes its functionality using the Web Services Framework (WSF). The Web Services Framework defines its interface using Web Service Description Language (WSDL), and communicates using Simple Object Access Protocol (SOAP) and Extensible Markup Language (XML) messages. Although web services enable open, flexible, and adaptive interfaces, this openness create security risks. Without proper security measures in place, a web service can expose vulnerabilities that could allow unauthorized entities access to the enterprise. You can ensure the integrity, confidentiality and security of web services by using a comprehensive security model. In a good security model, web services are secured either point-to-point as provided by SSL/TLS, or end-to-end as specified by the Web Services Security (WS-Security) Framework.

The WS-Security Framework was developed by the OASIS Security committee along with other WS-* specifications such as WS-Trust and WSPolicy. Transport-layer or point-to-point transport mechanisms transmit information over the wire between clients and providers. Transport-layer security relies on secure HTTP transport (HTTPS) using Secure Sockets Layer (SSL). Transport security can be used for authentication, message integrity, and confidentiality. When running over an SSL-protected session, the server and client can authenticate one another and negotiate an encryption algorithm and cryptographic keys before the application protocol transmits or receives its first byte of data. Security is enabled from the time data leaves the consumer until the data arrives at the provider, or from the time the data leaves the provider until the data arrives at the consumer. Sometimes security data transfer can transpire even across intermediaries.

The following figure illustrates a security model that uses point-to-point security.

Figure 11–1 Secure Communication Channel Providing Point-to-Point Security

A drawback to using point-to-point security is that the message is not protected once it gets to its destination. One solution is to encrypt the message before sending using application security.

Using application-layer or end-to-end security, the message is secure even when the message is not in transit. Additionally, in application-layer security, the security information is contained within the SOAP message and the message attachment. This allows security information to travel along with the message or attachment. For example, a portion of the message may be signed by a sender and encrypted for a particular receiver. When the message is sent from the initial sender, it may pass through intermediate nodes before reaching its intended receiver. When this happens, the encrypted portions continue to be opaque to any intermediate nodes, and can only be decrypted by the intended receiver. Message security can be used to decouple message protection from message transport so that the message remains protected after transmission. For this reason, application-layer security is also sometimes referred to as end-to-end security .

The following figure illustrates a security model that uses end-to-end security.

Figure 11–2 Secure Communication Channel Providing End-to-End Security

Application-layer security provides the following: Confidentiality, by encrypting message parts, integrity, by digital signatures , and authentication, by requiring username or X.509 tokens.

About OpenSSO Enterprise Web Services Security

You can configure OpenSSO Enterprise to act as a security token service, or as a web service security provider. When you use OpenSSO Enterprise to act as a web service security provider, you must configure both the web service client and at the web service provider.

Security Token Service

When configured as a security token service, OpenSSO Enterprise acts as a generic web service that does the following:

• Issues, renews, cancels, and validates security tokens.

• Enables customers to write custom security token providers by extending the framework.

• Provides standards-based APIs for clients and applications to access the security token service.

• Provides mechanisms to support additional security token types such as Kerberos and others.

Web Service Security Provider

OpenSSO Enterprise 8.0 provides web service security support for client applications which are based on Java API for XML Web Services (JAX-WS) or SOAP with Attachments API for Java (SAAJ). For JAX-WS based clients, web services security can be enforced at either the web or JavaEE container level using container-provided security authentication and authorization plug-ins, or using JAX-WS Handlers. The JSR 196 specification is one of the well known authentication and authorization security SPIs, currently supported by the Sun Application Server. Handlers are interceptors that can be easily plugged into the Java API for XML-Based Web Services (JAX-WS) 2.0 runtime environment to do additional processing of inbound and outbound messages.

For non-JAX-WS based client applications such as SAAJ-based, you can use the OpenSSO Enterprise client SDK can to programmatically, explicitly secure and validate both outbound and inbound messages between the web service client and web service provider.

Analyzing the Deployment Architecture

In this deployment example, messages are exchanged using the SOAP protocol to transfer security tokens between the communicating web service client and web service provider entities. The web service security providers can work independently of the OpenSSO Enterprise instance which is deployed as security token service. Web service security providers can secure the SOAP message by obtaining the security tokens from a vendor-neutral security token service.

The following are the major components in this deployment example:

• OpenSSO Enterprise configured as a security token service

• OpenSSO Enterprise configured as a web service security provider on a web service client

• OpenSSO Enterprise configured as a web service security provider on a web service provider

• Browser

The following figure illustrates the deployment architecture for using OpenSSO Enterprise to secure a web-based calendar service.

Figure 11–3 Deployment Architecture for Web Service Security Using Secure Token Service

In this deployment example, a company employee has a user account in the Example Company identity system. The employee wants to access an internal calendar application to view a calendar service. The calendar application is part of the Example Company portal. All Example Company employees are required to authenticate themselves before accessing this internal portal. Additionally, the individual employee's credentials, such as role or group membership, must be validated before the employee can access the calendar application service.

The calendar application, on the employee's behalf, securely supplies the employee's credentials to the remote calendar web service.

The following two figures illustrate the process flow for a Web Service Security using Secure token Service.

Figure 11–4 Process Flow for Web Service Security Using Secure Token Service (Continued on next page)

Figure 11–5 Process Flow for Web Service Security Using Secure Token Service (Continued)

Understanding Typical Business Use Cases

The following are the types of users involved in transactions using Web Services Security and Secure Token Service:

• Developers

  Developers are typically application owners who use the OpenSSO Enterprise Client SDK APIs to communicate with a local security token service instance, or with web service security providers, to secure the applications making web services calls.

• System administrators

  Administrators are responsible for the configuring the OpenSSO Enterprise secure token service.

• End users

  End users such as company employees are exposed to OpenSSO Enterprise when they access the published web services.

Use Case 1

The following figure illustrates the process flow for a secured stock quotes web service using a Kerberos security token.

Figure 11–6 Process Flow for a Stock Quote Web Service Using Kerberos Security Token

1. The Web Service Client authenticates to STS1 instance with the end user's Kerberos token .

   The end user logs in to the Desktop at the Web Service Client. This can be viewed as a Kerberos token for the Web Service Client, too.

2. The Web Service Client gets the SAML token for the end user (Web Service Client).

3. The Web Service Client then talks to the STS2 (Token Mapping Service) .

4. The Web Service Client converts the end user's (Web Service Client) SAML token to a functional SAML token.

   This is called an organizational SAML token, and used as an authentication token of the Web Service Client to STS2. Here the functional SAML token has the same identity or owner as the original SAML token, but with more attributes and privileges.

5. The Web Service Client then secures the web services request to the Web Service Provider with the functional SAML token.

The following are configuration suggestions for this use case:

1. STS client agent - profile name is STS1

   Security Mechanism:

   Kerberos

   STS End Point:

   of STS1 service

   STS Max End Point:

   of STS1 service

2. STS client agent - profile name is STS2

   Security Mechanism:

   STSSecurity

   STS config:

   STS1

   STS End Point:

   of STS2 service

   STS Max End Point:

   of STS2 service

3. WSC agent - profile name is StockService or WSC

   Security Mechanism:

   STSSecurity

   STS config:

   STS2

   WSP End Point:

   Default

Use Case 2

The following figure illustrates the process flow for a bank loan web service using a SAML 1 security token.

Figure 11–7 Process Flow for a Bank Loan Web Service Using SAML1 Security Token

1. WSC1 authenticates to STS1 with its X509 token.

2. WSC1 gets to SAML1 token (owner is WSC1).

3. WSC1 secures web service to WSP1 with its SAML1 token.

4. WSP1 then authenticates to STS2 with its X509 token, and sends the SAML1 token of WSC1.

5. The SAML1 token is sent on behalf of the X509 token in order to convert it to SAML2 token for WSC1.

6. WSC2 just passes through this SAML2 token of WSC1 to WSP2.

   WSC2 secures the web service to WSP2 with the SAML2 token of WSC1.

The following are configuration suggestions for the Bank Loan use case:

1. WSC agent - profile name is LoanRequestorService for WSC1

   Security Mechanism:

   STSSecurity

   STS config:

   SecurityTokenService

2. WSP agent - profile name is wsp for WSP1

   WSP End Point:

   Default

   Authentication Chain:

   ldapService

   Token Conversion Type:

   SAML2 token

3. WSC agent - profile name is LoanProcessorService for WSC2

   Use Pass Through Security Token

   Enabled

Use Case 3

The following figure illustrates the process flow for a bank loan web service using a X509 security token.

Figure 11–8 Process Flow for a Bank Loan Web Service Using an X509 Security Token

1. WSC1 authenticates to STS1 with its X509 token.

2. WSC1 gets the SAML1 token (owner is WSC1).

3. WSC1 secures web service to WSP1 with its SAML1 token.

4. WSP1/WSC2 passes through just this SAML1 token of WSC1 to WSP2.

   Secures web service to WSP2 with SAML1 token of WSC1.

5. WSP2 then authenticates to STS2 with its X509 token.

   Sends SAML1 token of WSC1 as On Behalf Of token in order to convert it to SAML2 token for WSC1.

6. STS2 sends back to WSP2 the converted SAML token for WSC1.

The following are suggested configurations:

1. Web Service Client agent - profile name is LoanRequestorService for WSC1

   Security Mechanism:

   STSSecurity

   STS Configuration:

   SecurityTokenService

2. Web Service Provider agent - profile name is wsp for WSP2

   Web Service Provider End Point:

   Default

   Authentication Chain:

   ldapService

   Token Conversion Type:

   SAML2 token

3. WSC agent - profile name is LoanProcessorService for WSC2

   Use Pass Through Security Token:

   Enabled

Considering Assumptions, Dependencies, and Constraints

Before using OpenSSO Enterprise to secure web services, you must resolve the following issues:

Assumptions and Dependencies

• Metadata exchange (MEX) between individual components has already been completed.

• Users are authenticated to an Identity Provider.

Constraints

• The scope of the current Web Service Security provider plug-ins is limited to JSR 196 SPI implementation, and is only supported on Sun Application Server version 9.0 and above.

• Clients using JAX-WS based applications on web or J2EE containers that do not support JSR 196 specifications must use handlers.

• Clients using SAAJ based applications need to secure the messages programmatically using the OpenSSO Enterprise Client SDK.

Setting Up and Configuring Web Services Security Using Security Token Service

OpenSSO Enterprise ships with the StockQuoteClient and StockService sample applications. These sample applications show you how the Web Service Client, Web Service Provider, and Secure Token Service interact together in a demonstration environment. The sample applications are available in the wssagents/openssowssproviders.zip on the OpenSSO Enterprise download site.

To configure and deploy the sample applications, see the README files in the zipped archive. The following steps describe the high-level tasks for setting up the deployment illustrated in section Use Case 1. This deployment uses the StockQuoteClient (Web Service Client) and StockService (Web Service Provider) applications, from the OpenSSO Enterprise samples.

1. Create and configure a Secure Token Service instance, STS-1.

   1. Install the STS-1 instance.

   2. Configure a policy agent profile for the Web Service Provider.

   3. Select security mechanisms.

2. Create and configure a second Secure Token Service instance, STS-2 instance.

   1. Install the STS-2 instance.

   2. Configure an policy agent profile for the STS-1 instance.

3. Create and configure the Configuration Instance for the Web Service Client and Web Service Provider.

   1. Install the WSC-WSP Configuration Instance.

   2. Create And Configure a policy agent profile for the STS-2 instance.

   3. Configure a policy agent profile for the STS-1 instance.

   4. Configure a policy agent profile for the Web Service Client.

   5. Configure a policy agent profile for the Web Service Provider.

4. Create and configure the Web Service Client instance.

   1. Install the Web Service Client Instance.

   2. Configure the Web Service Client as an OpenSSO Enterprise client.

   3. Configure the Web Service Client GlassFish instance.

      1. Update the GlassFish classpath.

      2. Configure for end-user authentication.

5. Create and configure the Web Service Provider instance.

   1. Install the Web Service Provider instance.

   2. The Web Service Provider as an OpenSSO Enterprise client.

   3. Configure the Web Service Provider GlassFish instance.

6. Build and deploy the Web Service Client application.

7. Build and deploy the Web Service Provider application.

8. Test to verify that the Web Service Security works as designed.

Evaluating Benefits and Tradeoffs

The following lists are designed to help you determine whether using OpenSSO Enterprise to secure web services is suitable in your environment.

Benefits

• Based on standards specification as developed by OASIS, Liberty Alliance Project, Web Services Interoperability Organization, World Wide Web Consortium.

• Secures the message over all hops and after the message arrives at its destination.

• Security is fine-grained and can selectively be applied to different portions of a message (and to attachments if using XWSS).

• Can be used in conjunction with intermediaries over multiple hops.

• Is independent of the application environment or transport protocol.

• Securing web services interactions is transparent to the client applications when web service security providers are configured in web or J2EE containers.

Tradeoff

The drawback to using message-level security is that it is relatively complex and adds some overhead to processing.