Using WS-Trust Support in Metro to Secure Web Services

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.

Comments:

The links to the zip file are broken.

Posted by Ulf Dittmer on October 15, 2008 at 06:19 PM PDT #

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

Posted by Edward Ort on October 15, 2008 at 09:07 PM PDT #

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?

Posted by Alwyn Schoeman on October 19, 2008 at 10:55 PM PDT #

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.

Posted by Jiandong Guo on October 20, 2008 at 02:30 AM PDT #

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

Posted by Glen on October 28, 2008 at 11:11 PM PDT #

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

Posted by Jiandong on October 29, 2008 at 04:27 AM PDT #

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

Posted by Johan Eltes on January 15, 2009 at 02:40 PM PST #

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

Posted by Jiandong Guo on January 16, 2009 at 04:11 AM PST #

Post a Comment:
Comments are closed for this entry.
About

edort

Search

Archives
« April 2014
SunMonTueWedThuFriSat
  
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
   
       
Today