Using the LTPA token

Introduction

If you've ever secured WebSphere Application Server to protect standard J2EE™ resources, like servlets or Enterprise JavaBeans™ (EJBs), you're probably already familiar with the Lightweight Third Party Authentication (LTPA) token. The LTPA token is easy to configure compared to a full Public Key Infrastructure (PKI). In its common form, it is simply a cookie that contains the user domain and the user identifier of the caller. You configure WebSphere Application Server to secure a Web service with the LTPA token the same way as you would configure any other resources using WebSphere Application Server security. The only difference is that, after you perform the standard security configuration, you need to secure the Web service by specifying the use of the LTPA token.

Because it is both encrypted and signed, the LTPA token is quite secure. On top of this, it has an absolute validity period which invalidates its usage after a defined period of time. In terms of interoperability, although the LTPA token is included in a wsse:Security element, the format of the token is proprietary and works only in environments that know how to handle LTPA tokens, like WebSphere Application Server Network Deployment, WebSphere Enterprise Service Bus (ESB), or WebSphere Process Server. Although this can be limiting, you may find that in your SOA infrastructure it makes sense to use different tokens. For example, you might want to use an LTPA token for internal Web services requests, and digital signature for external requests. There are three key advantages to using the LTPA token for Web services security:

• Ease of deployment.
• Improved performance; because the LTPA token is the principal mechanism used by WebSphere Application Server in a secured environment, the overhead to use it in a Web services call is very small.
• Identity propagation.

The purpose of the LTPA token is threefold:

• By conveying a unique identifier of the owner who made the request, it enables propagation of the caller identity.
• By signing the information, it establishes a trust relationship between the WebSphere Application Server requester and the WebSphere Application Server provider.
• By encrypting the information, it ensures the confidentiality of that information, for both the identity and the validity of the token.

BinarySecurityToken

The definition of the LTPA token in the security header follows the Web Services Security: SOAP Message Security 1.0 specification, and is included in a wsse:BinarySecurityToken element. This specification describes how to encode binary security tokens, provides a framework for XML-based tokens, and includes extensibility mechanisms you can use to further describe the characteristics of the tokens that are included with a message. Examples of binary token are X.509 certificates and Kerberos tickets. The value type of the LTPA token is wsst:LTPA where wsst defines the namespace of the token.

You can see these elements in the message below, which was extracted from a SOAP capture using the TCP/IP monitor. The token is included in the envelope (1) of the message, in a SOAP header (2), and the name of the security element is wsse:Security (3). You can recognize the namespace definition of the OASIS SOAP Message Security 1.0 specification (4), and then the BinarySecurityToken element (5) with the ValueType attribute (6). The token is base 64 encoded.

<soapenv:Envelope (1) 
xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <soapenv:Header (2) >
  <wsse:Security (3) soapenv:actor="myActor"
soapenv:mustUnderstand="1" xmlns:wsse="http://docs.oasis-
open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd (4) ">
     <wsse:BinarySecurityToken (5) ValueType="wsst:LTPA (6) "
xmlns:wsst="http://www.ibm.com/websphere/appserver/tokentype/5.0.2">981
XKEk+O46iPB1E2/4YB9HbMVQhu9cMpx3XSAwy1M9OEmJ9iVFZ9VnnQ8kMHCIdtfdqpAJWEr
z8oRISTYLvkDWcEdzsVt6rWzwFgqofzv0Cg/6slXuqnXmLq6SCS9slURSmz1mGOdDleM0XY
yqpcJXXUCnd55KgNOT55H3XOCUz+2wv57Qv0yiLHxx5UGKr44jAMIFQfXmLR8rJosu36Fo3
dxb0RlQ/dBPRKeTTI+eBmn6bmKvFKhHOsG7c/WLeVC8OGWmR2eisXEaCjCLF2IxZ2UwANJj
xOOwPCvbfBSFp9snPISYJumjsOImNZ4VcPA19S1HXcxU=</wsse:BinarySecurityToken
>
  </wsse:Security>
   </soapenv:Header>
   <soapenv:Body>
  .
   </soapenv:Body>
