by Jiandong Guo
Metro is a high performance, extensible, easy-to-use
web services stack. It combines the JAX-WS reference implementation with Project Tango. Project Tango, also called
Web Services Interoperability Technology or WSIT, implements 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, enterprise-ready
GlassFish v2 application server as well as in the
modular GlassFish v3
application server. Metro also runs in the
Tomcat web container.
In addition, it has been successfully used in
other application servers.
In an earlier Tech Tip, Securing
Web Services Using WSIT, I introduced Metro's support (through WSIT) for web services security. This support 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. The following tip focuses
on the support in Metro for WS-Trust. You will learn the basics of WS-Trust and its Security Token Service (STS) framework.
You'll also learn about the support in Metro for WS-Trust and STS. And you'll see how easy it is to take advantage
of this support to secure a web service using Metro and the NetBeans IDE.
A sample application package accompanies the tip. The package includes sample applications
that demonstrate how to enable web service security using STS-issued tokens associated with various types of proof keys
such as a symmetric proof key, a public proof key, or no proof key.
If would want to learn about other aspects of Metro security, see the September, 2008 Tech Tip
Securing Attachments With Metro 1.3 and the March 2008 Tech Tip
Secure Conversations
for Web Services With Metro.
WS-Trust and WSIT
In essence, WS-Trust specifies the following:
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. In WSIT, you specify authentication
requirements in a security policy which you attach to the Web Services Definition Language (WSDL) file for the service. For
example, the following X509Token assertion in a security policy specifies that an X509 certificate from the client is required
for the client to authenticate to the service:
In this case, the service understands the client's identity as represented by its certificate.
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.
In you use an STS, you need to change that assertion in the security policy to indicate that the client must call
an STS first to get a security token. The security token is usually a Security Assertion Markup Language (SAML) token.
Here's what the changed X509Token looks like:
The first <Address>
element in the changed X509Token specifies the endpoint of the STS. The second<Address>
element, the one under the <Metadata> element, specifies the address for obtaining the
WSDL of the STS using standard WS MetadataExchange (WS-MEX) protocols.
An STS itself is a web service -- a web service that issues security tokens. It makes assertions based on evidence
that it trusts, to whoever trusts it (or to specific recipients). To communicate trust, an STS requires proof, such as
a signature, to prove knowledge of a security token or set of security tokens. An STS can generate tokens or it can rely on
a separate STS to issue a security token with its own trust statement (note that for some security token formats this can
just be a reissuance or cosignature). This forms the basis of trust brokering.
WS-Trust in Metro
Here is a summary of the WS-Trust support in Metro:
In Metro, you use <sp:IssuedToken>
policy assertions in the service's WSDL to enable security with an STS.
No run-time API is required.
You secure the STS itself in the same way that you secure a regular web service.
Issued Tokens and Proof Keys
In many cases, an <sp:IssuedToken>
policy assertion may need to require a proof key to protect
communications between the client and the service. A proof key indicates proof of possession of the token associated
with the requested security token. There are two types of proof keys: symmetric or asymmetric. A symmetric proof key
is computed and verified with symmetric key algorithms. An asymmetric proof key is computed and verified with
asymmetric key algorithms. You can specify the requirement of the proof key type in
the service's security policy in the WSDL. You do this in the <KeyType>
entry in the<sp:IssuedToken>
policy assertion. Here's an example assertion:
In this example, the <KeyType>
entry specifies a symmetric key. As an alternative to
specifying a symmetric or asymmetric proof key, you can also specify a public proof key or no proof key.
Here is how these three cases are handled.
Symmetric Proof Key. In this case, the STS creates an associated symmetric proof key while creating
the issued SAML assertion. The symmetric key needs to be distributed
to both the client and the service that the client talks to. The STS sends the key to the client in a<RequestedProofToken>
element in the response message from the STS to the client. Another copy of the
key is embedded in a <KeyInfo>
property of the <SubjectConfirmation>
element in
the issued SAML assertion. The service retrieves the key after it gets the SAML assertion in the request message from
the client.
Public Proof Key. A public proof key is used for privacy reasons if the client doesn't want the STS to control
or issue the secret key. In this case, the client either supplies an X509 certificate or an ephemeral RSA public key in
the request message to the STS. The client certificate or the public key is embedded in
a <KeyInfo>
property of the <SubjectConfirmation>
element in the issued SAML assertion
passed to the service.
In Metro, an ephemeral RSA key pair is always created for use if the <KeyType>
is set toPublicKey
and <KeySize>
is set to a value (the values must be multiples of 1024). If<KeyType>
is set to PublicKey
and <KeySize>
is not set, then a client
certificate must be supplied to the STS as an authentication token or supporting token.
No Proof Key. In this case, the issued token is mainly used as a supporting token for authentication/authorization
purpose. If you choose to have no proof key with an issued token, the token must always be signed and encrypted in transport.
Enabling WS-Trust-Based Security With Metro and NetBeans
The NetBeans IDE offers an easy way to enable secure conversations in Metro for a web service. One of the ways it does this
is by providing a set of security profiles that specify the mechanism to be used in securing conversations. The profiles are:
Four of these profiles secure web services with STS-issued tokens:
You specify one of these mechanisms when you configure security for a web service using the NetBeans IDE.
You do this by expanding the Web Services node in the Projects window. Then right-click on web service
in the Web Services node and select Edit Web Services Attributes as shown in Figure 1.
![]() |
Figure 1. Configuring Security for a Web Service in NetBeans |
For each of these profiles, you can configure the proof key type for the issued tokens by specifying
a key type in the Configuration panel, as illustrated in Figure 2.
![]() |
Figure 2. Configuring a Proof Type Key for a Web Service in NetBeans |
Not all proof key types can be used with each of the profiles. Here are the general rules:
SymmetricKey
or PublicKey
type.SymmetricKey
or PublicKey
SymmetricKey
or PublicKey
is required.Once you choose one of the profiles to secure a web service, an IssueToken
policy assertion is created
in the service WSDL.
You can also use the NetBeans IDE to create an Metro-based STS. For more details, see
Section 12.8.
Configuring A Secure Token Service (STS) in the Metro User's Guide.
To further customize the STS, see my blog entry
Create customer STS with
WSIT.
A sample application package accompanies the tip. The package includes sample applications
that demonstrate how to enable web service security using STS-issued tokens associated with a symmetric proof key,
a public proof key, and no proof key. To install and run the samples do the following:
webservices-rt.jar
file and the wsservices-tools.jar
file from Metro 1.3.1 to<GF_Install>\\lib
, where <GF_Install>
is the GlassFish v2 ur2 installationwebservices-api.jar
file from Metro 1.3.1 to <GF_Install>\\lib\\endorsed
.trust_samples
.STS
project in the NetBeans IDE as follows:trust_samples
directory from the sample application download.STS
is a project for an STS that will be used by the sample applications. The STS was created using the
NetBeans IDE with the Mutual Certificates Security profile. You can see the security configuration for the STS service,STSService
, by expanding the Web Services node for the STS project in the Projects window.
Then right-click on STSService in the Web Services node and select Edit Web Services Attributes as shown in
Figure 3.
![]() |
Figure 3. STSService Security Configuration |
STS
project as follows:In response, the STS service is deployed to the GlassFish v2 application server and
the WSDL file for the web service is published to http://localhost:8080/STS/STSService?wsdl
.
CalculatorServiceIT
project with the NetBeans IDE as follows:trust_samples
directory from the sample application download.CalculatorServiceIT
is a simple calculator service created using the NetBeans IDE with
an STS Issued Token profile for security. The service was configured using a symmetric proof key
as shown in Figure 4.
![]() |
Figure 4. CalculatorServiceIT Security Configuration |
CalculatorServiceIT
project as follows:In response, the CalculatorServiceIT
service is deployed to the GlassFish v2 application server and
the WSDL file for the web service is published tohttp://localhost:8080/CalculatorServiceIT/CalculatorITService?wsdl
.
If you examine the WSDL file, you'll notice that it includes an <sp:IssuedToken>
policy assertion
with a <KeyType>
entry that specifies a symmetric proof key.
In other words, the NetBeans IDE generates the appropriate WSDL specifications for a secure conversation
based on the security profile and secure conversation selection that were made when the web service was created.
CalculatorClientIT
project with the NetBeans IDE as follows:trust_samples
directory from the sample application download.CalculatorClientIT
is the client for the CalculatorServiceIT
service.
CalculatorClientIT
project as follows:In response, you should see the following in your browser:
Servlet ClientITServlet at /CalculatorClientIT
Result = 3
CalculatorServiceET
as follows:sc_samples
directory from the sample application download.CalculatorServiceET
is a service that was created with an STS Issued Endorsing Token profile
using a PublicKey
proof key. This is illustrated in Figure 5.
![]() |
Figure 5. CalculatorServiceET Security Configuration |
CalculatorServiceET project as follows:- Right-click the CalculatorServiceET node in the Projects window.
- Select Run.
In response, the CalculatorServiceET
service is deployed to the GlassFish v2 application server and
the WSDL file for the web service is published to
http://localhost:8080/CalculatorServiceET/CalculatorETService?wsdl
.
If you examine the WSDL file, you'll notice that it includes an <sp:IssuedToken>
policy assertion
with a <KeyType>
entry that specifies a PublicKey
proof key type.
<ns2:IssuedToken ns2:IncludeToken=
"http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702/IncludeToken/AlwaysToRecipient">
...
<ns2:RequestSecurityTokenTemplate>
<ns7:KeyType>
http://docs.oasis-open.org/ws-sx/ws-trust/200512/PublicKey
</ns7:KeyType>
<ns8:TokenType>
http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV1.1
</ns8:TokenType>
</ns2:RequestSecurityTokenTemplate>
</ns2:IssuedToken>
- Open the
CalculatorClientET
project with the NetBeans IDE as follows:- Select Open Project from the File menu.
- Browse to the
trust_samples
directory from the sample application download. - Select CalculatorClientET in the Open Project window.
- Click the Open Project Folder button.
CalculatorClientET
is the client for the CalculatorServiceET
service.
- Run the
CalculatorClientET
project as follows:- Right-click the CalculatorClientET node in the Projects window.
- Select Run.
Servlet ClientETServlet at /CalculatorClientET
Result = 9
- Open the
CalculatorServiceST
project as follows:- Select Open Project from the File menu.
- Browse to the
sc_samples
directory from the sample application download. - Select CalculatorServiceST in the Open Project window.
- Click the Open Project Folder button.
CalculatorServiceST
is a service that was created with an STS Issued Supporting
Token profile using no proof key. This is illustrated in Figure 6.

