X
Try Oracle Cloud Platform For Free

Using WS-Trust Support in Metro to Secure Web Services

Guest Author

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


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.

In essence, WS-Trust specifies the following:

  • A general framework for token exchanges.
  • A model for brokering trust in web services.
  • A Security Token Service (STS) framework.
  • Protocols for issuing, renewing, validating, and canceling security tokens.

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:



   <sp:X509Token
      sp:IncludeToken=
      "http://schemas.xmlsoap.org/ws/2005/07/securitypolicy/
      IncludeToken/AlwaysToRecipient">
                        <wsp:Policy>
                              <sp:RequireThumbprintReference />
                              <sp:WssX509V3Token10 />
                        </wsp:Policy>
   </sp:X509Token>




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:



   <sp:IssuedToken sp:IncludeToken=
    "http://schemas.xmlsoap.org/ws/2005/07/securitypolicy/
    IncludeToken/AlwaysToRecipient">
       <sp:Issuer>
           <Address xmlns="http://www.w3.org/2005/08/addressing">
               http://localhost:8080/jaxws-sts/sts
           </Address>
           <Metadata xmlns=
              "http://schemas.xmlsoap.org/ws/2004/09/mex">
               <MetadataSection>
                   <MetadataReference>
                         <Address xmlns=
                         "http://www.w3.org/2005/08/addressing">
                          http://localhost:8080/jaxws-sts/sts
                         </Address>
                   </MetadataReference>
               </MetadataSection>
           </Metadata>
       </sp:Issuer>
   </sp:IssuedToken>




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:

  • Supports token issuance and token validation protocols.
  • Supports the STS framework.
  • Supports building an STS as an independent web service.
  • Supports client and service authentication and security with issued tokens from an STS
    within the general framework of WS-Security and WS-SecurityPolicy.
  • Provides a general framework for building an STS as a web service for issuing
    security tokens.
  • Supports authentication and secure communication between a client and an STS in the same way as for
    a regular web service.
  • Supports issuing SAML 1.0, SAML 1.1 and SAML2.0 tokens, by default.
  • Supports the issuing of symmetric proof keys, public proof keys, and no proof keys.
  • Can be extended to support the issuing of other types of tokens.
  • Allows for plugging in additional authorization mechanisms that control the issuing of
    tokens according to the user's identity and the targeted service.
  • Allows for plugging in user mappings that control the user identity/attributes carried in the
    SAML token issued by an STS for different services.

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:



   <sp:IssuedToken sp:IncludeToken=
    "http://schemas.xmlsoap.org/ws/2005/07/securitypolicy/IncludeToken/AlwaysToRecipient">
       <sp:RequestSecurityTokenTemplate>
           <t:TokenType xmlns=
              "http://schemas.xmlsoap.org/ws/2005/02/trust">
              http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV1.1
           </t:TokenType>
              <t:KeyType xmlns=
                "http://schemas.xmlsoap.org/ws/2005/02/trust">
                "http://schemas.xmlsoap.org/ws/2005/02/trust/SymmetricKey
              </t:KeyType>
              <t:KeySize xmlns=
                "http://schemas.xmlsoap.org/ws/2005/02/trust">256
              </t:KeySize>                
       </sp:RequestSecurityTokenTemplate>
              <wsp:Policy>
                <sp:RequireDerivedKeys/>
                <sp:RequireInternalReference/>
              </wsp:Policy>
   </IssuedToken>




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 to
PublicKey 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:

  • Username Authentication with Symmetric Keys
  • Mutual Certificates Security
  • Transport Security (SSL)
  • Message Authentication over SSL
  • SAML Authorization over SSL
  • Endorsing Certificate
  • SAML Sender Vouches with Certificates
  • SAML Holder of Key
  • STS Issued Token
  • STS Issued Token with Service Certificate
  • STS Issued Endorsing Token
  • STS Issued Supporting Token

Four of these profiles secure web services with STS-issued tokens:

  • STS Issued Token
  • STS Issued Token with Service Certificate
  • STS Issued Endorsing Token
  • STS Issued Supporting Token

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.













Configuring Security for a Web Service in NetBeans

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.













Configuring Security for a Web Service in NetBeans

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:

  • STS Issued Token. In this case the issued token is used as the primary protection token so it must associated with
    a proof key of SymmetricKey or PublicKey type.
  • STS Issued Token with Service Certificate. In this case, the issued token is used to protect the request message
    and the service certificate for the response message. A proof key of SymmetricKey or PublicKey
    is required.
  • STS Issued Endorsing Token. In this case, the service certificate is used to protect the message. The issued token
    is used for client authentication and the integrity of the message with an endorsing signature. A proof key of
    SymmetricKey or PublicKey is required.
  • STS Issued Supporting Token. In this case the issued token provides user information for authentication/authorization
    purposes. No proof key 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.