</soapenv:Envelope>

Interoperability

Interoperability is an important concern when developing Web services. Since the LTPA token is a proprietary format and IBM does not publish the specifications that describe the rules for creating and processing this binary security token format, you should only use the LTPA token when you have a compatible infrastructure, such as WebSphere Application Server Network Deployment, WebSphere ESB, or WebSphere Process Server nodes.

However, when you consider your overall SOA infrastructure, you'll likely find that there are many places where you don't need full interoperability, or where the additional cost of interoperability is not warranted. For example, if you know that certain nodes will always be LTPA-compatible, there are compelling reasons to use the LTPA token, such as manageability and performance. For performance, a security principle may promote the use of a more standard token, such as a SAML token, but when you're considering the implementation, you may find that the cost of consuming and generating that token on every hop of the system may counter-balance the need for it on every node. A broad rule of thumb is that where you were already using the LTPA token for simple Web traffic, you can probably also use it for Web services calls.

Identity propagation vs. user repository

The LTPA token provides several features, including authenticating the user with a secure mechanism, since it is encrypted (confidentiality) and signed (integrity), and also provides the a validity period feature. LTPA token is also very useful when propagating an identity, which means that you can pass along the LTPA token in the different tiers of the architecture, and still keep the identity of the caller. Passing the identity of the caller is a common Web services requirement.

However, there's an important aspect to consider regarding repository and identity management, which LTPA token is not intended to address. The identity of the user in the token includes both the user ID and the domain of the user (the LDAP server the user was authenticated against). In a real enterprise, it's always important to consider the different repositories that are going to be used along the chain. If you have several repositories, you need to consider the implications. For example, you may use the LTPA token between two hops, then use another token, such as a digital signature, where the DN of the user is specified in both user repositories.

Sample LTPA token scenario

In this section, you can see how the LTPA token is used in a real scenario. The example company has already chosen to use an ESB, and has a portal. It also integrates various legacy back-ends, including Microsoft ® .NET, that are both internal and external.

The red lines indicate the SOAP-based communication. The portal provides a Web user interface, but accesses the application using Web services, which go through an ESB. All the communication between the following nodes may be secured using an LTPA token:

• The portal (CN01) and the ESB (CN04)
• The DataPower® node (CN02) and the ESB (CN04)
• The ESB (CN04) and the Application Server node acting as a SOAP intermediary (CN05)
• The WebSphere Application Server node (CN06) and the other WebSphere Application Server node (CN08) acting as a legacy application.

In the case of an external invocation, for example, from the external Services Consumer (EU03) to a service exposed on the ESB (CN04), you might use a Username Token to the DataPower node (CN07), and an LTPA token from the DataPower node (CN07) to the ESB (CN04).

As you can see, there is no single solution, and other combinations of tokens could be used, but it's important that you clearly identify where it makes sense to use an LTPA token. (The LTPA token is currently supported as a cookie in WebSphere DataPower SOA Appliances; support for the LTPA token as a WS security element in WebSphere DataPower SOA Appliances is forthcoming.)

The scenario

We'll go through the following sample scenario to configure and secure an application using the LTPA token for the Web services call, and also for the Web application.

In this scenario, a Web application enables the user to convert the temperature from Celsius to Fahrenheit and back again. The application accesses a temperature conversion service, which could be an internal service. This service requires the Web services consumer to authenticate before using the service. This is a simple scenario with no real business value, except that it lets us concentrate just on the security aspects. Securing a more complex application and Web services would be just as easy.

We'll use the same application used in Part 2: Username Token and SSL.

