Sun OpenSSO Enterprise 8.0 Developer's Guide

Chapter 11 Securing Web Services

Web services are developed using open standards such as XML, SOAP, WSDL and HTTPS. Sun Java™ System OpenSSO Enterprise provides the functionality to secure web services communications using authentication agents and the Security Token Service. This chapter contains the following sections:

About Web Services Security

A web service is an application whose functionality and interfaces are exposed through open technology standards including the eXtensible Markup Language (XML), SOAP, the Web Service Description Language (WSDL) and HTTP(S). A web service client (WSC) sends a SOAP message to the endpoint (identified by a URI) of a web service provider (WSP); after receiving the request, the WSP responds appropriately with a SOAP response. The built-in openness of these technologies though creates security risks. Initially, securing these web services communications was addressed using transport level security in which the complete message was encrypted and transmitted using Secure Sockets Layer (SSL) with mutual authentication. But with current enterprise topologies (including proxies, load balancers, data centers, and the like) security must now be addressed when intermediaries are involved. Web services must be prepared to:

Pass fine-grained security data (for example, identity attributes for authorization).
Enable one or more trusted authorities to broker trust between communicating entities.
Maintain security on a per message basis.
Maintain transport layer independence.

These requirements call for message level security (also referred to as application level security and end-to-end security) in which only the content of the message is encrypted. Message level security embeds all required security information in a message's SOAP header. Additionally, encryption and digital signatures can be applied to the data itself. The advantages of message level security are that:

Security stays with the message through all intermediaries, across domain boundaries, and after the message arrives at its destination.
Security can be selectively applied to different portions of the message.
Security is independent of the application environment and transport protocol.

To address message level security in web services communications, organizations such as the Organization for Advancement of Structured Information Standards (OASIS), the Liberty Alliance Project and the Java Community Process (JCP) have proposed specifications based on open standards and from them OpenSSO Enterprise has implemented The Security Token Service using the WS-Trust specification and Security Agents.

About Web Services Security with OpenSSO Enterprise

Web services are accessed by sending SOAP messages to service endpoints identified by URIs, and receiving SOAP message responses. Towards this end, OpenSSO Enterprise has implemented a Security Token Service and agents to enforce security. This architecture is illustrated below.

Figure 11–1 Web Services Security Architecture in OpenSSO Enterprise

architecture of web services security components
in OpenSSO Enterprise

The top half of the diagram illustrates a typical web services communication with the addition of agents (WS-Security Provider Plug-in) to enforce message level security and a security token service to issue security tokens. The bottom half represents OpenSSO Enterprise and the interfaces that are called by the WSC and WSP to accomplish web services security. The agents provide access to OpenSSO Enterprise (using the Client SDK) to secure and validate the SOAP requests and responses.

When using web services security, the outgoing web service messages and the incoming web service calls must be authenticated and authorized. Towards this end, the messages must be modified to add headers containing credentials for those purposes. Additional identity attributes (for example, the roles and memberships) can also be added and used by the web service provider's agent and/or by the web service's business logic to provide appropriate service. The authentication and authorization by the agent at the web service provider would leverage the OpenSSO Enterprise Authentication Service and Policy Service. For authentication, it extracts the authentication credentials from the web service request and calls the appropriate authentication module for validation. For authorization, the web service's endpoint port and the operation being performed is the resource for the defined policy.

Security agents are deployed on both the WSC side and the WSP side of the communication. OpenSSO Enterprise contains interfaces with which the agents (deployed remotely to the server) can communicate. The WSC which makes the web service call provides support for securing outgoing communications and validating incoming responses from the WSP. There are two kinds of interfaces used by the WSC, one for administration and another used at run time for securing and validating requests and responses. The WSP which provides service based on calls from the WSC provides support for validating incoming requests and secure outgoing responses. Similar to the WSC, the WSP has an administration interface and an interface used at run time for securing and validating requests and responses. There are also administrative interfaces to configure (local to OpenSSO Enterprise) the Security Token Service and the respective security mechanisms supported by the WSC and WSP. These configurations are stored in the OpenSSO Enterprise configuration data store.

The following diagram illustrates support for web services security in OpenSSO Enterprise. The Security Token Service is supported with any party that understands the WS-Trust specification on which it is based. On the WSC side, an agent developed using the JSR-196 specification is supported on Glassfish (Sun Application Server). (Currently there are no other WSC supported agents although custom handlers and filters can be developed.) On the WSP, the same JSR-196 agent is supported on the Glassfish (Sun Application Server) while Sun policy agents 3.0 are supported on WebLogic, WebSphere and Tomcat.

