by Jiandong Guo
Metro is a high performance, extensible, easy-to-use
web services stack. It combines the JAX-WS reference implementation with Web Services Interoperability Technology (WSIT),
an implementation of numerous WS-\* standards to enable interoperability with other implementations and to provide
Quality of Service (QOS) features such as security, reliability, and transaction support. Metro is available in the open source,
GlassFish v3 application server as well
as in the open source, enterprise-ready,
GlassFish v2 application server.
Metro also runs in the
Tomcat web container.
In addition, it has been successfully used in
other application servers.
WSIT implements the following web services security specifications published by the Organization for the Advancement
of Structured Information Standards (OASIS) consortium: WS-Security, WS-SecurityPolicy, WS-SecureConversation, and WS-Trust.
An earlier tech tip, Using WS-Trust Support in Metro to Secure Web Services,
focused on the support in Metro for WS-Trust. It described the basics
of WS-Trust and its Security Token Service (STS) framework and showed
how to take advantage of Metro's support of WS-Trust and STS to secure
a web service.
The latest release of Metro, Metro 2.0, provides
many enhancements and new features, which are described in
Metro 2.0 One Pagers.
Among those enhancements is support for WS-Trust 1.4 and WS-SecureConversation 1.4.
The following tip describes how you can use the enhanced support for WS-Trust and WS-SecureConversation in
Metro 2.0 to access a back-end resource through a chain of services.
You'll also learn how identity delegation in STS is used to access the back-end resource in a secure way.
A sample application package accompanies the tip. The package includes a sample application
that demonstrates the concepts and techniques described in this tip. The code examples shown in the tip are taken from
source code in the sample application.
To understand identity delegation, let's briefly review some basic concepts related to WS-Trust and STS.
WS-Trust is a WS-\* specification that provides extensions to the WS-Security specification. WS-Security provides the basic
framework for message level security in web services. WS-Trust builds on that base to specify a framework for broker trust
across different security domains. It specifically deals with the issuing, renewing, and validating of security tokens,
as well as with ways to establish, assess the presence of, and broker trust relationships between participants in
a secure message exchange.
For a web service and its client to communicate securely there needs to be a trust relationship established between the service
and the client. If the service and client are in the same security domain they can have a direct trust relationship.
In this type of relationship the service and client can authenticate each other directly.
However, if the client and the service are in different security domains they have no direct trust relationship. In that case,
you can use an STS to authenticate the client. The STS is an authority trusted by the client and the service. You can also use
an STS to issue a security token, that is, a collection of claims such as name, role, and authorization code, for the client
to access the service. A request for a security token is made by sending a Request Security Token (RST) message to the STS
The STS approach works well if a client needs to securely access a
service in another domain. But what if the called
service needs to securely access another service on behalf of the
original client? For example, what if the client
needs to securely access a back-end resource through the second
service? In previous versions of WS-Trust, there was no way to pass
the authenticated identity of the client through this chain of
services. That obstacle was resolved in
the current version of the WS-Trust specification,
In particular, WS-Trust 1.4 defines extensions to the
<wst:RequestSecurityToken> element for indicating
delegation and forwarding requirements on the requested security token. One of those extensions is the
<wst:ActAs> element. The specification defines the
<wst:ActAs> element as follows:
This OPTIONAL element indicates that the requested token is expected to contain information about the identity represented
by the content of this element and the token requestor intends to use the returned token to act as this identity.
The identity that the requestor wants to act-as is specified by placing a security token or
element within the
In other words, by specifying a token in the
<wst:ActAs> element of an RST — let's call
<wst:ActAs> element the "ActAs" element — you can request
an STS to issue a security token that contains information about the identity
specified in the ActAs element. The identity in the ActAs element can be that of the original caller.
By specifying a token in the ActAs element — let's call the token the "ActAs token" — that identifies a client,
you can enable one service to call another service in a secure way on behalf of a client.
Figure 1 illustrates the control flow in a typical identity delegation scenario. Here a client, Client, wants
to access a back-end resource (not shown) across security domains. To do that, the client calls a service, Service, which in
turn calls a second service, Service 1, to access the resource.
Figure 1. Control Flow in an Identity Delegation Scenario
Implementing Identity Delegation
In order to implement identity delegation, you need to add an ActAs token to the RST submitted by the pertinent service.
For example, in the identity delegation scenario illustrated in Figure 1, you need to add an ActAs token in the RST
issued by Service, and that ActAs token needs to identify Client.
To do this, you can take advantage of a new feature in Metro 2.0
that allows you to programmatically inject
STS information and token requirements into a web service client at run
time. The following code snippet shows the code you can add
to the web service client. You can find the code in the
FSImpl class in the sample application.
This class implements a web service named
IFinancialService. In the sample application, the
web service calls another web service, IPingService, to access a resource.
STSIssuedTokenFeature classes are part of Metro's WS-Trust implementation. The
class is a JAX-WS class implemented in Metro.
In this approach you:
STSIssuedTokenConfigurationobject to hold the run-time configuration information.
Tokenobject and add it to the configuration object.
Note that in the STS, both the subject for the requestor and the subject for the act-as user are
available in the
STSAttributeProvider class is a part of Metro's
WS-Trust implementation. The class exposes an extension to WS-Trust that enables details about the requestor to be included
in the token to be issued by the STS. If this extension is implemented, the provider implementation returns an
attribute that is included in a SAML assertion created by the STS.
The following code snippet is from an
SampleSTSAttributeProvider, that is in the sample application.
Securing the Back-End Service
You can secure the back-end service in a chain of services, such as Service1 in the scenario illustrated in Figure 1,
with the token issued by the STS. You can also secure the back-end service with its own credential, such as an X509
certificate, or with both a token issued by the STS and a certificate. The back-end service must trust the STS, but
not necessarily have a direct trust relationship with the intermediate service. Unlike the Sender-Vouches case, the back-end
service should not ask for the intermediate service to provide any of its credentials to sign the issued token and the message.
Instead, it trusts the STS for the validity of the service token.
The NetBeans IDE offers an easy way to enable secure conversations
in Metro for a web service.
For details on using the NetBeans IDE to enable secure conversations
in Metro for a web service, see the tip
Using WS-Trust Support in Metro
to Secure Web Services.
The NetBeans IDE provides a set of security profiles that specify the mechanism
to be used in securing conversations. Four of these profiles secure web services with STS-issued tokens. Here are the four
profiles and the STS-issued token-based mechanisms they implement:
You can choose any of the four STS-issued token based mechanisms to secure the back-end service.
Securing the STS
In an identity delegation scenario involving a chain of services, as illustrated in Figure 1, messages exchanged between the
intermediate service and the STS are secured with service credentials and STS credentials. However, the only thing changed
in each request is the addition of an ActAs token to the message payload. In this situation, it makes sense
to enable a secure conversation for the STS through WS-SecureConversation. The WS-SecureConversation standard introduces
secure sessions on top of WS-Security. It enhances overall security through key derivations and improves performance by
avoiding repeated key exchanges in multi-message exchange scenarios. So by enabling a secure conversation for the STS, you
not only enhance overall security, but you can also improve performance.
You can enable a secure conversation for the STS in the same way as for a regular web service.
To take advantage of the secure conversation session with the STS, you must share a common
object with different calls from the intermediate service to the back-end service.
See the Tech Tip Secure Conversations
for Web Services With Metro to learn the basics of WS-SecureConversation and see examples of using the WS-SecureConversation
support in Metro.
Although this tip focuses on identity delegation as a technique for
securely accessing the back-end resource through a chain
of services, there is an alternative approach. The intermediate
service, such as Service in Figure 1, can propagate the end user's
by calling the back-end service with the token it receives from the
client. This approach is called token propagation.
Figure 2 illustrates the control flow in a typical token propagation scenario.
| Figure 2: Control Flow in a Token Propagation |
Token propagation is more efficient than identity delegation with an
ActAs token. However, it is less secure than identity delegation
for the following reasons:
AudiencesRestrictionConditioncheck on the SAML assertion.
AudiencesRestrictionConditionis used to restrict the validity of a SAML assertion to a specific audience.
For these reasons, token propagation is a better choice for service chains in the same security domain. In any case, you
can configure the back-end service for token propagation using either of the following security mechanisms:
The following code shows how to obtain the user SAML assertion in the intermediate service:
Element samlAssertion = null;
Here is how to inject to the context for the proxy to the back-end service:
You can find a complete code sample for token propagation
The Sample Application
A sample application package that accompanies the tip. The package includes a sample
application that demonstrates identity delegation using ActAs. The STS in the sample application contains two
endpoints. One endpoint is for end users who require username/password for authentication. The other endpoint
is for the intermediate requestor that has secure conversation enabled and requires an X509 certificate for
The intermediate service is configured to use the STS Issued Token mechanism, where an
issued token with a symmetric proof is used as the protection token.
The back-end service is configured to use an STS-issued endorsing
token, where the X509 certificate of the back-end service is used
as the protection token and an issued token with a public proof key is
as an endorsing supporting token.
To build, deploy, and run the sample, do the following:
webservices-api.jarfile from the
METRO_HOME/libdirectory to the
JAVA_HOMEis the directory where you installed JDK 6.
delegate/certs/xws-securitydirectory to one of the following locations:
GF_LOC is the directory where you installed GlassFish.
delegate/certs/xws-security directory contains key stores for the sample.
/delegate/src/fs/build.propertiesfile to properly set
glassfish.hometo the location of GlassFish
$WSIT_HOMEwith the GlassFish location:
/delegate/src/fsand enter the following commend from the command line:
You will be prompted to enter a username and password. Enter the username
alice and the password
bob and the password
bob. These two username-password pairs are preconfigured for use with the sample
If the sample application runs successfully, you should see
About the Author
Jiandong Guo has lead the development of implementations and solutions based on WS-SecureConversation and WS-Trust in the
Metro project in Sun . He is currently a security architect in Oracle security and Identity management platform security group.