First, the user authenticates to the secured Web application. The application requires a user ID and password by sending a 401 challenge, then the browser sends back the user ID and password included in the HTTP authorization header. The Web application, which is the standard JSP Web services test application, authenticates the user and creates the LTPA token. Second, the Web services requester generates the Web services security header, including the base 64 encoded LTPA token. Third, the Web services provider, including the secured temperature converter service, expects an LTPA token. The security handler parses the security header using the TokenConsumer. Then, using a JAAS callback handler and a login module, it validates the LTPA token, validating both the signature of the token and the validity time. It also extracts the identity of the caller, which is checked against the registry. If all the validations are passed, a JAAS-based security context is created, including the identity of the user in a JAAS subject. Notice that at this time there is no access control validation. Authorization is achieved when the service implementation, session EJB, is called using the EJB security model. For more information on JAAS, see Part 2.

To summarize the configuration explained in Part 2, the service is implemented with a stateless session EJB, which is exposed on the SOAP HTTP channel. The EJB is secured using standard J2EE security. IBM Tivoli Directory Server (ITDS) is used as the registry. Three users are defined: bob, wasadmin and ldapbind; and two groups: agents and managers. WebSphere Application Server has global security with LTPA and LDAP. We'll use IBM Rational® Application Developer with V6.0.2.5 of the test server.

Summary of the steps

To implement the scenario described above, you will execute the following steps. We'll assume that you're using the test environment; in a complex WebSphere Application Server environment, where several cells are in use, you need to manage the keys associated with the LTPA token, basically exporting and importing the keys between the different cells. We'll also assume that the development environment is correctly set up as described in Part 2 of this series. That is, Web services development capabilities are enabled and the EAR files have been imported into the workbench. These are the major steps, with specific details presented in the sections that follow:

1. Secure the Web application.
2. Configure the Web services requester to pass the LTPA token.
3. Configure the Web services provider to consume the LTPA token.
4. Test the application.

Step 1: Secure the Web application

We want to secure the sample JSP application that is automatically generated when selecting the generation of the JSP sample proxy application. To do this:

1. Add the agents and managers roles to the router Web application as follows:
   1. Open the deployment descriptor of the TemperatureConverterClientWeb.
   2. Click the Security tab.
   3. In the Security Roles section, click Add.
   4. Enter agents, then click OK.
   
   
   
   
   