Running the Samples

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:


  1. If you haven't already done so, download
    NetBeans IDE 6.5 Beta
    and GlassFish V2 Update Release 2 (v2 ur2).

  2. Start the NetBeans IDE.

  3. If GlassFish v2 is not one of the NetBeans application servers, add it as follows:
    • Right-click the Servers node in

      the Services window.
    • Select Add Server.
    • Select GlassFish v2.
    • Click the Next button.
    • Click the Browse button and browse to the location that you installed GlassFish v2.
    • Click the Choose button.
    • Click the Next button.
    • Set the Admin Password to the default, adminadmin, unless you chose a different password for GlassFish.
    • Click the Finish button.

  4. Update the Metro JAR files in GlassFish v2 to Metro 1.3.1 versions as follows:
    • Download Metro 1.3.1.
    • Copy the 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 installation
      directory.
    • Copy the webservices-api.jar file from Metro 1.3.1 to <GF_Install>\\lib\\endorsed.

  5. Add testing certificates to GlassFish as described in
    Section 12.5.
    Configuring Keystores and Truststores     in the Metro Users Guide.

  6. Download the sample application package and extract its contents. You should now see a newly extracted directory
    trust_samples.

  7. Open the STS project in the NetBeans IDE as follows:
    • Select Open Project from the File menu.
    • Browse to the trust_samples directory from the sample application download.
    • Select STS in the Open Project window.
    • Click the Open Project Folder button.

    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.













    STSService Security Configuration

    Figure 3. STSService Security Configuration




  8. Run

    the STS project as follows:
    • Right-click the STS node in the Projects window.
    • Select Run.

    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.

  9. Open the CalculatorServiceIT 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 CalculatorServiceIT in the Open Project window.
    • Click the Open Project Folder button.

    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.













    CalculatorServiceIT Security Configuration

    Figure 4. CalculatorServiceIT Security Configuration



    .


  10. Run the CalculatorServiceIT project as follows:
    • Right-click the CalculatorServiceIT node in the Projects window.
    • Select Run.

    In response, the CalculatorServiceIT service is deployed to the GlassFish v2 application server and
    the WSDL file for the web service is published to
    http://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.



       <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/SymmetricKey
       </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>




    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.


  11. Open the CalculatorClientIT 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 CalculatorClientIT in the Open Project window.
    • Click the Open Project Folder button.

    CalculatorClientIT is the client for the CalculatorServiceIT service.

  12. Run the CalculatorClientIT project as follows:
    • Right-click the CalculatorClientIT node in the Projects window.
    • Select Run.

    In response, you should see the following in your browser:

       Servlet ClientITServlet at /CalculatorClientIT
       Result = 3

  13. Open the CalculatorServiceET as follows:
    • Select Open Project from the File menu.
    • Browse to the sc_samples directory from the sample application download.
    • Select CalculatorServiceET in the Open Project window.
    • Click the Open Project Folder button.

    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.













    CalculatorServiceET Security Configuration

    Figure 5. CalculatorServiceET Security Configuration




  14. Run the 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>




  15. 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.

  16. Run the CalculatorClientET project as follows:
    • Right-click the CalculatorClientET node in the Projects window.
    • Select Run.
       Servlet ClientETServlet at /CalculatorClientET
       Result = 9


  17. 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.













    CalculatorServiceST Security Configuration

    Figure 6. CalculatorServiceST Security Configuration



    .


  18. 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>




  19. 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.

  20. 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.

Join the discussion

Comments ( 8 )
  • Ulf Dittmer Thursday, October 16, 2008

    The links to the zip file are broken.


  • Edward Ort Thursday, October 16, 2008

    Ulf: Sorry about that. The links to the zip file are now fixed.


  • Alwyn Schoeman Monday, October 20, 2008

    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?


  • Jiandong Guo Monday, October 20, 2008

    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.


  • Glen Wednesday, October 29, 2008

    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


  • Jiandong Wednesday, October 29, 2008

    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


  • Johan Eltes Thursday, January 15, 2009

    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


  • Jiandong Guo Friday, January 16, 2009

    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


Please enter your name.Please provide a valid email address.Please enter a comment.CAPTCHA challenge response provided was incorrect. Please try again.

Recent Content