Figure 6. CalculatorServiceST Security Configuration
.
- Run the
CalculatorServiceST project as follows:- Right-click the CalculatorServiceST node in the Projects window.
- Select Run.
In response, the CalculatorServiceST
service is deployed to the GlassFish v2 application server and
the WSDL file for the web service is published to
http://localhost:8080/CalculatorServiceST/CalculatorServiceSTService?wsdl
.
If you examine the WSDL file, you'll notice that it includes an <sp:IssuedToken>
policy assertion
with a <KeyType>
entry of Bearer
. This indicates that there is no proof key associated
with the assertion.
<ns2:IssuedToken ns2:IncludeToken=
"http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702/IncludeToken/AlwaysToRecipient">
...
<ns2:RequestSecurityTokenTemplate>
<ns6:KeySize>256</ns6:KeySize>
<ns7:KeyType>
http://docs.oasis-open.org/ws-sx/ws-trust/200512/Bearer
</ns7:KeyType>
<ns8:TokenType>
http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV1.1
</ns8:TokenType>
</ns2:RequestSecurityTokenTemplate>
</ns2:IssuedToken>
- Open the
CalculatorClientST
project with the NetBeans IDE as follows:- Select Open Project from the File menu.
- Browse to the
trust_samples
directory from the sample application download. - Select CalculatorClientST in the Open Project window.
- Click the Open Project Folder button.
CalculatorClientST
is the client for the CalculatorServiceST
service.
- Run the
CalculatorClientST
project as follows:- Right-click the CalculatorClientST node in the Projects window.
- Select Run.
In response, you should see the following in your browser:
Servlet ClientSTServlet at /CalculatorClientST
Result = 55
About the Author
Jiandong Guo is a staff engineer and a senior member of the Application Server Web Services Security Group.
He has lead the development of implementations and solutions based on WS-SecureConversation and WS-Trust in the Tango project.
The links to the zip file are broken.
Ulf: Sorry about that. The links to the zip file are now fixed.
It appears that Metro is the only stack with support for WS-Trust. I'm ignoring Axis2 and JBossWS.
So where does it leave me if I'm using say CXF or a commercial stack?
Hello Alwyn,
I don't think CXF support WS-Trust.
As for commercial stacks, maybe only IBM Tivoli and MS WCF.
Note that Sun's OpenSSO also support a hosted STS on top of Metro.
I'm confused by the statement for no proof key: "In this case, the issued token is mainly used as a supporting token for authentication/authorization purpose." as well as the other place you say "authentication/authorization" in the text (for the STS Issued Supporting Token). In this case, I think you just mean "authorization" i.e., "you already know that I am Bob, but am I allowed to do X?". Authentication is determining that I \*am\* Bob--and don't you need something like a client-side certificate or username/password combo to determine that--AFAICT the STS Issued Supporting Token will not help you with that--it just does authorization.
Or do you mean something else by "authentication"--perhaps you would use "identification" by what I'm saying above but use "authentication" for something else?
Thanks,
Glen
Hi Glenn,
Thank you for the comments.
Depend on the different siturations, an STS issued SAML tokens as a supporting tokens can carry on different informations of the users (e.g. AuthenticationStatement with user subject/identity, AttributeStatement with attributes of the user, or extended XACML statement for authorization, etc). So they can be used for authentication, authorization or both.
You may regard issued token just as another type of user credential like usename/password, certtificate, etc.
In many cases, the issued token (as a supporting token) can be the only token (credential) provided by the client, used in the same way as username/password, certificate, etc. You don't need have to use it together with the other types of credentials.
For example, you may have a common use case with the server certificate as the protection token with symmetric binding, and username token as a Signed(Encrypted)SupportingToken for authentication purpose. You may just replace the username toke with an issued token here for the same purpose.
Hope this answers your questions.
Thanks!
Jiandong
Hi! Thanks for the article! Where would I look to find information on how to develop a plug-in for additional authorization mechanisms that control the issuing of tokens according to the user's identity and the targeted service?
Thansk,
Johan
Hello Johan,
1. You need to develope a custom implementation of the STSAuthorizationProvider interface
(http://fisheye5.cenqua.com/browse/~raw,r=1.4/wsit/wsit/rt/src/com/sun/xml/ws/api/security/trust/STSAuthorizationProvider.java).
Here appliesTo is the endpoint URL of the targeted service, and Subject contains the authenticated identity of the user.
For a sample, see here:
http://fisheye5.cenqua.com/browse/~raw,r=1.3/wsit/wsit/samples/ws-trust/src/common/SampleAMSTSAuthorizationProvider.java
2. Plugin your authorization provider to the STS using the standard ServiceFinder mechanism. You may check this blog entry. It is for attribute provider. But authorization provider is handled in the same way:
http://blogs.sun.com/trustjdg/entry/create_customer_sts_with_wsit
3. If you have more questions, please try Metro forum:
http://forums.java.net/jive/forum.jspa?forumID=46
Thanks!
Jiandong