2. Add a security constraint for this Web application:
   1. Click Add.
   2. Enter WS_Access, then click Next.
   3. Enter All_resources for the resource name.
   4. Select GET and POST, then click Add to add the pattern, and click /* for the name of the pattern.
3. Add the authorized roles:
   1. Click Add and enter agents_authz for the description.
   2. Select agents and click Finish.
   
   
   
   
   
4. Complete the EAR file configuration:
   1. Open the deployment descriptor of the TemperatureConverterEAR, and click the Security tab.
   2. Click Gather, then select the agents.
   3. Check Users/Groups and click Add for the group definition.
   4. Enter agents for the Group name, then click OK
5. Follow the same steps for the managers.

The TemperatureconverterRouterWeb application is now secured.

Step 2: Secure the Web service requester to pass the LTPA token

To enable the Web service requester to pass the LTPA token, do the following:

6. In Rational Application Developer, open the deployment descriptor of the TemperatureConverterClientWeb application by double-clicking Web services => Client => TemperatureConverterClientWeb.
7. Click the WS Extension tab.
8. Select Request Generator Configuration => Security Token.
9. Click Add, then select LTPAToken, specify LTPA for the name, and click OK.
   
   
   
   
10. Click WS Binding under Security Request Generator Binding Configuration => Token Generator, then click Add.
11. Complete the Token Generator dialog:
    1. For Token generator name, specify LTPA_Token_Gen.
    2. For Token generator class, select com.ibm.wsspi.wssecurity.token.LTPATokenGenerator.
    3. For Security token, select LTPA.
    4. Check Use value type.
    5. For Value type, select LTPA Token.
    6. For Call back handler, select com.ibm.wsspi.wssecurity.auth.callack.LTPATokenCallbackHandler.
    7. Click OK, then Save.
       
       
       
       
12. Click OK.

Step 3: Configure the Web service provider to consume the LTPA token

13. In Rational Application Developer, open the deployment descriptor of the TemperatureConverter application by selecting Web services => Services => TemperatureConverterService, then clicking the Extensions tab.
14. Select Request Consumer Service Configuration Details => Required Security Token.
15. Click Add and select LTPA Token.
16. Select the port type on which you want to configure security (under Port component binding => TemperatureConverter).
17. Enter LTPA as the name, select LTPAToken for the token type, keep the usage type as Required, then click OK.
    
    
    
    
18. Select Request Consumer Service Configuration Details => Caller Part.
19. Click Add and enter LTPA_Caller as the name, select LTPA Token as the token type, and click OK.
    
    
    
    
20. To configure the token consumer, click on the Bindings Configuration tab, then expand Request Consumer Binding Configuration Details => Token Consumer.
21. Click Add, then fill in the Token Consumer dialog:
    1. For the Token consumer name, enter LTPA_token_con.
    2. For the Token consumer class, select com.ibm.wsspi.wssecurity.token.LTPATokenConsumer.
    3. For the Security token, select LTPA.
    4. Check Use value type.
    5. For the Value type, select LTPA Token.
    6. Click OK.
       
       
       
       
22. Click Save.

You have now secured both the requester and the provider with LTPA token at the message level.

Test the application

To test the application:

23. Open a browser and enter the URL of the sample JSP application.
24. When prompted, enter bob and his password.
25. Select setEndpoint(java.lang.String) in the left pane, and set the endpoint appropriately, depending on your port configuration and whether you want to go through the TCP/IP monitor or not. For example: http://localhost:9081/TemperatureConverterRouterWeb/services/TemperatureConverter.
26. Select celsiusToFahrenheit(int) in the left pane.
27. Enter a value in the Celsius field and click Invoke. You should see a value in Fahrenheit. You should also the following trace in the logs: SystemOut O Subject is : bob.

Examine the requests and responses

Now, let's take a look at the SOAP messages between the Web service requester and the Web service provider, and between the browser and the Web application. We're using the TCP/IP monitor as explained in Part 2 of this series.

Hint: It's a good practice to have the TCP/IP monitor started in a standalone mode. If you have WebSphere Application Server installed, you can create a shortcut with the following definition: <was_home>\java\bin\java.exe -cp <was_home>\lib\webservices.jar com.ibm.ws.webservices.engine.utils.tcpmon,where was_home is the directory where WebSphere Application Server is installed.

HTTP request

Here is the HTTP request between the Web browser and the Web application. You can see the LTPA token as a cookie.

POST /TemperatureConverterClientWeb/sampleTemperatureConverterProxy/Result.jsp HTTP/1.1
Host: 127.0.0.1
User-Agent: Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US; rv:1.7.10) 
Gecko/20050716 Firefox/1.0.6
Accept: 
text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;
q=0.8,image/png,*/*;q=0.5
Accept-Language: en-us,en;q=0.5
Accept-Encoding: gzip,deflate
Accept-Charset: ISO-8859-1,utf-8;q=0.7,*;q=0.7
Keep-Alive: 300
Connection: keep-alive
Referer: 
http://127.0.0.1:9083/TemperatureConverterClientWeb/sampleTemperature
ConverterProxy/Input.jsp?method=10
Cookie: LTPA Token =981XKEk+O46iPB1E2/4YB9HbMVQhu9cMpx3XSAwy1M9OEmJ9iVFZ9VnnQ8kMHCIdtfdqpA
JWErz8oRISTYLvkDWcEdzsVt6rWzwFgqofzv0Cg/6slXuqnXmLq6SCS9slURSmz1mGOdDle
M0XYyqpcJXXUCnd55KgNOT55H3XOCUz+2wv57Qv0yiLHxx5UGKr44jAMIFQfXmLR8rJosu3
6Fo3dxb0RlQ/dBPRKeTTI+eBmn6bmKvFKhHOsG7c/WLeVC8OGWmR2eisXEaCjCLF2IxZ2Uw
ANJjxOOwPCvbfBSFp9snPISYJumjsOImNZ4VcPA19S1HXcxU=;
JSESSIONID=0000H66Q8DabMuhdGo4hIs1pdi3:-1
Authorization: Basic ZGVzcHJldHM6cGFzc3dvcmQ=
Content-Type: application/x-www-form-urlencoded
Content-Length: 23

