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.

Data integrity and confidentiality during transport

Authentication of the sending entity

Message uniqueness

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

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.

Identify and authenticate the principal.

Generate and exchange security tokens in a trusted
environment.

Preserve the identity through multiple intermediaries
and across domain boundaries.

Maintain privacy and integrity of identity data.

Log the outcome.

Basically, the JCP, W3C, and OASIS are developing specifications
related to web services security. WS-I creates profiles that recommend
what to implement from various specifications and provides direction
on how to implement the specifications. The Liberty Alliance Project provides a
framework for building interoperable identity services, using specifications
such as WS-Security (OASIS), SOAP, Security Assertions Markup Language
SAML (OASIS) and XML (W3C). The following sections briefly discuss
the specifications and profiles being developed by each organization.

There are a number of web services security specifications,
guidelines, and tools that have been implemented to develop these
Web Services Security features for OpenSSO Enterprise. The following sections have
more general information on these specifications.

Web Services Interoperability Technology

Web Services Interoperability Technology (WSIT) is an open source
implementation of many of the web services specifications (commonly
referred to as WS-*). The project
was started by Sun Microsystems, and consists of Java API that allow
developers to create web service clients and services that enables
operations between the Java platform and clients and servers developed
with the WS-* specifications. WSIT provides implementation of the
following specifications for interoperability with .NET 3.0.

WS-Metadata Exchange

WS-Transfer

WS-Reliable Messaging

WS-Reliable Messaging Policy

WS-Atomic Transaction

WS-Coordination

WS-Security 1.0 and 1.1

WS-Security Policy

WS-Trust

WS-Secure Conversation

WS-Policy

WS-Policy Attachment

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.

A server side agent can be used to verify security
tokens or signatures on incoming requests and extract principal data
or assertions before adding them to the client security context.

A client side agent can be used to add security tokens
to outgoing requests, sign messages, and interact with the trusted
authority to locate targeted web service providers.

The JSR–196 SPI is structured so that the security processes
can be delegated to an agent at any of four interaction points (that
represent the methods of the corresponding ClientAuthModule and ServerAuthModule SPI). These point are illustrated in Figure 14–2.

Figure 14–2 Four Security Process Points

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.

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

The Web Services Security framework supports the following tokens.

Tokens that can be authenticated:

UserName

X509

SAML 1.1

SAML 2.0

Kerberos

Tokens that can be issued:

UserName (generated with the Security Token Service or locally at the
WSC)

X509 (generated with the Security Token Service or locally at the WSC)

SAML 1.1 (generated with the Security Token Service or locally at the
WSC)

SAML 2.0 (generated with the Security Token Service or locally at the
WSC)

Kerberos (generated locally at the WSC)

In general, securing web services involves establishing trust
between a WSC and a WSP. Towards this end, OpenSSO Enterprise provides security
agents to verify (and extract data from) security tokens on incoming
requests and to add security information (tokens and signatures) to
outgoing responses. It also provides a Security Token Service to handle security tokens,
and a number of Java interfaces. The following sections contain more
information on these components.

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

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.

The security agent protecting the internal calendar
application intercepts the outbound SOAP message, connects to a token
authority (in this case, the Security Token Service), determines the security mechanisms
of the WSP, obtains the appropriate security token(s), and secures
the request by inserting the tokens (in the form of a SAML assertion)
into the SOAP request headers.

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

The security agent protecting the remote calendar
web service retrieves and validates the security information and,
upon successful validation, forwards the request to the remote calendar
web service.

The calendar web service sends back a response.

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

The security agent protecting the internal calendar
application intercepts the inbound signed SOAP message, validates
the signature, and, upon successful validation, forwards the request
to the application.

The calendar application consumes the results and
presents the employee with the appropriate response.

For identity-based web services specifically (a calendar service
for example), the WSP would have to trust the WSC to authenticate
the user, or the WSC would have to include the user's credentials
as part of the web service request. The distinguishing factor is that
identity-based web services authenticate both the WSC and the user's
identity. The user must be authenticated so that the WSC can send
the user's token to the WSP in a SOAP security
header.

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:

Issues, renews, cancels, and validates security tokens.

Allows customers to write their own plug-ins for different
token implementations and for different token validations.

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

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

The Security Token Service supports the following tokens.

Tokens that can be authenticated with the Security Token Service:

UserName

X509

SAML 1.1

SAML 2.0

Kerberos

Tokens that can be issued with the Security Token Service:

UserName

X509

SAML 1.1

SAML 2.0

End user tokens that can be converted or validated
out of the box:

OpenSSO Enterprise SSOToken to SAML 1.1 or SAML
2.0 token

SAML 1.1 or SAML 2.0 token to OpenSSO Enterprise SSOToken

Additionally, end user tokens can be converted or validated
after customization. In this case, the new token is an On
Behalf Of token (WS-Trust protocol element) carried in the
WS-Trust request as part of the SOAP body and not as an authentication
token carried as part of the SOAP header. Custom tokens can also be
created and sent On Behalf Of an end user token
for conversion or validation by Security Token Service. To do this,
implement the com.sun.identity.wss.sts.ClientUserToken interface
and put the implemented class name in AMConfig.properties on
the client side and the global Security Token Service configuration using the OpenSSO
console.

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.

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:

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

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

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

Upon successful authentication, a response is returned
to the web service, carrying a token as part of the Java EE Subject.

This token is used to bootstrap the appropriate Liberty ID-WSF security
profile. If the response is successfully authenticated, the request
is granted.

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.

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.

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.

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

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:

Security agents bootstrap the Security Token Service or the Liberty Alliance Project Discovery Service using
the Client SDK.

Note –

The OpenSSO Enterprise Discovery Service can
be leveraged with the Client SDK so consumers can continue to use
it's end point for web services security token utilities, resource
offerings and WSP end points. A configuration on the client side would
choose either the WS-Trust orLiberty Alliance Project protocol for web services
security token management.

The Client SDK generates the proprietary SSOToken based on security token credentials provided to the WSP.
It also sets the SSOToken into the container Subject
for further authorization processing.

The Client SDK implements caching for the security
tokens generated by the Security Token Service or the Liberty Alliance Project Discovery Service. This improves
performance when requesting security tokens.

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.