Figure 11–2 Web Services Security Support in OpenSSO Enterprise

See The Security Token Service and Security Agents for more information.

The Security Token Service

When a WSC communicates with a WSP it must first connect with a trusted authority to determine the security mechanism and, optionally, obtain the security token expected by the WSP. This information is registered with the trusted authority by the WSP. The Security Token Service is a trusted authority that provides issuance and management of security tokens; that is, it makes security statements or claims often, although not required to be, in cryptographically protected sets. The OpenSSO Enterprise trust brokering process is as follows.

An authenticated WSC requests a token to access a particular WSP.
The Security Token Service verifies the credentials presented by the WSC.
In response to an affirmative verification, the Security Token Service issues a security token that provides proof that the client has been authenticated.
The WSC presents the security token to the WSP.
The WSP verifies that the token was issued by a trusted Security Token Service, affirming authentication and authorizing access.

The Security Token Service communicates using the WS-Trust protocol and serves WS-I BSP security tokens. (Any WSC or WSP can communicate remotely with OpenSSO Enterprise Security Token Service using the WS-Trust protocol.) The Security Token Service also serves as a Discovery Service, able to communicate using the Liberty ID-WSF protocol and serve Liberty Alliance Project security tokens.

Web Container Support

OpenSSO Enterprise as a Security Token Service is supported on different web containers including:

Glassfish (Sun Application Server 9.x)
Sun Web Server 7.x
WebLogic
Websphere
Tomcat
Oracle Application Server
JBoss
Geronimo

With this support, any WSC or WSP can communicate remotely with OpenSSO Enterprise Security Token Service using the WS-Trust protocol.

Security Tokens

The Security Token Service issues, renews, cancels, and validates security tokens that can contain an identifier for either the WSC or the actual end user. It also allows you to write a proprietary token providers using the included service provider interfaces (SPI). Finally, it provides application programming interfaces (API), based on the WS-Trust protocol, that allow applications to access the service. By default, the Security Token Service serves tokens based on the Liberty Alliance Project and WS-Trust specifications. The WS-I BSP specifications and the Liberty Alliance Project developed security profiles for web services security. These security mechanism are implemented for web services security using the provider interfaces. The following list contains the supported mechanisms.

Anonymous: Carries no security information.
User Name Token: Carries basic information (username and, optionally, a password or shared secret) for purposes of authenticating the user identity to the WSP. Communication is done in plain text so SSL over HTTPS transport must be used to protect the credentials.
User Name Token-Plain: Carries basic information (username and a clear text password or shared secret) for purposes of authenticating the user identity to the WSP. Communication is done in plain text so SSL over HTTPS transport must be used to protect the credentials.
Kerberos Token: Carries basic information (username and, optionally, a password or shared secret), in a Kerberos token, for purposes of authenticating the user identity to the WSP.
X.509 Token: Contains an X.509 formatted certificate for authentication using credentials created with a public key infrastructure (PKI). In this case, the WSC and WSP must trust each other's public keys or share a common, trusted certificate authority.
SAML-Holder-Of-Key Token: Uses the SAML holder-of-key confirmation method whereby 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 payload. Can use either SAML v1.x or SAML v2.
SAML-SenderVouches Token: Uses the SAML sender-vouches confirmation method whereby 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. Can use either SAML v1.x or SAML v2.

Token Conversion

The Security Token Service is able to convert from one token format to another. For example, an OpenSSO Enterprise SSOToken can be converted to a SAML v2 token or a SAML v1.x token to a SAML v2 token. Token conversion plug-ins can be developed using the token conversion interface in the com.sun.identity.wss.sts package.

Configuring the Security Token Service