method=10&celsius13=123

SOAP request

Here is the SOAP request between the Web service requester and the Web services provider. You can see the same LTPA token at the message level.

POST /TemperatureConverterEJBRouter/services/TemperatureConverter HTTP/1.1
Host: 127.0.0.1
Accept: application/soap+xml,multipart/related,text/*
User-Agent: IBM WebServices/1.0
Cache-Control: no-cache
Pragma: no-cache
SOAPAction: ""
Connection: Keep-Alive
Content-Type: text/xml; charset=utf-8
Content-Length: 1076
Date: Mon, 15 Aug 2005 12:33:39 GMT

<soapenv:Envelope xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <soapenv:Header>
  <wsse:Security soapenv:actor="myActor"soapenv:mustUnderstand="1"
xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-
wss-wssecurity-secext-1.0.xsd">
     <wsse:BinarySecurityToken ValueType="wsst:LTPA"
xmlns:wsst="http://www.ibm.com/websphere/appserver/tokentype/5.0.2">981
XKEk+O46iPB1E2/4YB9HbMVQhu9cMpx3XSAwy1M9OEmJ9iVFZ9VnnQ8kMHCIdtfdqpAJWEr
z8oRISTYLvkDWcEdzsVt6rWzwFgqofzv0Cg/6slXuqnXmLq6SCS9slURSmz1mGOdDleM0XY
yqpcJXXUCnd55KgNOT55H3XOCUz+2wv57Qv0yiLHxx5UGKr44jAMIFQfXmLR8rJosu36Fo3
dxb0RlQ/dBPRKeTTI+eBmn6bmKvFKhHOsG7c/WLeVC8OGWmR2eisXEaCjCLF2IxZ2UwANJj
xOOwPCvbfBSFp9snPISYJumjsOImNZ4VcPA19S1HXcxU=</wsse:BinarySecurityToken
>
  </wsse:Security>
   </soapenv:Header>
   <soapenv:Body>
  <p681:celsiusToFahrenheit xmlns:p681="http://ejb.ad.ibm.com">
     <celsius>123</celsius>
  </p681:celsiusToFahrenheit>
   </soapenv:Body>
</soapenv:Envelope>

SOAP response

Here is the SOAP response between the Web service requester and the Web service provider.

HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Language: en-GB
Content-Length: 462
Date: Mon, 15 Aug 2005 12:33:39 GMT
<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <soapenv:Header/>
   <soapenv:Body>
  <p681:celsiusToFahrenheitResponse xmlns:p681="http://ejb.ad.ibm.com">
     <celsiusToFahrenheitReturn>253.4</celsiusToFahrenheitReturn>
  </p681:celsiusToFahrenheitResponse>
   </soapenv:Body>
</soapenv:Envelope>

HTTP response

Here is the HTTP response between the Web browser and the Web application.

HTTP/1.1 200 OK
Content-Type: text/html;charset=UTF-8
Content-Language: en-GB
Content-Length: 124
Date: Mon, 15 Aug 2005 12:33:39 GMT
<HTML>
<HEAD>
<TITLE>Result</TITLE>
</HEAD>
<BODY>
<H1>Result</H1>
253.4
</BODY>
</HTML>
   

Previous | Next