To configure a WSC to communicate with the Security Token Service end point (by default, http://server:port/opensso/sts), download and deploy the Client SDK WAR and see the README and samples. To protect the Security Token Service, login to the console and click the Configuration tab. Following, click the Global tab and the Security Token Service link for security configurations. The Security Token Service WSDL is fam.sts.

Security Agents

There are two kinds of security agents developed for web services security. One protects the WSC and the other protects the WSP. The WSC which makes the web service call provides support for securing the outgoing communications and validating the incoming responses from a WSP. The WSP which provides a service from a WSC call provides support for validating the incoming request and securing the outgoing responses. These agents may establish the authenticated identities used by the containers allowing:

A server side agent to verify security tokens or signatures on incoming requests and extract principal data or assertions before adding them to the client security context.
A client side agent to add security tokens to outgoing requests, sign messages, and interact with the trusted authority to locate targeted web service providers.

A typical interaction between a WSC and a WSP begins with a request from the WSC. The container on which the WSP is deployed receives the request and dispatches it to perform the requested operation. When the web service completes the operation, it creates a response that is returned back to the client. The following illustration and procedure illustrates a scenario when both client and service web containers employ the Java Authentication SPI.

A typical interaction between a web services
client and a web services provider

The client browser's attempt to invoke a web service is intercepted by the client's web container.
The deployed security agent on the client's web container is invoked to secure the request (based on the security policy of the web service being invoked).
The client's web container sends the secured request message to the web service.
The web service's web container receives the secured request message and it's deployed security agent is invoked to validate the request and obtain the identity of the caller.
Assuming successful authentication, the web service's web container invokes the requested web service.
This action (the invocation of the web service) is returned to the web service's web container as a response.
The deployed security agent on the web service's web container is invoked to secure the response message.
The web service's web container sends the secured response message to the client.
The deployed security agent on the client's web container is invoked to validate the secured response message.
The invocation of the web service is returned to the client browser.

Security processes can be delegated to a security agent at any of the following interaction points.

Securing a request on the client side
Validating a request on the provider side
Securing a response on the provider side
Validating a response on the client side

This security agent uses an instance of OpenSSO Enterprise for all authentication decisions. Web services requests and responses are passed to the authentication modules using standard Java representations based on the transmission protocol. Currently, the following security agents are provided.

WSC Security Agents

The WSC security agent protects the endpoints of a web service that uses HTTP for communication. After the WSC security agent is deployed in a web container on the WSP side, all HTTP requests for access to the web services protected by the agent are redirected to the login and authentication URLs defined in the OpenSSO Enterprise configuration data store on the WSC side.

Note –

The available WSC security agent was developed using the Java Specification Request (JSR) 196. JSR 196 is the Java Authentication Service Provider Interface for Containers. It defines a standard service provider interface (SPI) with which a security agent can be developed to police Java EE containers on either the client side or the server side. These agents establish the authenticated identities used by the containers. The JSR 196 specifications are available at http://www.jcp.org/en/jsr/detail?id=196.

When the WSC makes a request to access a web application (1 in the illustration below), the agent intercepts the request and redirects it (via the browser) to OpenSSO Enterprise for authentication (2). Upon successful authentication, a response is returned to the application, carrying a token as part of the Java EE Subject (3). This token is used to bootstrap the appropriate Liberty ID-WSF security profile. If the response is successfully authenticated, the request is granted (3).

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

Note –

The functionality of the HTTP security agent is similar in to that of the Java EE policy agents 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 Java System Access Manager Policy Agent 2.2 User’s Guide.

Note –

Application Server 9 has the ability to configure only one HTTP agent per instance. Therefore, all authentication requests for all web applications hosted in the container will be forwarded to the one configured agent.

WSP Security Agent

The WSP which provides a service based on calls from a WSC provides support for validating incoming requests and securing outgoing responses. This agent encapsulates the Web Services-Interoperability Basic Security Profile (WS-I BSP) tokens as well as the Liberty Identity Web Services Framework (Liberty ID-WSF) SOAP Binding Specification tokens:

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 client requests access to a service. The configured security agent reads the configuration from the OpenSSO Enterprise configuration data store and 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 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 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. The following diagram illustrates the interactions as described.

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.

Supported Liberty Alliance Project Security Tokens

In a scenario where security is enabled using Liberty Alliance Project tokens, the client requests (via the WSC) access to a service. The 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. The following diagram illustrates the interactions as described.

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 web service consumer 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 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 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 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. This is accomplished using processing rules defined by the Liberty Alliance Project.

Testing Web Services Security

OpenSSO Enterprise provides two samples that can be used to test web services security. The Stock Quote Sample and the Loan Service Sample are available in the WSS Agent download available on OpenSSO Downloads. The Stock Quote Sample is for simple web services security. It focuses on building a WSP and a WSC, authenticating the WSC before access to the service is given, and guaranteeing the integrity of the authentication data. The Loan Service Sample is an advanced test case where Security Token Service brokerage is demonstrated.