Download PDF - IBM Redbooks

Security in WebSphere 

Application Server Version 6.1 

and J2EE 1.4 on z/OS 

WAS and J2EE security concepts and 

their implementation on z/OS 

Security integration scenarios, 

including SPNEGO and CSIv2 

Web services security 

and SSL in WAS V6.1 

ibm.com/redbooks 

Front cover 

Alex Louwe Kooijmans 

Yukari Hanya 

Keith Jabcuga 

Marc van der Meer 

Eran Yona 

Gabriel Mogos 

Foulques de Valence

International Technical Support Organization 

Security in WebSphere Application Server Version 

6.1 and J2EE 1.4 on z/OS 

December 2007 

SG24-7384-00

Note: Before using this information and the product it supports, read the information in 

“Notices” on page xi. 

First Edition (December 2007) 

This edition applies to WebSphere Application Server Version 6.1 for z/OS. 

© Copyright International Business Machines Corporation 2007. All rights reserved. 

Note to U.S. Government Users Restricted Rights -- Use, duplication or disclosure restricted by GSA ADP 

Schedule Contract with IBM Corp.

Contents 

Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi 

Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii 

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii 

The team that wrote this book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii 

Become a published author . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvi 

Comments welcome. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvi 

Chapter 1. Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 

1.1 Securing WAS for z/OS simplified. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 

1.2 WAS and security layers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 

1.2.1 Security terms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 

1.2.2 Security layering overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 

1.2.3 z/OS security overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 

1.2.4 Java security overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 

1.2.5 WebSphere security overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 

1.3 Securing WAS and applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 

1.3.1 WAS and security checkpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 

1.3.2 Web client authentication overview. . . . . . . . . . . . . . . . . . . . . . . . . . 15 

1.3.3 EJB client authentication overview . . . . . . . . . . . . . . . . . . . . . . . . . . 18 

1.3.4 MQ client authentication overview . . . . . . . . . . . . . . . . . . . . . . . . . . 19 

1.3.5 Web services security overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 

1.3.6 Backend connectivity security overview . . . . . . . . . . . . . . . . . . . . . . 22 

1.3.7 User registry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 

1.3.8 Authorization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 

Chapter 2. WebSphere security design. . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 

2.1 Chapter objectives. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 

2.2 Network protocol architecture overview . . . . . . . . . . . . . . . . . . . . . . . . . . 29 

2.3 SSL overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 

2.3.1 SSL handshake. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 

2.4 Authorization and EJB roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 

2.5 Our scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 

2.5.1 Scenario 1 - authentication in HTTP server . . . . . . . . . . . . . . . . . . . 34 

2.5.2 Scenario 2 - authentication in reverse proxy security server . . . . . . 37 

2.5.3 Scenario 3 - J2EE client authentication using CSIv2 . . . . . . . . . . . . 40 

2.5.4 Scenario 4 - J2EE server authentication using CSIv2 . . . . . . . . . . . 43 

2.5.5 Scenario 5 - JCA custom principal mapping . . . . . . . . . . . . . . . . . . . 46 

2.5.6 Scenario 6 - Web services authentication. . . . . . . . . . . . . . . . . . . . . 51 

© Copyright IBM Corp. 2007. All rights reserved. iii

2.5.7 Scenario 7 - WMQ client authentication . . . . . . . . . . . . . . . . . . . . . . 53 

2.5.8 Scenario 8 - authorization using external authorization server . . . . . 56 

2.5.9 Scenario 9 - bridged security between z/OS and distributed using JAAS 

58 

2.5.10 Scenario 10 - centralized user registry using LDAP on z/OS . . . . . 60 

Chapter 3. Web container security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 

3.1 Web authentication improvements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 

3.1.1 Separate Web authentication and authorization . . . . . . . . . . . . . . . . 64 

3.1.2 Web authentication enhanced control. . . . . . . . . . . . . . . . . . . . . . . . 64 

3.2 Implementation with the admin console . . . . . . . . . . . . . . . . . . . . . . . . . . 65 

3.2.1 General settings at the cell level . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 

3.2.2 Control server level Web authentication behavior. . . . . . . . . . . . . . . 67 

3.3 Why you should use these options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 

Chapter 4. Application security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 

4.1 Administrative security enablement. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 

4.2 Application security enablement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 

Chapter 5. Web services security introduction . . . . . . . . . . . . . . . . . . . . . 75 

5.1 SOA, Web services, z/OS, and security . . . . . . . . . . . . . . . . . . . . . . . . . . 76 

5.2 Web services security exposures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 

5.3 Web services message and transport security . . . . . . . . . . . . . . . . . . . . . 78 

5.3.1 When to use message layer security . . . . . . . . . . . . . . . . . . . . . . . . 80 

5.3.2 When to use transport layer security. . . . . . . . . . . . . . . . . . . . . . . . . 80 

5.4 Web services message layer security with WS-Security. . . . . . . . . . . . . . 81 

5.4.1 End-to-end security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 

5.4.2 WS-Security standard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 

5.4.3 WS-Security support in WebSphere . . . . . . . . . . . . . . . . . . . . . . . . . 83 

5.4.4 WS-I basic security profile support . . . . . . . . . . . . . . . . . . . . . . . . . . 84 

5.4.5 WS-Security high-level architecture . . . . . . . . . . . . . . . . . . . . . . . . . 85 

5.4.6 Message authentication, integrity, confidentiality, ID assertion. . . . . 86 

5.5 Web services transport layer security . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90 

5.5.1 Web services transports introduction . . . . . . . . . . . . . . . . . . . . . . . . 90 

5.5.2 Point-to-point security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 

5.5.3 The HTTP(S) transport protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 

5.5.4 JMS transport security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 

5.5.5 RMI-IIOP security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 

5.5.6 Enterprise Service Bus security . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 

5.6 Our SecurityInfo Web service application and environment . . . . . . . . . . . 98 

5.6.1 SecurityInfo J2EE architecture in our environment . . . . . . . . . . . . . . 99 

5.6.2 Our test environment. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100 

5.6.3 SecurityInfo Web service implementation . . . . . . . . . . . . . . . . . . . . 100 

5.6.4 SecurityInfo deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101 

iv Security in WebSphere Application Server Version 6.1 and J2EE 1.4 on z/OS

5.6.5 SecurityInfo in action. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104 

Chapter 6. Web services message layer security . . . . . . . . . . . . . . . . . . 107 

6.1 How to configure Web services message layer security . . . . . . . . . . . . . 108 

6.1.1 Web services message layer security and WS-Security. . . . . . . . . 108 

6.1.2 Web services message layer security configuration tools. . . . . . . . 109 

6.1.3 Web services message layer security configuration files . . . . . . . . 110 

6.1.4 Web services message-layer security configuration components . 114 

6.2 Authentication with a security token . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115 

6.2.1 Authentication support with WS-Security . . . . . . . . . . . . . . . . . . . . 116 

6.2.2 Authentication scenario description . . . . . . . . . . . . . . . . . . . . . . . . 117 

6.2.3 Authentication configuration overview. . . . . . . . . . . . . . . . . . . . . . . 118 

6.2.4 Configuring the Web service requestor for security token . . . . . . . 119 

6.2.5 Configuring the z/OS Web service provider for security token . . . . 123 

6.2.6 Validating authentication with a security token . . . . . . . . . . . . . . . . 129 

6.3 Integrity with XML digital signature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131 

6.3.1 Integrity support with WS-Security . . . . . . . . . . . . . . . . . . . . . . . . . 131 

6.3.2 Integrity scenario description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132 

6.3.3 Integrity configuration overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . 133 

6.3.4 Configuring the requestor for request XML digital signature. . . . . . 135 

6.3.5 Configuring the z/OS provider for request XML digital signature . . 146 

6.3.6 Configuring the z/OS provider for response XML digital signature . 154 

6.3.7 Configuring the requestor for response XML digital signature . . . . 159 

6.3.8 Validating integrity with XML digital signature. . . . . . . . . . . . . . . . . 159 

6.4 Confidentiality with XML encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164 

6.4.1 Confidentiality support with WS-Security . . . . . . . . . . . . . . . . . . . . 165 

6.4.2 Confidentiality scenario description. . . . . . . . . . . . . . . . . . . . . . . . . 165 

6.4.3 Confidentiality scenario key prerequisites. . . . . . . . . . . . . . . . . . . . 167 

6.4.4 Confidentiality configuration overview. . . . . . . . . . . . . . . . . . . . . . . 171 

6.4.5 Configuring the requestor for request XML encryption . . . . . . . . . . 172 

6.4.6 Configuring the z/OS provider for request XML encryption. . . . . . . 178 

6.4.7 Configuring the z/OS provider for response XML encryption . . . . . 183 

6.4.8 Configuring the z/OS requestor for response XML encryption . . . . 185 

6.4.9 Validating confidentiality with XML encryption . . . . . . . . . . . . . . . . 188 

6.4.10 Confidentiality using hardware cryptography . . . . . . . . . . . . . . . . 192 

6.5 Identity assertion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192 

6.5.1 Identity assertion support with WS-Security . . . . . . . . . . . . . . . . . . 193 

6.5.2 Identity assertion scenario description . . . . . . . . . . . . . . . . . . . . . . 194 

6.5.3 Identity assertion configuration overview . . . . . . . . . . . . . . . . . . . . 195 

6.5.4 Configuring the Web service requestor for identity assertion . . . . . 196 

6.5.5 Configuring the z/OS Web service provider for identity assertion. . 199 

6.5.6 Configuring the trust relationship for identity assertion . . . . . . . . . . 203 

6.5.7 Validating identity assertion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204 

Contents v

Chapter 7. Secure Sockets Layer (SSL) . . . . . . . . . . . . . . . . . . . . . . . . . . 209 

7.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210 

7.2 Centrally managed SSL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210 

7.3 WebSphere V6.1 for z/OS SSSL to JSSE changes . . . . . . . . . . . . . . . . 213 

7.4 SSL RACF certificate management . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214 

7.4.1 Viewing certificates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215 

7.4.2 Monitoring certificate expiration . . . . . . . . . . . . . . . . . . . . . . . . . . . 218 

7.4.3 Importing certificates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220 

7.4.4 Exporting certificates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220 

7.4.5 Deleting certificates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221 

7.4.6 Deleting keystores and truststores . . . . . . . . . . . . . . . . . . . . . . . . . 222 

7.5 Hardware crypto and Java crypto providers . . . . . . . . . . . . . . . . . . . . . . 222 

7.5.1 Choosing a JCE provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223 

7.5.2 Admin console keystore types . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224 

7.5.3 Keystores and truststores . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226 

7.6 IBMJCECCA and IBMJCE characteristics . . . . . . . . . . . . . . . . . . . . . . . 227 

7.7 SSL and JCERACFKS keystore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229 

7.7.1 Keyring and certificate setup. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229 

7.7.2 WebSphere admin console setup . . . . . . . . . . . . . . . . . . . . . . . . . . 230 

7.8 Hardware crypto using a JCECCARACFKS keystore. . . . . . . . . . . . . . . 233 

7.8.1 Keyring and certificate setup with keys in hardware . . . . . . . . . . . . 234 

7.8.2 Installing the unrestricted Java policy jars. . . . . . . . . . . . . . . . . . . . 236 

7.8.3 Update the java.security file with the IBMJCECCA provider. . . . . . 236 

7.8.4 Admin console setup. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237 

7.9 SSL troubleshooting and traces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239 

7.9.1 Diagnostic steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240 

7.9.2 SSL traces. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241 

7.9.3 Common errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242 

Chapter 8. Web services transport security . . . . . . . . . . . . . . . . . . . . . . . 245 

8.1 Authentication with HTTP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246 

8.1.1 HTTP basic authentication scenario description . . . . . . . . . . . . . . . 246 

8.1.2 Configuring the z/OS Web service provider with authentication . . . 247 

8.1.3 Configuring the Web service requestor to authenticate . . . . . . . . . 249 

8.1.4 Validating transport security using HTTP basic authentication . . . . 250 

8.2 Integrity with SSL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252 

8.2.1 Integrity with SSL scenario description . . . . . . . . . . . . . . . . . . . . . . 252 

8.2.2 Integrity scenario prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253 

8.2.3 Configuring the z/OS Web service provider SSL configuration. . . . 255 

8.2.4 Configuring the Web service requestor SSL configuration . . . . . . . 261 

8.2.5 Configuring the z/OS Web service provider for integrity . . . . . . . . . 264 

8.2.6 Configuring the Web service requestor for integrity . . . . . . . . . . . . 264 

8.2.7 Validating integrity with SSL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265 

vi Security in WebSphere Application Server Version 6.1 and J2EE 1.4 on z/OS

8.3 Confidentiality with SSL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268 

8.3.1 Confidentiality with SSL scenario description . . . . . . . . . . . . . . . . . 268 



8.3.4 Configuring the z/OS Web service provider for confidentiality . . . . 269 

8.3.5 Configuring the Web service requestor for confidentiality. . . . . . . . 269 

8.3.6 Validating confidentiality with SSL . . . . . . . . . . . . . . . . . . . . . . . . . 271 

8.4 Confidentiality with SSL using hardware crypto . . . . . . . . . . . . . . . . . . . 272 

8.4.1 Confidentiality with SSL using hardware crypto prerequisites . . . . 272 

8.4.2 Installing the unrestricted Java policy jars. . . . . . . . . . . . . . . . . . . . 275 

8.4.3 Updating the JVM to use the IBMJCECCA provider . . . . . . . . . . . . 275 



8.4.6 Configuring the z/OS Web service provider for confidentiality . . . . 281 

8.4.7 Configuring the Web service requestor for confidentiality. . . . . . . . 281 

8.4.8 Validating confidentiality with SSL using hardware crypto . . . . . . . 281 

8.5 Confidentiality and basic authentication . . . . . . . . . . . . . . . . . . . . . . . . . 282 

8.6 Confidentiality and client certificate authentication . . . . . . . . . . . . . . . . . 282 

8.6.1 Confidentiality and client certificate scenario description . . . . . . . . 283 

8.6.2 Confidentiality and client certificate prerequisites . . . . . . . . . . . . . . 283 



8.6.5 Configuring z/OS Web service provider for authentication . . . . . . . 289 

8.6.6 Validating client certificate authentication . . . . . . . . . . . . . . . . . . . . 291 

Chapter 9. Security attribute propagation and CSIv2 . . . . . . . . . . . . . . . 293 

9.1 Introduction, logins, and tokens. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294 

9.1.1 Security attribute propagation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294 

9.1.2 Initial login versus propagation login . . . . . . . . . . . . . . . . . . . . . . . . 295 

9.1.3 Token framework . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297 

9.2 Horizontal attribute propagation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298 

9.2.1 Horizontal attribute propagation description . . . . . . . . . . . . . . . . . . 298 

9.2.2 Horizontal attribute propagation in action . . . . . . . . . . . . . . . . . . . . 300 

9.2.3 Horizontal attribute propagation implementation. . . . . . . . . . . . . . . 301 

9.2.4 Cross-cell considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302 

9.3 CSIv2 standard identity assertion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305 

9.3.1 CSIv2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305 

9.3.2 CSIv2 standard identity assertion description . . . . . . . . . . . . . . . . . 307 

9.3.3 CSIv2 standard identity assertion in action . . . . . . . . . . . . . . . . . . . 309 

9.3.4 CSIv2 standard identity assertion implementation . . . . . . . . . . . . . 310 

9.3.5 Our CSIv2 identity assertion scenario. . . . . . . . . . . . . . . . . . . . . . . 321 

9.4 Vertical attribute propagation with CSIv2 . . . . . . . . . . . . . . . . . . . . . . . . 328 

9.4.1 Vertical attribute propagation with CSIv2 description . . . . . . . . . . . 328 

Contents vii

9.4.2 Vertical attribute propagation versus CSIv2 identity assertion . . . . 329 

9.4.3 Vertical attribute propagation with CSIv2 in action . . . . . . . . . . . . . 330 

9.4.4 Vertical attribute propagation with CSIv2 implementation. . . . . . . . 331 

9.4.5 Cross-cell considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334 

Chapter 10. User registries. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335 

10.1 Introduction to user registries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336 

10.2 Our scenario and our environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339 

10.3 Standalone LDAP registry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340 

10.3.1 WebSphere and z/OS LDAP SDBM back end (RACF). . . . . . . . . 341 

10.3.2 WebSphere and z/OS LDAP TDBM back end (DB2) . . . . . . . . . . 350 

10.3.3 WebSphere and z/OS LDAP TDBM native authentication . . . . . . 359 

10.4 Federated repositories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363 

10.4.1 What federated repositories are . . . . . . . . . . . . . . . . . . . . . . . . . . 363 

10.4.2 Our federated repositories scenario . . . . . . . . . . . . . . . . . . . . . . . 366 

10.4.3 Federated z/OS LDAP with TDBM back end (DB2) . . . . . . . . . . . 368 

10.4.4 Federated z/OS LDAP TDBM native authentication . . . . . . . . . . . 373 

10.4.5 Federated IBM Tivoli Directory Server . . . . . . . . . . . . . . . . . . . . . 375 

10.5 z/OS local operating system registry. . . . . . . . . . . . . . . . . . . . . . . . . . . 382 

10.5.1 System Authorization Facility (SAF) authorization . . . . . . . . . . . . 383 

10.5.2 OS thread security support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386 

10.5.3 Thread identity support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389 

Chapter 11. SPNEGO and Windows single sign-on. . . . . . . . . . . . . . . . . 391 

11.1 Introducing the SPNEGO TAI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392 

11.1.1 An introduction to Kerberos. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392 

11.1.2 An introduction to trust association interceptor (TAI) . . . . . . . . . . 395 

11.1.3 An introduction to SPNEGO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396 

11.1.4 The WebSphere SPNEGO TAI . . . . . . . . . . . . . . . . . . . . . . . . . . . 396 

11.2 Designing single sign-on with Microsoft Windows domain . . . . . . . . . . 397 

11.2.1 Single sign-on with Microsoft Windows KDC only. . . . . . . . . . . . . 397 

11.2.2 Single sign-on with z/OS KDC and Microsoft Windows KDC . . . . 399 

11.3 Implementing single sign-on using SPNEGO TAI . . . . . . . . . . . . . . . . . 400 

11.3.1 Our environment and our scenario . . . . . . . . . . . . . . . . . . . . . . . . 401 

11.3.2 Configuring the Microsoft Windows server . . . . . . . . . . . . . . . . . . 404 

11.3.3 Configuring WebSphere Application Server for z/OS . . . . . . . . . . 412 

11.3.4 Configuring the Web browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419 

11.3.5 Tips for troubleshooting the SPNEGO TAI configuration . . . . . . . 422 

11.4 Validating single sign-on using the SPNEGO TAI. . . . . . . . . . . . . . . . . 424 

Chapter 12. Operating system security. . . . . . . . . . . . . . . . . . . . . . . . . . . 429 

12.1 Out-of-the-box administrative security. . . . . . . . . . . . . . . . . . . . . . . . . . 430 

12.1.1 Cell-wide common user groups and IDs . . . . . . . . . . . . . . . . . . . . 430 

12.1.2 Security configuration options . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432 

viii Security in WebSphere Application Server Version 6.1 and J2EE 1.4 on z/OS

12.1.3 Security customization jobs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 438 

12.1.4 Comparison of security settings . . . . . . . . . . . . . . . . . . . . . . . . . . 440 

12.2 Automatically generated server IDs . . . . . . . . . . . . . . . . . . . . . . . . . . . 441 

12.3 RACF - mixed-case password support . . . . . . . . . . . . . . . . . . . . . . . . . 443 

12.4 Sync-to-OS thread update. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 444 

Chapter 13. WAS administrative security . . . . . . . . . . . . . . . . . . . . . . . . . 447 

13.1 Security configuration and administration . . . . . . . . . . . . . . . . . . . . . . . 448 

13.1.1 Simplified security administration . . . . . . . . . . . . . . . . . . . . . . . . . 448 

13.1.2 Administrative security implementation. . . . . . . . . . . . . . . . . . . . . 449 

13.1.3 Administrative security with SAF authorization . . . . . . . . . . . . . . . 450 

13.1.4 Administrative security with default authorization provider . . . . . . 455 

13.2 Role-based administrative security . . . . . . . . . . . . . . . . . . . . . . . . . . . . 460 

13.2.1 Administrative roles. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 460 

13.2.2 Fine-grained administrative security . . . . . . . . . . . . . . . . . . . . . . . 462 

13.3 Naming service security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 467 

13.3.1 CosNaming roles description . . . . . . . . . . . . . . . . . . . . . . . . . . . . 467 

13.3.2 Mapping users or groups to CosNaming roles . . . . . . . . . . . . . . . 468 

Appendix A. Additional material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 471 

Locating the Web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 471 

Using the Web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 472 

How to use the Web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 472 

Related publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 473 

IBM Redbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 473 

Other publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 474 

Online resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 474 

How to get IBM Redbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 475 

Help from IBM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 476 

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 477 

Contents ix

x Security in WebSphere Application Server Version 6.1 and J2EE 1.4 on z/OS

Notices 

This information was developed for products and services offered in the U.S.A. 

IBM may not offer the products, services, or features discussed in this document in other countries. Consult 

your local IBM representative for information about the products and services currently available in your 

area. Any reference to an IBM product, program, or service is not intended to state or imply that only that 

IBM product, program, or service may be used. Any functionally equivalent product, program, or service that 

does not infringe any IBM intellectual property right may be used instead. However, it is the user's 

responsibility to evaluate and verify the operation of any non-IBM product, program, or service. 

IBM may have patents or pending patent applications covering subject matter described in this document. 

The furnishing of this document does not give you any license to these patents. You can send license 

inquiries, in writing, to: 

IBM Director of Licensing, IBM Corporation, North Castle Drive, Armonk, NY 10504-1785 U.S.A. 

The following paragraph does not apply to the United Kingdom or any other country where such 

provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION 

PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR 

IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, 

MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer 

of express or implied warranties in certain transactions, therefore, this statement may not apply to you. 

This information could include technical inaccuracies or typographical errors. Changes are periodically made 

to the information herein; these changes will be incorporated in new editions of the publication. IBM may 

make improvements and/or changes in the product(s) and/or the program(s) described in this publication at 

any time without notice. 

Any references in this information to non-IBM Web sites are provided for convenience only and do not in any 

manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the 

materials for this IBM product and use of those Web sites is at your own risk. 

IBM may use or distribute any of the information you supply in any way it believes appropriate without 

incurring any obligation to you. 

Information concerning non-IBM products was obtained from the suppliers of those products, their published 

announcements or other publicly available sources. IBM has not tested those products and cannot confirm 

the accuracy of performance, compatibility or any other claims related to non-IBM products. Questions on 

the capabilities of non-IBM products should be addressed to the suppliers of those products. 

This information contains examples of data and reports used in daily business operations. To illustrate them 

as completely as possible, the examples include the names of individuals, companies, brands, and products. 

All of these names are fictitious and any similarity to the names and addresses used by an actual business 

enterprise is entirely coincidental. 

COPYRIGHT LICENSE: 

This information contains sample application programs in source language, which illustrate programming 

techniques on various operating platforms. You may copy, modify, and distribute these sample programs in 

any form without payment to IBM, for the purposes of developing, using, marketing or distributing application 

programs conforming to the application programming interface for the operating platform for which the 

sample programs are written. These examples have not been thoroughly tested under all conditions. IBM, 

therefore, cannot guarantee or imply reliability, serviceability, or function of these programs. 

© Copyright IBM Corp. 2007. All rights reserved. xi

Trademarks 

The following terms are trademarks of the International Business Machines Corporation in the United States, 

other countries, or both: 

Redbooks (logo) ® 

developerWorks® 

eServer 

iSeries® 

z/OS® 

zSeries® 

CICS® 

Domino® 

DB2® 

IBM® 

IMS 

Lotus® 

MQSeries® 

MVS 

Rational® 

Redbooks® 

The following terms are trademarks of other companies: 

RACF® 

RMF 

System z 

Tivoli® 

VTAM® 

WebSphere® 

Enterprise JavaBeans, EJB, Java, Java Naming and Directory Interface, JavaBeans, JavaServer, 

JavaServer Pages, JDBC, JDK, JMX, JSP, JVM, J2EE, and all Java-based trademarks are trademarks of 

Sun Microsystems, Inc. in the United States, other countries, or both. 

Active Directory, Expression, Internet Explorer, Microsoft, Windows Server, Windows, and the Windows logo 

are trademarks of Microsoft Corporation in the United States, other countries, or both. 

UNIX is a registered trademark of The Open Group in the United States and other countries. 

Linux is a trademark of Linus Torvalds in the United States, other countries, or both. 

Other company, product, or service names may be trademarks or service marks of others. 

xii Security in WebSphere Application Server Version 6.1 and J2EE 1.4 on z/OS

Preface 

This IBM® Redbooks® publication was written with the objective to provide a 

technical description of some of the most important security scenarios available 

with WebSphere® Application Server Version 6.1 for z/OS®. We chose 

scenarios that are not really documented elsewhere and that have had 

significant changes in Version 6.1. 

In the first two chapters we provide an overview of security with WAS on z/OS for 

those readers who are unfamiliar with the security landscape on z/OS. From 

Chapter 3, “Web container security” on page 63, onwards we go into more 

technical depth. 

The team that wrote this book 

This book was produced by a team of specialists from around the world working 

at the International Technical Support Organization, Poughkeepsie Center. 

Alex Louwe Kooijmans is a Project Leader with the International Technical 

Support Organization (ITSO) in Poughkeepsie, NY, and specializes in 

WebSphere, Java, and SOA on System z with a focus on integration, 

security, high availability, and application development. Previously, he worked as 

a Client IT Architect in the Financial Services sector with IBM in The 

Netherlands, advising financial services companies on IT issues such as 

software and hardware strategy and on demand. Alex has also worked at the 

Technical Marketing Competence Center for zSeries® and Linux® in 

Boeblingen, Germany, providing support to customers starting up with Java and 

WebSphere on zSeries. From 1997 to 2002, Alex completed a previous 

assignment with the ITSO, managing various IBM Redbooks projects and 

delivering workshops around the world. 

Foulques de Valence is a System z security IT Architect with IBM STG and is 

currently based in Poughkeepsie, NY, where he works for the Lab Services 

team. Previously, he was a Web infrastructure IT Architect in France focusing on 

SOA and z/OS. Foulques instructed about end-to-end security solutions for 

WebSphere on z/OS worldwide. He is a co-author of several IBM Redbooks 

publication dealing with security and WebSphere Application Server for z/OS. He 

received a Master’s Degree in Computer Science and Engineering from Ensimag 

in France. He furthered his education at the State University of New York at 

Buffalo and at Stanford University. 

© Copyright IBM Corp. 2007. All rights reserved. xiii

Yukari Hanya is an IT Specialist with the WebSphere for z/OS team in Design 

Center Makuhari in AP Advanced Technical Support (ATS). She has been 

involved in a WebSphere Application Server project for z/OS for the last two 

years and is responsible for providing technical support for WebSphere for z/OS 

customers. 

Keith Jabcuga is a Software Support Specialist working in the IBM Support 

Center in Poughkeepsie, New York. He has worked on the WebSphere for z/OS 

support team for five years, and his areas of expertise include defect support and 

application diagnostics. Keith holds an M.S. in Computer Science from the 

University of Buffalo. 

Marc van der Meer is a z/OS IT Specialist with IBM GTS/ITS in the Netherlands. 

He has been specializing in security and WebSphere on z/OS for several years. 

His current assignments include high-availability WebSphere infrastructures on 

z/OS through sysplex functionality, security migrations, and J2EE security 

implementations. 

Gabriel Mogos has been working on the z/OS platform for many years in the 

areas of VTAM® and TCP/IP products. He worked as a VTAM change team 

member in troubleshooting and fixing internal and external reported problems. 

He also worked as a services consultant assisting customers migrate from SNA 

to IP network infrastructure and custom application programming. He holds a 

Msc. degree in Mechanical/Industrial Engineering from the University of 

Cincinnati. Currently, he is working in Enterprise Network Transformation 

Solutions (ENTS) support and development. 

Eran Yona is an IT Architect from the Israeli Ministry of Defense. He has 15 

years of experience in IT. He has a B.A. in business from the College of 

Management in Israel. His areas of expertise include data center management, 

data center infrastructure, disaster recovery solutions, and virtualization. 

xiv Security in WebSphere Application Server Version 6.1 and J2EE 1.4 on z/OS

Figure 1 The team (left to right): Gabriel Mogos, Keith Jabcuga, Foulques de Valence, Yukari 

Hanya, and Eran Yona (Alex Louwe Kooijmans and Marc van der Meer not pictured) 

Thanks to the following people for their contributions to this project (In 

alphabetical order): 

Paola Bari 

Rich Conway 

Franck Injey 

Al Schwab 

International Technical Support Organization, Poughkeepsie Center 

Tom Hackett 

IBM System z, Poughkeepsie, NY 

Tim Hefele 

WebSphere z/OS Performance 

Preface xv

Ut V. Le 

WebSphere Security Development, Austin, TX 

Bill O’Donnell 

WebSphere Security Development, Madison, WI 

Gary Puchkoff 

WebSphere Application Server for z/OS Design and Development 

Ben Rogers 

IBM STG System z Lab Services, Poughkeepsie, NY 

Wade Wallace 

International Technical Support Organization, Austin Center 

Nigel Williams 

IBM Montpellier 

Become a published author 

Join us for a two- to six-week residency program! Help write an IBM Redbook 

dealing with specific products or solutions, while getting hands-on experience 

with leading-edge technologies. You'll have the opportunity to team with IBM 

technical professionals, Business Partners, and Clients. 

Your efforts will help increase product acceptance and customer satisfaction. As 

a bonus, you will develop a network of contacts in IBM development labs, and 

increase your productivity and marketability. 

Find out more about the residency program, browse the residency index, and 

apply online at: 

ibm.com/System Authorization Facilitys/residencies.html 

Comments welcome 

Your comments are important to us! 

We want our Redbooks to be as helpful as possible. Send us your comments 

about this or other Redbooks in one of the following ways: 

► Use the online Contact us review book form found at: 

ibm.com/System Authorization Facilitys 

xvi Security in WebSphere Application Server Version 6.1 and J2EE 1.4 on z/OS

► Send your comments in an e-mail to: 

System Authorization Facilitys@us.ibm.com 

► Mail your comments to: 

IBM Corporation, International Technical Support Organization 

Dept. HYTD Mail Station P099 

2455 South Road 

Poughkeepsie, NY 12601-5400 

Preface xvii

xviii Security in WebSphere Application Server Version 6.1 and J2EE 1.4 on z/OS

Chapter 1. Introduction 

Because of the rapid growth of e-business and the integration of different 

organizations, securing and managing information technology (IT) infrastructures 

has become very complex and demanding. Protecting sensitive and confidential 

data from malicious intruders, deadly viruses, and worms is not an easy task. It 

requires constant monitoring of the daily IT business operations and deploying 

the latest security technology. 

WAS for z/OS security and the underlying operating system infrastructure 

security can provide customers running enterprise applications with secure and 

reliable services. 

In this chapter, we introduce new and upgraded security features that are 

implemented in WebSphere Application Server WAS for z/OS V6.1 to secure 

WAS and e-business applications. 

This chapter contains the following sections: 

► “Securing WAS for z/OS simplified” on page 2 

► “WAS and security layers” on page 3 

► “Securing WAS and applications” on page 12 

1 

© Copyright IBM Corp. 2007. All rights reserved. 1

1.1 Securing WAS for z/OS simplified 

Securing an e-business application on the z/OS platform demands good 

knowledge of the underlying infrastructure and the areas that could be exposed 

to security attacks. It requires periodic review of the security system put in place 

to protect the network resources (files, databases, user accounts, and so on) and 

you to take the necessary action to improve the overall system operations. 

Needless to say, it is very tough out there. The competition has never been more 

intense than today. To survive in this highly competitive global market, companies 

must be innovative and come up with new ways of doing things within a short 

period of time. If they do not, they become obsolete and fade away. 

The product life cycle has now been shortened. To beat the competition, 

companies must invent, re-invent, and upgrade their products every six months 

to a year in order to stay in business and be successful. 

As IBM strategic middleware, WebSphere Application Server has been going 

through many changes, starting from Lotus® Go Domino® Webserver V4.6.1 in 

the late 1990s to what we have now (WebSphere Application Server for z/OS 

Version 6.1). In each version milestone achievements have been made, and like 

the previous versions, Version 6.1 has made great enhancements in securing 

WAS and the applications running in WAS. These enhancements are in the 

areas of ease of use, manageability, interoperablity, and compatibility. 

What is new in V6.1 can be summarized as follows: 

► For ease of use, the administrative security is simplified and enhanced. 

► RACF® enhancements such as mixed password support and sync to OS 

thread control. 

► Simplified key and certificate management. 

► New user registry - federated repository. 

► Web authentication enhancements. 

► Interoperability support - protected GSS-API Negotiation Mechanism Protocol 

support. 

► Web services security - messaging and transport security. 

► JCA 1.5 connectivity to back-end applications support. 

► Java 2 security - greater control over permissions (authorization). 

► Securing applications - identity assertion with trust validation. 

2 Security in WebSphere Application Server Version 6.1 and J2EE 1.4 on z/OS

Note that these new and enhanced v6.1 security features have been made 

available to the public in the WebSphere Application Server for z/OS InfoCenter. 

In addition, these features are described in detail in this book in later chapters. 

1.2 WAS and security layers 

1.2.1 Security terms 

Layering is a fine method of building software products. It helps connect pieces 

of functions together to build a large system. In this section, we describe the 

following: 

► Security terms 

► Security layering overview 

► An overview of security layering in z/OS 

► An overview of Java security 

► An overview of application security 

Security could mean many things to many people these days, but what we mean 

by security is the terms and standards given by ISO 7498-2. The terms that 

describe security are: 

► Integrity refers to the assurance that the data sent from one party to another 

has not been tampered with by a third party before it arrives at its destination. 

If such a breach occurred, it can be detected. This is typically achieved by the 

use of digital signatures. 

► Confidentiality refers to information that is classified as confidential and 

should not be seen by any body other than the two connection partners. The 

information must be fully encrypted using TLS/SSL or any other reliable 

encryption algorithm. WAS for z/OS uses SSL for encrypting messages. 

► Authentication refers to the obtainment of an acceptable identity for the 

execution of a specific service. This identity can then be delegated to other 

systems that in turn might require authentication as well. There are many 

implementation-specific ways to accomplish the enforcement of this security 

aspect. For example, WebSphere for z/OS allows for basic, form-based, 

client certificate, and JAAS authentication. 

► Authorization refers to any user who has been authenticated having the 

permission to access a specific resources. This type of control is usually 

managed by specialized software, either from a sub-system perspective like 

z/OS RACF or from an application layer like Tivoli® Access Manager. 

Chapter 1. Introduction 3

► Non-repudiation means that in the case of a transaction between two parties 

(a provider and a consumer), both parties can provide legal proof to a third 

party that the provider delivered and the consumer received the services. 

► Auditing refers to the ability to discern from gathered data who did what, 

when, and for what reason. This is usually made possible by the usage of 

monitoring tools and traces, which are then analyzed for patterns. This type of 

activity has been engaged in for several hundred years, across many fields, 

so most of the general concepts applied in other fields apply. A robust 

auditing and traceability implementation could dissuade potential attackers. 

In this chapter and in the rest of the book, we discuss security terms while 

introducing the new security features of WebSphere Application Server v6.1 

1.2.2 Security layering overview 

Figure 1-1 shows a high-level topological view of how security is layered in the 

z/OS platform. 

WebSphere/Application 

Resources 

WebSphere Security 

Java Security 

Platform Security 

Figure 1-1 Security layers 

Naming, 

Admin 

Access Control 


J2EE Security API 

CORBA Security / CSIv2 

Java 2 Security 

JVM 5 Security 

Operating System Security 

In WAS Version 4 there was security in many different layers. In WAS Versions 5 

and 6, the security options and capabilities in many of these layers were 

enhanced. In WAS Version 5 on the System z platform and later, the WAS 

security layers are intended to work like those on any other platform. What is 

unique to each platform is the operating system security. 

4 Security in WebSphere Application Server Version 6.1 and J2EE 1.4 on z/OS 

HTML, 

Servlet/JSPs, 

EJBs

Operating system (OS) security 

The security infrastructure of the underlying operating system provides certain 

security services to the WebSphere security application. This includes the file 

system security support to secure sensitive files in WebSphere product 

installation. The WebSphere system administrator can configure the product to 

obtain authentication information directly from the operating system user registry, 

for example, the NT Security Access Manager (SAM). On z/OS, we refer to that 

as SAF, which stands for System Authorization Facility. SAF is a common set of 

APIs being used to access RACF, Computer Associates’ Top Secret or ACF2 

security software and security databases that are present on the z/OS operating 

environment. These security products contain information about users, groups of 

users, resources, and user or group access to those resources. The purpose of 

these products is to provide authentication and access control for the z/OS 

environment. 

Java security 

The Java security is based on a few security elements: 

► The JVM in the SDK 1.5 

The JVM security model provides a layer of security above the operating 

system layer. For example, JVM security protects the memory from 

unrestricted access, creates exceptions when errors occur within a thread, 

and defines array types. 

► J2EE security 

The security collaborator enforces J2EE-based security policies and supports 

J2EE security APIs. 

► Java 2 security 

The Java 2 security model offers access control to system resources 

including file systems, system property, socket connection, threading, class 

loading, and so on. Application code must explicitly grant the required 

permission to access a protected resource. 

► CSIv2 

Any calls made among secure object request brokers (ORBs) are invoked 

over the Common Secure Interoperability Version 2 (CSIv2) security protocol, 

which sets up the security context and the necessary quality of protection. 

After the session is established, the call is passed up to the enterprise bean 

layer. CSIv2 is an IIOP-based, three-tiered, security protocol that is 

developed by the object management group (OMG). This protocol provides 

message protection, interoperable authentication, and delegation. The three 

layers include a base transport security layer, a supplemental client 

authentication layer, and a security attribute layer. 



WebSphere Application Server security relies on and enhances all the 

above-mentioned layers. It enforces security policies and services in a unified 

manner on access to Web resources and enterprise beans. It consists of 

WebSphere security technologies and features to support the needs of a secure 

enterprise environment. 

Individual servers can override a subset of the security configuration. When 

using mixed z/OS and distributed nodes, the security domain features are 

merged. 

1.2.3 z/OS security overview 

Resource Access Control Facility (RACF) is z/OS’s security component that 

implements System Access Facility (SAF) APIs. SAF is an interface that provides 

security services to many other subsystems on z/OS such as CICS®, DB2®, 

IMS, Unix Services Systems, and so on. 

In summary, RACF has the following capabilities and functionality. It allows the 

administrator to: 

► Create and manage digital certificates. 

► Protect data sets and UNIX® System Services HFS files. 

► Protect system resources and services. 

► Manage a large user database, and add, delete, list, and change user 

profiles. 

Authentication and authorization in RACF is very straight forward. When a user 

requests a service from the system, first RACF checks whether the user is 

defined to RACF. If yes, then it checks whether the user is authorized to access 

that resource. A user can be in a suspended or revoked state and will not be 

given any system privilege until the suspension or revocation is resolved. 

RACF keeps a profile for each system resource user that it knows, and the profile 

is kept in storage in the format shown in Figure 1-2. 

User ID Owner Password 

Attributes Security Groups Segments 

Classifications 

Figure 1-2 RACF profile 


OMVS TCP/IP TSO

As you can see in Figure 1-2 on page 6, the RACF profile contains: 

► User ID and password. The password is encrypted. 

► Owner of the profile. The owner can be a group or a single user. 

► Attributes, which allow users to do specific tasks with RACF. Four attributes 

that can be specified are special, auditor, operations, and protected. 

► Security classifications. This is optional, but it gives an additional way of 

controlling user authority. 

► Segments. Z./OS process or address spaces such as TSO, OMVS, and CICS 

can be added to a user profile. 

Finally, RACF provides a way to record what is done on the system. It keeps 

track of what happens on the system so that an organization can monitor who is 

logged on the system at any time. RACF reports whether anyone has attempted 

to perform unauthorized actions. For example, RACF can record that someone 

has tried to access or change data to which they do not have the correct 

authority. 

Access Control Element (ACEE) 

The Access Control Element is storage (a control block) that contains profile 

information of a user who is currently active. This control block is only valid in the 

address space task control block in which it was created. 

RACO (ENVR object) 

This is a mechanism by which RACF can pass a user’s credential from an 

address space to another address space. Once the new address space receives 

the RACO, RACF can then create a new ACEE for that user that is valid within 

the new address space. 

RACF GROUP 

Groups are a way to categorize subjects and objects. The types of groups used 

are administrative, resource control, and functional. 

RACF Administration EJB roles and their respective capabilities are classified 

as follows: 

Monitor View configuration files and status but not anything else. 

Configurator A monitor that can modify a configuration information but 

cannot change runtime states. 

Operator Can trigger runtime state changes, such as start/stop an 

application server, but cannot change configuration files. 

Administrator An operator as well as a configurator. 


RACF CLASS 

This section describes the pertinent RACF classes that are applicable to 

implementing WebSphere Application Server for Version 6 on z/OS. These 

classes represent a small subset of all available classes in RACF. 

► APPL - used for VTAM application ID (APPLID) access. The APPL class 

controls access to applications. 

► CBIND - controls the client’s ability to bind to the server. WebSphere uses the 

CBIND class to control access to the server. 

► DIGTCERT - contains digital certificates and related information. 

► DSNR - controls access to DB2 subsystems. 

► EJBROLE and GEJBROLE - These classes are used to register Enterprise 

JavaBeans (EJB) roles that will be used by WebSphere Application Server 

applications. EJBROLE is the member class for EJB authorization roles. The 

APPLDATA field in an EJBROLE profile defines the target Java identity when 

running in RunAs ROLE mode. GEJBROLE is the grouping class for EJB 

authorization roles. EJBROLE profiles have to be added for the required roles 

and for users to be given access to these profiles when SAF authorization is 

used. 

► FACILITY - miscellaneous uses. Profiles are defined in this class so that 

resource managers can check users’ access to the profiles when the users 

take some action. Here is where we place profiles for Digital Certificate, DCE, 

and Kerberos, plus UNIX System Services profiles (for example, 

BPX.DAEMON). 

► KERBLINK - mapping class for user identities of local and foreign principals. 

Used in Kerberos to map a unique RACF user ID to each foreign principal. 

► LOGSTRM - controls which applications can access the system logger 

resources. 

► SERVER - controls the server’s ability to register with the daemon. This class 

is used in WebSphere to control whether a servant can call authorized 

programs in the controller. 

► SERVAUTH - contains profiles that are used by servers to check a client’s 

authorization to use the server or to use the resources managed by the 

server. Use this class to protect TCP/IP ports. If you are using this class, you 

must give WebSphere and Kerberos access. 

► STARTED - used for identifying authorized system started procedures. 

WebSphere Application Server normally starts as a system task and would 

need an entry in the STARTED class to associate a valid RACF user ID and 

connected group to be able to access protected resources. This is used in 

preference to the started procedures table to assign an identity during the 


processing of an MVS START command. For example, WebSphere and 

Kerberos are defined as started tasks in this profile. 

► SURROGAT - whether surrogate submission or login is allowed, and if 

allowed, which user IDs can act as surrogates. SURROGAT is used here in 

conjunction with BPX.SRV profiles in the SURROGAT class to allow security 

context switches for unauthenticated user IDs. 

RACF cosnaming EJB roles 

These roles are: 

CosNaming Read Allowed to query WAS name space (JNDI) 

Cosnaming Write Allowed to do write operations (JNDI bind, re-bind, and 

unbind in the WAS name space) 

CosNameCreate Allowed to create objects to the WAS name space 

CosNamedelete Allowed to remove objects from WAS name space 

1.2.4 Java security overview 

Java is a programming language that is supposed to be platform independent 

and should run on any given operating system. Like any other software package, 

Java also has its own layering architecture. Therefore, Java 2 is above the 

operating system layer and J2EE is above the Java 2 layer. 

Java 2 security 

Java 2 security provides a policy-based, fine-grained access control mechanism 

that increases overall system integrity by checking for permissions before 

allowing access to certain protected system resources. Java 2 security guards 

access to system resources such as file I/O, sockets, and properties, while Java 

2 Platform, Enterprise Edition (J2EE) security guards access to Web resources 

such as servlets, JavaServer Pages (JSP) files, and Enterprise 

JavaBeans (EJB) methods. 

Many existing or even new applications might not be prepared for the very 

fine-grained access control programming model that Java 2 security is capable 

of enforcing. Administrators need to understand the possible consequences of 

enabling Java 2 security if applications are not prepared for Java 2 security. Java 

2 security places some new requirements on application developers and 

administrators. 

You can configure Java 2 security and administrative security independently of 

one another. Disabling administrative security does not disable Java 2 security 

automatically. You need to explicitly disable it. 


Attention: Java 2 security is very CPU consuming and therefore not 

recommended for a production environment. 

J2EE security 

The J2EE specification defines the building blocks and elements of a J2EE 

application that builds an enterprise application. The specification also provides 

details about security related to the different elements. A typical J2EE application 

consists of an application client tier, a Web tier, and an EJB tier. When designing 

a security solution, you need to be aware of the connections between each of the 

modules. 

It is possible that the J2EE application can control its own security issues 

programmatically, but with WAS, the J2EE application can be configured to 

enforce security features during deployment time. When an administrator installs 

the application, he can give the required users access to the application based 

on the roles as defined in the applications’s EJBROLES profiles. The permission 

given to the users is based on their roles and needs. 

There are two ways of enforcing security under J2EE: 

► Declarative security 

Declarative security is the means by which an application’s security policies 

can be expressed externally to the application code. At application assembly 

time, security policies are defined in an application’s deployment descriptor. A 

deployment descriptor is an XML file that includes a representation of an 

application’s security requirements, including the application’s security roles, 

access control, and authentication requirements. When using declarative 

security, application developers can write component methods that are 

completely unaware of security. By making changes to the deployment 

descriptor, an application’s security environment can be radically changed 

without requiring any changes in application code. 

► Programmatic security 

Programmatic security is useful when the application server provided security 

infrastructure cannot supply all the functions that are needed for the 

application. Using the Java APIs for security can be the way to implement 

security for the whole application without using the application server security 

functions at all. Programmatic security also gives you the option to implement 

dynamic security rules for your applications. Generally, the developer does 

not have to code for security because WebSphere Application Server 

provides a very robust security infrastructure, which is transparent to the 

developer. However, there are cases where the security provided is not 

sufficient and the developer wants greater control over to what the user has 


access. For such cases, there are a few security APIs that the developers can 

implement. 

1.2.5 WebSphere security overview 

One of the goals of the Java 2 Platform Enterprise Edition (J2EE) security 

architecture is isolating the application developer from issues of security. 

Application component providers should not have to know anything about 

security to write an application. 

Based on the J2EE container-based security architecture, the Web container and 

the EJB container can provide security without application code having to be 

written to provide security. Not all applications, however, can be designed in 

such a way that the application programmer is completely isolated from issues of 

security. But there are cases where WAS declarative security alone cannot 

provide security to application programs that require some functions. In this 

situation programmatic security can be done by the application. 

Programmatic security includes actions taken by application program code to 

authenticate users, test for authorization to resources, or change the effective 

user in the current execution context. WebSphere Application Server offers 

opportunities for applications to perform programmatic security. 

J2EE provides an API with two methods for the Web container and two methods 

for the EJB container. 

Web applications use these methods: 

► getUserPrincipal 

► isUserInRole 

EJB applications use these methods: 

► getCallerPrincipal 

► isCallerInRole 

The user ID related methods getUserPrincipal() and getCallerPrincipal() 

(respectively) are used to retrieve the user ID associated with the current Web 

application (servlet or JavaServer Page) or EJB: 

getUserPrincipal() For applications running in a Web container, this 

method, defined on HTTPServletRequest, can be 

used to retrieve a principal object for the user 

identity. The user ID can be retrieved from this 

principal object. 

getCallerPrincipal() For applications running in an EJB container, this 

method, defined on EJBContext, can be used to 


etrieve a principal object for the caller’s identity. The 

user ID can be retrieved from this principal object. 

The application can use the returned user ID or principal object for decisions in 

its program flow. For example, a program might have a private authorization 

protocol and use the principal name to search an authorization table. Another 

possibility would be if data is being retrieved from a relational database, and the 

principal name forms part of a key field. 

1.3 Securing WAS and applications 

In this section, first we describe access points to WAS and then we provide a 

high level of security features to implement authentication and authorization 

functions. 

1.3.1 WAS and security checkpoints 

Let us look at a classic example that is done everyday in the real world. 

A certain country with all its territorial boundaries puts into effect an immigration 

law to enforce that entry to its territory is not breached. To protect its territory, the 

country places checkpoints in all its entry points. The possible entry points would 

be sea ports, airports, border towns, and other ground entry points. So, the 

country places its immigration offices in all the entry points to allow or reject entry 

visas based on its rules and regulations. For example, if a person tries to enter 

the country using a falsified document, then he would be in trouble for breaking 

the law to enter the country. 

If we apply the same analogy to enforcing security in WAS, it requires identifying 

all entry points to the server. WAS, as it is rightfully called, is a server, and most 

of its work is driven by clients requesting access to resources such as J2EE 

enterprise applications and back-end enterprise information systems (EIS). In 

this case, different clients could be using different communication protocols and 

coming in through different entry points. WAS should be able to understand the 

different protocols and handle all incoming requests in such a manner that no 

security is breached. 


To demonstrate the entry checkpoint concept, we present Figure 1-3. Figure 1-3 

externalizes the communication channels between WAS and the outside world, 

and it represents the most common connections into and out of WAS. We also 

believe that knowing the entry checkpoints helps IT architects and designers 

consider the security issues during an overall network design phase and 

implementation. 

Figure 1-3 WAS security checkpoints 

Looking at Figure 1-3, the connections to WAS on z/OS can be categorized as 

front end and back end. The front end connections are: 

► Connecting from a browser or Web client via HTTPs 

There are two TCP/IP ports, one for unsecure connections and the other for 

secure connections. 

► Connecting from a J2EE client via RMI/IIOP 

There are two TCP/IP ports, one for unsecure and the other one for secure 

connections. 

► Connecting from an MQ client via TCP/IP 

► Commands originating from wsadmin via TSO or Telnet via native TCP/IP 


Similarly, the back end connections are: 

► Connecting to DB2 via Java DataBase Connectivity (JDBC), either using a 

local connection (T2) or a remote connection (T4). 

► Connecting to CICS and IMS via J2C connectors. Those connectors can also 

be used in local (cross-memory) or remote mode (over TCP/IP). 

► Connecting to an MQ Queue Manager, again, either in local (cross-memory) 

mode or remote mode (TCP/IP). 

There are more possibilities, but for the purpose of this introduction we do not 

discuss all of the options. 

After identifying the various access points to WAS for z/OS, the next step is 

handling security issues at these entry points. 

WAS on z/OS, like any TCP/IP application, obtains sockets and binds them to 

several defined or defaulted ports and IP addresses. In fact, WAS uses the 

INADDR_ANY parameter for all its listening ports by default. This means that it 

can accept requests from any IP address used by any client. By doing that, the 

gate is wide open for a security attack. 

To WAS and its clients, TCP/IP is just an underlying transport protocol. The real 

communication occurs on the application layer protocols (HTTPs, IIOP) that run 

on top of the TCP layer. The HTTP protocol is very well known and is much 

easier to use than the IIOP. The IIOP is more complex than the HTTP since it 

deals with objects and inter-communication between programs. 

The details follow in later chapters, but let us see how security is handled when 

an end-to-end communication is established between two endpoints. The two 

endpoints are a Web client and CICS on z/OS in one case, and a J2EE client and 

CICS on the same z/OS in the other case. 


J2EE 

Client 

0 

Web 

Client 

0 

In Figure 1-4, we show numbers for each stop the Web client and the J2EE client 

make as they go through the connection path to reach CICS. 

Web 

Server 

1 

Figure 1-4 Security checkpoint internal flow 

Web 

Container 

In each case the number zero (0) represents the initial point before doing 

anything, and WAS and CICS are local to each other, meaning that they are on 

the same LPAR on z/OS. 

For the Web client, authentication would be attempted at 1, 2, 4, and 5. 

Authorization would be attempted at 2, 3, 4, and 5. 

For the J2EE client, authentication would be attempted at 1, 2, 3, and similarly 

authorization would be attempted at 1, 2, and 3. 

To fully understand the security flow on the HTTP(s) and IIOP layers, it requires 

deep understanding of the specification and architecture of these protocols. 

Once TCP/IP delivers the data, the HTTP(s) and the IIOP code must parse and 

interpret the HTTP and GIOP (IIOP) headers in order to take an appropriate 

security action. 

We do not discuss the HTTP(s) and IIOP internal flow here in this book, but the 

security mechanisms implemented to secure HTTP and IIOP protocols are 

discussed later on. 

1.3.2 Web client authentication overview 

2 

EJB 

Container 

Authentication is performed using user information stored in a user account 

repository and based on the protocol the user uses to access WAS. 

3 

1 

4 

2 

J2C 

CICS 

Chapter 1. Introduction 15 

3 

5

In this section, we describe the mechanisms to authenticate Web clients. The 

Web authentication mechanisms are: 

► Single sign-on (SSO) 

– Lightweight Third Party Authentication (LTPA) 

The security token is created by WAS using configured keys. 

– Simple WebSphere Authentication Mechanism (SWAM) 

The security token is not created by WAS. If the authentication is needed 

to go from server to server, then the LTPA mechanism should be used. 

Important: SWAM is deprecated as of WAS V6.1. 

► Trust Association Interceptor (TAI) 

The Web authentication options are: 

► Basic 

► Form based 

► Client certificate 

Single sign-on 

Single sign-on is a mechanism where a principal can log in to multiple servers 

without being required to resubmit his credentials. Single sign-on is supported 

only when Lightweight Third Party Authentication protocol is being used. 

When using SSO, at initial login a cookie is returned in the HTTP response. 

Then, when the user accesses other servers that are in the same domain name 

service (DNS), she is not prompted to re-enter the credentials again for 

re-authentication. 

If you need to interoperate with network distributed servers you must use LTPA. 

Attribute propagation 

With security attribute propagation, WebSphere Application Server can transport 

security attributes (authenticated subject contents and security context 

information) from one server to another in your configuration. WebSphere 

Application Server might obtain these security attributes from either an enterprise 

user registry, which queries static attributes, or a custom login module, which can 

query static or dynamic attributes. Dynamic security attributes, which are custom 

in nature, might include the authentication strength that is used for the 

connection, the identity of the original caller, the location of the original caller, the 

IP address of the original caller, and so on. 


Security attribute propagation provides propagation services using Java 

serialization for any objects that are contained in the subject. WebSphere 

Application Server also offers a token framework that enables custom 

serialization functionality. 

When a request is being authenticated, a determination is made by the login 

modules as to whether this request is an initial login or a propagation login. An 

initial login is the process of authenticating the user information, typically a user 

ID and password, and then calling the application programming interfaces (APIs) 

for the remote user registry to look up secure attributes that represent the user 

access rights. A propagation login is the process of validating the user 

information, typically a Lightweight Third Party Authentication token, and then 

deserializing a series of tokens that constitute both custom objects and token 

framework objects known to WebSphere Application Server. 

Identity assertion 

Identity assertion is one of the most important areas of RMI-IIOP security. When 

coding EJBs and setting up the infrastructure, a key goal is to allow for access to 

a remote EJB with total transparency to the user while maintaining security. 

Common Secure Inter operability Version 2 (CSIv2) allows for an identity from 

one server to be passed to a downstream EJB call. 

Trust Association Interceptor (TAI) 

Trust association is a method that enables the integration of WAS security and 

third-party security servers. More specifically, a reverse proxy server can act as a 

front-end authentication server while the WAS applies its own authorization 

policy onto the resulting credentials that are passed to it by the proxy server. 

In a trust association setup, the back-end server accepts HTTP requests that 

pass through the front-end server. The back-end server is configured to receive 

HTTP requests only from the trusted server. HTTP requests that come in through 

other servers are rejected. 

The trust association function could be used with configurations that provide 

ways to demilitarize zones. 

The products that implement Trust Association Interceptors include: 

► IBM Tivoli Access Manager for e-business 

► WebSeal 

► Caching proxy 


1.3.3 EJB client authentication overview 

For EJB client authentication, two technologies are important to mention: 

► Common Secure Interoperability Specification v2 (CSIv2) can be used to 

enter a J2EE server on z/OS remotely from a J2EE client and authenticate to 

an EJB running in that server. 

► Java Authentication and Authorization Service (JAAS) can be used in any 

J2EE application to perform authentication functions. 

Common Secure Inter operability Specification V2 (CSIv2) 

The Common Secure Interoperability Specification v2 (CSIv2) is a specification 

adopted by the Object Management Group (OMG) to use the IIOP security 

protocol to authenticate and to provide message protection between client and 

server. CSIv2 is enabled in WAS via security administration configuration. Note 

that the CSIv2 protocol is applicable only on communication between a J2EE 

client and an EJB. 

Briefly, CSIv2 provides the following security features: 

► SSL client certification authentication 

The authentication occurs during the initial connection handshake using SSL 

certificates. 

► Message layer authentication 

This uses a token or basic authentication to store and exchange credential 

information with the receiving server. 

► Identity assertion 

This uses a CSIv2 identity token to identify the client to the downstream 

without providing authentication data. Identity assertion requires a trusted 

channel between the asserting server and the one that receives the identity. 

► Security attribute propagation 

This enables authenticated subject contents and security context to be 

passed from one server to another. 

► Stateful and stateless 

Since CSIv2 is a communication between two J2EE partners, the 

authentication follows depending the session state, statefull, or stateless. 

Statefull authentication is supposed to produce better performance since it is 

done during initial contact. 


Java Authentication and Authorization Service (JAAS) 

Briefly, JAAS is a J2EE standard and pluggable Java code (stub) that enables 

J2EE-compliant applications to authenticate and enforce access controls upon 

users. JAAS provides two interfaces: 

► An application-level programming interface (API) for use by J2EE applications 

► A service programming interface (SPI) for the providers of its functionality 

JAAS uses the concept of a subject in which a principal and credential are 

created for a user request to log in. 

1.3.4 MQ client authentication overview 

Message queuing, which was founded on queuing theory, is a communication 

vehicle where two application programs can exchange messages using 

predefined queues. The application programs simply do read/write messages to 

these queues, and the message is handled by other message queue processors. 

IBM award-winning messaging queuing, formerly known as MQSeries®, has 

been renamed as WebSphere MQ (WMQ). WebSphere MQ can communicate 

with JMS-based applications running in WAS. This can be either a JMS client 

application (WAS outbound) or a message-driven bean (MDB) (WAS inbound). 

There are two ways WAS and WMQ can communicate. If WMQ is local (that is, 

on the same LPAR as WAS), then the communication is via cross memory. If 

WMQ is remote to WAS, then the communication is over TCP/IP. 

MQ clients and other WMQ queue managers communicate with WMQ queue 

managers over channels. When WAS applications use direct JMS connections to 

a WebSphere MQ queue manager, not using the Service Integration Bus, the 

WAS applications appear as MQ clients. When communication is done via the 

Service Integration Bus, the MQ link appears as another queue manager to 

WebSphere MQ. Regardless of what method is used, communication is done 

over one or more channels. SSL properties on the channel allow for selection of 

which Cipher Spec to use and which clients, based on DN, to accept connections 

from. Enabling SSL on the channel is as simple as selecting the Cipher Spec and 

restarting the channel. 

For more information about configuring SSL between WebSphere Application 

Server and WebSphere MQ as the JMS provider, review the following articles in 

the WebSphere Developer Technical Journal: 

► Securing connections between WebSphere Application Server and 

WebSphere MQ: Part 1: Using the WebSphere MQ JMS provider at: 

http://www-128.ibm.com/developerworks/websphere/techjournal/0601_ 

ratnasinghe/0601_ratnasinghe.html 


► Securing connections between WebSphere Application Server and 

WebSphere MQ: Part 2: Secure the WebSphere MQ link using the service 

integration bus at: 


smithson/0601_smithson.html 

For more information about security related to the usage of JMS and WAS on 

z/OS, refer to Java Message Service (JMS) Security on z/OS, REDP-4203, at: 

http://www.System Authorization 

Facilitys.ibm.com/abstracts/redp4203.html?Open 

1.3.5 Web services security overview 

In the traditional way of client-server communication, anything above the TCP 

layer is considered as user data that needs to be delivered to the application 

layer for the running application to add, change, update, or delete a record in a 

file. But with Web- based communication, there are other protocols that are 

added on top of the TCP layer. One of these protocols is HTTP. Again on top of 

the HTTP layer, there is the SOAP protocol that is added for service-based 

communication. 

Web services and service-oriented architecture (SOA) are being used by most 

people synonymously lately, but are in fact not the same things. When we talk 

about Web services, we refer to the usage of a set of protocols that make it 

easier to transparently access a component from anywhere else. SOA is much 

more a way of architecting the entire IT landscape in such a way that it becomes 

easier to use and manage. 


As depicted in Figure 1-5, there are two ways of securing Web services 

communication. They are: 

► Message level security 

► Transport level security (TLS/SSL) 

TCP 

IP 

LINK 

HTTP 

SOAP 

SSL 

Socket 

IP address 

Mac address 

Requestor 

JMS 

Figure 1-5 Web services security layers 

The SOAP Message Security 1.0 (WS-Security 2004) is proposed by the OASIS 

WSS Technical Committee. 

This specification proposes a standard set of SOAP extensions. This 

specification is flexible and is designed to be used as the basis for securing Web 

services within a wide variety of security models including PKI, Kerberos, and 

SSL. It provides support for multiple security token formats, multiple trust 

domains, multiple signature formats, and multiple encryption technologies based 

on XML Signature and XML Encryption to provide integrity or confidentiality. 

The specification includes security token propagation, message integrity, and 

message confidentiality. However, these mechanisms by themselves do not 

address all the aspects of complete security solution. Therefore, WS-Security 

represents only one of the layers in a complex secure Web services solution 

design. The WS-Security specification defines the usage of XML Signature and 

XML Encryption. Message integrity is provided by XML Signature in conjunction 

with security tokens to ensure that modifications to messages are detected. See: 

http://www.w3c.org/Signature 

Message confidentiality leverages XML Encryption in conjunction with security 

tokens to keep portions of a SOAP message confidential. See: 

http://www.w3c.org/Encryption 

Message Level Security 

Transport level security (TLS/SSL) 

HTTP 

SOAP 

Socket 

Port 

IP address 

Mac address 

The Web services security model introduces a set of individual interrelated 

specifications to form a layering approach to security. It includes several aspects 

SSL 

JMS 

Service Provider 


of security: identification, authentication, authorization, integrity, confidentiality, 

auditing, and non-repudiation. It is based on the WS-Security specification, 

co-developed by IBM, Microsoft®, and VeriSign. 

The Web services security model is based on: 

► WS-Policy 

This describes the capabilities and constraints of the security (and other 

business) policies on intermediaries and endpoints (for example, required 

security tokens, supported encryption algorithms, and privacy rules). 

► WS-Trust 

This describes a framework for trust models that enables Web services to 

securely interoperate. This specification is responsible for managing trusts 

and establishing trust relationships. 

► WS-Privacy 

This describes a model for how Web services and requestors state privacy 

preferences and organizational privacy practice statements. 

► WS-Federation 

This describes how to manage and broker the trust relationships in a 

heterogeneous federated environment, including support for federated 

identities. 

► WS-Authorization 

This describes how to manage authorization data and authorization policies. 

► WS-SecureConversation 

This describes how to manage and authenticate message exchanges 

between parties, including security context exchange and establishing and 

deriving session keys. 

The combination of these security specifications enables many scenarios that 

are difficult or impossible to implement with today's more basic security 

mechanisms such as transport securing or XML document encryption. 

1.3.6 Backend connectivity security overview 

Enterprise Information Systems (EIS) such as CICS, IMS, and DB2 are known as 

back-end systems from a connectivity point of view. The standard way to access 

DB2 is to use Java DataBase Connectivity (JDBC). CICS and IMS can be 

accessed in a number of different ways. The J2EE way of accessing CICS and 

IMS is by using either a J2C connector or Web services. 


J2C connector components 

J2C defines contracts between the application, the connector, and the 

application server where the application will be deployed: 

► Container contract 

The container contract defines what the application server expects to find in a 

deployed application. This is the standard contract between an EJB and its 

container. It consists of the bean callback methods, such as ejbCreate(), 

ejbLoad(), and ejbActivate(). 

► Application contract 

The application contract defines what the connector expects to receive from 

the application. It is defined by the Common Client Interface (CCI) API. 

► System contract 

The system contract specifies the behavior that every J2C resource adapter 

must support. The contract components are: 

– Connection management contract 

This allows the application server, with the assistance of the adapter, to 

pool connections to the EIS. 

– Transaction management contract 

Transactions are a key concept needed to support distributed computing. 

– Security management contract 

This details the sign-on procedures that are carried out when the client in 

WebSphere establishes a connection to the resource adapter or EIS. 

These contracts imply that all participating components are J2EE connector 

architecture-compliant. The application, connector, and application server must 

all be compliant with the J2EE architecture. 

CICS authorization and authentication support 

Each application that accesses a JCA resource has a resource deployment 

descriptor (res-auth) that determines the authentication behavior when 

accessing the resource. 

Authentication can be done using: 

Container authentication When container authentication is specified, 

the user ID and password used on the 

connection are provided by the container. 

Application authentication When application authentication is specified, 

the user ID and password used on the 

connection are provided explicitly by the 


1.3.7 User registry 

application or the J2C connection factory in 

the component-managed authentication 

alias entry. 

IMS authorization and authentication support 

IMS J2C connection factories support the assignment of the current thread 

identifier as the owner of a connection for authentication purposes when global 

security is enabled. Thread identity assignment is performed when the following 

conditions are met: 

► Container-managed resource authority (res-auth=Container) is specified in 

the application deployment descriptors. 

► The J2C connection factory uses a local connection (no TCP/IP), and no 

container-managed authentication alias is specified. 

Back-end connectivity has been discussed in detail in The IBM Redbooks 

publication WebSphere for z/OS connectivity Handbook, SG24-7064-00. 

Redpaper J2C security on z/OS, REDP-4204, addresses J2C security aspects in 

detail. 

User registry is a mechanism to organize user information, such as user ID, 

password, and other identity information, and store it in a repository. WAS for 

z/OS uses a registry to authenticate users and retrieve user account information. 

Currently, there are four user registry types in WAS for z/OS: 

► LocalOS 

► LDAP 

► Custom 

► Federated repository 

Each registry has its own way of registering and saving user information. Usually, 

users are added into groups based on their roles: 

► LocalOS 

In was for z/OS, this implements a SAF-based user registry used for 

authentication and group information lookup. 

► LDAP 

The Lightweight Directory Access Protocol is used as the user registry for 

authentication and group information lookup. WAS supports a wide range of 

directory solutions. 


1.3.8 Authorization 

► Custom 

This registry mechanism is user customized and can use relational database 

files, flat files, and others to organize and store user information 

► Federated Repository 

This is new in WAS Version 6.1 and supports multiple registry chaining. Its 

most popular use is the ability to chain LDAP directories. In addition, 

federated repository supports identity management capabilities. 

How are registries used in WebSphere Application Sever for z/OS? Here we 

present how authentication is performed using registries in WAS for z/OS. These 

steps are performed in sequential order: 

1. The client’s credentials (usually, user ID/password) are passed to an 

authenticating module. 

2. The authenticating login module then passes on the credentials to a login 

module that determines what protocol to use to process the request, for 

example, LTPA. 

3. The user data is received by the protocol processor (LTPA in this case) and 

performs authentication against the current active registry. 

4. After authentication is successfully done, the login module generates a JAAS 

subject and credential list for the user and passes control back to the 

authentication module. 

5. The authenticating module then saves the credentials for future use. 

WebSphere Application Server provides many different methods for authorizing 

accessing resources. For example, you can assign roles to users and configure a 

built-in or external authorization provider. The default authorization uses 

application deployment descriptors for authorization rules. As an alternative to 

WebSphere Application Server default authorization, security authorization 

facility (SAF)-based authorization (for example, using the RACF EJBROLE 

profile) can be used to control access by a client to Java 2 Platform, Enterprise 

Edition (J2EE) roles in EJB and Web applications. When SAF authorization is 

enabled, SAF EJBROLE profiles are used to authorize J2EE roles. WebSphere 

Application Server supports authorization that is based on the Java 

Authorization Contract for Containers (JACC) specification. JACC is a new 

specification in Java 2 Platform, Enterprise Edition (J2EE) 1.4. It enables 

third-party security providers to manage authorization in the application server. 

Authorization has also been covered in WebSphere Application Server for z/OS 

V5 and J2EE 1.3 Security Handbook, SG24-6086. 



2 

Chapter 2. WebSphere security design 

This chapter contains a high-level security design that can be used to make the 

correct decisions about customizing the WAS for z/OS security implementation. 

The objective of the design is to show the reader various ways of using security 

in WAS on z/OS and integrating security with the outside world. The design can 

also be beneficial to IT architects and security specialists when they perform 

initial network solution proposals for customers. 

Security design depends on the requirements and business objectives of an 

organization. An organization can be small, medium, or large size, and the type 

of business it runs can make a big difference in designing its IT infrastructure. 

For example, designing an IT infrastructure for a bank can be a challenging task 

when making sure that there will be no security issue that is not adequately 

addressed. 

Here we provide the most common security design scenarios that can be used in 

the real world. Each configuration is designed to address specific security 

implementation scenarios. The purpose of being specific is to simplify the 

complexity of using various security methodologies in a single configuration. 

Using the configurations we show in this chapter, users can build their own 

security solutions based on their overall network topologies and requirements. 


2.1 Chapter objectives 

This chapter is structured to give you the information needed to be able to: 

► Design a secure end-to-end solution using WAS on z/OS. 

► Diagnose security caveats in your solution design. 

► Make sure that you can manage the security in your environment. 

We compiled this chapter to prepare you to successfully perform the above three 

tasks. Briefly, what this chapter attempts to address are the following areas: 

► End-to-end security design/configuration. 

► Connection protocols and their security aspects. The protocols addressed are 

HTTP, RMI-IIOP, SOAP, CSIv2, and MQ messaging. 

► SSL handshake communication flows. This is very important information to 

diagnose security-related problems. 

► Authentication via LDAP or RACF and authentication flows during initial 

sign-on and thereafter. 

► Authorization via RACF, J2EE roles, or through an external authorization 

server. 

We advise the reader to use this chapter as a starting point before getting into a 

more detailed security implementation and analysis. 

After a brief overview of network protocol layering, SSL handshake, and 

authorization EJB roles, the security designs that we discuss in this chapter are 

listed below. However, we recommend that the reader go through the brief 

overviews first. 

► “Scenario 1 - authentication in HTTP server” on page 34 

► “Scenario 2 - authentication in reverse proxy security server” on page 37 

► “Scenario 3 - J2EE client authentication using CSIv2” on page 40 

► “Scenario 4 - J2EE server authentication using CSIv2” on page 43 

► “Scenario 5 - JCA custom principal mapping” on page 46 

► “Scenario 6 - Web services authentication” on page 51 

► “Scenario 7 - WMQ client authentication” on page 53 

► “Scenario 8 - authorization using external authorization server” on page 56 

► “Scenario 9 - bridged security between z/OS and distributed using JAAS” on 

page 58 

► “Scenario 10 - centralized user registry using LDAP on z/OS” on page 60 


2.2 Network protocol architecture overview 

TCP 

IP 

LINK 

SOAP 

HTTP 

MSG 

SSL 

Socket 

IP address 

Mac address 

Client/Requester 

Figure 2-1 Protocol layering 

` 

The foundation of network communication has been based on the architecture of 

protocol layering. The two most widely known network architectures are the 

Open System Interconnection (OSI) model and System Network Architecture 

(SNA), and they both have seven layers, the link layer at the bottom, and the 

application layer at the top. At each layer there is a protocol that must be 

followed before a full communication between two endpoints can be made, in 

any given network configuration. 

The TCP/IP architecture is based on the OSI model. Originally, it was limited to 

the United States Department of Defense and universities to do simple mail 

transfer and file transfer type of operations. But, after the emergence of the 

Internet and World Wide Web (WWW), it became the dominant network transport 

provider. Even though it is based on the OSI model, the TCP/IP architecture is 

much more simple than the OSI or SNA layers. From an architectural point of 

view, there are two layers besides the link layer: the IP/UDP layer and the TCP 

layer. Anything above the TCP layer is considered an application layer, and it is 

the responsibility of the application to handle any protocol beyond the TCP layer. 

WAS for z/OS is just another application to TCP/IP. This means that the HTTP, 

IIOP, and MQ message headers and protocols are handled by WAS front-end 

processing modules. 

The discussions of the various security designs are based on the protocol 

architecture illustrated in Figure 2-1. 

IIOP 

WS – Security ( Authentication) 

IP address IP address 

IP address 

Mac address 

Authentication 

SSL (Integrity,Confidentiality) 

Mac address 

Router Router 

SOAP 

HTTP 

MSG 

SSL 

Socket 

Port 

Mac address 

IIOP 

Server/Service Provider 

Chapter 2. WebSphere security design 29

2.3 SSL overview 

2.3.1 SSL handshake 

For our discussion, we use HTTP for Web clients, IIOP for J2EE clients, MSG for 

message queue (MQ) clients, and SOAP for Web services requestor. These are 

the protocols that would be implicated in the design, and in each protocol header, 

there may be security-related information, such as user ID, password, token, 

cookie, key, and digital certificate, that is exchanged between the endpoints 

during communication. The security information that flows depends on the stage 

of communication. For example, during the initial phase of the communication, a 

user ID and password is exchanged if SSL is not enabled. If SSL is enabled then 

a user ID/password or other security information flows after a successful 

completion of a SSL handshake. 

Also, sometimes protocols are stacked on top of each other and the 

security-related information may be in any or all of the levels. A good example of 

this is the usage of SOAP over HTTP. There may be a user ID/password at the 

HTTP level, but there might also be security artifacts in the SOAP message. 

Secure Sockets Layer (SSL) is a protocol developed by the Netscape 

Communications Corporation that uses encryption to provide privacy and 

authentication between two applications in TCP/IP. SSL uses asymmetric cipher 

algorithms (RSA is normally used) to authenticate users and sign messages, 

and symmetric algorithms to ensure confidentiality and integrity. SSL is used for 

protecting connections between application users. 

This allows Web clients and servers to pass confidential or sensitive data 

through the Internet or intranet. SSL is also used by the Lightweight Directory 

Access Protocol (LDAP) for secure connections between LDAP clients and LDAP 

servers. 

When a secure connection is initiated by any of the partners, the first flow that 

occurs is the handshake. This is done after the port number of the destination is 

located, in which the port is defined as secured. Once the handshake is 

successfully completed, then the connection is secured for the entire duration of 

the communication. 


Referring to Figure 2-2, the steps are as follows: 

1. First, the client sends a Client Hello message that lists the cryptographic 

capabilities of the client (sorted in client preference order) and contains the 

SSL/TLS protocol version desired. It also contains a random value. 

Client/Requester 

Figure 2-2 SSL handshake 

1. Client Hello 

2. Server Hello 

3. Server certificate 

4. Certificate Request 

5. Certificate done 

6. Client certificate 

7. Client key exchange 

8. Certificate verify 

9. Change cipher spec 

10. Finished 

11. Change cipher spec 

12. Finished 

Server/Service Provider 

2. The server responds with a Server Hello message, which contains the 

cryptographic method (cipher suite) selected by the server, the session ID, 

another random number, and the acceptable SSL/TLS protocol version. The 

client and server must support at least one common cipher suite or the 

handshake will fail. 

3. Following the Server Hello message, the server sends its certificate. With 

Secure Sockets Layer (SSL), X.509 V.3 certificates are used. 

4. If SSL Version 3 is used and the server application (for example, the Web 

server) requires a certificate for client authentication, the server sends a 

certificate request message. In the certificate request message, the server 

sends a list of the types of certificates supported and the distinguished names 

of acceptable certification authorities. 

5. The server then sends a Server Hello done message and waits for a client 

response. Upon receipt of the Server Hello done message, the client (the 

Web browser) verifies the validity of the server’s certificate and checks that 

the server hello parameters are acceptable. 

6. If the server requested a client certificate, the client sends a certificate or, if no 

suitable certificate is available, a no certificate alert. This alert is only a 

warning, but the server application can fail the session if client authentication 

is mandatory. 


7. The client then sends a client key exchange message. This message 

contains the so-called pre-master secret, a 46-byte random number that is 

used in the generation of the symmetric encryption keys and the message. 

8. Authentication keys are encrypted with the public key of the server. If the 

client sent a certificate to the server, the client will now send a certificate 

verify message, which is signed with the client’s private key. By verifying the 

signature of this message, the server can explicitly verify the ownership of the 

client certificate. A similar process to verify the server certificate is not 

necessary. If the server does not have the private key that belongs to the 

certificate, it cannot decrypt the pre-master secret nor create the correct keys 

for the symmetric encryption algorithm, and the handshake must fail. 

9. The client uses a series of cryptographic operations to convert the pre-master 

secret into a master secret, from which all key material required for encryption 

and message authentication is derived. Then the client sends a change cipher 

spec message to make the server switch to the newly negotiated cipher suite. 

10.The finished message immediately following is the first message encrypted 

with this cipher method and keys. 

11.After the server responds with a change cipher spec and a finished message 

of its own, the SSL handshake is completed and encrypted application data 

can be sent. 

The SSL record protocol transfers application data using the encryption 

algorithm and keys agreed upon during the handshake phase. 

As explained above, symmetric encryption algorithms are used, since they 

provide much better performance than asymmetric algorithms. 

For SSL information visit: 

http://publib.boulder.ibm.com/infocenter/wasinfo/v6r1/index.jsp?topic=/ 

com.ibm.websphere.zseries.doc/info/welcome_nd.html 


2.4 Authorization and EJB roles 

In Chapter 1, “Introduction” on page 1, we said that the servant region of the 

server is the address space (task/thread) that does the real work, executing 

servlet or EJB code. The servlet and the EJB both have two identities associated 

with them: 

► A security identity, which is used for controlling access to J2EE resources and 

downstream processing (calling another EJB or J2C resource). The default 

identity is the calling entity (user ID or another program’s process ID). 

► An execution identity, which is associated with the operating system 

task/thread during run time. The default identity is the servant region’s 

address space (process ID). This is supposed to be always trusted. 

To better control the security identity part, the J2EE authorization model provides 

for the usage of security roles for each servlet and EJB that is deployed to WAS 

for z/OS. The security role is determined at deployment time and is located in the 

deployment descriptor. The security role is then defined in RACF using the 

EJBROLE class in which the profile is checked against the role name to verify 

authority to access code. 

Furthermore, the default caller identity can be changed using the RunAs identity 

mechanism. The RunAs can be: 

► Run as the caller (which is just like the default). 

► Run as server (servant region’s user ID). 

► Run as based on role (role provided by the deployment descriptor) and 

mapped to an EJBROLE in RACF. 

2.5 Our scenarios 

In previous three sections set the tone for the next sections. Regardless of the 

title of the design or the flow of the client and server communication, the main 

goal of this chapter is to describe how security is handled at each stage during 

communication between two endpoints. Therefore, the security issues 

addressed are: 

► Client authentication 

► Client authorization 

► Data confidentiality 

► Data integrity 

Data confidentiality and integrity are secured when SSL is enabled. This means 

that when we say SSL, both confidentiality and integrity are implied. So, by doing 


that, all security issues are discussed in each design that we present in the 

subsequent sections. For each scenario, we present the following: 

► Description 

► Logical flow 

► Configuration tasks and references 

2.5.1 Scenario 1 - authentication in HTTP server 

This scenario is intended to assist those who are z/OS-centric users whose main 

business is still running SNA and TCP/IP based applications, but at the same 

time want to use WAS for z/OS on a small scale with a simple configuration. This 

can be, for example, one HTTP server and one or several application servers. 

In addition, this scenario can be used as a starting point to develop, secure, and 

deploy simple J2EE applications for testing and some small-scale production. 

Description 

Figure 2-3 describes what this design provides. The HTTP server is on z/OS and 

it uses RACF facilities for its authentication requests. Since RACF is already 

used for other security purposes, it can also be used for securing the Web 

applications with minimum effort. The user registry used in WAS is LocalOS 

(SAF-based). 

Keep in mind that this design does not cover the back-end systems such as 

CICS, IMS, and DB2. Connectivity to the back-end systems is addressed 

separately. 

Web 

Client 

HTTP(s) 

HTTP 

Server 

z/OS 

Authentication Authorization DB2 

RACF 

Figure 2-3 Scenario 1 - authenticating on HTTP server 

WebSphere 

Application Server 

The configuration illustrated in Figure 2-3 assumes that the user is a Web client 

and that all client requests start with sending an HTTP request from the browser 


SSO 

CICS 

IMS

to the HTTP server on z/OS. The server redirects all HTTP requests to WAS after 

having done an authentication. 

Single sign-on (SSO) is enabled in WAS, and the user’s security credentials are 

propagated from the HTTP server to WAS. We assume that the user ID with 

which a user authenticates to the HTTP server is the same user ID that will be 

used to access WAS. The HTTP server sends the user’s credentials (certificate, 

basic authentication headers) to WAS when making requests. In this case, the 

HTTP server only operates as a proxy server. It forwards credentials at the HTTP 

protocol layer level. There is no propagation of a user’s identity, but only 

propagation of the user’s security credentials. 

Important: Note that form-based authentication is not possible for this 

configuration. 

We would like to inform the reader that data integrity and confidentiality is implied 

by the fact that the connection is over SSL. 


Logical flow 

The flow deals mostly with authentication and to some degree authorization. 

Figure 2-4 describes the sequence of events that occur during client basic 

authentication and authorization using RACF. 

1. If SSL is requested, first the hello handshake is performed. Then, once the 

channel is secured, the client sends an HTTP request looking for an 

application (servlet/JSP or EJB) deployed in WebSphere Application Server. 

Client 

1 

HTTP 

Server 

WAS 

(sso, TAI) 

Figure 2-4 Scenario 1 - authenticating on HTTP server - logical flow 

2. The HTTP server receives the request from the client, retrieves the client user 

ID and password from the HTTP header, and calls RACF to verify the client’s 

identity. 

3. RACF verifies the identity of the client in its database and replies with a 

positive/negative response. 

4. If the response from RACF is negative, the HTTP server sends a request to 

the client to provide a valid user ID and password. If the response was 

positive, the HTTP server forwards the request to WAS. 

5. WAS looks at the HTTP request and, since single sign-on is enabled, 

bypasses the client authentication step and calls RACF to verify whether the 

client is authorized to execute the operation. 

6. RACF, based on its security definitions, either authorizes the request or 

rejects it. The URI needs to be defined as a protected resource for this 

purpose. 


2 

4 

7 

5 

3 

6 

RACF

7. If the response from RACF for the authorization request was yes, then the 

application requested by the client is executed and a reply is sent back to the 

client with the results. 

Configuration tasks 

Here we provide the list of tasks that need to be done to configure security for 

this design. The main task items are as follows: 

► Enable single sign-on (SSO) via the WebSphere administrative console, as 

follows: secure administration, applications, and infrastructure > single 

sign-on (SSO). 

► Add user ID/password of client to RACF. 

► Define EJBROLES in RACF to enable application authorization. 

► Configure SSL in each endpoint. 

References 

Refer to: 

► IBM HTTP Server Web site at: 

http://www-306.ibm.com/software/webservers/httpservers/doc/v51/icswg 

003.html 

► WebSphere Application Server on z/OS and Security Integration, REDP-4161 

2.5.2 Scenario 2 - authentication in reverse proxy security server 

This design is intended to assist users who are positioning to increase their 

e-business transactions using WAS on z/OS. The design can provide secure 

e-business by putting a Reverse Proxy Security Server (RPSS) outside the z/OS 

domain. That way z/OS and its domain would be within an intranet and anything 

beyond the RPSS would be in the Internet. 

In addition to the RPSS, a firewall can be placed to further tighten the security. 

Therefore, the goal is to have a tightly secured z/OS environment. 


Description 

The scenario illustrated in Figure 2-5 also assumes (as in the previous scenario) 

that the user interface is inside a Web browser and that all transactions start with 

sending an HTTP request from the browser to an HTTP server on z/OS. This 

scenario includes a separate authentication server running outside the z/OS 

platform, and a single HTTP server and WAS running on z/OS. 

Web client 

HTTP(s) 

RPSS 


RPSS = Reverse Proxy Security Server 

HTTP(s) 

Web 

Server 

LDAP 

z/OS 

Native 


WebSphere 

Application 

Server 

Figure 2-5 Scenario 2 - authentication in reverse proxy security server 

Authentication is initially handled by the Reverse Proxy Security Server. Each 

Web client request has to go through this server first before going anywhere else. 

The RPSS’s user registry is an LDAP server on z/OS. The LDAP server on its 

turn is tied to RACF via the native authentication feature of LDAP on z/OS. This 

configuration makes it possible to authenticate outside z/OS using the RACF 

user ID and password. The HTTP server and application server always receive 

an authenticated user ID from the RPSS in a format that the HTTP server can 

understand. This user ID is used for authorization further on in the application 

server and is checked against RACF. There are two available mechanisms to 

forward the user ID: 

► LTPA tokens 

► HTTP headers and the Trust Association Interceptor (TAI) 

Privacy is implemented by using SSL/TLS between the Web client and HTTP 

server. Similarly, SSL can be used between the HTTP server and the application 

server. 

In this design, the RPSS is outside z/OS and it is using the LDAP registry located 

inside z/OS to carry out the authentication of the client. The RPSS and the LDAP 

communication is secured via SSL. 


SSO 

RACF 

Authorization 

CICS 

IMS 

DB2

This design does not cover the back-end systems such as CICS, IMS, and DB2. 

Connectivity to the back-end systems is addressed separately. 

Logical flow 

Data integrity and confidentiality is implied by the fact that the connection is over 

SSL. The flow deals mostly with authentication and to some degree 

authorization. 

Figure 2-6 shows a flow of the authentication from end to end. The flow 

describes a Web client accessing a Web-based application that resides in WAS 

for z/OS. 

Client RPSS LDAP 

1 

6 

2 

5 

3 

Web 

Server 

WAS 

(sso, TAI) RACF 

Figure 2-6 Scenario 2 - authenticating in reverse proxy security server - logical flow 

The flow given in Figure 2-6 describes an event that takes place at each step as 

clients initiate a connection to a J2EE application that is deployed to WAS. The 

sequence of events is: 

1. The client initiates a connection via HTTP to the Reverse Proxy Security 

Server. The connection goes through a three-way handshake and the 

connection is secured if SSL is enabled. Then the client sends the user ID 

and password in a secure communication. 

2. The RPSS receives the client request, looks at the HTTP header, and finds a 

user ID and password. To authenticate the user ID/password, the RPSS 

queries the LDAP server. 

3. The LDAP server is tied to RACF for native authentication and queries RACF 

if the specified user ID is known and valid to RACF. 

7 

10 

Chapter 2. WebSphere security design 39 

8 

4 

9

4. RACF verifies the validity of the user ID and positively replies to LDAP. 

5. LDAP also positively replies to RPSS. 

6. RPSS then forwards the HTTP request to the Web server in z/OS via a 

secure connection if SSL is enabled. 

7. The Web server receives the HTTP request and passes it on to WAS. 

8. If the Since single sign-on (SSO) mechanism is turned on, WAS does not 

need to do another authentication, but queries RACF to see whether the user 

is authorized to execute the work. 

9. RACF checks whether the user is authorized to execute the code (method). 

10.If the response from RACF is positive, the connection is complete, the work is 

done, and a reply is sent back to the client with the results of the operation. 



this design. This list may not be complete, but the main task items are: 

► Enable single sign-on (SSO) via the WebSphere Administrative console as 

follows: secure administration, applications, and infrastructure > single 

sign-on (SSO). 

► Set up LDAP with SDBM configuration. 

► Add user ID/password of client to RACF. 


► Configure SSL in each endpoint. 

References 

For more information see: 


► Secure Production Deployment of B2B Solutions using WebSphere Business 

Integration Connect, SG24-6457 

2.5.3 Scenario 3 - J2EE client authentication using CSIv2 

Our objective here is to demonstrate a simple security aspect between a J2EE 

client and a J2EE application deployed to WAS on z/OS. This design is intended 

to assist users who are beginners to the J2EE (IIOP) communication in how to 

secure IIOP using CSIv2 security. A simple JavaBean program can be 

developed for the client to invoke a method (an EJB) on z/OS and verify that the 

connection is secured with CSv2 protocol. 


Description 

Figure 2-7 is very simple. The J2EE client communicates directly with the 

application server on z/OS using the J2EE Remote Method Invocation over 

Internet Inter-Orb Protocol (RMI-IIOP). There is no HTTP server involved. Again, 

the user registry used in WAS is LocalOS (SAF-based). 

J2EE 

Client 

CSIv2 

RMI/IIOP 


WebSphere 

Application 

Server 

RACF 

z/OS 

Authorization 

Figure 2-7 Scenario 3 - J2EE client authentication with CSIv2 

CICS 

IMS 

At the WAS V6.1 level, there is only one available protocol for communicating 

securely between a J2EE client and WAS for z/OS: Common Secure 

Interoperability Version 2 (CSIv2). CSIv2 is a standard protocol that should be 

used for any new implementations. CSIv2 enables user ID propagation between 

J2EE environments. Using CSIv2, this user ID can be an LDAP distinguished 

name, a client certificate, a basic user ID, and so on. The user ID that is retrieved 

from the CSIv2 protocol can either be a RACF user ID or be mapped to a RACF 

user ID. The transport layer can be secured using SSL/TLS. 

Keep in mind that this design does not cover the back-end systems, such as 

CICS, IMS, and DB2. Connectivity to the back-end systems is addressed 

separately. 

Furthermore, the data integrity and confidentiality aspect of the security is 

handled by CSIv2, which we assume that the reader is aware of. 

Logical flow 

Data integrity and confidentiality is implied by the fact that the connection is over 

CSIv2/SSL. The flow deals mostly with authentication and to some degree 


DB2 


Figure 2-8 shows a flow of a J2EE client accessing WAS on z/OS and the events 

that take place at each step. 

J2EE 

Client 

1 

WAS 

Figure 2-8 Scenario 3 - J2EE client using CSIv2 - logical flow 

The J2EE client initiates the communication using the CSIv2 protocol. By default, 

SSL ports for Common Secure Interoperability Version 2 are dynamically 

generated. The WAS port being used is a secured ORB port. 

1. Once the SSL handshake is complete, the J2EE client sends the internal IIOP 

(GIOP) request to WAS with security information added to the GIOP header. 

2. WAS receives the IIOP (GIOP) request, retrieves the security information, 

and queries RACF to authenticate the client. 

3. RACF checks the database to verify that the client is valid and known, and 

replies to WAS. 

4. WAS receives a positive or negative response for the authentication and, if 

the response from RACF is positive, queries RACF again to verify that the 

client is authorized to execute the code. 

5. RACF checks its profiles to see whether the client is authorized to access and 

execute the requested method and replies to WAS with positive or negative. 

6. WAS receives the response from RACF and, if the reply is yes, the method is 

executed and the reply is sent back to the client with the results. 

Note that all communication between WAS (servlet, EJB) and RACF is internal 

via interprocess communication. 


4 

2 

3 

RACF


Here we provide a list of tasks that need to be done to configure security for this 

design. This list may not be complete, but the main task items are as follows: 

► Add the user ID/password of client to RACF. 


► Enable CSIv2 (inbound/outbound) via the WebSphere administrative console 

on z/OS. 

► CSIv2 is considered enabled on the client with the existence of the 

com.ibm.CORBA.ConfigURL Java property. If the property is not specified or 

the property does not exist, CSIv2 is not enabled. 

References 

Refer to: 

► IBM Redbooks Technote: Configuration of WebSphere Application Server 

Security, TIPS0206, at: 


Facilitys.ibm.com/abstracts/TIPS0206.html?Open 

► IBM Education Assistant at: 

http://publib.boulder.ibm.com/infocenter/ieduasst/v1r1m0/index.jsp? 

topic=/com.ibm.iea.doc/welcome.htm&tab=search&searchWord=csiv2&maxHi 

ts=50 


2.5.4 Scenario 4 - J2EE server authentication using CSIv2 

The objective of this design is to expand the previous design that dealt with a 

J2EE client directly connecting to z/OS. In this design the J2EE client is attached 

to an intermediate box that has a J2EE server running on it. The main goal with 

this design is to show users how authentication can be done using an identity 

assertion mechanism. Once the client is authenticated by the J2EE server 

running machine, there is no need to re-authenticate the client in WAS for z/OS, 

if an identity assertion mechanism is enabled. 

This is the most commonly used J2EE application connectivity, where two J2EE 

servers talk to each other over a secure connection using CSIv2. 

The integrity and confidentiality of data aspect of the security has been taken 

care of by CSIv2 internally and there is no need to describe it. 


Description 

Figure 2-9 shows what this design is all about. The client to the J2EE server 

connection can be secured or not secured, but the J2EE server to WAS z/OS is a 

secure connection. The authentication registry being used in this case is LDAP 

attached to RACF via SDBM. 

J2EE 

Server 

Identity 

assertion 

CSIv2 

Client RMI/IIOP 


z/OS 

WebSphere 


LDAP 

Native 


Authorization 

Figure 2-9 Scenario 4 - J2EE server authentication using CSIv2 

The Common Secure Interoperability Version 2 protocol is designed to exchange 

its protocol elements in the service context of General Inter-ORB Protocol 

(GIOP) request and reply messages that are communicated over a 

connection-based transport. The protocol is intended for use in environments 

where transport layer security, such as that available through Secure Sockets 

Layer (SSL) and Transport Layer Security (TLS), is used for providing message 

protection (that is, integrity and or confidentiality) and server-to-client 

authentication. The protocol provides client authentication, delegation, and 

privilege functionality that might be applied to overcome security deficiencies in 

an underlying transport. 

CSIv2 authentication protocols used by WebSphere Application Server are 

add-on Interoperable Inter-ORB Protocol (IIOP) services. IIOP is a 

request-and-reply communications protocol used to send messages between 

two object request brokers (ORBs). 

For each request made by a client ORB to a server ORB, an associated reply is 

made by the server ORB back to the client ORB. Prior to any request flowing, a 

connection between the client ORB and the server ORB must be established 

over secured TCP/IP transport (SSL is a secure version of TCP/IP). 

An identity assertion is a way for one server to trust another server without the 

need to re-authenticate or re-validate the originating client. In this case, WAS for 


RACF 

CICS 

IMS 

DB2

z/OS is the server configured as the identity asserting server. The server being 

trusted is the J2EE server. 

Also note that this design does not cover back-end systems such as CICS, IMS, 

and DB2. Connectivity to the back-end systems is addressed separately. 

Logical flow 

The numbers shown in Figure 2-10 represent security actions taken at each step 

during a connection setup process. 

1. Initially, the client requests that it wants to access an object that resides on 

WAS for z/OS. Then the client starts its connection request via HTTP or IIOP. 

The connection is secured if SSL is enabled. 

Client 

1 

J2EE 

z/OS 

Server LDAP 

WAS 

RACF 

10 

2 

6 

Figure 2-10 Scenario 4 - J2EE server authentication - logical flow 

2. The J2EE server receives the client request and binds to LDAP to see 

whether the client can be authenticated. The binding to LDAP is over a secure 

connection using SSL. 

3. LDAP, which is connected to RACF via SDBM, then queries RACF to see 

whether the client can be authenticated. 

4. RACF checks its database profiles to verify that the client in question has a 

UID/GID defined for him and replies back to LDAP with the results of the client 

being authenticated or rejected. 

5. LDAP looks at the response from RACF and if the client cannot be 

authenticated, it sends a negative response back to the J2EE server. If the 

response is positive, then connection continues. 

5 

3 

9 


7 

4 

8

6. The J2EE server passes the client request to WAS on z/OS via IIOP (GIOP) 

with the security credentials. 

7. At this stage, authentication is complete, the requested object is located, and 

WAS checks to see whether the user is authorized to access and execute the 

method indicated in the object. To verify authorization, WAS queries RACF. 

8. RACF responds to WAS positively or negatively. 

9. If the response from RACF is positive, then the method is executed and 

results are sent back to the J2EE server. If the response from RACF is 

negative, the method is not executed. 

10.Finally, the outcome of the original operation is sent back to the client. 



this design. This list may not be complete, but the main task items are as follows: 

► Add the user ID/password of the client to RACF. 


► Enable CSIv2 (inbound/outbound) via the admin console on z/OS. 

► Enable identity assertion via the WebSphere administrative console on z/OS. 

References 

Refer to: 

► IBM Redbooks Technote: Configuration of WebSphere Application Server 

Security, TIPS0206, at: 


Facilitys.ibm.com/abstracts/TIPS0206.html?Open 

► IBM Education Assistant at: 


topic=/com.ibm.iea.doc/welcome.htm&tab=search&searchWord=csiv2&max 

Hits=50 

2.5.5 Scenario 5 - JCA custom principal mapping 

WAS Version 6.0.x supports the J2EE Connector architecture (JCA) Version 1.5 

specification, which provides new features such as the inbound resource 

adapter. 

The demand to do more business online has forced companies to find ways to 

integrate their back-end systems such as CICS, IMS, and DB2 to the Internet. To 

integrate the back-end system to the Internet, one of the available solutions is to 

use J2C connectors. But with the J2C security architecture integrated with the 


ack-end rigid security system, accessing applications running on these systems 

may not be trivial. 

Log in to any of the back-end systems via the Internet t requires the user provide 

to his user ID/password several times. The requirement to re-authenticate a user 

is repetitive to some clients. In addition, it is not efficient to use many login 

passwords to access a single application in a system. The requirement to 

re-authenticate users must be minimized to a single sign-on, or at the most two 

sign-ons. 

The Java Connector Architecture (JCA) 1.5 has enhanced its connection factory 

specification to use JAAS for customizing principal login capability. This 

enhanced custom mapping capability allows users accessing the back-end 

system through the connectors to not have to resubmit their user ID/password 

information. 

From a security perspective, WebSphere Application Server Version 6.0.x 

provides an enhanced custom principal and credential mapping programming 

interface and custom mapping properties at the resource reference level. 

Therefore, our objective is to describe a scenario that can be used for 

implementing J2C custom principal mapping. 

Description 

Figure 2-11 to shows J2C custom principal mapping. 

Web Client 

TAM 

WebSEAL 

sso 


LDAP 

z/OS z/OS 

WebSphere 


JCA 

Mapping 

Module 

TAM 

Policy 

Server 

SAF user ID / 

password 

Figure 2-11 Scenario 5 - JCA custom principal mapping authentication 

CTG CICS 


RACF 

Authorization 


As you can see, Web clients are first authenticated by Tivoli Access Manager 

and WebSeal before they can continue to access WAS on z/OS. TAM WebSeal 

is a trusted server to WAS on z/OS and provides the single sign-on. Therefore, 

there is no need for client re-authentication in WAS on z/OS, except for 


Note also that the CICS Transaction Gateway (CTG) and CICS reside in a 

separate z/OS system, and there is a big difference between the CTG being local 

to WAS or remote. We cover the difference later in the flow. 

With GSO principal mapping, a special-purpose JAAS login module inserts a 

credential into the subject header. This credential is used by the resource 

adapter (a pluggable J2C code) to authenticate to the EIS. The JAAS login 

module used is configured on a per-connection factory basis. The default 

principal mapping module retrieves the user name and password information 

from XML configuration files. The JACC provider for Tivoli Access Manager 

bypasses the credential that is stored in the Extensible Markup Language (XML) 

configuration files and uses the Tivoli Access Manager Global Sign-On (GSO) 

database instead to provide the authentication information for the EIS security 

domain. 

WebSphere Application Server provides a default principal mapping module that 

associates user credential information with EIS resources. The default mapping 

module is defined in the WebSphere Application Server Administrative console 

on the Application login panel. To access the panel, click Security → Secure 

administration, applications, and infrastructure. Under Java Authentication 

and Authorization Service, click Application logins. The mapping module name 

is DefaultPrincipalMapping. 

The EIS security domain user ID and password are defined under each 

connection factory by an authDataAlias attribute. The authDataAlias attribute 

does not contain the user name and password. This attribute contains an alias 

that refers to a user name and password pair that is defined elsewhere. 

The Tivoli Access Manager principal mapping module uses the authDataAlias 

attribute to determine the GSO resource name and the user name that is 

required to perform the lookup on the Tivoli Access Manager GSO database. 

The Tivoli Access Manager Policy Server retrieves the GSO data from the user 

registry. 

Tivoli Access Manager stores authentication information about the Tivoli Access 

Manager GSO database against a resource and user name pair. 


Logical flow 

The logical shown in Figure 2-12 describes the steps taken at each stage during 

end-to-end communication with an enterprise information systems (EIS), in this 

case CICS. The flow is very high level but can be useful for indentifying the key 

areas when considering securing an application that communicates with an EIS, 

namely CICS and IMS. 

Client 

1 

TAM 

WebSeal 

4 

2 

3 

LDAP 

WAS 

(sso, TAI) 

5 

J2C 

Principal 

Mapping 

Module 

TAM Policy 

server CTG CICS RACF 

Figure 2-12 Scenario 5 - J2C custom principal mapping authentication - logical flow 

The flow is: 

1. The client opens a browser and mouse-clicks to access a bank account, and 

as a result an HTTP request is sent to TAM WebSeal over a secure 

connection, using SSL. 

2. TAM receives an HTTP request from the client over a secured connection, 

and accesses LDAP to verify whether the client is a known user. 

3. LDAP verifies that the client is a valid user. 

4. TAM WebSeal forwards the HTTP request over a secure connection to WAS 

on z/OS, after having authenticated the client. 

5. WAS for z/OS receives the HTTP request over a secure connection, and the 

Web container passes control to the EJB container to invoke the service. 

6. The service being requested is built based on accessing CICS using a J2C 

connector. Then the principal mapping module calls TAM to provide a 

16 

6 

8 

7 


15 

9 

11 

14 

12 

13 

10

mapping user ID to the user ID and password provided by the J2C resource 

adapter. 

7. The TAM policy server accepts the request and provides a mapped version of 

the user ID and returns control back to principal mapping module. 

8. Once the user ID mapping is done, connection continues, and since CTG is 

not local, the connection is sent over a TCP/IP connection to the destination 

z/OS system running the CTG daemon. 

9. CTG gets control and needs to authenticate the user and queries RACF for 

authentication. 

10.RACF finishes authentication and passes control back to CTG. 

11.CTG calls CICS via an interprocess signal since CICS is local. 

12.CICS needs to check whether the user is authorized to access CICS 

resources and queries RACF for authorization. 

13.RACF verifies that the user is authorized and passes control back to CICS. 

14.The service code is executed and a response with the results is sent back to 

CTG. 

15.CTG sends the response back on the same TCP/IP connection to the J2C 

persistent connection. 

16.From here the result is directly sent to the user. 


To enable the J2C custom principal mapping scenario, at least the following 

configurations are required: 

► CTG configuration 

► J2C adapter resource configuration 

► TAM configuration 

► JAAS login module 

References 

The following resources are helpful in enabling J2EE connectors and the Tivoli 

Access Manager implementation: 

► WebSphere for z/OS V6 Connectivity Handbook, SG24-7064 

► WebSphere Application Server V6.1 InfoCenter 

► Security with IBM Tivoli Access Manager V6 and IBM WebSphere Application 

Server V6 on IBM z/OS, REDP-4205 


2.5.6 Scenario 6 - Web services authentication 

Web services is being touted to be the next Web communication protocol. It uses 

the service-oriented architecture model where one partner is the service 

consumer and the other one is the service provider. Web services uses SOAP for 

its communication, and SOAP is carried over by either HTTP or JMS. 

The objective of this design is to describe a scenario where a Web client 

requests a service that is deployed to WAS on z/OS. The Web client is attached 

to WAS on distributed. See Figure 2-13. 

Web 

Client 

HTTP(s) 

WAS 

Distributed 

Web Service 

ID assertion 

SOAP/HTTP 


Figure 2-13 Scenario 6 - Web services authentication 

WebSphere 

Application 

Server 

LDAP 

z/OS 


The user name and password information is stored in the SOAP message 

header as a username Token. When the username token is received by the Web 

service provider, the user name and password are extracted from the username 

token and are verified. Only when both user name and password are valid is the 

message accepted and processed at the server. 

Using the username token is just one of the ways of implementing authentication. 

This mechanism is also known as basic authentication. Other forms of 

authentication are digital signature, ID assertion, LTPA, and custom tokens. 


Logical flow 

The high-level sequence of events that occur at each step is described as follows 

(Figure 2-14): 

1. The Web client requests access to a service deployed on WAS for z/OS, and 

sends an HTTP request over a secure connection to WAS on distributed. 

Client 

1 

WAS 

z/OS 

Distributed LDAP 

WAS 

RA 

Figure 2-14 Scenario 6 - Web services authentication - logical flow 

2. WAS on distributed binds to LDAP to authenticate the client. 

3. LDAP authenticates the client and returns the reply to WAS on distributed. 

4. WAS on distributed (EJB) builds a SOAP message and sends it over HTTP to 

WAS on z/OS. 

5. WAS on z/OS looks at the SOAP header and retrieves the client security 

information, then binds to LDAP to authenticate the client. 

6. LDAP authenticates the client and returns a reply to WAS on z/OS. Then the 

service provider executes the client’s request. 

7. WAS on z/OS passes the results back to WAS on distributed. 

8. WAS on distributed receives the results and sends back the results to the 

client. 


Web services message security configuration is described in Chapter 6, “Web 

services message layer security” on page 107. 

Web services transport security configuration is described in Chapter 8, “Web 

services transport security” on page 245. 


2 

6 

8 

5 

3 

7 

4

References 

Refer to WebSphere Version 6 Web Services Handbook Development and 

Deployment, SG24-6461. 

2.5.7 Scenario 7 - WMQ client authentication 

WebSphere Message Queueing (WMQ), formerly known as MQSeries, is a 

product developed based on queuing theory. A queue has two endpoints, one for 

putting something into the queue and the other for taking something out of the 

queue. So WMQ provides a queuing mechanism for applications to exchange 

messages. In WMQ, queues are managed by a queue manager. To send and 

receive a message to or from the queue, the applications must first be connected 

to the queue manager through a channel. The channel can be local or remote. 

A WMQ client is an application that can be installed with no local queue 

manager, but can be connected to a remote queue manager via a TCP/IP. 

It would be efficient to run the queue managers on z/OS and the clients running 

WMQ on a different machine. In this case the application doing the MQI calls is a 

WMQ client, and there are benefits in doing that. The benefits can be: 

► There is no need for a full WebSphere MQ implementation on the client 

machine. 

► System administration requirements are reduced. 

► A WebSphere MQ application running on the client machine can connect to 

multiple queue managers on different systems. 

► Alternative channels using different transmission protocols can be used. 


Description 

The configuration described below (Figure 2-15) focuses on security-related 

issues regarding messages that trigger a message-driven bean (MDB). 

MQ 

Client 

MDB = Message Driven Bean 

EJB = Enterprise JavaBean 

Message 

WebSphere 

Application 

Server 


Figure 2-15 Scenario 7 - MQ client authentication 

z/OS 

MDB EJB 

Authorization 

RACF 

When a JMS listener port passes on a message with a JMS or MQ format header 

to the MDB asynchronous processor, there is no password provided in the 

message header and there is no trust relationship established. 

Messages received asynchronously by the MDB are, in many cases, automated 

return messages from some kind of process, such as order received, handled, 

shipped, or delivered. In those cases it is unlikely that the message has 

originated from a user application, or a user, but from a system or process. So, in 

this kind of message processing, the presence of a password in the message 

header is not likely. 

After receiving the message from the listener port, the MDB analyzes the 

message and calls an EJB (stateless session bean), which runs under a system 

user. When the EJB is called, it might be desirable to run it under a user ID 

different from this system user ID in order to use standard J2EE role-based 

security at the user level, and eventually propagate the user ID downstream. 

If you have this requirement, you can have the EJB run under a meaningful user 

ID by performing a JAAS login, with the JMSX user ID. This way the EJB can be 

scheduled with this user ID, and the user information from the MQ message can 

be propagated further. 

Authorization on the provider side, MQ in this case, should be thoroughly 

planned. The listener port that triggers the MDB has a one-on-one relationship 

with a queue as defined in the queue destination. MQQUEUE SAF class profile 


CICS 

IMS 

Authorization

permits should reflect the identities related to the work being done after a 

message has been processed by an MDB. 

Logical flow 

By default, WMQ does not provide secure access when using client mode (see 

JMS transport security part 1 and 2 at developerWorks®), which communicates 

over TCP/IP. So, the client mode is unsecure unless SSL is configured and the 

JMS port is secured. 

WMQ 1 


Client MDB EJB 

CICS 

RACF 

1 

2 

4 

Figure 2-16 Scenario 7 - WMQ client authentication and authorization - logical flow 

The flow of this solution can be described as follows: 

1. The MQ client issues an MQI call and an SSL handshake is done to secure 

the connection. The client message is sent via the secured channel to the 

remote queue manager on WMQ on z/OS. 

2. The message is received on the WMQ port on z/OS and a message-driven 

bean is triggered. The bean extracts the user ID and password and queries 

RACF to check whether the user can be authenticated. 

3. RACF replies to the MDB after the client is authenticated. 

4. The MDB generates a passticket for the RACF user ID, using special code 

that can generate the passticket, or by calling a JAAS login module with the 

(RACF) user ID sent in the message and the password and the passticket 

generated in the previous step. Then the (stateless) session EJB is called 

with RunAs set to the (RACF) user ID used in the previous step. 

7 

5 


8 

3 

6 

9

5. WAS calls RACF to see whether the RunAs user is authorized to execute the 

EJB. 

6. RACF replies with the results and, if there is a positive response, the flow 

continues. 

7. The EJB then passes the message on to CICS via a message queue 

channel. 

8. CICS then calls RACF to check whether the passed user ID is authorized to 

execute code in its region. 

9. RACF responds with positive or negative. 

10.If the response from RACF is positive, the message is delivered to CICS, and 

at this time the message is said to be delivered. 

Reference 

Refer to: 

► WebSphere MQ Security, SC34-6588 

► WebSphere MQ Clients, GC34-6590 

► IBM WebSphere Developer Technical Journal: Securing connections 

between WebSphere Application Server and WebSphere MQ -- Part 1 at: 

http://www-128.ibm.com/developerworks/websphere/techjournal/0601_rat 

nasinghe/0601_ratnasinghe.html 

2.5.8 Scenario 8 - authorization using external authorization server 

Traditionally, authorization on the z/OS platform is done via the Resource 

Access Control Facility. But time has changed and technology has also changed. 

Many originally z/OS applications have a Web front-end nowadays and may 

even have a new tier in the middle. Many times, those new layers and front ends 

use Java, J2EE, and open source code and provide APIs to perform 

authorization functions, either locally or remotely (external to z/OS). 

Externalizing authorization can be cost effective, but at the same time it can be 

costly in terms of authorization response time. It can also introduce additional 

complexity, when multiple registries (on z/OS and on distributed) are being used 

and have to be kept in-sync. We cannot say that externalizing authorization is 

good for everyone. It depends on the end-to-end configuration of the systems 

that require user authorization. 

Description 

Java Contract for Containers (JACC) support allows the use of third-party 

authorization providers for access decisions. The default JACC provider for WAS 


is the Tivoli Access Manager. Tivoli Access Manager client functions are 

integrated in WAS. 

The configuration shown in Figure 2-17 has an external authorization server that 

has access to WAS on z/OS. 

Web Client 

HTTP(s) 

RPSS 

RPSS = Reverse Proxy Security Server 

HTTP(s) 


Web 

Server 

z/OS 

WebSphere 

Application 

Server 

Authorization 

Server 

Figure 2-17 Scenario 8 - authorization using external authorization server 

Authorization with 

JACC 

First the authentication is done through propagation of the client user ID using 

two possible mechanisms: LTPA tokens or the Trust Association Interceptor, 

which both provide single sign-on capability. Then WAS communicates with the 

external authorization server to verify that the user has been authorized to 

access the requested object. 


To configure an external authorization server, use the WAS admin console: 

1. Select Secure administration, applications, and infrastructure → 

External authorization providers. 

2. Then select External authorization using a JACC provider. 

3. Select Secure administration, applications, and infrastructure → 

External authorization providers → Tivoli Access Manager. 

4. Fill out the general properties and Tivoli Access Manager properties. The 

general properties are: 

– Name (This is the name of the external authorization server name.) 

– Policy class name 

– Policy configuration factory class name 

– Role configuration factory class name 

– Provider initialization class name 

LDAP 

HTTP(s) 

SSO 

User Registry 


References 

Refer to: 

► IBM WebSphere Application Server V6.1 Security Handbook, SG24-6316 


2.5.9 Scenario 9 - bridged security between z/OS and distributed 

using JAAS 

This section describes how a non-z/OS server can be bridged to WAS for z/OS 

via JAAS. 

JAAS has been defined in many books in many ways, but in the simplest terms 

JAAS is pluggable code used by WAS to authenticate and authorize users. In 

fact, JAAS means a user exit. 

When using JAAS to authenticate a user, a subject is created to represent the 

authenticated user. A subject comprises a set of principals, where each principal 

represents an identity for that user. You can grant permissions in the policy to 

specific principals. After the user is authenticated, the application can associate 

the subject with the current access control context. So, basically, the control is in 

the JAAS login module as to whether to authenticate or reject user requests 

coming in through WAS on distributed. 

This configuration describes a scenario where two existing security domains that 

operate in two different platforms can be consolidated. 


Description 

Bridging, as defined in networking, is to join two or more different network 

platforms so that there is communication between users residing in either side of 

network. The distributed world and the z/OS world are two different platforms, 

and JAAS can be used for securing communication between them. 

Client 


WAS 

Distributed 

Authorization 

LDAP 

CSIv2 

RMI/IIOP 

JAAS 

Login 

Module 

z/OS 

WebSphere 

Application 

Server 

RACF 


Authorization 

Figure 2-18 Scenario 9 - bridged security between z/OS and distributed 

CICS 

IMS 

The challenge for a large enterprise is to leverage its existing security 

mechanisms on all of its platforms and to create an end-to-end security context 

flow. For example, if WAS is used as a layer to give a large number of users 

access to data that is kept in DB2, there would be security issues that need to be 

addressed. Some of these issues would be: 

► How to define all those potential users in RACF 

► If not defined in RACF, how to secure access to DB2 or other back-end 

systems in a sufficient manner 

► How to synchronize all existing user registries 

The suggested scenario illustrated in Figure 2-18 describes a combination of 

distributed security making use of a JAAS login module for authentication and 

authorization purposes and z/OS security for checking back-end access by 

means of RACF. 

► The user ID must be verified based on the user ID and password. 

► The message has to be encrypted to guarantee transport security, using 

SSL/TLS. 

► All Web-related parts of the enterprise application are deployed to WAS on 

distributed in this scenario. The user is allowed to access the application part 

(servlet, JSP) that calls an EJB in WebSphere on z/OS (WAS on z/OS being 

the J2EE server). WAS on distributed acts as a J2EE client to WAS on z/OS. 

DB2 


► The user’s credentials are sent over RMI-IIOP using the CSIv2 security 

protocol to WAS on z/OS. 

► A custom-built JAAS login module is configured on z/OS to retrieve the tag 

from the credentials, map it to a system user, and set it as a principal for 

downstream authorizations. WAS on z/OS is configured to use localOS as an 

active user registry. Role-based security constraint decisions are handled by 

the security server (RACF) on z/OS. EJBROLE/GEJBROLE profiles are 

checked for that purpose. 

► Accessibility to z/OS back ends is handled by RACF in the usual manner. 

In this scenario there is no need to synchronize user registries. The addition of a 

tag to the user’s credentials and the mapping of that tag to a z/OS system user is 

the key for back-end access on z/OS. The amount of mapped RACF IDs in this 

way can be relatively limited, depending on the different types of access you wish 

to give to the Internet user. To block an unknown user coming in through the 

Internet, you could use a WebSEAL in front to the WAS distributed server. 

References 

Refer to IBM WebSphere Application Server V6.1 Security Handbook, 

SG24-6316. 

2.5.10 Scenario 10 - centralized user registry using LDAP on z/OS 

This scenario is to show users how LDAP and RACF can cooperate to provide a 

flexible user registry. 


The objective of this scenario is to describe the benefits of running an LDAP with 

SDBM. See Figure 2-19. 

Web 

Client 

HTTP(s) 

Web 

Server 

z/OS 

HTTP(s) 

WebSphere 

Application 

Server 

Authorization 

z/OS 

LDAP 


WAS distributed 

Web 

Client 

Figure 2-19 Scenario 10 - centralized z/OS LDAP user registry 

SDBM 


RACF 

The Lightweight Directory Access Protocol is an open industry standard that has 

evolved to meet these needs. LDAP defines a standard method for accessing 

and updating information in a directory. LDAP has gained wide acceptance as 

the directory access method of the Internet. 

Understanding LDAP design and implementation is becoming strategic within 

corporate intranets. It is being supported by a growing number of software 

vendors and is being incorporated into a growing number of applications. For 

example, the two most popular Web browsers, Netscape 

Navigator/Communicator and Microsoft Internet Explorer®, as well as application 

middleware, such as the IBM WebSphere Application Server or the IBM HTTP 

server, support LDAP functionality as a base feature. 


References 

To learn more about LDAP and RACF integration on z/OS, refer to: 

► Understanding LDAP - Design and Implementation, SG24-4986 

► Implementation and Practical Use of LDAP on the IBM eServer iSeries 

Server, SG24-6193 

► Using LDAP for Directory Integration, SG24-6163 


Chapter 3. Web container security 

The Web container processes servlets, JSPs, and other types of server-side 

includes. Requests are sent by the Web client. Web clients use the HTTP or 

HTTPS protocol to send the authentication information. Web authentication is 

required for Web clients when they access protected resources and is performed 

by the Web authentication module. 

In WAS V6.1, Web container security is improved. We introduce the Web 

authentication improvements in this chapter: 

► “Web authentication improvements” on page 64 

► “Implementation with the admin console” on page 65 

► “Why you should use these options” on page 69 

3 


3.1 Web authentication improvements 

An authentication mechanism defines rules about security information, for 

example, whether a credential is forwardable to another process, and the format 

security information is stored in. 

In V6.1, the Web authentication mechanism is improved. We introduce the 

following Web authentication improvements in this chapter: 

► Separate Web authentication and authorization, discussed in “Separate Web 

authentication and authorization” on page 64 

► Enhanced control over Web authentication behavior, discussed in “Web 

authentication enhanced control” on page 64 

3.1.1 Separate Web authentication and authorization 

In WebSphere Application Server V6.1, Web authentication and authorization 

are separated. 

Before supporting this new function, in order for a request to be authenticated, it 

had to be a Uniform Resource Identifier (URI) requiring authorization, too. 

Now, Web authentication can be performed with or without Web authorization, 

and the Web client’s authenticated identity is available whether or not Web 

authorization is required. An authenticated identity is persisted both for protected 

and unprotected resources. Without the separation of Web authentication and 

Web authorization, a Web authenticated identity is not available when Web 

authorization is not required, and programmatic security cannot work 

independently without container declarative security. 

3.1.2 Web authentication enhanced control 

WebSphere Application Server provides enhanced control over the 

authentication behavior of a Web client. 

Depending upon the option that you select, WebSphere Application Server can 

retain the authentication data for future use. This adds flexibility to the handling 

of authentication for Web applications: 

► To allow failed certificate authentication to fall back to basic authentication 

(user ID/password challenge). 

► To allow the retention of an authenticated identity and make it available to 

Web applications running under an unprotected URI. Without this capability, 


such Web applications would not be able to use getRemoteUser(), 

isUserInRole(), or getUserPrincipal(). 

3.2 Implementation with the admin console 

You can configure the Web authentication behavior with the WebSphere 

administrative console. 

3.2.1 General settings at the cell level 

Through the following setting, Web authentication behavior is controlled. This 

setting affects the entire cell. Remember that it affects all applications deployed 

to the cell. 

In order to set up the Web authentication behavior: 

1. Click Security → Secure administration and applications. 

2. Under Authentication, select Web security → General settings (Figure 3-1). 

Figure 3-1 Web security settings in WebSphere admin console 

The following options exist to change the behavior of Web authentication when 

accessing a URI: 

► Authenticate only when the URI is protected. 

This is a default option, and is the same as in the previous version of 

WebSphere. The Web client can retrieve an authenticated identity only when 

it accesses a protected URI. WebSphere Application Server challenges the 

Chapter 3. Web container security 65

Web client to provide authentication data when the Web client accesses a 

URI that is protected by a J2EE role. 

► Authenticate when any URI is accessed. 

The Web client must provide authentication data regardless of whether the 

URI is protected. 

Figure 3-2 URI access authentication behavior 

The following options are available for Web authentication enhanced control: 

► Use available authentication data when an unprotected URI is accessed. 

The Web client is authorized to call the getRemoteUser, isUserInRole, and 

getUserPrincipal methods. It retrieves an authenticated identity from either a 

protected or an unprotected URI. Although the authentication data is not used 

when you access an unprotected URI, the authentication data is retained for 

future use. This option is available when you select the “Authenticate only 

when the URI is protected” check box. 

► Default to basic authentication when certificate authentication for the HTTPS 

client fails. 

The WebSphere Application Server challenges the Web client for a user ID 

and password when the required HTTPS client certificate authentication fails. 


Figure 3-3 Web authentication enhanced control 

3.2.2 Control server level Web authentication behavior 

The settings introduced in 3.2.1, “General settings at the cell level” on page 65 

control Web authentication behavior on the cell level. If you wish to control it on 

the server level, you can specify the system properties given in Table 3-1. 

Table 3-1 Web authentication system property values 

Property name Value Description 

com.ibm.wsspi.security.web.webA 

uthReq 


uthReq 


uthReq 

lazy equiv. 

Authenticate only when the URI is 

protected option 

persisting equiv. 

Use available authentication data 

when an unprotected URI is 

accessed option 

always equiv. 

Authenticate when any URI is 

accessed option 


Property name Value Description 

com.ibm.wsspi.security.web.failO 

verToBasicAuth 

true equiv. 

Default to basic authentication 

when certificate authentication for 

the HTTPS client fails option 

To specify the system property, complete the following steps: 

1. Click Servers → Application servers → server_name. 

2. Under Server Infrastructure, click Java and Process Management → 

Process Definition → Servant → Java Virtual Machine. 

3. Under Additional properties, click Custom properties → New. 

4. Specify property name and value, as shown in Figure 3-4. 

Figure 3-4 Configuration of Web security for server level control 


Figure 3-5 shows that a new property has been added. 

Figure 3-5 Example of server level control for Web security 

You can override the general settings of Web security by specifying a system 

property on the server level. 

3.3 Why you should use these options 

The following are good reasons to use the options discussed: 

► As an alternative to using a role with all authenticated. 

All authenticated specifies whether to map all of the authenticated users to a 

specified role. When you map all authenticated users to a specified role, all of 

the valid users in the current registry who have been authenticated can 

access resources that are protected by this role. 

► Do your own authorization with no role. 

► Use SAF EJBROLEs. 



Chapter 4. Application security 

4 

One of the features of WebSphere is the ability to enable or disable global 

security. Global security acts as a switch that enables various security settings in 

WebSphere. For WebSphere V6.1 for z/OS, security enablement has been 

extended to allow enabling or disabling of application security while leaving 

administrative security enabled. By separating the two, application security can 

be disabled to diagnose application-related setup problems, while still leaving 

administrative security enabled to protect the administrative console. Application 

security is disabled by default. 

To enable application security, both administrative security and application 

security must be enabled. This brief chapter explains how to do this. 


4.1 Administrative security enablement 

Turning on administrative security activates the settings that protect your server 

from unauthorized users. The settings include the authentication of users, the 

use of Secure Sockets Layer (SSL), and the choice of user account repository. 

Administrative security protects the following: 

► Authentication of HTTP clients 

► Authentication of IIOP clients 

► Administrative console security 

► Naming security 

► Use of SSL transports 

► Role-based authorization checks of servlets, enterprise beans, and mbeans 

► Propagation of identities (RunAs) 

► CBIND checks 

► The common user registry 

► The authentication mechanism 

► Other security information that defines the behavior of a security domain 

includes: 

– The authentication protocol (remote method invocation over the Internet 

Inter-ORB Protocol (RMI/IIOP) security) 

– Other miscellaneous attributes 

4.2 Application security enablement 

Application security enables security for the applications in your environment. 

This type of security provides application isolation and requirements for 

authenticating application users. 

For Web resources, when application security is disabled, security constraints on 

those resources in the web.xml located in the Web application archive (WAR) file 

are not enforced. When accessing a protected resource, a Web client is not 

prompted for authentication, and the resources protected by the security 

constraint can be accessed by anyone. For example, authentication methods 

such as form-based authentication, basic authentication, and client certificate 

authentication are not in affect when application security is disabled. Resources 

such as HTML pages, images, or other files are accessible by everyone. In 


addition, transport settings that guarantee integrity or confidentiality are also not 

in effect, and the application can be accessed from a non-SSL port. 

For enterprise bean resources, when application security is disabled, the client 

Common Secure Interoperability Version 2 (CSIv2) code ignores the CSIv2 

security tags for objects that are unknown system objects. When pure clients see 

that application security is disabled, these clients prompt for naming lookups, but 

do not prompt for enterprise bean operations. 

Attention: Administrative security must be enabled in order to enable 

application security. 

Application security can be enabled or disabled in the administrative console by 

following the path Security → Secure administration, applications, and 

infrastructure. 

Chapter 4. Application security 73

Figure 4-1 illustrates the application security enablement check box in the 


Figure 4-1 Enabling application security 


Chapter 5. Web services security 

introduction 

5 

This chapter provides an introduction for Chapter 6, “Web services message 

layer security” on page 107 and Chapter 8, “Web services transport security” on 

page 245. Here we discuss security for Web services as part of a 

service-oriented architecture (SOA). We introduce the message and the 

transport layers where security can be enforced. Then we further describe 

security features available for each layer. Finally, we present our test application 

in our test environment. 

This chapter focuses on presenting Web services security concepts, whereas the 

following two chapters focus on the practical implementation of these concepts in 

WebSphere Application Server for z/OS. 

The following topics are discussed here: 

► “SOA, Web services, z/OS, and security” on page 76 

► “Web services security exposures” on page 77 

► “Web services message and transport security” on page 78 

► “Web services message layer security with WS-Security” on page 81 

► “Web services transport layer security” on page 90 

► “Our SecurityInfo Web service application and environment” on page 98 


5.1 SOA, Web services, z/OS, and security 

About 50% of WebSphere Application Server for z/OS applications running in 

production are used as an “integration layer in Service-Oriented Architecture” 

(Gartner 2005). This integration layer for SOA is composed of Web services or 

EJBs. For example, it may integrate services deployed in core-business 

transaction processors such as CICS or IMS, or services deployed in 

WebSphere Application Server for z/OS itself. 

WebSphere Application Server for z/OS is a central component in an SOA for the 

following purposes: 

► SOA-enable, extend, and reuse existing mainframe assets. 

► Execute business critical services requiring the highest quality of service. 

► Connect and integrate services or composite applications across disparate 

information systems. 

WebSphere Application Server for z/OS is also the foundation of strong SOA 

building blocks such as WebSphere ESB for z/OS (Enterprise Service Bus) and 

WebSphere Process Server for z/OS. WebSphere ESB for z/OS provides a 

flexible connectivity infrastructure for integrating services. WebSphere Process 

Server for z/OS forms processes and orchestrates services. 

Web services is the most common technology standard used to implement SOA. 

However, it is not the only technology one can use to develop the parts of an 

SOA. Many SOAs involve the integration of legacy data, which is contained in 

systems that use technology such as MQSeries and CORBA. However, Web 

services is rapidly becoming the de facto standard used to support SOA. 

As companies are transforming towards SOA, information systems reach an 

unprecedented level of integration and flexibility. SOA is about integration inside 

or across enterprises. In such an environment, non functional requirements 

become increasingly important. Performance, scalability, availability, 

manageability, and so on, must be taken into account. But, because SOA 

involves the core business applications, because SOA impacts the handling of 

critical business data, one of the major non functional requirements to consider is 

security. 

In this chapter we introduce Web services security features relating to 



5.2 Web services security exposures 

Generally, an end-to-end security solution addresses the security issues found 

along the path of a request from an end client to a target service, including any 

intermediary services that route, or participate in, the service request. 

Potential security exposures are illustrated in Figure 5-1. 

Figure 5-1 Potential security exposures with Web services 

These potential security exposures are of three kinds: 

► When there is no authentication, spoofing can happen. An attacker can send 

a modified SOAP message to the service provider, pretending to be a bank 

teller, to obtain confidential information, or to withdraw money from another 

customer’s account. 

► When there is no integrity, tampering can happen. The SOAP message can 

be intercepted between the Web service requester and provider. An attacker 

can modify the message, for example, to deposit the money into another 

account by changing the account number. Because there is no integrity 

constraint, the Web service provider does not verify whether the message is 

valid, and accepts the modified transaction. 

► When there is no confidentiality, eavesdropping can happen. Without data 

encryption, SOAP messages are sent in clear text, and the information 

contained in the message can be intercepted or read by an attacker. 

Confidential customer or bank information can get into the wrong hands. 

Chapter 5. Web services security introduction 77

5.3 Web services message and transport security 

In order to protect against the risk of the above-mentioned security exposures, it 

is possible to use a combination of two types of security to secure the Web 

services environment: 

► Message layer security 

In the Web services context, the message layer is the SOAP layer. The 

WS-Security specifications indicate how SOAP Extensible Markup Language 

(XML) messages can carry security contexts. 

► Transport layer security 

In the Web services context, the transport layer can be of different types: 

Hypertext Transfer Protocol (HTTP), Remote Method Invocation/Internet 

Inter-ORB Protocol (RMI/IIOP), and WebSphere MQSeries. Hence, transport 

layer security relies on the security features offered by the chosen transport 

protocol. These transport layers typically carry authentication information in 

headers, with optional additional security provided by encapsulation in the 

Secure Sockets Layer (SSL)/Transport Layer Security (TLS) protocol. 

Because TLS establishes security context that is meaningful only to the two 

physical endpoints of a connection, it does not fully meet typical Web services 

end-to-end security requirements. For example, an HTTP connection can be 

protected by SSL/TLS. However, the security context resulting from the partners’ 

mutual authentication, and the negotiation of cryptographic parameters, cannot 

be propagated from the user to the final service if intermediary services or 

gateways have to be traversed. 

On the other hand, the WS-Security specifications allow for the propagation of 

security context, using SOAP messages. 


Figure 5-2 illustrates the differences between message and transport layer 

security. 

Figure 5-2 Web services message and transport layer security 

Transport layer security (such as basic authentication and SSL client 

authentication) is a point-to-point security that identifies one server to another but 

does not allow for security context information to be passed through 

intermediaries or gateways. 

WS-Security addresses this problem by allowing security credentials to be 

passed within the SOAP message, so that the credentials of the service 

requester can be passed via an intermediate gateway, and can still be used to 

identify the requester to the service provider. This is end-to-end security. 

It is possible to implement Web services security at two levels: the message 

layer level and the transport layer level. If the Web services environment is 

simple (for example, it does not span multiple nodes), a security solution based 

on transport level security alone may be all that is needed. For more complex 

scenarios, however, it may not be enough on its own. 

In the two following sections, we provide general guidelines to help decide what 

type of security solution to implement. 


5.3.1 When to use message layer security 

A security solution might choose to use message layer security with WS-Security 

when: 

► Intermediaries are used. Intermediaries is a generic word for any server, 

gateway, appliance, or ESB that can handle SOAP messages. Intermediaries 

might provide services or mediations to the SOAP requests. For example, a 

gateway might provide an authentication service and then forward credentials 

or an asserted identity to the Web service provider. 

► Multiple transport protocols or middleware are being used. Message layer 

security with WS-Security is transport independent. This gives a lot of 

flexibility and allows you to change the transport protocol without having to 

change the security architecture. 

► The Web service partners support WS-Security, and a general decision has 

been made to flow security tokens in accordance with the WS-Security 

specification. This decision may also be made so that the security design is 

based on open standards. 

► Multiple parts of the message have to be secured in different ways. You can 

apply multiple different security requirements, such as integrity, on the 

security token (user ID and password), and confidentiality on the SOAP body. 

► Identity assertion or attribute propagation is required. If an already 

authenticated user needs to access a Web service that has to know the user 

identity, then it is necessary to propagate the user identity and maybe the 

security context to the Web service provider. WS-Security implements identity 

assertion. 

Message layer security can be used with or without transport security. 

5.3.2 When to use transport layer security 

A security solution might choose to use transport layer security when: 

► No intermediaries are used in the Web service environment or, if there are 

intermediaries, you can guarantee that once the data is decrypted, it cannot 

be accessed by an untrusted node or process. 

► The transport is only based on one protocol or middleware such as HTTP, 

RMI/IIOP, messaging middleware, and so on. 

► The complete SOAP message integrity and confidentiality need to be 

ensured. WS-Security allows you to ensure integrity and confidentiality for 

parts of the SOAP message. Some security architecture might find easier or 

more secure to ensure full SOAP message integrity and confidentiality. 


► The Web service client or provider does not support the WS-Security 

specification. 

► A trust relationship needs to be created between two parties. This is 

particularly useful to build up the trust relationship for identity assertion. In 

that case, identity assertion occurs at the message layer and the trust 

relationship occurs at the transport layer. 

Transport layer security can be used with or without message layer security. 

5.4 Web services message layer security with 

WS-Security 

In this section we introduce Web services security at the message layer level. 

We describe the WS-Security standard and how WebSphere Application Server 

for z/OS supports it. 

5.4.1 End-to-end security 

End-to-end security is about ensuring integrity, confidentiality, authentication, 

and authorization along the path between the user’s initial authentication, across 

intermediaries, and the for final use of the authenticated identity for the purpose 

of access control or auditing. 

Because the WS-Security specifications allow for the propagation of security 

context using SOAP messages, Web service message layer security provides 

the ability to enforce end-to-end security. 


5.4.2 WS-Security standard 

SOAP messaging security is defined in the WS-Security standard. The other 

specifications define security services that themselves are implemented as Web 

services. See Figure 5-3. 

Figure 5-3 WS-Security standard 

The WS-Security specifications evolve to standards as a process driven by the 

Organization for the Advancement of Structured Information Standards (OASIS). 

OASIS is a not-for-profit, international consortium that drives the development, 

convergence, and adoption of On Demand business standards. Members 

themselves set the OASIS technical agenda, using a lightweight, open process 

expressly designed to promote industry consensus and unite disparate efforts. 

The consortium produces open standards for Web services, security, On 

Demand business, and standardization efforts in the public sector and for 

application-specific markets. 

WS-Security defines a set of extensions to the SOAP standards, which are used 

to: 

► Provide message integrity and confidentiality for SOAP messages. 

► Associate a security token to a SOAP message. 

► Provide for the propagation of a security context. 

Other WS-Security specifications are introduced briefly in the following list: 

► WS-Policy 

This addresses the capabilities and constraints of security or business 

policies on intermediaries and endpoints, for instance, required security 

tokens, supported encryption algorithms, and privacy rules. 


► WS-Trust 

This describes a framework for trust models that enable Web services to 

securely interoperate. 

► WS-Privacy 

This describes a model for how Web service providers and requestors state 

privacy preferences and organizational privacy practice statements. 

► WS-Secure Conversation 

This describes how to manage and authenticate message exchanges 

between parties, including security context exchange and establishing and 

deriving session keys. 

► WS-Federation 

This describes how to manage and broker the trust relationships in a 

heterogeneous federated environment, including support for federated 

identities. 

► WS-Authorization 

This describes how to manage authorization data and authorization policies. 

WS-Security provides a general purpose mechanism for associating security 

tokens with messages. Typical examples of security tokens in 

WebSphere-based Web services are user name and password, X.509 

certificates, and LTPA tokens. 

5.4.3 WS-Security support in WebSphere 

The WS-Security support is provided in WebSphere 5.0.2 and later. Each 

version of WebSphere is based on different versions of the Web services 

security language. 

The first version of the WS-Security specification was proposed by IBM, 

Microsoft, and VeriSign in April 2002. After the formalization of the April 2002 

specifications, the specification is transferred to the OASIS consortium. In OASIS 

activities, core specification and many profiles that describe the use of a specific 

token framework in WS-Security have been discussed. The latest specification 

and profiles of WS-Security were proposed in March 2004 as the OASIS 

standard. The latest core specification, Web Services Security: SOAP Message 

Security 1.0 (WS-Security 2004) was standardized in March 2004. The two 

profiles, Web Services Security Username Token Profile 1.0 and Web Services 

Security X.509 Certificate Token Profile 1.0, were standardized at the same time. 

There are other token profiles that OASIS is currently working on: Web Services 

Security: SAML Token Profile, Web Services Security: Rights Expression® 


Language (REL) Token Profile, Web Services Security: Kerberos Token Profile, 

Web Services Security: Minimalist Profile (MProf), and Web Services Security: 

SOAP Message with Attachments (SwA) Profile. 

The support of the April 2002 specification is provided in WebSphere 5.0.2 and 

5.1. WebSphere Application Server Versions 6.0 and 6.1 support the 

WS-Security 1.0 specification and two profiles (UserName-Token 1.0, x.509 

Token 1.0). 

WebSphere Application Server for z/OS supports most of the WS-Security 

specifications and profiles. Web services security is still fairly new, and some of 

the standards are still being defined or standardized. Some functionalities are not 

supported in WebSphere Application Server for z/OS. 

For more details about what precisely is supported with WebSphere Application 

Server for z/OS, refer to the InfoCenter: 


com.ibm.websphere.zseries.doc/info/zseries/ae/cwbs_supportfunction.html 


com.ibm.websphere.zseries.doc/info/zseries/ae/cwbs_welcwebsvcsec.html 

5.4.4 WS-I basic security profile support 

Web services Interoperability Organization (WS-I) is an open industry effort 

promoting Web services interoperability across vendors, platforms, programming 

languages, and applications. One of WS-I’s major deliverables to date is WS-I 

Basic Profile, which provides implementation guidelines for how the profiled Web 

services specifications should be used together for best interoperability. WS-I 

Basic Profile V1.1 (BP1.1) is supported in WebSphere v6.0 and later. 

WS-I Basic Security Profile (BSP) v1.0 is a working group draft that consists of a 

set of non-proprietary Web services specifications that clarifies and amplifies 

those specifications to promote Web services security interoperability across 

different vendor implementations. 

WebSphere Application Server for z/OS v6.1 now supports applications to 

comply with the WS-I Basic Security Profile V1.0. It provides configuration 

options to ensure that the BSP recommendations and security considerations 

can be enabled to ensure interoperability. 


5.4.5 WS-Security high-level architecture 

Figure 5-4 shows the WS-Security high-level architecture of how WebSphere 

applies WS-Security information to the SOAP message. 

Figure 5-4 WS-Security high-level architecture 

WS-Security is designed and implemented as message level handlers of the 

Web services engine. A WS-Security handler is a system handler (called security 

handler in the figure) and is registered to the Web service run time. 

► On the client side (assuming a WebSphere J2EE client), the WS-Security 

handler is invoked to generate the required security headers in the SOAP 

message before the message is sent out to the wire. The security handler 

generates the security constraint defined in the deployment descriptor and 

packages the security information (digital signature, encrypted data, and 

security tokens) in the SOAP message. 

► On the server side, the WS-Security handler is called to enforce the declared 

security constraint in the deployment descriptor prior to dispatching the 

request to the Web service EJB or JavaBeans implementation. 

This is similar to security interceptors with CSIv2. 

The security constraints of the request sender and the request receiver must 

match. Also, the security constraints of the response sender and response 


eceiver must match. For example, if you specify integrity as a constraint in the 

request receiver, then you must configure the request sender to have integrity 

applied to the SOAP message. Otherwise, the request is denied because the 

SOAP message does not include the integrity specified in the request constraint. 

5.4.6 Message authentication, integrity, confidentiality, ID assertion 

Using WS-Security, the authentication mechanism, integrity, confidentiality, and 

identity assertion can be applied at the message level. 


Web services security provides a general-purpose mechanism to associate 

security tokens with messages for single message authentication. A specific type 

of security token is not required by Web services security. Web services security 

is designed to be extensible and support multiple security token formats to 

accommodate a variety of authentication mechanisms. 

WS-Security supports the following authentication mechanisms via the insertion 

of a security token: 

► Basic authentication: The security token includes the user name and 

password information, and is generated as with 

and . 

► Signature: The security token includes the X.509 certificate of the signer of 

the data and is generated as with 

. 

► ID assertion: ID assertion includes a user name only, since the identity is 

asserted, and is generated as with 

only. 

► Custom: This mechanism includes a custom-defined token. 

► LTPA: Use of an LTPA token is a WebSphere-specific customer token, 

generating a with . 

When using WS-Security for authentication, a security token is embedded in the 

SOAP header and is propagated from the message sender to the intended 

message receiver. On the receiving side, it is the responsibility of the server 

security handler to authenticate the security token and to set up the caller identity 

for the request. 

Section 6.2, “Authentication with a security token” on page 115, describes in 

detail how to configure WS-Security authentication with WebSphere Application 

Server for z/OS. 


Integrity 

Integrity is applied to a message to ensure that no one modifies the message 

while it is in transit. Essentially, integrity is provided by generating an XML digital 

signature on a part of the SOAP message. If the message data changes, the 

signature would no longer be valid. 

With WS-Security, it is possible to use XML digital signatures in conjunction with 

security tokens to detect any modifications to messages. Data integrity is 

provided by generating a signature from the contents of the SOAP message. If 

the message data changes, the signature is found to be invalid by the recipient. 

The use of XML digital signatures also provides authentication, because a valid 

signature implies proof of possession of a private key. A message with a digital 

signature contains the digital certificate of the signer, and therefore the signer’s 

name and bound public key are validated by a trusted certificate authority. The 

trustworthiness of the signature is then a transitive trust process. The trusted 

certification authority vouches for the public key value used to verify the 

signature. 


A digital signature is a word attached to the message. This signature establishes 

that the message has not been modified and the identity of the signer of the 

message. See Figure 5-5. 

Figure 5-5 Digital signature creation and validation 

A digital signature is created in two steps: 

1. The first step distills a part of the SOAP message (for example, the body) into 

a large number. This number is the digest code or fingerprint. Several options 

are available for generating the digest code, for example, the MD5 message 

digest function and the SHA1 secure hash algorithm. Both of these 

procedures reduce a message to a number. The crucial aspect of distilling the 

document to a number is that if the message changes, even in a trivial way, a 

different digest code results. When the recipient gets a message and verifies 

the digest code by recomputing it, any changes in the document result in a 

mismatch between the stated and the computed digest codes. 


2. In the second step, the digest code is encrypted with the sender's private key. 

This two-step process creates the digital signature. The digital signature is 

appended to the SOAP message before being sent to the service provider. 

When the service provider receives the message, it follows these steps to verify 

the signature: 

1. It recomputes the digest code for the message. 

2. It decrypts the signature by using the sender's public key. This decryption 

yields the original digest code for the message. 

3. It compares the original and recomputed digest codes. If these codes match, 

the message is both intact and authentic. If not, something has changed and 

the message is not to be trusted. 

The receiver normally obtains the sender’s public key from the sender’s X.509 

certificate, which is sent as a security token in the SOAP message. 

6.3, “Integrity with XML digital signature” on page 131 describes in detail how to 

configure WS-Security integrity with WebSphere Application Server for z/OS. 

Confidentiality 

Confidentiality is the process in which a SOAP message is protected so that only 

authorized recipients can read the SOAP message. Confidentiality is provided by 

encrypting the contents of the SOAP message using XML encryption. If the 

SOAP message is encrypted, only a service that knows the key for confidentiality 

can decrypt and read the message. 

The XML encryption standard specifies a process for encrypting data and 

representing the result in XML. XML encryption can be used to encrypt any part 

of a SOAP message, normally sensitive data such as bank account numbers or 

user credentials. The result of encrypting data is an XML encryption element that 

contains or references the cipher data. 

WS-Security uses a combination of XML Encryption and security tokens to 

implement confidentiality for portions of the SOAP message. Unlike transport 

security encryption, it is possible at the message level to encrypt local pieces of 

the SOAP message. It is not all-or-nothing encryption. 

6.4, “Confidentiality with XML encryption” on page 164 describes in detail how to 

configure WS-Security confidentiality with WebSphere Application Server for 

z/OS. 


Identity assertion 

Identity assertion (ID assertion) is a mechanism that allows the propagation of an 

already authenticated identity from one server to another. The receiver can 

assume that the identity has been authenticated because he trusts the sender. 

This is particularly well suited for end-to-end security solutions. 

WS-Security supports the following trust modes with a downstream server: 

► Basic authentication: The asserting server authenticates itself, sending a user 

name and password in the SOAP header, in addition to the transmitted 

asserted identity. 

► Digital signature: The asserted identity is transmitted digitally signed by the 

asserting server, along with the asserting server x.509 certificate. This 

provides both for data integrity of the transmitted asserted identity and for 

authentication of the sender. 

► Presumed trust: In this case, communication flows inside a secure channel or 

uses a secure transport protocol so that the asserting server does not need to 

provide authentication data at the SOAP message level. Typically, this can be 

achieved using HTTP as the transport protocol with SSL/TLS client (the client 

is the asserting server) authentication. 

Section 6.5, “Identity assertion” on page 192, describes in detail how to configure 

WS-Security identity assertion with WebSphere Application Server for z/OS. 

5.5 Web services transport layer security 

In this section, the different transport options for Web services are presented 

along with the uses of each transport and how security can be applied. 

5.5.1 Web services transports introduction 

Web services can communicate using different transport mechanisms. The 

transport mechanisms build upon or are combinations of other protocols or APIs. 

The listed terms are provided to help facilitate describing how Web services 

builds upon or utilizes existing protocols and APIs. 

► Simple Object Access Protocol (SOAP) is a protocol for exchanging XML 

messages over a computer network. 

► Hypertext Transfer Protocol (HTTP) is a protocol for transferring hypertext, 

files, Web pages, and Web page components over the Internet or computer 

network. 


► Secure Sockets Layer (SSL) is a cryptographic protocol to provide secure 

communication over the Internet. SSL makes use of symetric or assymetric 

key encryption, and can provide client certificate authentication (mutual 

authentication). 

► Hyptertext Transfer protocol over SSL (HTTPS) is a combination of HTTP 

communication over an encrypted SSL connection. 

► Java Message Service (JMS) is a set of standard APIs for accessing 

enterprise messaging systems using Java programs. JMS supports the 

publish/subscribe and point-to-point messaging, and is included in the J2EE 

specification. 

► Remote Method Invocation over Internet Inter-ORB Protocol (RMI-IIOP) is 

the use of Java Remote Method Invocation (RMI) interfaces over the IIOP 

(CORBA) protocol. This is used for remote EJB calls, for example. 

► Java API for XML based Remote Procedure Call (JAX-RPC) is a 

transport-neutral process for performing XML-based remote procedure calls 

using SOAP. 

SOAP is transport-independent and can be bound to any protocol. SOAP over 

HTTP is a commonly used tranport protocol for Web services communication. 

WebSphere also supports two other transport mechanisms for Web services 

such as SOAP over JMS and RMI-IIOP with multiprotocol JAX-RPC. The 

different transport options for Web services communication are summarized with 

the pros and cons of each. 

SOAP over HTTP 

The SOAP over HTTP protocol is one of the most widely used transport protocols 

for implementing Web services. HTTP is a request/response protocol between 

client and server. HTTP is commonly used between client browsers and Web 

servers for transferring files and Web content. The client usually initiates a 

request by establishing a TCP/IP connection to a remote host using a 

predetermined host name and port number. The host name and port may be 

stored in the form of a Universal Resource Identifier (URI). The server listening 

on the port waits for the client to send a request message, and responds with an 

HTTP response message and status code. The body of the message can 

comprise text data, error code, or some other information. A Web service can 

send a SOAP message over the HTTP protocol (SOAP over HTTP) for client 

server communication leveraging the benefits of HTTP. 

There are certain advantages to using SOAP over HTTP for Web services. The 

HTTP protocol is widely used in most Internet communication on various 

platforms. SOAP over HTTP can be implemented in different programming 

languages, allowing Web services to be portable and interoperable across 

platforms. In J2EE, support for SOAP over HTTP has been standardized with the 


Web services for J2EE specification, Version 1.1. Additionally, SOAP can exploit 

security capabilities of SSL through SOAP over HTTPS communication. 

SOAP over JMS 

SOAP over JMS is a vendor-specific transport mechanism that provides an 

alternative to SOAP over HTTP. When using SOAP over JMS in WebSphere, the 

SOAP message, including the SOAP envelope, is wrapped with a JMS message 

and put on a queue. The container receives the JMS message and removes the 

SOAP message to be sent to the client. 

The benefit of using SOAP over JMS as a transport is that you inherit the quality 

of service that is associated with JMS messaging. For example, JMS guarantees 

message delivery through persistent messages and acknowledgements, and it 

provides transaction support. If a message client or receiver experiences an 

outage, the message will remain in the client or receiver queue until both parties 

are available to transfer messages again. The message that could not be sent 

when the outage occurred can be retrieved from persistent storage and resent 

until transmission is successful. 

JMS also scales well with large volumes of messages, and supports 

asynchronous communication. Depending on your messaging provider, JMS can 

service numerous messaging clients concurrently. 

There are some drawbacks to using SOAP over JMS. There is no standard on 

how to implement SOAP over JMS, and it can pose interoperability issues when 

trying to communicate across platforms or programming languages. SOAP over 

JMS requires a messaging engine for communication, and additional setup on 

both the client and server to make use of the messaging engine. The client may 

not have access to a messaging engine or messaging APIs, and the need for a 

message engine to be set up may be excessive for simple client SOAP 

communication. JMS does not provide an API for controlling the privacy and 

integrity of messages, thus leaving the responsibility of this security to the JMS 

provider. 

RMI-IIOP with multiprotocol JAX-RPC 

Remote Method Invocation over Internet Inter-ORB Protocol (RMI-IIOP) can be 

used with JAX-RPC to support non-SOAP bindings. Using RMI-IIOP with 

JAX-RPC enables WebSphere Java clients to invoke enterprise beans using a 

WSDL file and the JAX-RPC programming model instead of using the standard 

J2EE programming model. When a WebSphere Java client invokes a Web 

services-enabled EJB, RMI-IIOP with multiprotocol JAX-RPC permits the Web 

service invocation path to be optimized. 

The advantage of using RMI/IIOP with the JAX-RPC protocol instead of a SOAP 

with JAX-RPC protocol is that XML processing is not required to send and 


eceive messages. Java serialization and deserialization are used instead. This 

can lead to better performance since the EJB Web service is invoked directly 

rather than having the overhead of sending a SOAP message over HTTP to a 

Web service router that then invokes an EJB. The JAX-RPC client using 

RMI/IIOP can also participate in a user transaction, which is not possible with 

SOAP over HTTP. 

The disadvantage to using RMI/IIOP with JAX-RPC is that the transport 

mechanism is vendor specific, and can only be used when invoking Web service 

enabled EJBs, not Web service enabled JavaBeans. Furthermore, RMI/IIOP with 

JAX-RPC is not standardized, and can cause interoperability problems across 

platforms. 

Enterprise Service Bus (ESB) 

The Enterprise Service Bus is a concept for integrating enterprise applications 

and providing connectivity between services. The ESB can rely on the previously 

mentioned transports or proprietary transports for interconnecting services. 

5.5.2 Point-to-point security 

Transport layer security is often considered to be a point-to-point security means 

since the communication over the network is secured between two parties. 

Hence, a security context only exists between those two parties. Securing the 

transport simply creates a secure pipeline between two nodes. Transport 

security does not address a full end-to-end security solution in which security 

context can be propogated across intermediaries. 

5.5.3 The HTTP(S) transport protocol 

In this section we provide more details on using HTTP(S) as the transport layer. 

The benefits of HTTP(S) as a transport protocol 

HTTP(S) is a well-known protocol used for internet communication. There are 

several advantages to using Web services SOAP over HTTPS: 

► It can be used to provide a very fast and secure transport for Web services. 

► It provides authentication through either HTTP basic authentication or a client 

X.509 certificate. 

► It provides integrity. 

► It provides confidentiality. 

► It has good support for a broad array of hardware accelerators. 


► It is mature and similarly implemented by most vendors, and therefore is 

subject to few interoperability problems. 

► It is firewall friendly. Ports can be opened in the firewall to allow HTTP traffic 

through. 

We choose to focus on the security aspects of the SOAP over HTTP protocol in 

Chapter 8, “Web services transport security” on page 245 based on many of the 

points highlighted here. 

HTTP(S) transport security 

The transport-level security provides client-server authentication, integrity, and 

confidentiality. For Web services using HTTP as a transport, authentication can 

be performed using either basic authentication or client certificate authentication. 

Integrity and confidentiality can be achieved by securing the transport through 

the use of SSL. 


Web services support builds on top of existing J2EE infrastructure. Currently, 

there are two forms of authentication available for use with Web services: basic 

Authentication (BA) and client certificate authentication. 

For Web services transport layer security, basic authentication information (user 

ID and password) is provided by the client programmatically or using WebSphere 

client bindings, and is passed in the HTTP header of the request that carries the 

SOAP message. The application server extracts the basic authentication 

information from the header and authenticates the user ID to a user registry. The 

application server uses the authentication information to authorize the user to 

application components or resources. 

Client certificate authentication, or mutual HTTPS authentication, is achieved by 

the client authenticating the server, and being authenticated by the server, 

through the exchange of X.509 certificates. 

Integrity and confidentiality 

Integrity ensures that data is not accidentally or maliciously changed or 

destroyed during data exchange. Integrity also ensures that the data cannot be 

tampered with if intercepted, usually accomplished with digests and digital 

signatures. Choosing whether to use confidentiality with integrity or just integrity 

alone depends on whether the data needs to be kept confidential. 

Applying integrity to transport communication is useful if the sender and receiver 

do not care if the data is visible, but want to ensure that the data is accurate. 


For example, a stock company may want to send an up-to-the-minute stock price 

to a client so that the client can decide whether to buy, hold, or sell. The stock 

company does not care whether others can see the stock price, but the client 

would be concerned if the data was not accurate, as it might affect his 

purchasing decision. 

For this type of scenario, choosing integrity without confidentiality is beneficial 

because integrity signing algorithms incur less overhead, and require less 

processing since the data being transferred does not need to be encrypted. 

Confidentiality ensures that the data sent from the client and received by the 

server cannot be viewed. Privacy is maintained by encrypting the data prior to 

transmission and decrypting the data on the receiving end. 

Continuing with the previous example, confidentiality may be desired after a 

client has decided what stock to purchase and needs to send sensitive 

information such as his credit card number to the stock company to complete the 

sale. 

Integrity and confidentiality are provided through the use of SSL over HTTP, also 

known as HTTP(S). Web services makes use of a secure transport by sending 

SOAP messages over HTTPS utilizing the security features of the transport. 

SSL Flow 

Figure 5-6 illustrates the message flow for a full SSL handshake. The steps are 

listed to explain what occurs in the process. The SSL flow is provided to show 

where the certificates are needed for establishing an SSL handshake and 

providing client certificate authentication (mutual authentication). 

Figure 5-6 SSL handshake flow 


The steps in bold in Figure 5-6 on page 95 are additional steps specific to client 

certificate authentication: 

1. The client sends a client hello command to the server, which includes: 

– Client version - highest SSL and TLS version supported by the client 

– Random structure generated by the client for use in the key generation 

process 

– A session ID that the client wishes to use for the connection 

– Ciphers supported by the client with client's first preference first 

– Data compression methods supported by client sorted by client preference 

2. The server sends a server hello command to the client, which includes: 

– Highest client SSL or TLS version that server supports 

– Random structure generated by the server for use in the key generation 

process 

– A session ID for the SSL session 

– A cipher selected by the server from the list of client-supported ciphers 

– Data compression method selected by the server from the list of 

client-supported compression methods 

3. The server sends the server certificate (that is, the X.509 certificate). 

4. The server sends a certificate request to authenticate the client. This step 

occurs with client certificate authentication only. 

5. The server sends the server hello done, indicating that the server is done 

sending messages to support the key exchange. The client should verify that 

the server provided a valid certificate upon receiving the server hello done. 

6. The client sends a client certificate only if the server requested a certificate. 

This step occurs with client certificate authentication only. 

7. The client key exchange occurs using a premaster secret that was created by 

the client and was then encrypted using the server’s public key. 

Both the client and the server generate the symmetric encryption keys on 

there own using the premaster secret and the random data that is generated 

from the server hello and client hello commands. 

8. The certificate verify message is sent to provide explicit verification of a client 

certificate. This step occurs with client certificate authentication only. 

9. The change cipher spec message is sent by the client to notify the server that 

subsequent records will be protected under the newly negotiated CipherSpec 

and keys. 


10.The client sends the finished command. This command includes a digest of 

all the SSL handshake commands that have flowed between the client and 

the server up to this point. This command is sent to validate that none of the 

commands sent previously, which flow between the client and the server 

unencrypted, were altered in flight. 

11.The change cipher spec message is sent by the server to notify the client that 

subsequent records will be protected under the newly negotiated CipherSpec 

and keys. 

12.The server sends the finished command, which includes a digest of all the 

SSL handshake commands that have flowed between the server and the 

client up to this point. This is also used to validate the integrity of the 

commands sent previously. 

Subsequent requests are done using symetric keys, which are less 

computationally intensive. 

5.5.4 JMS transport security 

The JMS specification does not address privacy or integrity of messages, and 

the user must rely on the underlying JMS provider for those functions. 

If generic messaging is selected, the vendor documentation needs to be 

reviewed for available security facilities. Default messaging in WebSphere uses 

TCP/IP for communication. For WebSphere MQ, there are two methods of 

communication: 

► Direct communication with WebSphere MQ using cross-memory devices if 

they are on the same LPAR, the so-called bindings mode 

► Using TCP/IP communication 

Default messaging and WebSphere MQ using TCP/IP for messaging 

communication can be configured to use an SSL-enabled transport chain to 

provide integrity and confidentiality. Details for configuring the transport chain for 

message security are provided in WebSphere for z/OS V6 Connectivity 

Handbook, SG24-7064-02. 

Securing the TCP/IP transport that JMS messages flow across may not be 

sufficient, and a more desirable JMS application-level of protection may be 

needed. An alternate end-to-end security mechanism is available using 

WebSphere MQ Extended Security Edition, which secures JMS messages by 

signing each message with a private key associated with the sending application, 

and encrypting individual messages under unique keys. 


When invoking a Web service using SOAP over JMS, the SOAP message is 

embedded within the JMS message and is secured in the method that the JMS 

message is sent. 

The following are some SOAP over JMS transport considerations: 

► Messaging security is vendor specific and depends on the JMS provider. 

► For default messaging and WebSphere MQ, the JMS identity decision is 

based on the J2C authentication mechanism. 

► JMS provides a highly scalable, reliable message transport for SOAP 

messages. 

► SOAP over JMS allows for asynchronous communication. 

5.5.5 RMI-IIOP security 

RMI over IIOP security is provided using the Common Secure Interoperability 

Version 2 (CSIv2) authentication protocol. WebSphere supports basic 

authentication, identity assertion, client certificate authentication, and tokens 

when using CSIv2. In addition, CSIv2 communication can occur over an SSL 

transport to provide integrity and confidentiality. More information is provided in 

Chapter 9, “Security attribute propagation and CSIv2” on page 293. 

5.5.6 Enterprise Service Bus security 

The Enterprise Service Bus (ESB) can rely on the previously mentioned 

transports or a proprietary transport for interconnecting services. When using 

SOAP over HTTP or SOAP over JMS refer to “HTTP(S) transport security” on 

page 94 or 5.5.4, “JMS transport security” on page 97, for security 

considerations. If the ESB relies on a proprietary transport refer to the ESB 

documentation for security facilities. 

5.6 Our SecurityInfo Web service application and 

environment 

The SecurityInfo Application is a sample application used in the subsequent 

chapters to demonstrate different message layer and transport layer security 

scenarios. Refer to Appendix A, “Additional material” on page 471, for details on 

acquiring the sample application from the Web. 


5.6.1 SecurityInfo J2EE architecture in our environment 

A Web request is initiated by a client browser to the SecurityCaller index.html 

page. The page presents a link to the SecurityCaller ClientServlet that, when 

clicked, invokes the local SecurityCallerEJB. The SecurityCallerEJB performs the 

JAX-RPC Web service call using SOAP over HTTP to the Web service enabled 

SecurityInfoEJB. The Web service enabled SecurityInfoEJB has a Web service 

router SecurityInfoRouterWS for receiving a SOAP request and routing the call to 

the SecurityInfoEJB. A response is sent back to the client Web page showing 

assorted information about the local and remote EJBs. 

Figure 5-7 illustrates a typical flow of the SecurityInfo Web service by the 

SecurityInfoCaller. 

Figure 5-7 Basic flow of SecurityInfo application 

Web service provider 

The design of the SecurityInfo Web service consists of a stateless session bean 

SecurityInfoEJB, with one remote method obtainSecurityInfo, which returns a 

string array containing a request ID, date and time, host name, IP address, 

principal, operating system name, and operating system version for the EJB. 

The SecurityInfo EJB has been Web service enabled through a router module 

SecurityInfoRouterWS that is generated by the Rational® Application Developer 

tooling. The router module Web application provides a Web service endpoint for 

receiving requests over HTTP. 


Web service requestor 

The design of the SecurityCaller application consists of a Web application 

SecurityCallerWAR and a stateless session bean SecurityCallerEJB. 

The SecurityCallerEJB has two remote methods, obtainSecurityLocalInfo and 

obtainSecurityRemoteInfo. The obtainSecurityLocalInfo returns the request ID, 

date and time, host name, IP address, principal, operating system name, and 

operating system version for the local SecurityCallerEJB. The 

obtainSecurityRemoteInfo returns the same information, but does this via a 

JAX-RPC Web service call to remote method obtainSecurity from the Web 

service enabled SecurityInfoEJB. 

The SecurityCallerWAR contains an index.html page and two identical servlets, 

ClientServlet and SecuredClientServlet. The ClientServlet is not protected by 

any security constraints in the Web deployment descriptor. The 

SecuredClientServlet URI is protected by a security constraint for which users 

permitted to the role customer are allowed to access through basic 

authentication. Both servlets create a unique RequestID (specific to the 

application) and call the obtainSecurityLocalInfo and obtainSecurityRemoteInfo 

methods for the SecurityCallerEJB. The information is then displayed on a Web 

page as two tables. 

5.6.2 Our test environment 

The setup of the test environment consists of a Windows® and z/OS system 

setup at the service levels listed in Table 5-1. 

Table 5-1 Test environment for SecurityInfo sample application 

Test environment 

Web service requestor Web service provider 

Windows XP (version 5.1 build 2600 

Service Pack 2) 

WebSphere base server 

6.1.0.2 cf20633.22 

J2RE 1.5.0 IBM J9 2.3 Windows XP 

x86-32 j9vmwi3223-20060504 

z/OS 1.8 

5.6.3 SecurityInfo Web service implementation 

WebSphere 6.1.0.2 base server 

J2RE 1.5.0 IBM z/OS build 

pmz31devifx-20060727a 

The SecurityInfoCaller EJB uses a JAX-RPC call implemented with a static stub 

to invoke the SecurityInfoEJB Web service. Although dynamic proxy and 

dynamic invocation allow for changes to a Web service, such as the location of 


the Web service, the WebSphere bindings are sufficient for overriding the service 

endpoint URI in the sample scenarios. The actual call to the Web service is 

performed by doing a lookup on the service reference 

java:comp/env/service/SecurityInfoService, which is coded in the 

SecurityCallerEJB deployment descriptor. The remote Web service method 

obtainSecurityInfo is called to obtain the SecurityCallEJB information. 

Example 5-1 contains the source for the actual Web service invocation. 

Example 5-1 Web service call 

javax.naming.InitialContext ic = new javax.naming.InitialContext(); 

SecurityInfoService myService = (SecurityInfoService) 

ic.lookup("java:comp/env/service/SecurityInfoService"); 

SecurityInfo mySecurityInfo = myService.getSecurityInfo(); 

securityArray = mySecurityInfo.obtainSecurityInfo(uniqueID); 

Less emphasis was placed on the display of the application in the 

SecurityCallerWAR, in order to keep the source simple to follow, and to place 

more emphasis on the Web service call and security setup. The 

SecurityCallerWAR outputs the result information to the Web page directly, and 

does not follow an model-view-controller (MVC) practice for this reason. 

5.6.4 SecurityInfo deployment 

This section describes the steps for deploying the SecurityCaller ear file to 

WebSphere on Windows and the SecurityInfo ear file to WebSphere for z/OS. 

Additional steps are described after installation. 

Deployment of SecurityCaller EAR file on Windows 

The SecurityCaller ear file can be deployed in WebSphere on Windows, 

choosing the default options presented to the user in the WebSphere admin 

console during deployment. A user should click Next to all options presented 

during deployment of the ear file. Additional steps need to be taken after 

deployment to configure the Web service client bindings. 

For the scenario role customer is used for the identity assertion. The purpose of 

this role is to secure part of the application so that a user can authenticate. The 

user identity can then be propogated with identity assertion. 


If the external authorization provider is set to default authorization, then the users 

permitted to the role should be set to All Authenticated in the application client 

bindings. Select Enterprise Applications → SecurityCallerEAR → Security 

role to user/group mapping. 

Figure 5-8 Mapping users to roles for SecurityCallerEAR 

After a successful deployment of the application, the endpoint URL needs to be 

overridden in order to specify the correct host name and port for where the 

SecurityInfo Web service resides. Select Enterprise Applications → 

SecurityCallerEAR → Manage Modules → SecurityCallerEJB.jar → Web 

services client bindings → Edit Port Information. 

In this example, the Endpoint URL is: 

http://wtsc58.itso.ibm.com:19080/SecurityInfoRouterWS/services/Security 

Info 

Figure 5-9 Overridden endpoint UR 


Deployment of SecurityInfo ear file on z/OS 

The SecurityInfo ear file can be deployed to WebSphere for z/OS, leaving the 

default settings. Additional steps need to be taken after deployment to configure 

the client bindings or setup of a role in RACF depending on how your 

WebSphere is configured for authorization. 

For the scenarios involving message-level authentication, message-level identity 

assertion, transport-level basic authentication, and transport-level client 

certificate authentication, the role SecureCustomer is used. 

If the external authorization provider is set to default authorization, then the users 

permitted to the role should be set to All Authenticated in the application client 

bindings. Select Enterprise Applications → SecurityInfoEAR → Manage 

Modules → SecurityInfoRouterWS.war → Security role to user/group 

mapping. See Figure 5-10. 

Figure 5-10 Mapping users to roles for SecurityInfoRouterWS 

If the external authorization provider is set to System Authorization Facility (SAF) 

authorization, then the SecureCustomer role needs to be defined in RACF. 


Example 5-2 provides the sample commands for defining the SecureCustomer 

role in RACF with the ID WINSERV permitted to the role. 

Example 5-2 Defining SecureCustomer role 

SETROPTS CLASSACT(EJBROLE) 

RDEFINE EJBROLE SecureCustomer UACC(NONE) 

PERMIT SecureCustomer CLASS(EJBROLE) ID(WINSERV) ACCESS(READ) 

SETROPTS RACLIST(EJBROLE) REFRESH 

5.6.5 SecurityInfo in action 

Once the SecureCaller and SecureInfo Web services are successfully deployed 

to WebSphere on Windows and WebSphere on z/OS, the application can be run 

by invoking the URL: 

http://:/SecurityCallerWAR/index.html 

Figure 5-11 SecureInfo Welcome page 

Click the ClientServlet link to invoke the Web service call. 


The SecuredClientServlet link is used in 6.5, “Identity assertion” on page 192 so 

that the user can authenticate. See Figure 5-12. 

Figure 5-12 Successful execution with application security disabled 



6 

Chapter 6. Web services message layer 

security 

This chapter provides an in-depth description of Web services message layer 

security following the introduction in Chapter 5, “Web services security 

introduction” on page 75. 

Here we discuss about how to configure Web services message layer security 

for different purposes such as authentication, integrity, confidentiality, and 

identity assertion. 

This chapter focuses on the practical implementation of Web services message 

layer security for WebSphere Application Server for z/OS. 


► “How to configure Web services message layer security” on page 108 

► “Authentication with a security token” on page 115 

► “Integrity with XML digital signature” on page 131 

► “Confidentiality with XML encryption” on page 164 

► “Identity assertion” on page 192 


6.1 How to configure Web services message layer 

security 

This section introduces how to configure Web services message layer security. 

We describe some configuration tools and configuration files, and we present 

configuration components. 

6.1.1 Web services message layer security and WS-Security 

Web services message layer security is defined in the WS-Security standard. 

Web services Security (WS-Security) is a message-level standard that is based 

on securing SOAP messages through XML digital signature, confidentiality 

through XML encryption, and credential propagation through security tokens. 

The WS-Security specification defines the core facilities for protecting the 

integrity and confidentiality of a message and provides mechanisms for 

associating security-related claims with the message. 

Refer to 5.4, “Web services message layer security with WS-Security” on 

page 81 for an introduction to WS-Security. 

Using WS-Security, the authentication mechanism, integrity, and confidentiality 

can be applied at the message level. In WebSphere Application Server V6.1, 

there are many options to apply and combine these security mechanisms. 


After configuring WS-Security, security tags are added to the SOAP message 

security header. As illustrated in Figure 6-1, the security header may possess 

security tokens, time stamps, signatures, keys, encrypted data, and so on. The 

SOAP body might be encrypted. With WS-Security, encryption can be applied to 

parts of the SOAP message only. 

Figure 6-1 SOAP message security with WS-Security 

This chapter shows some sample SOAP messages with various security 

techniques applied in the validation sections. 

6.1.2 Web services message layer security configuration tools 

It is possible to configure Web services security on the application level, server 

level, and cell level. When multiple applications use the same binding 

information, consider configuring the binding information on the server or cell 

level. For example, you might have a global key locator configuration that is used 

by multiple applications. Configuration information for the application level 

precedes similar configuration information on the server level and the cell level. 

In this chapter we show how to configure Web services security at the application 

level. 

WebSphere Application Server uses for security an extension of the Web 

services deployment model for J2EE. The Web services security constraints are 

Chapter 6. Web services message layer security 109

defined in IBM extension deployment descriptor and the binding file based on the 

Web service port. At the application level this means that the Web services 

configuration is stored in the two following extension deployment descriptors: 

► ibm-webservices-ext.xml 

► ibm-webservices-bnd.xml 

The format of the deployment descriptor and the binding file is IBM proprietary 

and is not available. However, WebSphere Application Server provides the 

following tools that you can use to edit the deployment descriptor and the binding 

file: 

► Rational Application Developer (RAD) 

Use RAD to develop Web services and configure the deployment descriptor 

and the binding file for Web services security. RAD enables you to assemble 

both Web and EJB modules. 

► Application Server Toolkit v6.1 (AST) 

Use AST as an assembly tool designer for WebSphere Application Server 

Version 6.0.x and later, to specify the deployment descriptor and the binding 

file for Web services security. It is not possible to develop Web services with 

the AST. 

► WebSphere Application Server Administrative console 

It is possible to use the administrative console to configure the Web services 

security binding of a deployed application with Web services security 

constraints that are defined in the deployment descriptor. 

In this chapter we show how to configure Web services security using RAD or 

AST, as the panels are the same for the deployment descriptors we configured. 

Important: The format of the deployment descriptor and the binding file for 

Web services security in WAS Version 6.0.x and later is different from WAS 

Versions 5.0.2, 5.1, and 5.1.1. Web services security support in WAS versions 

5.0.2, 5.1, and 5.1.1 is based on the Web services security draft 13 

specification and the username token draft 2 profile. But this support is 

deprecated. However, applications that you configured using the Web service 

security Versions 5.0.2, 5.1, and 5.1.1 deployment descriptor and binding file 

can work with WebSphere Application Server Version 6 and later. 

6.1.3 Web services message layer security configuration files 

The WebSphere WS-Security constraints and configuration are defined in the 

IBM extension of the J2EE Web services deployment descriptor. There are four 


configuration files, which are the application-level deployment descriptor 

extensions and bindings for a client and a server. See Figure 6-2. 

Figure 6-2 Web services message layer security configuration files 

The configuration files are: 

► Client deployment descriptor extension file 

This includes request generator and response consumer constraints: 

ibm-webservicesclient-ext.xmi 

► Client binding configuration file 

This includes how to apply request generator and response consumer 

security measures: 

ibm-webservicesclient-bnd.xmi 

► Server deployment descriptor extension file 

This includes request consumer and response generator constraints: 

ibm-webservices-ext.xmi 


► Server binding configuration file 

This includes how to apply request consumer and response generator 

security measures: 

ibm-webservices-bnd.xmi 

The deployment descriptor extension files specify what security constraints are 

required, for example, what type of security token and whether to sign the 

message. The binding files specify how to apply the required security constraints 

defined in the deployment descriptor extension, for example, which security 

token is inserted and which keys are used for signing. 

These deployment descriptor extension and binding files define the 

application-level security constraints, and they belong to each application. 

These files are updated using the tooling when configuring the J2EE module 

deployment descriptor, as follows: 

► On the Web service provider side (server), open the webservices.xml file. 

► On the Web service client side, open the deployment descriptor relevant to 

the J2EE module you configure: 

– For a Web client (servlet, JSP, JavaBean), edit the web.xml file. 

– For an EJB client (a session bean accessing a Web service), edit the 

ejb-jar.xml file. 

– For a J2EE application client, edit the application-client.xml file. 

Hence, when configuring WS-Security between two parties, one has to go 

through the following four steps: 

1. Configure WS-Security for sending the request message (client) in ejb-jar.xml 

to open the deployment descriptor editor for the request generator. 

2. Configure WS-Security for receiving the request message (server) in 

webservices.xml to open the Web services editor for the request consumer. 

3. Configure WS-Security for sending the response message (server) in 

webservices.xml to open the Web services editor for the request generator. 

4. Configure WS-Security for receiving the response message (client) in 

ejb-jar.xml to open the deployment descriptor editor for the response 

consumer. 


For each of these files, the tooling offers two tabs for WS-Security configuration: 

► WS Extension (or Extension) for configuring what security measures to apply 

(This tab updates the Web services extension deployment descriptor in the 

background.) 

► WS Binding (or Binding Configurations) for configuring how to apply the 

security measures (This tab updates the Web services bindings deployment 

descriptor in the background.) 

Figure 6-3 shows the Application Server Toolkit v6.1 display including the 

Extension and the Binding Configurations tabs. In this example the 

webservices.xml file has been opened for configuration on the server side. 

Figure 6-3 Web service message layer security tooling 

For authentication purposes, only the request generator and the request 

consumer might need some security configuration. But, for integrity and 

confidentiality, generally both the request and the response have these 


equirements. This means that the request generator, the request consumer, the 

response generator, and the response consumer might need some security 


6.1.4 Web services message-layer security configuration 

components 

In this section we briefly describe some components that need to be configured 

for Web services message layer security. 

Token generator 

The token generator inserts a security token (username or binary) in the SOAP 

request. The token generator needs to know the type of token, where to find the 

token value, and how to secure the token value in order to generate the token 

consequently. 

CallbackHandler 

The CallbackHandler retrieves security-related information from the security 

context. As an example, for a Web service request reaching the Web service 

provider, the CallbackHandler may acquire the security token that is inserted in 

the Web services security header within the SOAP message. The token 

acquisition is a pluggable framework that leverages the JAAS 

javax.security.auth.callback.CallbackHandler interface for acquiring the security 

token. 

Caller part 

On the Web service provider side, the caller part specifies the security token, 

signed part, or encrypted part used for authentication. This configuration explains 

where to find the authentication credentials within the incoming SOAP message. 

If a signed or encrypted part is used, the value of the part attribute must be the 

name of a defined required integrity or required confidentiality constraint. If a 

stand-alone security token is used for authentication, then the URI and local 

name attributes must define the type of security token used for authentication. 

Key locator 

The key locator information for the generator specifies which key locator 

implementation is used to locate the key to be used for signature validation or 

encryption. 

Key information 

The key information is used to specify the configuration needed to generate the 

key for digital signature and encryption. The signing information and the 


encryption information configurations can share the key information, so they are 

both defined at the same level. 

Trust anchor 

A trust anchor specifies key stores that contain trusted root certificates, which 

validate the signer certificate. These key stores are used by the request 

generator and the response generator (when acting as a client) to generate the 

signer certificate for the digital signature. 

Nonce 

Nonce is a randomly generated, cryptographic token that is used to prevent 

replay attacks. Although nonce can be inserted anywhere in the SOAP message, 

it is typically inserted in the UsernameToken element. 

Without nonce, when a user name token is passed from one machine to another 

machine using a nonsecure transport, such as HTTP, the token might be 

intercepted and used in a replay attack. The same password might be reused 

when the user name token is transmitted between the client and the server, 

which leaves it vulnerable to attack. The user name token can be stolen even if 

you use an XML digital signature and XML encryption. 

Time stamp 

A time stamp can be attached in the target element of the signature and 

encryption to put a lifetime on the signed and encrypted element. If the time 

stamp is specified when an element is signed, a time stamp is attached to the 

target element, and the target element with the time stamp is signed. Because 

this is an extension of WebSphere Application Server 6.1, other vendor 

implementations might not be able to consume the message generated with the 

additional time stamp inserted in the message. 

6.2 Authentication with a security token 

Authentication is the process of validating the identity claimed by the accessing 

entity. Authentication is needed when access discrimination is required on the 

basis of requesting identities. Authentication is performed by verifying 

authentication information provided with the claimed identity. The authentication 

information is generally referred to as credentials. A credential can be the 

accessor’s name and password. It can also be a token provided by a trusted 

party, such as a Kerberos ticket or an X.509 certificate. 


This section describes how WS-Security supports authentication, explains our 

authentication scenario, gives an overview of how to configure authentication, 

and thoroughly describes the steps to configure this scenario. 

6.2.1 Authentication support with WS-Security 

Web services security provides a general-purpose mechanism to associate 

security tokens with messages for single message authentication. A security 

token represents a set of claims made by a client that might include a name, 

password, identity, key, certificate, group, privilege, and so on. 

A specific type of security token is not required by Web services security. Web 

services security is designed to be extensible and support multiple security token 

formats to accommodate a variety of authentication mechanisms. For example, a 

client might provide proof of identity and proof of a particular business 

certification. However, the security token usage for Web services security is 

defined in separate profiles such as the username token profile, the X.509 token 

profile, the Security Assertion Markup Language (SAML) token profile, the 

eXtensible rights Markup Language (XrML) token profile, the Kerberos token 

profile, and so on. 

Username token 

A username token is a token mainly for basic authentication, which has a user 

name and password. The username token profile 1.0 is published by OASIS, and 

WS-Security in WebSphere Application Server 6.1 supports the profile. 

In the username token profile, the password digest is specified as a password 

type, but the password digest is not supported in WebSphere Application Server 

6.1. Only the clear-text password can be inserted in a username token and 

should not be transferred over a non-secure network. Basic authentication 

should be used over the secure network, such as HTTPS or intranet, or 

encryption should be applied to hide the user information. 

Basic authentication relies on username tokens. Identity assertion also relies on 

username tokens with no password. Identity assertion is described in details in 

6.5, “Identity assertion” on page 192. 

Binary security token 

The two types of binary security tokens that are provided as a default are the 

X.509 certificate token and the LTPA token. The LTPA token is a 

WebSphere-specific binary token that is authenticated by a WebSphere security 

mechanism. The X.509 certificate token is published, and the profile is supported 

by the WS-Security implementation in WebSphere Application Server 6.1. The 

encoding method is specified in each binary security token. 


Custom token 

A user can implement a custom token using a pluggable token architecture 

provided by WebSphere Application Server 6.1. To implement a custom token, 

WebSphere provides interfaces that must be implemented 

(TokenGeneratorComponent, CallbackHandler, TokenConsumerComponent, 

LoginModule). 

XML digital signature 

Using XML digital signature is also a way to authenticate. You can assume that a 

valid signature is proof of possession. A message with a digital certificate that is 

issued by a certificate authority (CA) and a signature in the message that is 

validated successfully by a public key in the certificate are proof that the signer 

has the corresponding private key. The receiver can authenticate the signer by 

checking the trustworthiness of the certificate. XML digital signatures also rely on 

binary security tokens and signature tags. 

6.2.2 Authentication scenario description 

This scenario uses the application and the environment described in 5.6, “Our 

SecurityInfo Web service application and environment” on page 98. This 

scenario illustrates the usage of a security token to have a Web service client 

authenticate to a Web service provider. This security token is a username token 

in this example. See Figure 6-4. 

Figure 6-4 Web service message security authentication scenario 

On the Web service client side, the user does not provide any credentials to the 

application. Hence, the principal of the client EJB is unauthenticated. This client 


EJB makes a Web service call. The Web service request generator includes a 

security token in the SOAP message header. This security token contains the 

client server user name and password (WINSERV, WINSERV). This is not the 

user identity. 

On the Web service provider side (WebSphere for z/OS), the Web service 

request consumer receives the security token and uses a JAAS login module to 

authenticate the user name and password and set the principal. The EJB runs 

with a WINSERV principal. 

Authentication occurs only when sending the request. Hence, there is no security 

mechanism when receiving the response. 

6.2.3 Authentication configuration overview 

For configuring authentication, the Web service client and provider have to agree 

on a security token type. Then configuration has to be executed on both sides. 

Web service client side 

To insert a security token into a SOAP message, a security token and its token 

generator must be specified in the client’s WS-Security configuration: 

1. Specify a security token in the request generator configuration. In case of 

basic authentication, the security token type should be username. This 

security token is sent inside the SOAP header to the server. 

2. Specify a token generator for the username token in the request generator 

configuration. The role of the token generator is to grab the user name and 

password from the configuration file and generate the username token with 

the user name and password. The token generator class for the username 

token, UsernameTokenGenerator, is provided by the Web services security 

run time as a default implementation. 

Web service provider side 

To receive the security token, you must specify a security token that is required 

by the server and a token consumer in the server’s WS-Security configuration, as 

follows: 

1. Specify a security token that is required by the server. In case of basic 

authentication, the required security token type is username (same as in the 

client configuration). 

2. Specify a token consumer in the request consumer configuration. The token 

consumer receives a security token in the request message and validates it. 

The token consumer class for the username token, 


UsernameTokenConsumer, is provided by the Web services security run time 

as a default implementation. 

6.2.4 Configuring the Web service requestor for security token 

To configure the Web service requestor for security token: 

1. Configure the security token. 

Open the SecurityCallerEJB ejb-jar.xml deployment descriptor. Select the WS 

Extension tab. In the Port Qualified Name Bindings section, select the 

SecurityInfo port. (This is necessary in order to activate the Add button in the 

next step.) Expand the Security Request Generator Binding Configuration 

section. Expand the Security Token section and click Add. 

Figure 6-5 Request generator Security Token Dialog 

Configure the Security Token Dialog (Figure 6-5): 

a. Enter a name such as BasicAuthToken. 

b. Select a token type from the drop-down list. The available choices are: 

Username: username token with a user name and password 

X509 certificate token: binary security token of X.509 certificate 

X509 certificates in a PKIPath: binary security token of an ordered list 

of X.509 certificates packaged in a PKIPath 

A list of X509 certificates and CRLs in a PKCS#7: binary security token 

of a list of X.509 certificates and (optionally) CRLs packaged in a 

PKCS#7 wrapper 

LTPAToken: binary security token of a Lightweight Third Party 

Authentication (LTPA) token 

Custom token: Custom-defined token 

For basic authentication, select Username as the token type. When you 

select a token type, the local name is filled in automatically. For user name 


and four types of X509 certificates, the URI is not necessary (leave it empty). 

If you select a custom token, you have to enter the URI and the local name of 

the custom token manually. 

Click OK. 

2. Configure the token generator. 

a. Open the SecurityCallerEJB deployment descriptor. Select the WS 

Binding tab. Expand the Security Request Generator Binding 

Configuration section. 

b. To specify a token generator for a list of X.509 certificates and CRLs in a 

PKCS#7, expand Certificate store list and click add (for basic 

authentication, you do not specify this). 

c. Enter any name. Add a CRL path pointing to the CRL file. These specified 

CRLs are packaged in a PKCS#7 wrapper. Click OK, and a collection 

certificate store is created. 


d. Expand the Token Generator section and click Add. 

Configure the Token Generator dialog () Figure 6-6: 

a. Enter Token generator name such as BasicAuthTokenGen. 

Figure 6-6 Request generator Token Generator dialog 

b. Select a token generator class or input your custom token generator class 

name manually. You have to select a corresponding token generator class 


for the specified security token type. For example, if you select Username 

as the token type, you have to select the UsernameTokenGenerator class 

as the token generator class. 

c. For the security token, expand the drop-down list and select the security 

token defined on the WS Extension page (BasicAuthToken). 

d. Select Use value type. Select the value type from the drop-down list that 

matches your selection. This selection fills the local name and callback 

handler. If you specify a token generator for a custom token, select 

Custom Token as the value type and enter the URI and local name 

manually. In our example, we select Username Token for basic 


e. Select the callback handler class or input your custom callback handler 

class name manually (for a custom token). Some provided callback 

handler classes can be selected from the list. The provided default 

callback handler classes are as follows: 

NonPromptCallbackHandler: Enter the user ID and password 

manually. 

GUIPromptCallbackHandler: Request the user ID and password by 

displaying a GUI prompt dialog box. This is useful for a J2EE 

application client. 

X590CallbackHandler: Get an X.509 certificate for a key store file. 

PkiPathCallbackHandler: Create an X.509 certificate and binary data 

without CRL using PKIPath encoding. 

PKCS7CallbackHandler: Create an X.509 certificate and binary data 

with or without CRL using PKCS#7 encoding. 

LTPATokenCallbackHandler: Get user credentials from the LTPA 

token. 

StdinPromptCallbackHandler: Prompt the user for a user ID and 

password on the command line. 

We select the NonPromptCallbackHandler for basic authentication. The 

user ID and password must be known in the server user registry. 

f. If the token generator is the NonPromptCallbackHandler, enter the user ID 

and password of the client. We use a user ID and password of WINSERV. 

g. If the selected callback handler requires a key store (for example, the 

X509CallbackHandler, PkiPathCallbackHandler, and 

PKCS7CallbackHandler), select Use key store and specify the key 

store-related information. You have to specify the key store storepass 

(password to access the key store), key store path, and key store type 

from the list. 


If you specified a key store, add the key. You can specify which key is 

used. Enter the alias of the key, the key pass (password to get the key 

from key store file), and the key name. 

h. If you have to specify the properties of the callback handler or token 

generator, add a call back handler property or a property. 

If you specify a token generator for a list of X.509 certificates and CRLs in 

a PKCS#7, select Use certificate path settings and select the 

Certificate path reference. If you select Certificate path reference, you 

can select the certificate store from the drop down-list. Select one 

collection certificate store name from the list, which is packed in PKCS#7. 

i. Click OK and a token generator is created. 

3. Save the configuration. 

6.2.5 Configuring the z/OS Web service provider for security token 

To configure the Web service provider for security token: 

Attention: Administrative security and application security have to both be 

enabled on the Web service provider side for Web service authentication to 

operate. 

1. Configure the required security token. 

Open the SecurityInfoEJB webservices.xml deployment descriptor. Select the 

Extensions tab. Expand the Request Consumer Service Configuration 

Details section. Select the port component, expand the Required Security 

Token, and click Add. 


Configure the Required Security Token Dialog (Figure 6-7): 

a. Enter a name such as BasicAuthToken. 

Figure 6-7 Request consumer Required Security Token dialog 

b. Select a token type from the drop-down list, matching the client 

specification. If a client’s security token is the username token, you should 

select Username token as the token type. The URI and local name are 

filled in automatically except when using a custom token. 

c. Select the usage type from the drop-down list. The available choices are 

required or optional. If you select required, a SOAP fault is thrown if a 

required security token is not included in a client’s request message. If you 

select optional, the process of consuming a request message continues 

without throwing a SOAP fault. 

Click OK. 


2. Configure the caller part. 

Expand Caller Part under Request Consumer Service Configuration Details 

and click Add. 

Configure the Caller Part Dialog (Figure 6-8): 

a. Enter a name for the caller part, such as BasicAuthCallerPart. 

Figure 6-8 Request consumer Caller Part dialog 

b. If a client’s security token is used for signing or encryption, select the 

name of an integrity or confidentiality part from the drop-down list. The 

security token that is used for the selected integrity or confidentiality part is 

regarded as the client’s security token. In our case, the security token for 

basic authentication is not used for signing or encryption. 


c. If the client’s security token is not used for signing or encryption, select a 

token type of the security token. If the security token is username token, 

select Username token as the type. If you select custom token as the type, 

you have to specify a custom URI and local name of the token. 

Click OK and a caller part is created. Save the configuration. 

3. Configure the token consumer. 

Select the Binding Configurations tab. Expand the Request Consumer 

Binding Configuration Details section. 

– If you want to specify a token consumer for the four types of X.509 

certificate tokens, expand Trust Anchor and click Add (not for basic 

authentication): 

i. Enter a name for the trust anchor. 

ii. Specify the key store information (key store storepass, key store path, 

and key store type). If you trust any certificate, you do not have to 

specify this. 

iii. Click OK and a trust anchor is created. 

– If the token consumer is for an X.509 certificate token, and you want to 

specify an intermediate trusted certificate store or CRL, add a collection 

certificate store under the certificate store list (for basic authentication, you 

do not have to specify this): 

i. Enter a name for the collection certificate store. 

ii. Add the X.509 certificate path for the trusted X.509 certificate file. 

iii. Add the CRL path for a CRL file. 

iv. Click OK and a collection certificate store is created. 


– Expand Token Consumer and click Add. 

Configure the Token Consumer Dialog (Figure 6-9): 

i. Enter a token consumer name such as BasicAuthTokenConsumer. 

Figure 6-9 Request consumer Token Consumer dialog 


ii. Select a token consumer class or input your custom token consumer 

class name manually. The token consumer class matches the security 

token type. For a Username token, select the 

UsernameTokenConsumer class. 

iii. Expand the drop-down list for the security token and select the token 

specified on the extension page (BasicAuthToken). 

iv. Select Use value type and select the value type from the list 

(Username Token in our case). For a custom token, you have to enter 

the URI and local name manually. 

v. Select Use jaas.config to validate a security token in a client’s request 

message. Specify the name of the JAAS configuration. The default 

JAAS configurations are specified in WebSphere Application Server, 

and you can add your custom JAAS configuration name to invoke your 

custom JAAS login module implementation. The predefined JAAS 

configuration names are system.wssecurity.UsernameToken, which 

validates a username token with the user name and password; 

system.wssecurity.X509BST, which validates an X.509 certificate 

token; system.wssecurity.PkiPath, which validates a token of X509 

certificates in a PKIPath; system.wssecurity.PKCS7, which validates a 

token of a list of X509 certificates and CRLs in a PKCS#7; and 

system.wssecurity.IDAssertionUsernameToken, which validates a 

username token with the user name only. 

However, for an LTPA token, it is not necessary to configure a JAAS 

configuration name for the username token. 

vi. If you use a self-signed certificate that has no trust anchor and 

intermediate certificate, and you cannot trust any certificate, you have 

to specify your self-signed certificate information in two jaas.config 

properties (com.ibm.wsspi.wssecurity.token.x509.issuerName and 

com.ibm.wsspi.wssecurity.token.x509.issuerSerial). You can see your 

certificate issuer name and serial number using the keytool. 

vii. If you specify a token consumer for identity assertion, you can specify 

the trusted ID evaluator. It evaluates the trust of the endpoint identity 

sent by identity assertion. Select Use trusted ID evaluator and enter 

the trusted ID evaluator class name manually. 

viii.If you specify a token consumer for the three types of X.509 

certificates, select Use certificate path settings. If you trust any 

certificate, select Trust any certificate. If you want to specify a trust 

anchor and a trusted certificate store, select Certificate path 

reference and select the Trust anchor and Certificate store 

references from the drop-down lists. For an X.509 certificate in a 

PKIPath and a list of X509 certificates and CRLs in a PKCS#7, only the 

trust anchor reference is required. 


ix. Click OK and a token consumer is created. 


6.2.6 Validating authentication with a security token 

We validate the authentication scenario using our application described in 5.6, 

“Our SecurityInfo Web service application and environment” on page 98. 

The application is called with the following URL: 

http://windowsbax.pok.ibm.com:9081/SecurityCallerWAR/ 

The application displays the Principal on Web service client side and also on the 

Web service provider side. See Figure 6-10. 

Figure 6-10 SecurityInfo application authentication display 

The display shows that the user did not authenticate, as the principal on the Web 

service client side is unauthenticated. 

The display shows that the Web services client sent a username security token 

and authenticated, as the principal on the Web service provider side is 

WINSERV. 


The Web service client log confirms that the principal is unauthenticated, as 

shown in Example 6-1. 

Example 6-1 Web service requestor server log 

ITSO SecurityCallerBean - RequestID = ITSO3967 

ITSO SecurityCallerBean - Timestamp = Wed Nov 08 11:37:27 EST 2006 

ITSO SecurityCallerBean - Hostname = windowsbax 

ITSO SecurityCallerBean - ipaddress = 9.56.23.149 

ITSO SecurityCallerBean - Principal = UNAUTHENTICATED 

ITSO SecurityCallerBean - OSName = Windows XP 

ITSO SecurityCallerBean - OS Version = 5.1 build 2600 Service Pack 2 

The Web service provider log confirms that the Web service has been called, 

run, and that the Principal is WINSERV, as shown in Example 6-2. 

Example 6-2 z/OS Web service provider server log 

ITSO SecurityInfoBean - RequestID = ITSO3967 

ITSO SecurityInfoBean - Timestamp = Wed Nov 08 16:37:30 GMT+00:00 2006 

ITSO SecurityInfoBean - Hostname = WTSC58 

ITSO SecurityInfoBean - ipaddress = 9.12.4.8 

ITSO SecurityInfoBean - Principal = WINSERV 

ITSO SecurityInfoBean - OSName = z/OS 

ITSO SecurityInfoBean - OS Version = 01.08.00 

We use the Ethereal software to see messages flowing between the Web service 

client and the provider. The Ethereal output shows that the Web service request 

includes the security token with the and 

tags. See Example 6-3. 

Example 6-3 SOAP/HTTP message from requestor to provider 

POST /SecurityInfoRouterWS/services/SecurityInfo HTTP/1.1 

Host: wtsc58.itso.ibm.com:49080 

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: 790 

Date: Wed, 08 Nov 2006 16:32:09 GMT 


 

WINSERVWINSERV 

 

 

 

ITSO136 

All this validates that authentication of the Web service client occurs at the Web 

service provider level using WS-Security. 

6.3 Integrity with XML digital signature 

Integrity is applied to the application to ensure that no one illegally modifies the 

message while it is in transit. Essentially, integrity is provided by generating an 

XML digital signature on the contents of the SOAP message. If the message data 

changes illegally, the signature would no longer be valid. 

A signature is created using the sender private key. Unauthorized sniffers do not 

have this key. When the receiver gets the message, it also creates a signature 

using the message content. Only if the two signatures match does the receiver 

honor the message. If the signatures are different, a SOAP fault is returned to the 

sender. 

This section describes how WS-Security supports integrity, explains our integrity 

scenario, gives an overview of how to configure integrity, and thoroughly 

describes the steps to configure this scenario. 

6.3.1 Integrity support with WS-Security 

With WS-Security, you can use XML digital signatures, in conjunction with 

security tokens, to detect any modifications to messages. Data integrity is 


provided by generating a signature from the contents of the SOAP message. If 

the message data changes, the signature is found to be invalid by the recipient. 

A digital signature is the application of a combination of one-way and public key 

algorithms to a set of data (the data to be signed). The one-way algorithm 

produces a hash of the data to be signed. The hash is itself encrypted with the 

public key algorithm using the signer’s private secret key. The digital signature, 

therefore, establishes the integrity of the signed data and the authentication of 

the originator of the same data. 

The digital signature mechanism is explained in detail in 5.4.6, “Message 

authentication, integrity, confidentiality, ID assertion” on page 86. 

The specification for XML Signatures can be found at the following URL: 

http://www.w3c.org/Signature 

6.3.2 Integrity scenario description 



scenario illustrates the usage of the XML digital signature to make sure that 

flowing SOAP messages are not altered between the Web service client and the 

Web service provider. The body part of the SOAP message is signed in this 

example. See Figure 6-11. 

Figure 6-11 Web service message security integrity scenario 


On the Web service client side, the user does not provide any credential to the 


EJB makes a Web service call. The Web service request generator signs the 

body part of the SOAP message with the Web service client private key. The 

Web service request generator also includes its own public key as a security 

token in the SOAP message header. 


request consumer receives the security token and retrieves the client public key. 

It uses this client public key to decrypt the signature. It verifies the signature so 

that the SOAP message body part has not been changed while flowing. No 

identity is being used for authentication. Hence, the EJB runs with an 

unauthenticated principal. 

For the response, a digital signature is also used to ensure integrity. On the Web 

service provider side (WebSphere for z/OS), the response generator side signs 

the body part of the SOAP message with the Web service provider private key. 

The Web service response generator also includes its own public key as a 

security token in the SOAP message header. 

On the Web service client side, the Web service response consumer receives 

the security token and retrieves the provider public key. It uses this provider 

public key to decrypt the signature. It verifies the signature so that the SOAP 

message body part has not been changed while flowing. 

6.3.3 Integrity configuration overview 

For configuring integrity, the Web service client and provider have to agree on a 

signature algorithm, on how to find public keys to decrypt the signature, and on 

which SOAP message parts to be signed. Then configuration has to be executed 

on both sides. 

Client side 

To specify integrity for a part of a SOAP message, you have to specify the part 

that should be signed and the method of signing in the client’s WS-Security 

configuration: 

► Specify the parts of the message that have to be signed in the request 

generator configuration. The message parts can be specified by predefined 

keywords or XPath expressions. You can specify multiple parts that require a 

signature. 

► In the most typical integrity example, a security token is inserted into the 

SOAP message, which is used for signature verification by the server. In such 

an example, a token generator should be specified in the request generator 

configuration. The token generator for an X.509 certificate token, 


X509TokenGenerator, is provided by the Web services security run time as a 

default implementation. 

► Specify key-related information, which includes the location of the client’s key, 

the type of key, and a password for protecting the key. 

► Specify signing information, which defines how to sign the specified part. You 

have to specify some options, such as a signature method algorithm and 

key-related information. 

► If the client expects a response that includes integrity information by the 

server, the client also has to be configured to validate the integrity of the 

response message in the response consumer configuration. 

Server side 

To specify integrity for a part of a SOAP message, you have to specify the part 

that was signed and the way of verifying the signature in the server’s 

WS-Security configuration: 

► Specify the parts of the message that require a signature in the request 

consumer configuration. The message parts can be specified by predefined 

keywords or XPath expressions. You can specify multiple parts that require a 

signature. 

► In a most typical integrity example, a security token is inserted into the SOAP 

message, which will be used for the signature verification by the server. In 

such an example, a token consumer should be specified in the request 

consumer configuration. This token consumer’s role is to receive the token 

and extract the client certificate for signature verification. The token consumer 

for an X.509 certificate token, X509TokenConsumer, is provided by the Web 

services security run time as a default implementation. 

► Specify key-related information, which includes the location of the key to be 

used (which is in the token in our example). 

► Specify signing information, which defines how the signature should be 

verified. You have to specify some options, such as a signature method 

algorithm and key-related information. 

► If the server sends a response that includes integrity information by the 

server, the server also has to be configured to sign the response message in 

the response generator configuration. 


6.3.4 Configuring the requestor for request XML digital signature 

To configure the Web service requestor for integrity: 

1. Configure the Integrity. 




next step.) Expand the Request Generator Configuration section. Expand 

the Integrity section and click Add. 

Configure the Integrity dialog (Figure 6-12 on page 136): 

a. Select the order in which the signature is generated. Multiple integrity 

parts can be specified, and you have to specify the order of generating the 

signature. In our case, we select 1. The WS-Security runtime of Version 

6.1 supports multiple signature and encryption parts in one SOAP 

message. For multiple signature and encryption parts, you have to specify 

the processing order. For example, if you want to sign and encrypt the 

SOAP body, you should specify 1 in the Integrity dialog and 2 in the 

Confidentiality dialog. 

b. Add and configure the message part. The default created part is for 

signing the SOAP body. If you want to sign the SOAP body only, you have 

nothing more to do. For another integrity part, you have to specify the 

dialect (WebSphere keywords or XPath). 

In the parts keyword section, you can select from predefined keywords for 

which message parts are signed. The keywords are body (SOAP body 

element is signed), time stamp (all time stamp elements are signed), 

securitytoken (all security tokens are signed), dsigkey (KeyInfo elements 

of the signature are signed), enckey (KeyInfo elements of the encryption 

are signed), messageid (MessageID element of WS-Addressing is 

signed), to (To element of WS-Addressing is signed), action (action 

element of WS-Addressing is signed), relatesto (RelatesTo element of 

WS-Addressing is signed), wsaall (all the WS-Addressing elements are 

signed), wsafrom (from element of WS-Addressing is signed), wsareplyto 

(ReplyTo element of WS-Addressing is signed), wsafaultto (FaultTo 

element of WS-Addressing is signed), and wsacontext (WS-Context 

header is signed). 

In our case we choose to sign the body part only. 


Figure 6-12 Request generator Integrity dialog 

Attention: if you use a security token such as basic authentication, you 

should also sign the security token by adding another part with the 

keyword securitytoken. 

c. If the XPath expression dialect is selected, you should input the XPath 

expression to specify the integrity part. 

d. Add a nonce or time stamp, or both, if you require WebSphere Application 

Server Version 6.1 extensions. For both, you select the dialog and 

keyword in the same way as for the message parts. For the time stamp, 

you can specify an expiration date. 


e. You can add multiple message parts, a nonce, and a time stamp in one 

dialog. All message parts that are specified in one Integrity dialog are 

signed by the same signing information, which is defined on the WS 

Binding page. 

Click OK and an integrity part is created. If you need multiple integrity parts, 

you can add them. Save the configuration. 

2. Configure the token generator (Figure 6-13 on page 138). 

Open the SecurityCallerEJB deployment descriptor. Select the WS Binding 

tab. Expand the Security Request Generator Binding Configuration 

section. You have to know whether a token reference type and a security 

token are inserted. Expand Token Generator and click Add. 



Note that to specify a token generator used for signing, a security token is not 

specified on the WS Extension page. 


Configure the Token Generator dialog: 

a. Enter a token generator name such as IntegrityX509Token. 

b. For the token generator class, select X509TokenGenerator. 

c. Do not select a security token. 

d. Select Use value type, and then select X509 certificate token. 

e. Select X509CallbackHandler. 

f. Select Use key store. In our case, we use the WebSphere default pkcs12 

keystore. Enter the password keystore (WebAS for the WebSphere 

default), the keystore path, and the keystore type. 

g. Click Add under Key and enter default as the alias, WebAS as the key 

password, and the key name. 

h. Click OK and a token generator is created. 

Tip: The WebSphere default keystore path can be found with the 

administrative console in Security → SSL certificate and key 

management → SSL configurations → NodeDefaultSSLSettings → 

Key stores and certificates → NodeDefaultKeyStore. 

The default personal key description can be found in Security → SSL 

certificate and key management → SSL configurations → 

NodeDefaultSSLSettings → Key stores and certificates → 

NodeDefaultKeyStore → Personal certificates. 


3. Configure the key locator. 

Expand Key Locators and click Add. Specify how to retrieve a key for 

signing. 

Configure the Key Locator dialog (Figure 6-14): 

a. Enter a Key locator name such as IntegrityKeyLocator. 

Figure 6-14 Request generator Key locator dialog 

b. Select or enter a key locator class name. The class to retrieve a key 

implements the com.ibm.wsspi.wssecurity.keyinfo.KeyLocator interface. 

Three implementations of KeyLocator are provided in WebSphere 

Application Server Version 6.1, and you can implement your own class if 

necessary. 

The provided implementations are KeyStoreKeyLocator (locates and 

obtains the key from the specified key store file), SignerCertKeyLocator 

(uses the public key from the certificate of the signer of the request 

message), and X509TokenKeyLocator (uses the X.509 security token 

from the requester message for signature validation and encryption). The 

two last ones are used by the request consumer and the response 

consumer. In our case, we select the KeyStoreKeyLocator. 


c. If the selected key locator class requires the key store file, you can specify 

the key store and key by selecting Use key store. Enter the same 

information as in the previous dialog. 

Click OK and a key locator is created. 

4. Configure the key information. 

Expand Key Information and click Add. Specify which type of security token 

reference is used. 

Configure the Key Information dialog (Figure 6-15): 

a. Enter a name such as IntegrityKeyInfo. 

Figure 6-15 Request generator Key Information dialog 

b. Select a key information type from these choices: 

STRREF - direct reference (our choice) 

EMB - embedded reference 

KEYID - key identifier reference 

KEYNAME - key name reference 

X509ISSUER - X.509 issuer name and serial number reference 

The key information class name is filled in when a type is selected. 


c. Select Use key locator and select a key locator from the list. Key locators 

that have been defined are listed. Select IntegrityKeyLocator. Also select 

one of the predefined keys. 

d. If a security token is inserted into the message, and a token generator is 

specified already, specify which token generator is used. Select Use 

token and select one token generator name from the list. The selected 

token generator is invoked to generate the token that is referenced from 

this key information. In our case, we select IntegrityX509Token. 

e. Click OK and the key information is created. 

5. Configure signing information (Figure 6-16). 

Expand Signing Information and click Add. You have to specify how to sign. 

Figure 6-16 Request generator Signing Information dialog 


Configure the Signing Information dialog: 

a. Enter a name such as IntegritySigning. 

b. Select a canonicalization method algorithm. The supported algorithms are: 

http://www.w3.org/2001/10/xml-exc-c14n# (canonical XML algorithm 

without comments (our choice)) 

http://www.w3.org/2001/10/xml-exc-c14n#WithComments (canonical 

XML algorithm with comments) 

http://www.w3.org/TR/2001/REC-xml-c14n-20010315 (exclusive XML 

canonicalization algorithm without comments) 

http://www.w3.org/TR/2001/REC-xml-c14n-20010315#WithComments 

(exclusive XML canonicalization algorithm with comments) 

c. Select a signature method algorithm from the list. The supported 

algorithms are: 

http://www.w3.org/2000/09/xmldsig#rsa-sha1 (RSA with SHA1 (our 

choice)) 

http://www.w3.org/2000/09/xmldsig#dsig-sha1 (DSA with SHA1) 

http://www.w3.org/2000/09/xmldsig#hmac-sha1 (HMAC-SHA1) 

d. Enter any key information name such as IntegrityKeyInfo. 

e. Select a key information element from the list. Predefined key information 

is listed. Select IntegrityKeyInfo. 

f. If you specify signature information for integrity on the KeyInfo element of 

the signature or encryption, meaning that dsigkey or enckey is specified 

as an integrity part, you can specify how to sign the KeyInfo element. 

Select Use key information signature and select from the following 

choices: 

keyinfo specifies the whole KeyInfo element to be signed. 

keyinfochildelements specifies the child elements of KeyInfo element 

to be signed. 

In our case, we do not have to specify this. 

Click OK and the signing information is created. 


6. Configure the part reference (Figure 6-17). 

Expand Part References and click Add. This specifies an integrity part that 

applies to this signature information. 

Figure 6-17 Request generator Part Reference dialog 

Configure the Part Reference dialog: 

a. Enter a part reference name such as IntegrityPart. 

b. Select an integrity part from the list of parts defined on the WS Extensions 

page. In our case, we select BodyIntegrity. 

c. Select a digest method algorithm from the list. The supported digest 

method algorithm is http://www.w3.org/2000/09/xmldsig#sha1. 

d. Click OK and a part reference is created. You can specify multiple part 

references that apply to the same signature information. 


7. Configure the transforms (Figure 6-18). 

After adding part references, adding a transform becomes enabled. Expand 

Transforms and click Add and complete the dialog. 

Figure 6-18 Request generator Transform dialog 

Configure the Transform dialog: 

a. Enter a name such as IntegrityTransform. 

b. Select a transform algorithm from the list. You can specify multiple 

transforms for one part reference. We choose the exclusive 

canonicalization algorithm, which is 

http://www.w3.org/2001/10/xml-exc-c14n#. 

c. Click OK and a transform is created. Save the configuration. 


6.3.5 Configuring the z/OS provider for request XML digital signature 

To configure the Web service provider for integrity: 

1. Configure the required integrity (Figure 6-19). 



Details section. Select the port component, expand Required Integrity, and 

click Add. 

Figure 6-19 Request consumer Required Integrity dialog 

Configure the Required Integrity dialog: 

a. Enter a name denoting the part, such as IntegrityBody. 


. Select the usage type, required or optional. If the usage type is required, a 

request message without integrity throws a SOAP fault. If the usage type 

is optional, and a request message does not have the integrity part, the 

message is received. We select Required. 

c. Click Add under Message Parts to specify an integrity required part. We 

select http://..../dialect-was and body to match our client configuration. 

d. Nonce and time stamp extensions can be specified in the same way as for 

the client. 

e. Click OK and a required integrity part is created. 

2. Configure the token consumer. 


Binding Configuration Details section. 

You have to know whether a required token reference type and a security 

token are required. These settings should match the client configuration: 

a. If you want to specify a token consumer for the three types of X.509 

certificate tokens, specify a trust anchor. We do not specify this. 

b. If the token consumer for the X.509 certificate token is necessary, and you 

want to specify an intermediate trusted certificate store, specify a 

collection certificate store under Certificate Store List. We do not specify 

this. 

c. If the security token is inserted in the request message, add a Token 

Consumer (expand Token Consumers and click Add). To specify a token 

consumer, refer to “Configuring the z/OS Web service provider for security 

token” on page 123. To specify a token consumer for the token used for 

signing, a required security token is not specified in the deployment 

descriptor. 

Configure the Token Consumer dialog (Figure 6-20 on page 148): 

a. Enter a name such as IntegrityToken. 

b. Select the token consumer class X509TokenConsumer. 

c. Do not select a security token. 

d. Select Use value type and select X509 certificate token. 

e. Select Use jaas.config and enter system.wssecurity.X509BST as the 

name. 

f. Select Use certificate path settings and select Trust any certificate. 




3. Configure the key locator (Figure 6-21). 

Expand Key Locators and click Add to specify how to retrieve a key for a 

signature verification. 

Figure 6-21 Request consumer Key Locator dialog 

Configure the Key Locator dialog: 

a. Enter a name such as IntegrityKeyLocator. 

b. Select the X509TokenKeyLocator class. 


4. Configure the key information (Figure 6-22). 

Expand Key Information and click Add to specify which type of security 

token reference is required. The type should match the client configuration. 

Figure 6-22 Request consumer Key Information dialog 

Configure the Key Information dialog: 

a. Enter a name such as IntegrityKeyInformation. 

b. Select STRREF as the type. 

c. Select Use key locator and IntegrityKeyLocator. 

d. Select Use token and IntegrityToken 

e. On the consumer side, we do not have to specify the key name. 


5. Configure the signing information (Figure 6-23). 

Expand Signing Information and click Add to define how to verify a required 

integrity part. 

Figure 6-23 Request consumer Signing Information dialog 

Configure the Signing Information dialog: 

a. Enter a name such as IntegritySigningInfo. 

b. Select http://www.w3.org/2001/10/xml-exc-c14n# as the 

canonicalization method algorithm. 

c. Select http://www.w3.org/2000/09/xmldsig#rsa-sha1 as the signature 

method algorithm. 


d. For the signing key information, click Add, enter 

IntegrityKeyInformation as the key information name, and select 

IntegrityKeyInformation as the key information element. 


Expand Part References and click Add. 

Figure 6-24 Request consumer Part Reference dialog 

Configure the Part Reference dialog: 

a. Enter a name such as IntegrityBody. 

b. For the consumer, you should select the name of a required integrity part 

from the list instead of a part name. Select IntegrityBody in the list. 

c. Select http://www.w3.org/2000/09/xmldsig#sha1 as the algorithm. 


7. Configure the transform (Figure 6-25). 

Expand Transforms and click Add. 

Figure 6-25 Request consumer Transform dialog 

Configure the Transform dialog: 

a. Enter a name such as IntegrityTransform. 

b. Select http://www.w3.org/2001/10/xml-exc-c14n# as the algorithm. 



6.3.6 Configuring the z/OS provider for response XML digital 

signature 

The configuration for this section is similar to the configuration in 6.3.4, 

“Configuring the requestor for request XML digital signature” on page 135. We 

only point out differences in this section. 

1. Configure the integrity (Figure 6-26). 


Extensions tab. Expand the Response Generator Service Configuration 

Details section. Select the port component, expand Integrity, and click Add. 

Figure 6-26 Response generator Integrity dialog 

The configuration is explained in 6.3.4, “Configuring the requestor for request 

XML digital signature” on page 135. 


2. Configure the token generator (Figure 6-27). 

Select the Binding Configurations tab. Expand the Response Generator 

Binding Configuration Details section. Expand Token Generator and click 

Add. 

Figure 6-27 Response generator Token Generator dialog 




For WebSphere Application Server for z/OS, we choose to use the 

WebSphere default pkcs12 keystore. The password is WebAS and we use its 

default alias. 

Tip: The WebSphere default keystore path can be found with the 







NodeDefaultKeyStore → Personal certificates 


Figure 6-28 Response generator Key locator dialog 




4. Configure the key information (Figure 6-29). 

Figure 6-29 Response generator Key Information dialog 




5. Configure signing information (Figure 6-30). 

Figure 6-30 Response generator Signing Information dialog 




Figure 6-31 Response generator Part Reference dialog 




7. Configure the transform (Figure 6-32). 

Figure 6-32 Response generator Transform dialog 



6.3.7 Configuring the requestor for response XML digital signature 


“Configuring the z/OS provider for request XML digital signature” on page 146. 




next step.) Expand the Response Consumer Configuration section. Expand 

the Integrity section, click Add, and configure as described in 6.3.5, 

“Configuring the z/OS provider for request XML digital signature” on page 146. 

Open the SecurityCallerEJB deployment descriptor. Select the WS Binding tab. 

Expand the Security Response Consumer Binding Configuration section. 

Configure as described in 6.3.5, “Configuring the z/OS provider for request XML 

digital signature” on page 146. 

6.3.8 Validating integrity with XML digital signature 

We validate the integrity scenario using our application described in 5.6, “Our 

SecurityInfo Web service application and environment” on page 98. 




The application displays the principal on Web service client side and also on the 

Web service provider side. 

Figure 6-33 SecurityInfo application display with integrity 

The display shows that the user did not authenticate, as the principal on the Web 


The display shows that the Web services client does not authenticate to the Web 

service provider, as the principal on the Web service provider side is 

unauthenticated. 






ITSO SecurityCallerBean - Timestamp = Fri Nov 10 10:47:57 EST 2006 







run, and that the principal is unauthenticated, as shown in Example 6-5. 



ITSO SecurityInfoBean - Timestamp = Fri Nov 10 15:48:04 GMT+00:00 2006 



ITSO SecurityInfoBean - Principal = UNAUTHENTICATED 





includes the security token containing the client public key and also the signature 

of the signed SOAP body. 

We also see the security token and the digital signature for the response SOAP 

message. 

The SOAP messages flow in clear, as the purpose of integrity is only to make 

sure that the content has not been altered. 

Example 6-6 SOAP/HTTP conversation 



... 

Date: Fri, 10 Nov 2006 15:47:56 GMT 

xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wss 

ecurity-secext-1.0.xsd">MIICEDCCAXmgAwIBAgIERU5DqzANBgkqhkiG9w0BAQUFADB 

ucG9rLmlibS5jb20wHhcNMDYxMTA1.............8cUUF4aH9TANBgkqhkiG9w0BAQUFA 

AOBgQB7c1icR21nrqiYprRncUn23GivfBLyNNZtKIB+1BohOvrmVzJLS4BRd/AdZxTDLb1J 

4CESk2KpeuXsFK6D5WC8AFEzAmVEfBGHyvw==vQa 

/lbLPXVv0rFc9PS6+8lHiBmY=BmEw84oUOpYzgnh7b2uqDy1JEZQO4qPDNj1J2UYiFcCalDlI+8 

5O3E4NnG391TqPoZ/76K/DY2XMxI65dnDeCdYxOluU0pXhSL53+Afri+Y+sJsMQkgVx0Zx4 

ALdXEgjE3WjWVTyiZMAYLOfvEAJw3NpO+xDLFLH0ugWvuOnBV4= 

 

ITSO3036 

HTTP/1.1 200 OK 

... 



Server: WebSphere Application Server/6.1 


MIICADCCAWmgAwIBAgIERT6FVDANBgkqhkiG9w0BAQUFADA 

5MQswCQYDVQQGEwJVUzEMMAoGA1UE..............Hb62hxqB28S29uNKgiMatiySUfG5 

8SFsyOTjnQk1UVtud8Y9JLjz7kI1LVTiM1EP6Y++XP+Pq2t8qSNWAN+nVnaE8A4X8EuGRDU 

b/DjAjh8LCAWY6CsA37 

Up9iFTwgagkadxBg4uk5wprQ=pO+JYmFGdps3yutO6oUbqggknDagy+0pv1cb7C0SRhdw/jD5Vr 

Ixe+9Jp/xqZcNrz+yhuE05cCNwk/QznjHxvQ0L8YB4C88A/uG9k7M4Lnv+Dd0RD+MfFaxbP 

v3MQETlPBdV69frKEdz+SjJO5jxFhxb4OomHIFKoXQpMXKcVQQ= 

 

ITSO3 

036Fri Nov 10 15:48:04 GMT+00:00 

2006WTSC589.12.4.8UN 

AUTHENTICATEDz/OS01.08.00

tainSecurityInfoReturn> 

All this validates that digital signatures are being used to sign SOAP messages 

between the Web service client and the Web service provider using 

WS-Security. 

6.4 Confidentiality with XML encryption 

Confidentiality refers to the concept that an unauthorized party cannot obtain the 

meaning of the transferred or stored data. Typically, confidentiality is achieved by 

encrypting the data using cryptography. 

Cryptography is required to thoroughly achieve authentication, data integrity, 

confidentiality, and non-repudiation. Three kinds of algorithms are most 

commonly used for these purposes. 

► Public key, or asymmetric, algorithms (typically the RSA algorithm) 

These algorithms use a pair of keys. What has been encrypted with one key 

of the pair can only be decrypted with the other key of the pair. One key is 

kept secret. This is the private key. The other key is the public key, and, as 

the name implies, its value is public knowledge. Public key algorithms can 

also be used to achieve authentication. 

► Shared secret key, or symmetric algorithms (typically the Data Encryption 

Standard (DES) algorithm) 

The same single secret key is used both for encryption and decryption. 

Shared secret key algorithms are used for data confidentiality. 

► One-way algorithm 

This algorithm condenses an input string to a short fixed length numeric 

value, the hash. Typically, a hash is a 128-bit or 160-bit value. Any change in 

the input string induces a change in the hash value. The Secure Hash 

Algorithm (SHA-1) is such an algorithm. Its output is used as a fingerprint for 

the contents of a message. 

This section describes how WS-Security supports confidentiality, explains our 

confidentiality scenario, gives an overview of how to configure confidentiality, 

and thoroughly describes the steps to configure this scenario. 


6.4.1 Confidentiality support with WS-Security 

Confidentiality is the process in which a SOAP message is protected so that only 

authorized recipients can read the SOAP message. Confidentiality is provided by 

encrypting the contents of the SOAP message using XML encryption. If the 

SOAP message is encrypted, only a service that knows the key for confidentiality 

can decrypt and read the message. 

The XML encryption standard specifies a process for encrypting data and 

representing the result in XML. XML encryption can be used to encrypt any part 

of a SOAP message, normally sensitive data such as bank account numbers or 

user credentials. The result of encrypting data is an XML encryption element that 

contains or references the cipher data. 

WS-Security uses a combination of XML encryption and security tokens to 

implement confidentiality for portions of the SOAP message. 

Message confidentiality leverages XML encryption in conjunction with security 

tokens to keep portions of a SOAP message confidential. For more information 

refer to: 


6.4.2 Confidentiality scenario description 


SecurityInfo Web service application and environment” on page 98. 


This scenario illustrates the usage of XML encryption to make sure that flowing 

SOAP messages are not readable (in clear text) between the Web service client 

and the Web service provider. The body part of the SOAP message is encrypted 

in this example. See Figure 6-34. 

Figure 6-34 Web service message security confidentiality scenario 

On the Web service client side, the user does not provide any credential to the 


EJB makes a Web service call. The Web service request generator encrypts the 

body part of the SOAP message with the Web service provider public key. This 

Web service provider public key is available as a signer certificate in the client 

key store. 


request consumer receives the SOAP message request with the encrypted body 

part. It uses its own private key to decrypt the body part. Its own private key is 

available as a personal certificate in its key store. No identity is being used for 

authentication. Hence, the EJB runs with a unauthenticated principal. 

For the response, encryption is also used to ensure confidentiality. On the Web 

service provider side (WebSphere for z/OS), the reponse generator side 

encrypts the body part of the SOAP message with the Web service client public 

key. This Web service client public key is available as a signer certificate in the 

provider key store. 


On the Web service client side, the Web service response consumer receives 

the SOAP message response with the encrypted body part. It uses its own 

private key to decrypt the body part. Its own private key is available as a personal 

certificate in its key store. 

6.4.3 Confidentiality scenario key prerequisites 

As described in the above scenario, the public keys need to be available on the 

other party side so that encryption can occur. 

Hence, the key stores have the following configuration: 

► Web services client (winbax) key store possesses: 

– Client public and private keys as a personal certificate 

– Provider certificate with only a public key as a signer certificate 

► The Web services provider (wtsc58) key store possesses: 

– Provider public and private keys as a personal certificate 

– Client certificate with only a public key as a signer certificate 

In our configuration we use the default key stores that already have the default 

personal certificates configured. So we only have to extract the public keys (in 

the form of signer certificates) from the personal certificates and transfer them to 

the other party key store. 

Key configuration for request encryption 

In this section we extract a signer certificate from the Web service provider 

personal certificate. Then we transfer this certificate and import it as a signer 

certificate in the Web service client key store. 

We show in this section how to extract the WebSphere z/OS signer certificate 

using the administrative console. It is also possible to do it using RACF 

commands, as shown in 8.2.2, “Integrity scenario prerequisites” on page 253. A 

detailed description about different export options is available in 7.4.4, “Exporting 

certificates” on page 220. 


To do this: 

1. Using the Web service provider (WebSphere for z/OS) administrative 

console, navigate to the default configured personal certificate in SSL 

certificate and key management → Key stores and certificates → 

NodeDefaultKeyStore → Personal certificates, select the default 

certificate, and click Extract (Figure 6-35). 

Figure 6-35 Web service provider personal certificate 

It is important to click Extract and not Export. Extract takes the public key 

only. Export takes the public key and the private key. But the private key 

should stay private and should not be shared with other parties. 

2. Enter an HFS path and file name to store the resulting signer certificate. 

Select the Binary DER data type and click OK (Figure 6-36). 

Figure 6-36 Web service provider certificate extraction 

3. FTP this DER file in binary format to the Web service client. 


4. Using the Web service client administrative console, navigate to the Add 

signer certificate section of the defaultkey store in SSL certificate and key 

management → Key stores and certificates → NodeDefaultKeyStore → 

Signer certificates and select the Add signer certificate. 

Enter an alias refering to the Web service provider name. Enter the path and 

the file name of the DER file you just transfered. Select the Binary DER data 

type and click OK (Figure 6-37). 

Figure 6-37 Web service signer certificate add 

The signer certificate now appears in the list of signer certificates on the Web 

service client side. 

Key configuration for response encryption 

In this section we extract a signer certificate from the Web service client personal 

certificate. Then we transfer this certificate and import it as a signer certificate in 

the Web service provider key store. 

The following steps describe how to do this: 

1. Using the Web service client administrative console, navigate to the default 

configured personal certificate in SSL certificate and key management → 

Key stores and certificates → NodeDefaultKeyStore → Personal 

certificates, select the default certificate, and click Extract. 

It is important to click Extract and not Export. Extract takes the public key 

only. Export takes the public key and the private key. But the private key 

should stay private and should not be shared with other parties. 


2. Enter a path and file name to store the resulting signer certificate. Select the 

binary DER data type and click OK. 

Figure 6-38 Web service client certificate extraction 

3. FTP this DER file in binary format to the Web service provider (WebSphere 

for z/OS). 

4. Using the Web service provider administrative console, navigate to the Add 

signer certificate section of the defaultkey store in SSL certificate and key 


Signer certificates and select the Add signer certificate. 

Enter an alias refering to the Web service client name. Enter the path and the 

file name of the DER file you just transfered. Select the Binary DER data 

type and click OK (Figure 6-39). 

Figure 6-39 Web service signer certificate add 


The signer certificate now appears in the list of signer certificates on the Web 

service provider side. 

6.4.4 Confidentiality configuration overview 

For configuring confidentiality, the Web service client and provider have to agree 

on an encryption algorithm, on which SOAP message parts are to be encrypted 

and have to transfer their public keys as described in the preceding section. 

Then configuration has to be executed on both sides. 

Client side 

To specify confidentiality for a part of a SOAP message, you have to specify the 

parts that should be encrypted and the method of encryption in the client’s 


► Specify the parts of the message that have to be encrypted in the request 

generator configuration. The message parts can be specified by predefined 

keywords or XPath expressions. You can specify multiple parts that require 

encryption. 

► Specify key-related information, which includes the location of the encryption 

key, type of key, and a password for protecting the key. 

► Specify encryption information, which defines how to encrypt to the specified 

part. You have to specify options, such as an encryption method algorithm 

and key-related information. Application Server Toolkit helps you to specify 

these options. 

► If a client expects a response that includes confidentiality by the server, the 

client also has to be configured to decrypt the server’s encryption of the 

response message in the response consumer configuration. 

Server side 

To specify confidentiality required for part of a SOAP message, you have to 

specify the encrypted parts and the method of decryption in the server’s 


► Specify the parts of the message that require decryption in the request 

consumer configuration. The message parts can be specified by predefined 

keywords or XPath expressions. You can specify multiple parts that require 

encryption. 

► Specify key-related information, which includes the location of the decryption 

key, the type of key, and a password for protecting the key. 

► Specify encryption information, which defines how to decrypt the specified 

part. You have to specify options, such as an encryption method algorithm 

and key-related information. 


► If a server sends a response that includes confidentiality, the server also has 

to be configured to encrypt of the response message in the response 

generator configuration. 

6.4.5 Configuring the requestor for request XML encryption 

To configure the Web service requestor for confidentiality: 

1. Configure the confidentiality. 




next step.) Expand the Request Generator Configuration section. Expand 

the Confidentiality section and click Add. 

Configure the Confidentiality dialog (Figure 6-40 on page 173): 

a. Enter a name such as ConfidentialityBody. 

b. Select the order in which the encryption is generated. Multiple 

confidentiality parts can be specified, and you have to specify the order of 

generating the encryption. In our case, we select 1. 

The WS-Security run time of Version 6.1 supports multiple signature and 

encryption parts in one SOAP message. For multiple signature and 

encryption parts, you have to specify the processing order. For example, if 

you want to sign and encrypt the SOAP body, you should specify 1 in the 

Integrity dialog and 2 in the Confidentiality dialog. 

c. Click Add for message parts, and one confidentiality part is created. The 

created part is an encryption of the SOAP body content. To specify other 

confidentiality parts, specify the message parts dialect and message parts 

keyword. Refer to the definition of message parts dialect described in 

“Configuring the requestor for request XML digital signature” on page 135. 

The message parts keywords for specifying a confidentiality part are 

different from an integrity part. The keywords for a confidentiality part are: 

bodycontent: content of SOAP body element 

usernametoken: username token element 

digestvalue: digest value element from a signature element 

signature: specifies an entire signature 

wscontextcontent: encrypts the WS-Context header 

We select http://........../dialect-was and bodycontent as the keyword. 


Figure 6-40 Request generator Confidentiality dialog 

d. Add a nonce or time stamp, or both, if you require them. For both, select 

the dialog and keyword in the same way as for the message parts. For the 

time stamp, you can specify an expiration date. 

e. You can add multiple message parts, a nonce, and time stamp in one 

dialog. All message parts that are specified in one Confidentiality dialog 

are encrypted by the same encryption information, which is defined on the 

WS Binding page. 

Click OK, and a confidentiality part is created. Save the configuration. 





section. Expand the Key Locators section and click Add to specify how to 

retrieve a key for encryption. 

Figure 6-41 Request generator Key Locator dialog 

To specify a key locator, refer to 6.3.4, “Configuring the requestor for request 



a. Enter a name such as ConfidentialityKeyLocator. 

b. Select KeyStoreKeyLocator as the class name. The class to retrieve a 

key implements the com.ibm.wsspi.wssecurity.keyinfo.KeyLocator 

interface. 

c. Select Use key store and specify a client key store. We choose the 

WebSphere default key store. 


d. Click Add under Key to define the key. Enter the provider key alias, a key 

password, and the provider key name. We choose the wtsc58 alias. 

Tip: The WebSphere default key store path can be found with the 




The personal key description can be found in Security → SSL 




3. Configure key information (Figure 6-42). 

Expand Key Information and click Add to specify which type of key 


Figure 6-42 Request generator Key Information dialog 

To specify key information, refer to 6.3.4, “Configuring the requestor for 

request XML digital signature” on page 135. 



a. Enter a name such as ConfidentialityKeyInfo. 

b. Select a type (KEYID) from the Key information type list. 

c. Select Use key locator, and then select the key locator and the key name 

you defined before. 

4. Configure encryption information (Figure 6-43). 

Expand Encryption Information, click Add, and specify how to encrypt. 

Figure 6-43 Request generator Encryption Information 

Configure the encryption information: 

a. Enter a name such as ConfidentialityEncryptionInfo. 

b. Select a data encryption method algorithm from the list. The supported 


http://www.w3.org/2001/04/xmlenc#tripledes-cbc: Triple DES in CBC 

(our choice) 

http://www.w3.org/2001/04/xmlenc#aes128-cbc: AES 128 in CBC 




c. Select a Key encryption method algorithm from the list. The supported 


http://www.w3.org/2001/04/xmlenc#rsa-1_5: RSA Version 1.5 (our 

choice) 

http://www.w3.org/2001/04/xmlenc#kw-tripledes: Triple DES Key Wrap 

http://www.w3.org/2001/04/xmlenc#kw-aes128: AES 128 Key Wrap 



http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p: RSA-OAEP 

If no algorithm is selected, the encryption key is not encrypted. 

d. Enter any key information name. This specifies the key information 

reference. We specify ConfidentialityKeyInfo. 

e. Select a key information element from the list of the key information that 

was defined. The selected key information is used for encryption. In our 

case, we select ConfidentialityKeyInfo from the list. 

f. Select a confidentiality part from the list of confidentiality parts that were 

defined in the extensions. In our case, we select ConfidentialityBody from 

the list. 

g. Click OK and the encryption information is created. Save the 



6.4.6 Configuring the z/OS provider for request XML encryption 

Follow the steps to configure the Web service provider for confidentiality: 

1. Configure the required confidentiality (Figure 6-44). 



Details section. Select the port component, expand Required 

Confidentiality, and click Add. 

Figure 6-44 Request consumer Required Confidentiality dialog 

Configure the Required Confidentiality dialog: 

a. Enter a name such as ConfidentialityBody. 


. Select the usage type, either required or optional. If the usage type is 

required, an unencrypted request message throws a SOAP fault. If the 

usage type is optional, an unencrypted message is received. Select 

Required. 

c. Click Add for message parts and select http://.../dialect-was and 

bodycontent as the keyword. 

d. Nonce and time stamp extensions can be specified as on the generator 

side. In our case, we do not specify them. 

e. Click OK and a required confidentiality part is created. 

2. Configure the trust anchor (Figure 6-45). 


Binding Configuration Details section. Expand Trust Anchor and click 

Add. 

Figure 6-45 Request consumer Trust Anchor dialog 

Configure the Trust Anchor dialog: 

a. Enter a name such as ConfidentialityTrustAnchor. 

b. Enter the trust store password. We choose the WebSphere default 

password WebAS. 

c. Enter the trust store path. We use the WebSphere default trust store. 

d. Select the trust store type. We choose PKCS12. 


Tip: The WebSphere default trust store path can be found with the 



Key stores and certificates → NodeDefaultTrustStore. 





Click OK and a trust anchor is created. 


Expand Key Locators and click Add to specify how to retrieve a key for 

decryption. 

Figure 6-46 Request consumer Key Locator dialog 

To specify a key locator, refer to 6.3.4, “Configuring the requestor for request 




a. Enter a name such as ConfidentialityKeyLocator. 

b. Select KeyStoreKeyLocator as the class name. The class to retrieve a 

key implements the com.ibm.wsspi.wssecurity.keyinfo.KeyLocator 

interface. 

c. Select Use key store and specify a client key store. We choose the 

WebSphere z/OS default key store. 

d. Click Add under Key to define the key. Enter the provider key alias, a key 

password, and the provider key name. We choose the wtsc58 Alias. 




Figure 6-47 Request consumer Key Information dialog 

To specify a key information, refer to 6.3.4, “Configuring the requestor for 

request XML digital signature” on page 135. 


a. Enter a name such as ConfidentialityKeyInfo. 

b. Select a type (KEYID) from the Key information type list. 


c. Select Use key locator, and then select the key locator and the key name 

you defined before. 

5. Configure encryption information (Figure 6-48). 

Expand Encryption Information, click Add, and specify how to encrypt. 

Figure 6-48 Request consumer Encryption Information 

To specify encryption information, refer to 6.4.5, “Configuring the requestor for 

request XML encryption” on page 172. 

Configure the encryption information: 

a. Enter a name such as ConfidentialityEncryptionInfo. 

b. Select a data encryption method algorithm from the list. If no algorithm is 

selected, the encryption key is not encrypted. 

c. Enter any key information name. This specifies the key information 

reference. We specify ConfidentialityKeyInfo. 


d. Select a key information element from the list of the key information that 

was defined. The selected key information is used for encryption. In our 

case, we select ConfidentialityKeyInfo from the list. 

e. Select a confidentiality part from the list of confidentiality parts that were 

defined in the extensions. In our case, we select ConfidentialityBody from 

the list. 

f. Click OK and the encryption information is created. Save the 


6.4.7 Configuring the z/OS provider for response XML encryption 


“Configuring the requestor for request XML encryption” on page 172. We only 

point out differences in this section. 

1. Configure the confidentiality. 




next step.) Expand the Response Generator Configuration section. Expand 

the Confidentiality section and click Add. 

Refer to 6.4.5, “Configuring the requestor for request XML encryption” on 

page 172, for details about this dialog configuration. The configuration of this 

dialog is similar. 




Binding Configuration tab. Expand the Response Generator Binding 

Configuration Details section. Expand the Key Locators section and click 

Add to specify how to retrieve a key for encryption. 

Figure 6-49 Response generator Key Locator dialog 


page 172 for details about this dialog configuration. 





Figure 6-50 Response generator Key Information dialog 



4. Configure encryption information. 

Expand Encryption Information and click Add and specify how to encrypt. 


page 172 for details about this dialog configuration. The configuration of this 


6.4.8 Configuring the z/OS requestor for response XML encryption 


“Configuring the z/OS provider for request XML encryption” on page 178. We 

only point out differences in this section. 

1. Configure the required confidentiality. 





next step.) Expand the Response Consumer Configuration section. 

Expand the Required Confidentiality section and click Add. 

Refer to 6.4.6, “Configuring the z/OS provider for request XML encryption” on 



2. Configure the trust anchor (Figure 6-51). 

Select the WS Binding tab. Expand the Security Response Consumer 

Binding Configuration section. Expand Trust Anchor and click Add. 

Figure 6-51 Response consumer Trust Anchor dialog 


page 178, for details about this dialog configuration. 



Expand Key Locators and click Add to specify how to retrieve a key for 

decryption. 

Figure 6-52 Response consumer Key Locator dialog 







Figure 6-53 Response consumer Key Information dialog 


page 178, for details about this dialog configuration. 

5. Configure encryption information. 

Expand Encryption Information and click Add and specify how to encrypt. 




6.4.9 Validating confidentiality with XML encryption 

We validate the confidentiality scenario using our application described in “5.6, 






Web service provider side (Figure 6-54). 

Figure 6-54 SecurityInfo application confidentiality display 

The display shows that the user did not authenticate, as theprincipal on the Web 


The display shows that the Web services client does not authenticate to the Web 

service provider, as the principal on the Web service provider side is 

unauthenticated. 





ITSO SecurityCallerBean - Timestamp = Mon Nov 13 08:55:35 EST 2006 








run, and that the principal is unauthenticated, as shown in Example 6-8. 



ITSO SecurityInfoBean - Timestamp = Mon Nov 13 13:55:47 GMT+00:00 2006 



ITSO SecurityInfoBean - Principal = UNAUTHENTICATED 





body part is encrypted and not readable. An EncryptedData tag is added to the 

SOAP message. 

We also see that the body part of the SOAP message for the response is 

encrypted. 

Example 6-9 SOAP/HTTP conversation 



... 





Date: Mon, 13 Nov 2006 13:55:34 GMT 

SnrZxQvN4uw=YLx8JzXGihdnEFtk7NMKxrZ/jO5V2dZWOhXiEL0Y/c72Tf3nkoUmRz3r1xTuSW9fcvn 

6LKtKzAM0WNFEzIFpeoOVoUtMWoRNLUBLSI3SyUdBIaS6en6536M2CwFRbFCDDzekPQ6ynY 

mxpYxrQiIpkRIsbxMIw6O+66lG43y88rU=

List> 

Ngo63Q72UWG0r/Z3zvyFAVTTlAdTlw4+vtumTqZSgvzbLp8/V5pjE7Pru 

X1MxUN+arMjxaC0afV7yP+9nKbNgagf+EB5yFVRCju3PzJXYpg6OBWHwfl/6WWwIpbNLVXN 

4ntU5dRSQ5+bC6o6lTQk/PuH3LNAWWlm 

 

HTTP/1.1 200 OK 

... 



Q/HFFBeGh/U=kB+/NZaPzXVouZYZVa/l991AnRXRMsDkIm/nyJhwWzchOMeE3eaXYHRExjIWCOazJ+G 

wZ3tRGLRpkfg9BKJBmQWzKgiGnflgSl+hyqmNnzNb9xzi4Y4zkrvKYuk4Ov6yub7NG94bIS 

ndgeSqqBVeMY0KYcAPzx8jo3ES7WghqRk= 

M1YgSFnIrz89VFHdPsmVT0PauBHcbxs+qdeLp1/f+BnsDzzz8dCIr1RT5 

Sy2fK2nUuW2YRFOjr+0Ryaaw6gWbDDCbG+1FyG3E6YqGvaHng6uM39Hm/Om4wTq8kKYqQaG 

HX0lnlieRs04D6iyzk3NfPLXDoxqov4LIuEZaLL5YcxuVmF5+OgPj8mnEe3QN47ENF9Ygjw 

mzv2jb21Euz8H0oK5nVBBqMXJH8zakgU2+qOGMsTAUrLd5eCsVqH1jwKmW+VvwXRH65VlZT 

o1PV40x5Zn8BpLCA/sfd5GzmtoytAIjxipAVoYw0ebd6IA4msJZ1U/EcLD+rD/bABSSdelF 

zHgyw6MZmpWfYgkAC6fw/2p1PrRCCnC12M2xz214TUQgHrljPbtGl73/dz5F77ow8wW+oK9 


A4rAxe3jWkLuFZwqgPCbRWXYZeCJBB5vp0L1O8O005Q6OUr784vzTlIqj39VtLDaFcJ4wP8 

36yoSa8w= 

All this validates that XML encryption is used to encrypt SOAP messages 

between the Web service client and the Web service provider using 

WS-Security. 

6.4.10 Confidentiality using hardware cryptography 

With WebSphere Application Server for z/OS v6.1, it is not necessary to use 

ICSF-managed keys for hardware cryptography. You may use 

non-ICSF-managed keys (soft keys) for hardware cryptography. For example, 

using the IBMJCECCA java cryptographic provider, it is possible to use keys in 

JKS keystores (same configuration as the configuration described in the 

preceding sections) and benefit from hardware cryptography. If you want such a 

configuration, configure confidentiality as described in the preceding sections, 

install the unrestricted Java policy jar files, and select the IBMJCECCA provider 

as the first choice in the java.security file. 

For more information see 7.5, “Hardware crypto and Java crypto providers” on 

page 222, which describes extensively the different achoices vailable for 

exploiting hardware cryptography. Section 7.8.2, “Installing the unrestricted Java 

policy jars” on page 236, shows how to install the unrestricted Java policy jar 

files. 

6.5 Identity assertion 

Identity assertion (or ID assertion) is a mechanism that allows the propagation of 

an already authenticated identity from one server to another. ID assertion is 

different from the other authentication methods in that it is based on a trust 

relationship between the sender of the identity and the receiver. The receiver can 

assume that the identity has been authenticated, because he trusts the sender. 

You can use ID assertion when an intermediary server must invoke a service 

from a downstream server on behalf of the client. The intermediary server 

establishes a trust relationship with the downstream server (using authentication, 

for instance, but not necessarily) and then is recognized as a trusted partner by 

the downstream server. The intermediary server can then assert the client 

identity to the downstream server. 

Identity assertion is particularly well suited for end-to-end security solutions. 


This section describes how WS-Security supports identity assertion, explains our 

identity assertion scenario, gives an overview of how to configure identity 

assertion, and thoroughly describes the steps to configure this scenario. 

6.5.1 Identity assertion support with WS-Security 

WS-Security support two formats for sending the caller identity to an endpoint 

server: 

► Caller’s username token without the caller’s password 

► Caller’s X.509 certificate token 

WS-Security supports the following trust modes with a downstream server: 

► Basic authentication 

The asserting server authenticates itself, sending a user name and password 

in the SOAP header, in addition to the transmitted asserted identity. 

► Digital signature 

The asserted identity is transmitted digitally signed by the asserting server, 

along with the asserting server x.509 certificate. This provides both for data 

integrity of the transmitted asserted identity and for authentication of the 

sender. 

► Presumed trust 

In this case, communication flows inside a secure channel or uses a secure 

transport protocol so that the asserting server does not need to provide 

authentication data at the SOAP message level. Typically, this can be 

achieved using HTTP as the transport protocol with the SSL/TLS client (the 

client is the asserting server) authentication. 

When you use the BasicAuth and digital signature trust modes, the intermediary 

server passes its own authentication information to the downstream server for 

authentication. The Web services security implementation for WebSphere 

Application Server validates the trust relationship by following this procedure: 

1. The downstream server validates the authentication information of the 

ntermediary server. 

2. The downstream server verifies whether the authenticated intermediary 

server is authorized for identity assertion. For example, the intermediary 

server must be in the trust list for the downstream server. 

3. If the validations described previously succeed, the asserted identity is set as 

the identity of the running thread. If any of the validations fail, the request is 

rejected with a SOAP fault exception. 


When asserting an identity, the already authenticated identity must be known in 

the downstream server user registry. This implies that identities known to the 

intermediary server and identity known to the downstream server must be the 

same. This can be ensured sharing the same user registry such as an LDAP user 

registry. In a z/OS environment, this can be fulfilled sharing a RACF database 

among several LPARs. Or across disparate environments, it might be necessary 

to synchronize user registries. 

6.5.2 Identity assertion scenario description 



scenario illustrates the usage of identity assertion to have a Web service client 

assert an identity to a Web service provider. This identity is a user name in this 

example. The intermediary server (winbax) uses the embedded file-based user 

registry (federated repository). The downstream server (wtsc58) uses RACF 

(LocalOS). These two registries are synchronized manually so that an 

authenticated user in the intermediary server is also known by the downstream 

server. The trust relationship between the intermediary server and the 

downstream server is a presumed trust in this example. 

Figure 6-55 Web service message security identity assertion scenario 

On the Web service client side, the user authenticates to the intermediary server 

(winbax) using a user ID (USER1) and a password. These credentials are 

validated against the intermediary server user registry. Because credentials are 

valid, the login module sets the user ID (USER1) in the Java principal for 


executing the client EJB. This client EJB makes a Web service call. The Web 

service request generator includes a security token in the SOAP message 

header. This security token is a username token that contains the user username 

only (USER1). No password is inserted. The Web service request generator also 

performs the actions necessary to establish the trust relationship (basic 

authentication token, sign the user name, or nothing). In our example the trust is 

presumed, hence no additional action is required. 


request consumer receives the security token and uses a JAAS login module to 

accept the asserted user name and set the principal. The EJB runs with a 

USER1 principal. 

In this example, the user identity USER1 flows from the browser, through the 

intermediary server (winbax), to the downstream server (wtsc58). 

Identity assertion occurs only when sending the request. Hence, there is no 

security mechanism when receiving the response. 

6.5.3 Identity assertion configuration overview 

For configuring identity assertion, the Web service client and provider have to 

agree on a trust relationship and on an assserted identity format. Then 

configuration has to be executed on both sides. 

Client side 

To insert an asserted identity into a SOAP message, a username token and its 

token generator must be specified in the client’s WS-Security configuration: 

► Specify a security token in the request generator configuration. In case of 

identity assertion, the security token type must be username. This security 

token is sent inside the SOAP header to the server. 

► Specify a token generator for the user name token in the request generator 

configuration. The role of the token generator is to retrieve the user name 

from the current Java principal and generate the user name token with the 

user name only and no password. The token generator class for the user 

name token, UsernameTokenGenerator, is provided by the Web services 

security run time as a default implementation. Some specific properties need 

to be defined so that the callback handler knows where to find the user name. 


Server side 

To receive the asserted identity, you must specify a security token that is 

required by the server and a token consumer in the server’s WS-Security 

configuration, as follows: 

► Specify a security token that is required by the server. In case of identity 

assertion, the required security token type is username (same as in the client 

configuration). 

► Specify a caller part that enforces the trust relationship. 

► Specify a token consumer in the request consumer configuration. The token 

consumer receives a security token in the request message and validates it. 

The token consumer class for the user name token, 

UsernameTokenConsumer, is provided by the Web services security run time 

as a default implementation. The JAAS login module is specific for identity 

assertion, as it only accepts the asserted identity. 

6.5.4 Configuring the Web service requestor for identity assertion 

To configure the Web service requestor for identity assertion: 

1. Configure the security token (Figure 6-56). 




next step.) Expand the Security Request Generator Binding Configuration 

section. Expand the Security Token section and click Add. 

Figure 6-56 Request generator Security Token dialog 


Configure the Security Token dialog: 

a. Enter a name such as IDAssertionToken. 

b. Select the Username Token type from the drop-down list. When you 

select a token type, the local name is filled in automatically. The URI is not 

necessary (leave it empty). 

Click OK. 


2. Configure the token generator (Figure 6-57). 



section. Expand the Token Generator section and click Add. 



Configure the Token Generator dialog: 

a. Enter a token generator name such as IDAssertionTokenGen. 

b. Select the UsernameTokenGenerator token generator class. 

c. For the security token, expand the drop-down list and select the security 

token defined on the WS Extension page (IDAssertionToken). 

d. Check the Use value type check box. 

e. Select the Username Token value type from the drop-down list. This 

selection fills the local name and callback handler. 

f. Verify the callback handler class is NonPromptCallbackHandler. 

g. Do not specify any user ID and password, as the flowing identity comes 

from the principal. 

h. Add callback handler properties: 

com.ibm.wsspi.wssecurity.token.IDAssertion.isUsed set to true: This 

option indicates that the identity of the initial sender is required and 

inserted into the Web services security header within the SOAP 

message. For example, WebSphere Application Server only sends the 

user name of the original caller for a username token generator. For an 

X.509 token generator, the application server sends the original signer 

certification only. 

com.ibm.wsspi.wssecurity.token.IDAssertion.useRunAsIdentity set to 

true: This option indicates that the RunAs identity will be used instead 

of the initial caller identity for identity assertion for a downstream call. 

i. Click OK and the identity assertion token generator is created. 


6.5.5 Configuring the z/OS Web service provider for identity 

assertion 

To configure the Web service provider for identity assertion: 

Attention: Administrative security and application security have to be both 

enabled on the Web service provider side for Web service identity assertion to 

operate. 


1. Configure the required security token (Figure 6-58). 



Details section. Select the Port Component Binding, expand the Required 

Security Token, and click Add. 

Figure 6-58 Request consumer Required Security Token dialog 

Configure the Required Security Token dialog: 

a. Enter a name such as IDAssertionToken. 

b. Select the Username token type from the drop-down list, matching the 

client specification. The local name is filled in automatically. 

c. Select the usage type from the drop-down list. The available choices are 

required or optional. If you select required, a SOAP fault is thrown if a 

required security token is not included in a client’s request message. If you 

select optional, the process of consuming a request message continues 

without throwing a SOAP fault. We choose Required. 

Click OK. 


2. Configure the caller part (Figure 6-59). 

Expand Caller Part under Request Consumer Service Configuration 

Details and click Add. 

Figure 6-59 Request consumer Caller Part dialog 

Configure the Caller Part dialog: 

a. Enter a name of for the caller part such IDAssertionCallerPart. 

b. Select Username Token as the token type. This automatically fills the 

local name. 

c. Check Use IDAssertion and choose the message layer level trust method 

name. We choose None. If Signature is selected for the trust method, 

specify the required integrity part that specifies the signature of the trusted 

intermediary certificate. 


Click OK and a caller part is created. Save the configuration. 

3. Configure the token consumer (Figure 6-60). 


Binding Configuration Details section. Expand Token Consumer and click 

Add. 



Configure the Token Consumer dialog: 

a. Enter a token consumer name such as IDAssertionTokenConsumer. 

b. Select the IDAssertionUsernameTokenConsumer token consumer 

class. This class processes the username token for identity assertion, 

which does not have a password element. This interface invokes the 

system.wssecurity.IDAssertionUsernameToken JAAS login configuration 

with the 

com.ibm.wsspi.wssecurity.auth.module.IDAssertionUsernameLoginModul 

e login module to validate the IDAssertion user name token. An object of 

the com.ibm.wsspi.wssecurity.auth.token.UsernameToken class is created 

for the validated username token and stored in the JAAS subject. 

c. Expand the drop-down list for security token and select the token specified 

on the extension page (IDAssertionToken). 

d. Select Use value type and select the Username Token value type from 

the list. This fills the local name automatically. 

e. Select Use jaas.config to validate the security token in the client’s 

request message. Specify the name of the JAAS configuration: 

system.wssecurity.IDAssertionUsernameToken. This enables the 

application to use identity assertion to map a user name to an application 

server credential principal. 

f. Click OK and the token consumer is created. 


6.5.6 Configuring the trust relationship for identity assertion 

Identity assertion relies on the trust relationship between an intermediary server 

and a downstream server. Because of this, the downstream server trusts the 

intermediary server and accepts the asserted identity. 

This section discusses different ways to create the trust relationship between the 

intermediary server and the downstream server. 

Trust enforced with Web service message security 

As described in 6.5.1, “Identity assertion support with WS-Security” on page 193, 

the trust relationship can be created at the Web service message layer level 

using one of the following methods: 


The asserting server authenticates itself, sending a user name and password 

in the SOAP header, in addition to the transmitted asserted identity. 


► Digital signature 

The asserted identity is transmitted digitally signed by the asserting server, 

along with the asserting server x.509 certificate. This provides both for data 

integrity of the transmitted asserted identity and for authentication of the 

sender. 

Consider that basic authentication is not very secured by itself, as the user name 

and password flow in clear in the SOAP message. If you choose basic 

authentication, you should also consider some other security mechanisms such 

as SSL at the transport layer level. 

Presumed trust and Web service transport security 

If the trust relationship is not created at the Web service message layer level, 

then it is only presumed at the message layer level and it can be enforced at the 

Web service transport layer level. 

In this case, communication flows inside a secure channel or uses a secure 

transport protocol so that the asserting server does not need to provide 

authentication data at the SOAP message level. 

Depending on the transport security capabilities, different mechanisms may be 

used. If HTTP is being used as the transport, see Chapter 8, “Web services 

transport security” on page 245, which describes in detail the different 

possibilities. With HTTP you may use, for instance, HTTP basic authentication, 

confidentiality with SSL, or confidentiality with client certificate authentication. 

Presumed trust 

If the trust relationship is not created at the Web service message layer level, 

then it is only presumed at the message layer level, and it can be enforced 

outside of the Web service flow itself. 

Trust can be enforced at the network level, for instance. For example, network 

appliances such as firewalls can be used to create a secured zone in which 

servers trust each others. Another example at the network level could be using 

different networks for incoming communication to the intermediary server and for 

outgoing communication to the downstream server. 

6.5.7 Validating identity assertion 

We validate the identity assertion scenario using our application described in 5.6, 





For this scenario we use the secured servlet so that the user has to authenticate 

and provide credentials. We provide the username and password known to the 

Web service client (windowsbax) user registry. This username is valence in our 


Figure 6-61 SecurityInfo application secured servlet display 

The servlet runs, calls the client EJB, makes the Web service call, and displays 

the results. 



Web service provider side (Figure 6-62). 

Figure 6-62 SecurityInfo application identity assertion display 

The display shows that the user did authenticate, as the principal on the Web 

service client side is valence. 

The display shows that the Web services client sent a username security token 

with the asserted identity, as the principal on the Web service provider side is 

valence. 

The Web service client log confirms that the principal is valence, as shown in 

Example 6-10, “Web service requestor server log” on page 206. 



ITSO SecurityCallerBean - Timestamp = Mon Nov 13 10:19:11 EST 2006 



ITSO SecurityCallerBean - Principal = valence 





run, and that the principal is valence, as shown in Example 6-11. 



ITSO SecurityInfoBean - Timestamp = Mon Nov 13 15:19:21 GMT+00:00 2006 



ITSO SecurityInfoBean - Principal = valence 





includes the username security token with the tag only. There 

is no password being transfered. This is indeed an asserted identity. See 

Example 6-12. 

Example 6-12 SOAP/HTTP message from requestor to provider 



... 






< 

wsse:Security soapenv:mustUnderstand="1" 

xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wss 

ecurity-secext-1.0.xsd">valenceITSO1235 

HTTP/1.1 200 OK 



Content-Language: en-US 




ITSO1 

235Mon Nov 13 15:19:21 GMT+00:00 

2006WTSC589.12.4.8va 

lencez/OS01.08.00 

All this validates that identity assertion occurs between the Web service client 

and the Web service provider using WS-Security. 


Chapter 7. Secure Sockets Layer (SSL) 

This chapter provides an overview of SSL changes in WebSphere V6.1 for z/OS 

and how these changes are applied. 


► “Centrally managed SSL” on page 210 

► “WebSphere V6.1 for z/OS SSSL to JSSE changes” on page 213 

► “SSL RACF certificate management” on page 214 

► “Hardware crypto and Java crypto providers” on page 222 

► “IBMJCECCA and IBMJCE characteristics” on page 227 

► “SSL and JCERACFKS keystore” on page 229 

► “Hardware crypto using a JCECCARACFKS keystore” on page 233 

► “SSL troubleshooting and traces” on page 239 

7 


7.1 Introduction 

This section introduces new SSL features, changes, and provides z/OS-specific 

considerations when using SSL. 

7.2 Centrally managed SSL 

In previous versions of WebSphere, every endpoint using SSL required a 

repertoire alias to be configured. Consequently, changing the SSL repertoire 

alias for an endpoint was cumbersome since the user had to know what path to 

take in the admin console to get to a desired endpoint, and getting to the 

endpoint configuration usually involved traversing several screens. 

WebSphere V6.1 provides a new approach to organizing SSL configurations by 

centralizing all SSL configurations on one panel. Additionally, SSL configurations 

can be scoped at the cell (network deployment only), node, server, and endpoint 

level so that an alias is not required for every endpoint. The panel is broken into 

two hierarchies, one tree for inbound endpoints, and one tree for outbound 

endpoints. 


A new WebSphere base installation will have only one SSL configuration defined 

at the node level, as illustrated in Figure 7-1. Select SSL certificate and key 

management → Manage endpoint security configurations. 

Figure 7-1 Centrally managed SSL configuration 

In Figure 7-1, the server and endpoints under the inbound topology inherit their 

SSL configuration NodeDefaultSSLSettings from the node-level SSL 

configuration. Additional SSL configurations can be defined at a lower scope 

overriding the node-level configuration by simply clicking the server or endpoint 

and choosing a new SSL configuration. 

SSL aliases are still supported in WebSphere V6.1, but using centrally managed 

SSL configuration is recommended for ease of management. Application servers 

that are migrated from earlier releases of WebSphere to WebSphere V6.1 still 

use SSL aliases, and the endpoints need to be manually configured to take 

advantage of the centrally managed SSL support. 

Following any of the paths for the endpoints in Table 7-2 on page 214, the 

transport chain can be changed from using an SSL configuration alias specific to 

an endpoint to using the centrally configured SSL configuration. 

Chapter 7. Secure Sockets Layer (SSL) 211

Figure 7-2 shows an example of how the admin console’s SSL inbound channel 

was changed from using an SSL configuration alias to being centrally managed. 

Figure 7-2 Centrally managed SSL endpoint 


7.3 WebSphere V6.1 for z/OS SSSL to JSSE changes 

There have been improvements to the way SSL is configured and managed in 

the admin console in WebSphere V6.1. In previous versions of WebSphere an 

SSL repertoire could be defined as one of two types, either as Java Secure 

Socket Extension (JSSE) or System SSL (SSSL). JSSE and SSL differed in the 

following ways: 

► JSSE 

– Used Java APIs for SSL 

– Defined with path to an HFS Java keystore file 

– Defined with a path to a safkeyring URI 

► SSL (system SSL) 

– Used z/OS set of C/C++ APIs for SSL 

– Defined with z/OS SAF keyring name only 

Certain endpoints were designed to only work with SSSL or JSSE, and each 

endpoint needed to be configured with a repertoire alias. It was important to 

know the location in the admin console for updating the alias of a transport. 

Table 7-1 shows the WebSphere V6.0 SSL type and admin console location for 

specifying a repertoire alias. 

Table 7-1 WebSphere V6.0 endpoint details 

WebSphere V6.0 for z/OS base server 

Endpoint Type Administration console location 

HTTPS SSSL Application servers → server name → 

Web container → HTTP transport → 

Choose SSL transport 

RMI-IIOP CSIV2 SSSL Global security → 

Authentication Protocol → 

CSIv2 inbound/outbound transport 

Daemon SSL SSSL Application servers → server name → 

z/OS location service daemon 

JMX Soap 

Connector 

JSSE Application servers → server name → 

Administration Services → JMX connectors → 

SOAPConnector → Custom Properties → sslConfig 

In WebSphere V6.1, all endpoints with the exception of the daemon use JSSE as 

the SSL type. The daemon is a lightweight address space that uses system SSL 

because the address space does not run with a JVM. All other endpoints are 

used in a WebSphere control regions that run with a JVM. 


Table 7-2 shows the WebSphere V6.1 equivalent location for specifying an SSL 

configuration for various endpoints, and the endpoints that were converted to 

JSSE. 

Table 7-2 WebSphere V6.1 endpoint details 

WebSphere V6.1 for z/OS base server 

Endpoint Type Central/alias Administration console location 

HTTPS JSSE Centrally 

configured 

(preferred) 

RMI-IIOP 

CSIV2 

Daemon 

SSL 

JMX Soap 

Connectors 

7.4 SSL RACF certificate management 

SSL certificate and key management → 

Manage endpoint security 

configurations 

Alias Application servers → server name → 

Web container → 

z/OS additional settings → 

Web container transport chains → 

Choose SSL enabled transport 

SSL inbound channel (SSL_2) 

JSSE Centrally 

configured 

(preferred) 




Alias Secure administration, 

applications, and infrastructure → 

RMI/IIOP security → 

CSIv2 inbound/outbound transport 

SSSL Not Centrally 

configured 

See Alias 


z/OS location service daemon 

JSSE Centrally 

configured 

(preferred) 





Administration Services → 

JMX connectors → SOAPConnector → 

Custom Properties > sslConfig 

The WebSphere V6.1 for z/OS admin console has a new facility for managing 

certificates similar to the ikeyman utility provided with the WebSphere distributed 


platforms. For certificates stored in the HFS keystore and trustore files, full 

management of the certificates can be done from the admin console. 

For certificates stored in RACF, the keystores are read only, meaning that 

certificates cannot be added, deleted, received, or imported. These operations 

need to be performed by the RACF administrator. However, it is possible to view 

the certificates and monitor their expirations in the administrative console. 

This section shows how to perform certain administrative tasks with safkeyrings 

and are supplemented with sample RACF commands. The tasks include 

viewing, importing, exporting, and deleting certificates. For more details about 

the RACF commands, see Security Server RACF Command Language 

Reference, SA22-7687, which provides a complete list of RACF security 

commands and options. 

7.4.1 Viewing certificates 

The WebSphere administrative console has the facility for viewing the signer 

certificate and personal certificate for a keystore configured with a safkeyring 

URI that uses a keystore type of JCERACFKS. 


The following path can be used to locate the signer certificates and personal 

certificates in the WebSphere admin console: SSL certificate and key 

management → Key stores and certificates → NodeDefaultKeyStore 

(Figure 7-3). 

Figure 7-3 Viewing signer certificate and personal certificate in the admin console 


Important certificate information such as issuer, issued by, and validity period 

can be obtained for a signer certificate or personal certificate. The certificate 

information obtained from the administrative console can be useful for 

diagnosing problems related to SSL and for confirming that the application server 

is able to access the certificates for a particular keyring. See Figure 7-4. 

Figure 7-4 Example of signer certificates details 

When adding or deleting a signer certificate or personal certificate to or from a 

keyring in RACF, the application server or deployment manager may need to be 

recycled in order to view the certificate in the administration console. 


The following RACF commands are provided to show how to obtain 

corresponding certificate information that is displayed in the admin console. 

► View a list of certificates on a keyring for a user ID: 

RACDCERT LISTRING(ring-name) ID(userid) 

► View certificate authority information: 

RACDCERT CERTAUTH LIST(LABEL('certificate_authority_label')) 

► View personal certificate information for a user ID: 

RACDCERT LIST (label('personal_certificate_label')) ID(userid) 

7.4.2 Monitoring certificate expiration 

WebSphere V6.1 provides a certificate expiration monitoring task that cycles 

through all the keystores in the security.xml file to check for expired certificates. 

The cycle can be specified by the day of the week, or by a certain number of 

days, and a notification can be provided as a message in the message log, or as 

an e-mail. For e-mail notification, a Simple Mail Transfer Protocol (SMTP) server 

address needs to be specified with a recipient’s e-mail address. The WebSphere 

Application Server issues an expiration warning before expiration based on the 

number of days specified in the Expiration notification threshold field. 

The admin console path to manage certificate expiration is SSL certificate and 

key management → Key stores and certificates → Manage certificate 

expiration. 


Figure 7-5 illustrates the options for managing certificate expiration. 

Figure 7-5 Certificate management expiration panel 

The options for “Automatically replace expiring self-signed certificates” and 

“Delete expiring certificates and signers after replacement” are not applicable to 

certificates stored in RACF. More information is provided in the Information 

Center at: 


com.ibm.websphere.zseries.doc/info/zseries/ae/csec_sslcertmonitoring. 

html 


7.4.3 Importing certificates 

The import operation in the admin console is applicable to file-based keystore 

types. SAF-based keystore types are read only, and the following commands are 

provided to show how to import a certificate from an HFS file into a keyring: 

► Copy the certificate to a data set from an HFS file: 

OGET '/tmp/certificate.cer' DSN.NAME binary convert(no) 

► Add the certificate from the data set to RACF with a label: 

RACDCERT ADD(DSN.NAME) withlabel('certificate_label') 

7.4.4 Exporting certificates 

RACF commands can be used to export a certificate from a keyring to a data set, 

and then the data set can be placed into the HFS as a file to be used on other 

systems. 

The following RACF commands and steps are provided to show an example of 

how to export a signer certificate or personal certificate into an HFS file to be 

transferred to another system: 

► Exporting a signer certificate to an HFS file: 

RACDCERT ID(userid) CERTAUTH 

EXPORT(LABEL('certificate_authority_label')) DSN(CA.DSN.NAME) 

FORMAT(CERTDER) 

Once the certificate is exported to a data set in DER format, the data set can 

be moved to an HFS file with the following command: 

OPUT CA.DSN.NAME '/tmp/ca.crt' binary convert(no) 

► Exporting a personal certificate to an HFS file: 

RACDCERT ID(userid) EXPORT(LABEL('personal_certificate_label')) 

DSN(PS.DSN.NAME) FORMAT(PKCS12DER) PASSWORD('XXXX') 

Once the certificate is exported to a data set in PKCS12 format, the data set 

can be moved to an HFS file with the following command: 

OPUT PS.DSN.NAME '/tmp/personal.p12' binary convert(no) 

Important: While the CERTDER and CERTB64 keywords indicate to export 

only a certificate, the PKCS12DER and PKCS12B64 keywords export the 

certificate and the private key (which must exist and not be an ICSF key). 

Care should be taken when specifying the format to not mistakenly export a 

private key with the PKCS12 format when the intent is to export the signer 

certificate only. 


Table 7-3 shows the available formats that the WebSphere administration 

console can import from a file. 

Table 7-3 Export formats for certificates 

Format Description 

CERTB64 Specifies X.509 certificate and public key that has been encoded 

using Base64. This format can be transferred in ASCII. 

CERTDER Specifies encoded X.509 certificate and public key encoded in 

binary DER format. This format should be transferred in binary. 

PKCS12B64 Specifies a PKCS #12 package that has been encoded using 

Base64. This format may not be compatible with non-IBM 

applications, and should be transferred in ASCII. 

PKCS12DER Specifies a PKCS #12 package encoded using binary DER 

format. This format should be transferred in binary. 

The signer certificate or personal certificate can then be transferred from an HFS 

file to a client in binary using FTP. 

8.2, “Integrity with SSL” on page 252 shows one example of using the RACF 

commands to export a certificate to an HFS file, and 6.4, “Confidentiality with 

XML encryption” on page 164 shows how to export a certificate from the 

administration console to an HFS file. 

7.4.5 Deleting certificates 

The delete operation in the admin console is applicable to file-based keystore 

types. SAF-based keystore types are read only, and the following RACF 

commands are provided for removing a certificate from a keyring, removing a 

keyring, and deleting certificates for a user ID: 

► Remove a CA signer certificate from a keyring: 

RACDCERT REMOVE(CERTAUTH LABEL('certificate_authority_label') 

RING(ring-name)) ID(userid)) 

► Remove a personal certificate from a keyring: 

RACDCERT REMOVE(LABEL('personal_certificate_label') RING(ring-name)) 

ID(userid) 

► Delete the keyring: 

RACDCERT DELRING(ring-name) ID(userid) 


► Delete a CA signer certificate: 

RACDCERT CERTAUTH DELETE(LABEL('certificate_authority_label')) 

► Delete a personal certificate: 

RACDCERT DELETE(LABEL('personal_certificate_label')) ID(userid) 

7.4.6 Deleting keystores and truststores 

Keystores and truststores can be deleted if no SSL configurations are 

referencing them. This applies to keystores with paths to HFS files or safkeyring 

URIs. The following example error message (Figure 7-6) appears when 

attempting to delete a keystore or truststore that is still being used by an SSL 


Figure 7-6 Error received when deleting a keystore defined in an SSL configuration 

To resolve this issue, delete the SSL configuration that has this keystore 

specified first before deleting the keystore. 

7.5 Hardware crypto and Java crypto providers 

The Java Cryptography Extension (JCE) is a set of Java packages that provides 

a framework and implementations for encryption, key generation, key 

agreement, and Message Authentication Code (MAC) algorithms. Support for 

encryption includes symmetric, asymmetric, block, and stream ciphers. JCE is a 

pluggable framework that allows other providers (security packages) signed by a 

trusted entity to be plugged into the JCE framework, allowing new algorithms to 

be added seamlessly. 

Vendors such as SUN and IBM provide their implementations of JCE. The IBM 

version of the Java Cryptography Extension (IBMJCE) is an implementation of 

the JCE cryptographic service provider compatible in z/OS environments. The 

IBMJCE is similar to SunJCE with a few differences. IBMJCE has a different 

package naming convention, it offers more algorithms, and it supports 

z/OS-specific keystores. 

The IBMJCECCA is an extension to IBMJCE in that it adds the capability to use 

hardware cryptography through IBM Common Cryptographic Architecture (CCA) 


interfaces. IBMJCECCA provides secure, high-speed cryptographic services on 

various platforms through hardware cryptographic devices. 

The IBMJCECCA provider is new in Java 1.5, which ships as part of WebSphere 

V6.1. Previous WebSphere configurations running with Java 1.4.2 may have 

been accessing keys stored in hardware using the IBMJCE4758 provider. The 

IBMJCECCA provider extends and replaces the IBMJCE4758 provider from 

earlier releases. At this time, the IBMJCECCA provider and the IBMJCE4758 

provider are functionally equivalent. 

To use IBMJCECCA, the following are required: 

► A system at the z/OS V1R6 level or later with one of the following: 

– On a z800 or z900 processor, a CCF and a PCICC card 

– On a z890 or z990 processor, a CPACF and a PCIXCC card 

– On a z890 or z990 processor, a CPACF and a CEX2C card 

– On a z9-109 processor, a CPACF and a CEX2C or CEX2A card 

► ICSF must be running. 

There are a variety of other security providers that can be used with the JCE 

architecture. The focus of this section is on the IBMJCE and IBMJCECCA 

providers in a WebSphere 6.1 z/OS environment. 

7.5.1 Choosing a JCE provider 

A JCE provider is a Java package or set of Java packages that supply a 

concrete implementation of a subset of cryptography aspects of the Java security 

API. The provider is typically packaged in a jar file, and placed on the classpath 

to be used by the Java Virtual Machine (JVM) during startup. The providers that 

the JVM use are listed in a java.security file located in the HFS, and are 

instantiated when the JVM starts. Beginning with WebSphere V6.0 for z/OS, the 

JVM is now shipped as part of WebSphere. For WebSphere V6.1 for z/OS the 

provider jars and java.security file can be found in: 

► /java/lib/security (location of java.security file) 

► /java/lib (location of provider jars) 

Where is the location of the WebSphere configuration HFS. 


Example 7-1 shows a list of providers in the java.security file. IBMJCECCA and 

IBMJCEFIPS are commented out in this sample. The providers are listed in order 

by preference, and the first provider IBMJCE is used as the default provider. 

Example 7-1 Providers listed by preference 

# List of providers and their preference orders (see above): 

# 

#security.provider.1=com.ibm.crypto.hdwrCCA.provider.IBMJCECCA 

#security.provider.1=com.ibm.crypto.fips.provider.IBMJCEFIPS 

security.provider.1=com.ibm.crypto.provider.IBMJCE 

security.provider.2=com.ibm.jsse.IBMJSSEProvider 

security.provider.3=com.ibm.jsse2.IBMJSSEProvider2 

security.provider.4=com.ibm.security.jgss.IBMJGSSProvider 

security.provider.5=com.ibm.security.cert.IBMCertPath 

security.provider.6=com.ibm.security.sasl.IBMSASL 

security.provider.7=com.ibm.security.cmskeystore.CMSProvider 

security.provider.8=com.ibm.security.jgss.mech.spnego.IBMSPNEGO 

A new default provider can be chosen by setting the provider name as the first in 

the list and saving the file. WebSphere needs to be restarted to pick up any 

changes made to the java.security file. 

7.5.2 Admin console keystore types 

In previous versions of WebSphere, the keystore types available were only those 

programmed into the admin console. In WebSphere V6.1, the admin console 

dynamically builds its list of available keystore types based on the providers 

listed in the java.security file. The java.security file is read during server startup, 

and any changes to the java.security file require the application server to be 

restarted. 

In Example 7-2 the java.security file was modified to have only the IBMJCE 

provider. 

Example 7-2 Modified file 


# 

security.provider.1=com.ibm.crypto.hdwrCCA.provider.IBMJCE 


Figure 7-7 illustrates only the keystore types available for the IBMJCE provider. 

The keystore types are listed as: 

► PKCS12 

► JCERACFKS 

► JCEKS 

► JKS 

► PKCS11 

Figure 7-7 Keystore types from the IBMJCE provider 

In Example 7-3, the java.security provider was modified to include an additional 

hardware cryptography provider IBMJCECCA. 

Example 7-3 java.security file 


# 

security.provider.1=com.ibm.crypto.hdwrCCA.provider.IBMJCECCA 



Upon restarting the application server and attempting to create a new keystore, 

the admin console presents additional keystore types JCECCARACFKS and 

JCECCAKS as a result of adding the IBMJCECCA provider to the front of the list. 

Figure 7-8 shows the additions to the keystore list. Select SSL certificate and 

key management → Key stores and certificates → New. 

Figure 7-8 Keystore types from the IBMJCECCA and IBMCE providers 

When using the IBMJCECCA hardware cryptography provider, the unrestricted 

jar files need to be installed on the WebSphere system, and the ICSF address 

space must be up and running prior to starting WebSphere. 

7.5.3 Keystores and truststores 

The keystore is a database that can contain public and private keys. In 

WebSphere the public keys are stored as signer certificates, while private keys 

are stored in personal certificates. The keys are used for a variety of purposes, 

including authentication and data integrity. 


A truststore is a type of keystore whose database contains one or more 

certificates that are trusted belonging to another party. In WebSphere a trusted 

certificate and public key are stored as a signer certificate. The certificates are 

considered trusted because the truststore owner trusts that the public key in the 

certificate belongs to the identity identified by the subject of the certificate. The 

public key certificate can be used to confirm that a person is really who she 

claims to be, and that data really came from that person. In general terms, 

truststores and keystores are often referred to as keystores. 

7.6 IBMJCECCA and IBMJCE characteristics 

Table 7-4 JCE Characteristics 

Provider 

name 

IBMJCECCA 

IBMJCE 

In WebSphere, on distributed systems, the certificates in a keystore are usually 

stored in a file. In WebSphere V6.1 for z/OS, the certificates in a keystore can be 

stored in a file, or in the SAF database. The actual public/private keys for the 

corresponding certificates can be stored in a file, in a SAF database, or in 

hardware, depending on the provider and keystore being used. The IBMJCE and 

IBMJCECCA provider support various keystore types that can be selected 

depending on the use of the location of certificates and keys. 

Table 7-4 describes the characteristics between the IBMJCE and IBMJCECCA 

providers based on the keystore types. 

Keystore 

type 

JKS 

JCEKS 

PKCS12 

IBMJCE JKS 

JCEKS 

PKCS12 

Certificate 

location 

Key 

location 

File File 

system 

Use 

HW 

WebSphere 

path 

Tooling 

Yes path/file WAS 

ikeyman 

keytool 

JCECCARACFKS RACF Hardware Yes safkeyring:/// 

safkeyringhw:/// 

RACF 

JCECCAKS File Hardware Yes path/file hwkeytool 

File File 

system 

No path/file WAS 

ikeyman 

keytool 

JCERACFKS RACF RACF No safkeyring:/// RACF 

The Use HW column indicates that hardware is used for SSL acceleration. 


Note: To use hardware cryptography, both the IBMJCECCA and IBMJCE 

providers need to be listed in the java.security file with the IBMJCECCA listed 

first. 7.8.3, “Update the java.security file with the IBMJCECCA provider” on 

page 236, provides an example on how to do this. 

Note: RACF is used in explaining the acronyms in “Keystore descriptions” on 

page 228. The security product RACF in Table 7-4 can be replaced with other 

security products accessible with SAF interfaces (that is, Top Secret and 

ACF2). 

Keystore descriptions 

A description of each of the keystore types from Table 7-4 on page 227 is 

provided: 

► JKS (Java KeyStore file) 

This is a traditional file-based keystore format available with the standard 

JDK. Files based on this format are usually stored with a .jks extension. 

Use this option if the keystore file is stored in JKS format. 

► JCEKS (Java Cryptography Extension Keystore) 

This is a file-based keystore implementation of the Java Cryptography 

Extensions provider. Files based on this format are usually stored with a 

*.jceks extension. 

Use this option if the keystore file is stored in JCEKS format. 

► PKCS12KS (Public Key Cryptography Standards version 12 Keystore) 

This is a file format commonly used to store private keys with accompanying 

public key certificates protected with a password-based symmetric key. Files 

based on this format are usually stored with a .p12 extension. 

Use this option if your keystore uses the PKCS#12 file format. 

► JCERACFKS (JCE RACF Keystore) 

This is the keystore used in which certificates are stored in a SAF keyring and 

the keys stored in RACF. 

► JCECCARACFKS (JCE Common Crytpographic Architecture RACF 

Keystore) 

This is the keystore used for certificates that are stored in a SAF keyring, and 

the keys can be stored in RACF, or stored in hardware, and are ICSF 

managed. 


► JCECCAKS (JCE Common Crytpographic Architecture Keystore) 

A file-based keystore where certificates are stored in a file, but the keys are in 

hardware managed with hwkeytool utility. 

► PKCS11KS (Public Key Cryptography Standards version 11 Keystore) 

This option is not currently supported on WebSphere V6.1 for z/OS. 

To better understand how to use certificates that are stored in RACF, see 7.7, 

“SSL and JCERACFKS keystore” on page 229 and 7.8, “Hardware crypto using 

a JCECCARACFKS keystore” on page 233, which provide two examples that 

step through setting up and accessing certificates in RACF with a safkeyring 

URI. 

7.7 SSL and JCERACFKS keystore 

This example demonstrates creating a signer certificate and a personal 

certificate, attaching them to a keyring, and configuring the admin console to use 

that keyring. This example assumes that the provider is set to the default 

IBMJCE and that the keys are managed in software. 

7.7.1 Keyring and certificate setup 

This example creates a new signer certificate and personal certificate, and 

connects these certificates to a keyring using the RACF commands provided. 

1. Generate a signer certificate labeled TESTCA: 

RACDCERT CERTAUTH GENCERT SUBJECTSDN(CN('TEST CertAuth') OU('IBM')) 

WITHLABEL('TESTCA') 

2. Create a personal certificate signed by TESTCA: 

RACDCERT ID (ASCR1) GENCERT SUBJECTSDN(CN('wtsc58.itso.ibm.com') 

O('IBM')) WITHLABEL('TESTPersonal') SIGNWITH(CERTAUTH 

LABEL('TESTCA')) TRUST 

3. Create a ring called WASKeyring.TEST for the control region’s user ID: 

RACDCERT ADDRING(WASKeyring.TEST) ID(ASCR1) 

4. Connect the TESTCA to the ring WASKeyring.TEST: 

RACDCERT ID(ASCR1) CONNECT (RING(WASKeyring.TEST) LABEL('TESTCA') 

CERTAUTH) 


5. Connect the personal certificate to WASKeyring.TEST: 

RACDCERT ID(ASCR1) CONNECT (LABEL('TESTPersonal') 

RING(WASKeyring.TEST) DEFAULT) 

7.7.2 WebSphere admin console setup 

In the WebSphere for z/OS administration, create a new key store by selecting 

SSL certificate and key management → Key stores and certificates → New. 

► Name: JCERACFKS KeyStore 

► Path: safkeyring:///WASKeyring.TEST 

► Password: password 

► Confirm password: password 

► Type: JCERACFKS 

► Check the Read Only check box. 

Then click Apply and then save the changes. 

The admin console’s panel is set up to accommodate file-based and SAF-based 

keystore types. File-based keystores are normally protected with a password 

when the keystore database is first created, and the admin console needs to 

have this password specified to access a file-based keystore. For certificates 

stored in RACF, the certificates are protected by the access granted to the user 

by the RACF administrator. JSSE still requires that a password to be specified as 

password to access a SAF keystore, although the certificates are protected by 

the user ID’s access privileges in the RACF database. The certificates in RACF 

will not be accessible unless the password is specified as password. 

The Read Only check box is checked since SAF keystores are read only. 


Figure 7-9 shows the options chosen in the admin console when setting up the 

keystore. 

Figure 7-9 Creating a JSSE configuration using a safkeyring URI 

Important: The admin console stores the exact string that you type for the 

safkeyring URI in the security.xml file in the HFS. Be sure not to add any 

trailing spaces when specifying the safkeyring URI, otherwise you will not be 

able to view or access your certificates in RACF. The port configured with this 

SSL configuration will not work correctly. 

For safkeyring URIs, the admin console only confirms that the Change 

password entry and the Confirm password entry match. It does not verify that 

the password should be password, which is the valid password that can be 

used to access certificates using a safkeyring URI. 

If the keyring is set up correctly in RACF, the signer certificate or personal 

certificate connected to the user ID for the control region address space can be 

viewed by clicking either signer certificates or personal certificates for that 

keystore. 


Figure 7-10 shows the output of the signer certificate for WASKeyring.TEST 

created for this example. 

Figure 7-10 Signer certificate information from admin console 


Figure 7-11 shows the output of the personal certificate for WASKeyring.TEST 

created for this example. 

Figure 7-11 Personal certificate information from admin console 

7.8 Hardware crypto using a JCECCARACFKS keystore 

This example demonstrates creating a signer certificate and personal certificate 

with the keys in hardware, and the setup needed in the admin console to use 

these certificates. This example assumes that the default provider is set to 

IBMJCECCA, and that ICSF is currently running. 

The steps for this exercise can be summarized as: 

1. Create the certificates in RACF with keys in hardware. 

2. Install unrestricted policy jars in WebSphere. 

3. Update the java.policy file with the IBMJCECCA provider. 

4. Create a keystore in the administration console. 


7.8.1 Keyring and certificate setup with keys in hardware 

To set this up: 

1. Create a new signer certificate called HDCA with its key in hardware: 

RACDCERT CERTAUTH GENCERT SUBJECTSDN(CN('HDwtsc58.itso.ibm.com') 

OU('IBM')) WITHLABEL('HDCA') TRUST ICSF 

2. Create a new keyring called WASKeyring.HD for the control user ID ASCR1 

and servant user ID ASSR1: 

RACDCERT ADDRING(WASKeyring.HD) ID(ASCR1) 

RACDCERT ADDRING(WASKeyring.HD) ID(ASSR1) 

3. Connect the signer certificate HDCA to WASKeyring.HD for ASCR1 and 

ASSR1: 

RACDCERT ID(ASCR1) CONNECT (RING(WASKeyring.HD) LABEL('HDCA') 

CERTAUTH) 

RACDCERT ID(ASSR1) CONNECT (RING(WASKeyring.HD) LABEL('HDCA') 

CERTAUTH) 

4. Create a new personal certificate HDPersonal signed by HDCA with its key in 

hardware: 

RACDCERT ID (ASCR1) GENCERT SUBJECTSDN(CN('HDPersonal') O('IBM')) 

WITHLABEL('HDPersonal') SIGNWITH(CERTAUTH LABEL('HDCA')) TRUST ICSF 

5. Connect the new personal certificate to the control region’s keyring: 

RACDCERT ID(ASCR1) CONNECT (LABEL('HDPersonal') RING(WASKeyring.HD) 

DEFAULT) 

The commands in step 3 connect the HDCA signer certificate to both the control 

and servant region keyrings. It may not be necessary to connect the signer 

certificate to the servant region keyring depending on the endpoint for SSL 

communication, but it is done in this step so that the signer certificate can be 

viewed in the administration console. 

The creation of the certificates is appended with the ICSF keyword, which 

indicates that RACF should attempt to store the private key associated with this 

certificate in the ICSF PKDS. 


Example 7-4 shows a display of the signer certificate information: 

RACDCERT CERTAUTH LIST(LABEL('HDCA')) 

Example 7-4 Signer certificate HDCA information 

Digital certificate information for CERTAUTH: 

Label: HDCA 

Certificate ID: 2QiJmZmDhZmjgcjEw8FA 

Status: TRUST 

Start Date: 2006/12/04 00:00:00 

End Date: 2007/12/04 23:59:59 

Serial Number: 

>00< 

Issuer's Name: 

>CN=HDwtsc58.itso.ibm.com.OU=IBM< 

Subject's Name: 


Key Usage: CERTSIGN 

Private Key Type: ICSF 

Private Key Size: 1024 

PKDS Label: IRR.DIGTCERT.CERTIFAUTH.SC58.BFCDC999793165CE 

Ring Associations: 

Ring Owner: ASCR1 

Ring: 

>WASKeyring.HD< 

Ring Owner: ASSR1 

Ring: 


Example 7-5 shows a display of the personal certificate information: 

RACDCERT LIST (label('HDPersonal')) ID(ASCR1) 

Example 7-5 HDPersonal certificate information 

Digital certificate information for user ASCR1: 

Label: HDPersonal 

Certificate ID: 2QXB4sPZ8cjE14WZopaVgZNA 

Status: TRUST 

Start Date: 2006/12/04 00:00:00 

End Date: 2007/12/04 23:59:59 


>01< 



CN=HDwtsc58.itso.ibm.com.OU=IBM< 


>CN=HDPersonal.O=IBM< 



PKDS Label: IRR.DIGTCERT.ASCR1.SC58.BFCDCD6AB6371A8E 



Ring: 


7.8.2 Installing the unrestricted Java policy jars 

The WebSphere JVM ships with policy jars that provide only limited function 

cryptography. Certain countries have restrictions on the import, re-export, 

possession, and use of encryption software. To use the IBMJCECCA provider 

with hardware, the unrestricted policy jars that provide full function cryptography 

need to be downloaded and installed in WebSphere. 

To obtain the Java unrestricted policy jars and place them on the WebSphere 

z/OS system: 

1. Obtain the unrestricted policy jars from: 

http://www.ibm.com/developerworks/java/jdk/security/index.html 

2. Make a backup of the original restricted local_policy.jar and 

US_export_policy.jar. 

3. Download the unrestricted local_policy.jar and US_export_policy.jar to your 

WebSphere z/OS system in /AppServer/java/lib/security. 

4. After copying the local_policy.jar and US_export_policy.jar, change the 

permissions so that the control and servant region address spaces can 

access the jar files: 

– chmod 644 local_policy.jar 

– chmod 644 US_export_policy.jar 

7.8.3 Update the java.security file with the IBMJCECCA provider 

The java.security file located in the WebSphere HFS needs to be updated with 

the IBMJCECCA provider as the first provider in the list of providers. The 

java.security file is in ASCII, so it may be necessary to convert the file to EBCDIC 

first before making changes. 


Example 7-6 illustrates the addition made to the java.security file. 

Example 7-6 Updating the java.security file for IBMJCECCA 




security.provider.3=com.ibm.jsse.IBMJSSEProvider2 

security.provider.4=com.ibm.jsse2.IBMJSSEProvider 






7.8.4 Admin console setup 

In the WebSphere for z/OS admin console, create a new key store by selecting 

SSL certificate and key management → Key stores and certificates → New. 

► Name: JCECCARACFKS KeyStore 

► Path: safkeyringhw:///WASKeyring.HD 

► Password: password 


► Type: JCECCARACFKS 

► Check the Read Only check box. 

Then click Apply and then save the changes. 

The safkeyring URI needs to be specified as safkeyringhw to indicate that the 

keys for the certificates in the keyring are stored in hardware. Avoid trailing 

spaces after the safkeyringhw URI. The password for accessing certificates in 

RACF is password. 

When setting up the certificates, the HDCA certificate was connected to both the 

control region and servant region user ID so that the certificate information can 

be viewed in the admin console. 


Figure 7-12 shows the options chosen in the administrative console when setting 

up the keystore. 

Figure 7-12 Creating a JSSE configuration using a safkeyring URI 


Figure 7-13 shows the signer certificate information for keyring WASKeyring.HD. 

Figure 7-13 Signer certificate HDCA information 

7.9 SSL troubleshooting and traces 

SSL handshake errors are one of the most common problems that can surface 

when attempting to set up secure communications in WebSphere. This section 

provides diagnostic steps that can be performed to identify an incorrect SSL 

setup, and the types of traces to gather to diagnose them, and common 

problems. 


7.9.1 Diagnostic steps 

When attempting to diagnose SSL handshake issues the following steps can be 

taken to identify what is causing the problem: 

1. Identify the endpoints for the SSL communication. It is important to determine 

who is the SSL client (client initiating the SSL handshake) and who is the SSL 

server (the receiving party in the SSL handshake attempt). This is sometimes 

not that obvious, as the SSL client can be a distributed J2EE client or thin 

client, a Web browser, a WebSphere distributed process, or a z/OS 

Deployment Manager or Application server control or servant region address 

space. The SSL server is usually a WebSphere on distributed process or 

WebSphere on z/OS control region. 

2. Determine the SSL configuration for the SSL client and SSL server. SSL 

handshake issues occur between two endpoints, and the SSL handshake 

error usually surfaces in the job output or error log of the client. 

If the SSL client or server is on z/OS, obtain the user ID of the address space 

or process. A keyring that contains the certificates is associated with the user 

ID. Knowledge of the certificates attached to those keyrings can be used to 

identify where the setup may be incorrect. 

If the SSL client or server is on distributed, it is necessary to obtain the SSL 

configuration (keystore, truststore, and certificates). 

A list of example scenarios is provided to demonstrate where to obtain the 

SSL configuration for client and server: 

– SSL handshake issue that occurs during synchronization between the 

deployment manager and node agent: 

Deployment manager control region user ID 

Node agent control region user ID 

– SSL handshake issue attempting to connect to the admin console: 

SSL configuration of off-platform Web browser 

Deployment manager control region user ID (network deployment) or 

application server control region user ID (base configuration) 

– SSL handshake issues when attempting to connect to a Web application: 

SSL configuration of off-platform Web browser 

Application server control region user ID 


7.9.2 SSL traces 

– SSL handshake issues when using HFS clients (that is, wsadmin.sh, 

syncNode.sh, launchClient.sh, and so on) 

User ID executing the client on z/OS 

User ID of admin console it is running in (either the user ID of the 

deployment manager control region (network deployment) or the user 

ID of the application control region user ID (base)) 

3. For a z/OS client or server, display the certificates on the keyring associated 

with the user ID and provide the certificate details for the signer certificate and 

personal certificate (if there is one). The SSL commands to display the 

certificate information are provided in “Viewing certificates” on page 215 

For the distributed client or server, display the certificate information for the 

signer certificate and personal certificate (if there is one) using the admin 

console SSL management, or ikeyman utility. 

4. From the displayed information check the validity period for the signer 

certificate on the SSL client side and SSL server side. Verify that the current 

date falls within the start date and end date for the certificates. The 

certificate’s start date should precede the current date and not be expired. 

5. From the displayed information, confirm that the SSL client’s truststore 

contains the signer certificate of the server. Verify that the issuer’s 

distinguished name and subject distinguished name for the server’s signer 

certificate on the SSL client side matches that the server personal certificate 

on the SSL server side. 

When SSL errors surface, and analyzing the certificates, keyrings, and 

WebSphere setup does not provide enough information to diagnose the problem, 

SSL traces can be enabled in either the WebSphere admin console or in the 

JVM. 

WebSphere SSL trace 

When diagnosing WebSphere SSL problems, SSL traces can be enabled in 

WebSphere and in the JVM. 

Follow the path in the admin console in WebSphere: Logging and Tracing > 

servername → Change Log Detail Levels. Click the Configuration tab and 

add the WebSphere trace specification: 

SSL=all 


7.9.3 Common errors 

The WebSphere trace can also be turned on dynamically from the MVS console 

using command: 

F control_region,TRACEJAVA=’SSL=all’ 

Reset the trace to the original trace specification at startup with: 

F control_region,TRACEINIT 

Java JSSE trace 

To enable diagnostic trace for determining the cause of SSL handshake errors 

follow the path in the admin console to Application servers → server_name → 

Process Definition → Control/Servant → Java Virtual Machine. 

In the Generic JVM Arguments field add: 

-Djavax.net.debug=true -Djava.security.auth.debug=all 

The Java trace setting cannot be enabled dynamically and requires the 

application server to be restarted to pick up the change. 

The following section includes some common errors that can occur when 

attempting SSL handshake communication. The examples provide the cause of 

the problem that resulted in the error message. 

► Example error when signer certificate is missing from a client’s truststore in 

order to create attempt an SSL handshake. This type of error surfaces on the 

client initiating the SSL handshake: 

CWPKI0022E: SSL HANDSHAKE FAILURE: A signer with SubjectDN 

"CN=wtsc58.itso.ibm.com, OU=SC58, O=IBM" was sent from target 

host:port "*:9044". The signer may need to be added to local trust 

store 

"C:/Program1/IBM/WebSphere/AppServer/profiles/AppSrv01/config/cells/ 

Node02Cell/nodes/Node02/trust.p12" located in SSL configuration 

alias "NodeDefaultSSLSettings" loaded from SSL configuration file 

"security.xml". The extended error message from the SSL handshake 

exception is: "No trusted certificate found". 

► The error text shows a problem that can occur using the IBMJCECCA 

provider with safkeyring URI. The ICSF address space has become 

unavailable while a user is attempting to access the admin console or 

application. 

Message: BBOO0220E: SSLC0008E: Unable to initialize SSL connection. 

Unauthorized access was denied or security settings have expired. 


Exception is javax.net.ssl.SSLHandshakeException: Client requested 

protocol Unknown 0.2 not enabled or not supported. 

com.ibm.ws.ssl.channel.impl.SSLHandshakeErrorTracker 

► The error text shows a problem while starting WebSphere using the 

IBMJCECCA provider, but with the ICSF address space not running: 

java.lang.RuntimeException: Hardware error from call CSNBOWH 

returnCode 12 reasonCode 0 

com.ibm.crypto.hdwrCCA.provider.SHA.a(Unknown Source) 

com.ibm.crypto.hdwrCCA.provider.SHA.engineDigest(Unknown Source) 

java.security.MessageDigest$Delegate.engineDigest(MessageDigest.java 

:554) 

java.security.MessageDigest.digest(MessageDigest.java:332) 

com.ibm.ws.management.repository.DocumentDigestImpl.calc(DocumentDig 

estImpljava:128) 

com.ibm.ws.management.repository.FileDocument.calcDigest(FileDocumen 

t.java:212) 



Chapter 8. Web services transport 

security 

Web services security can be addressed at both the transport level and the 

message level. In this chapter we focus on the transport level security features 

for Web services. 

The following examples are provided here: 

► “Authentication with HTTP” on page 246 

► “Integrity with SSL” on page 252 

► “Confidentiality with SSL” on page 268 

► “Confidentiality with SSL using hardware crypto” on page 272 

► “Confidentiality and basic authentication” on page 282 

► “Confidentiality and client certificate authentication” on page 282 

8 


8.1 Authentication with HTTP 

Basic authentication can be enabled for a Web service in the application server 

at the transport level by specifying BASIC in the Web deployment descriptor. 

When basic authentication is enabled, the client needs to specify a user name 

and password that will be passed in the header when calling the Web services 

protected URL. The user name and password are sent over the network 

unencrypted using the HTTP protocol. The user name and password are also 

sent with each subsequent request. Since HTTP communication is not 

encrypted, the user name and password are visible and can be intercepted. To 

protect the user name and password from being sent over the network, basic 

authentication is usually performed over an encrypted transport through the use 

of Secure Sockets Layer (SSL). 

8.1.1 HTTP basic authentication scenario description 

On the client side, a user invokes a servlet from a static Web page running in the 

WebSphere distributed system. The servlet invokes a Web service enabled EJB 

that has its Web service client descriptor configured with a user name and 

password. The user name and password flow in the HTTP header to the Web 

service provider. The Web service provider extracts the user ID and password to 

authenticate the Web service requestor. 

Figure 8-1 illustrates the HTTP basic authentication scenario. 

Figure 8-1 Web service transport security HTTP basic authentication scenario 

In this scenario, we demonstrate how the client SecureCaller EJB can provide a 

user name and password to authenticate to the SecureInfo EJB that is Web 


service enabled. An authentication method of BASIC is specified in the 

SecurityInfoRouterWS deployment descriptor. The user name and password are 

specified in a Web service client binding, as opposed to specifying them 

programmatically in the code. The transport does not have SSL enabled. 

8.1.2 Configuring the z/OS Web service provider with authentication 

The process for configuring transport-level basic authentication for a Web 

service is similar to configuring transport-level basic authentication for a Web 

application. The Web service endpoint resides in a WAR file, and can be 

configured using the Web deployment descriptor editor. 

1. In the J2EE perspective, traverse the tree under Dynamic Web Projects, and 

open the deployment descriptor for the SecurityInfoRouterWS. 

2. Select the Security tab. Under Security Roles, add a role named 

SecureCustomer. 

3. Under Security Constraints, add a security constraint named 

SecureConstraint. 

– Set Resource Name to Secure Web Resource. 

– Select the check box for “GET, and POST” HTTP Methods. 

– Add the pattern /*. 

4. Under Authorized Roles, add SecureCustomer. 

5. Select the Pages tab. Under Authentication Method, select BASIC and 

provide the realm name SecurityInfo Realm. 

In Example 8-1, the XML code shows how the security-constraint, 

login-config, and security role were setup in the web.xml. 

Example 8-1 Security setup in web.xml 

 

SecureConstraint 

 

Secure Web Resource 

/* 

GET 

POST 

 

 

 

 

SecureCustomer 

 

 

Chapter 8. Web services transport security 247

NONE 

 

 

 

BASIC 

SecurityInfo Realm 

 

 

 

 


 

6. In the J2EE perspective, traverse the tree under Enterprise Applications, and 

open the deployment descriptor for the SecurityInfoEAR. 

7. Select the Security tab. Click the Gather button, and check the box for All 

authenticated users under WebSphere bindings. 

Testing basic authentication for the Web service provider 

Deploy the SecurityInfo ear file in the admin console, accepting the default 

settings presented during deployment. 

The Web service client example uses a POST method to invoke the Web 

service. Since the GET method was included in the security constraint, the URI 

for the service endpoint can be invoked from a Web browser to verify that a 

challenged response is sent to the Web browser. This can be useful for verifying 

that basic authentication has been set up correctly for the Web service provider 

before proceeding to set up the Web service requestor. 

In this example, the following URL was invoked: 

http://wtsc58.itso.ibm.com:19080/SecurityInfoRouterWS/services/Security 

Info 

A Basic Authentication window should appear in the Web browser. 

Upon entering a valid user ID and password for an ID permitted to the role 

SecureCustomer, the following output appears on the Web browser: 

{http://itso.ibm.com}SecurityInfo 

Hi there, this is a Web service! 


8.1.3 Configuring the Web service requestor to authenticate 

WebSphere bindings facilitate where to specify the user name and password for 

a Web services client so that the application does not have to do this 

programmatically. In this section we demonstrate how to set the user ID and 

password in the Rational Application Developer tool and in the WebSphere 

distributed admin console. 

Start Rational Application Developer: 

1. In the J2EE perspective, traverse the tree under EJB Projects and open the 

deployment descriptor for SecurityCallerEJB. 

2. Select the WS Binding tab and under Port Qualified Name Binding Details 

set the HTTP basic authentication user ID and password, as shown in 

Example 8-2 on page 251. 

Figure 8-2 Web service client user ID and password 


To configure the user ID and password in the admin console for the 

SecurityCallerEJB, follow the path Enterprise Applications → 


services client bindings → Web services: Client security bindings → HTTP 

basic authentication. See Figure 8-3. 

Figure 8-3 Admin console basic authentication user ID and password 

Follow the steps in 5.6.4, “SecurityInfo deployment” on page 101, for overriding 

the client endpoint URL of the client if it has not already been done. This step is 

necessary so that the client knows the host name and port for the Web service 

provider. 

8.1.4 Validating transport security using HTTP basic authentication 

To validate that transport security is working correctly with HTTP basic 

authentication, execute the client application. A successful output to the Web 

page of the application should show the user principal of the user ID specified on 

the Web services client security binding in the Web table under Remote 

SecurityInfoBean Information. 


In Figure 8-4, principal WINSERV can be seen. 

Figure 8-4 SecurityInfo output 

Using the TCP/IP monitor to view the header information, you can verify that the 

authorization field is set to BASIC. The SOAP message in the HTTP request is 

unchanged. 

Example 8-2 shows example output of the header information and authorization 

field. The SOAP message follows the HTTP header information. 

Example 8-2 Header information with authorization BASIC 








Authorization: Basic V0lOU0VSVjpXSU5TRVJW 





Date: Wed, 08 Nov 2006 16:33:48 GMT 

 

ITSO5285 

8.2 Integrity with SSL 

Integrity and confidentiality are provided through the use of HTTP over the SSL 

protocol, also known as HTTPS. Once SSL had been configured in WebSphere, 

the level of the cipher suite group being used by the SSL configuration 

determines whether WebSphere supports integrity or confidentiality algorithms 

(or both). Additionally, the application can enforce that the communication is 

performed with integrity and confidentiality in the Web application’s deployment 

descriptor using security constraints. 

8.2.1 Integrity with SSL scenario description 

On the client side, the user invokes a servlet from a static Web page running in 

the WebSphere distributed system. The WebSphere distributed run time initiates 

an SSL handshake with the WebSphere for z/OS run time. A weak cipher signing 

algorithm is negotiated between WebSphere on distributed and WebSphere on 

z/OS. Finally, an SSL connection with no encryption (only integrity validation) is 

established between the client and server endpoints. Once the transport is 

secure, the SOAP message flows from client to server. 


Figure 8-5 illustrates the Integrity with SSL scenario. 

Figure 8-5 Web service transport security integrity scenario 

In this section, we demonstrate how to set up SSL at the transport layer between 

WebSphere distributed and WebSphere z/OS. We extract the signer certificate 

from the WebSphere z/OS server and import it into the WebSphere distributed 

server using the new admin console SSL support. A new SSL-enabled inbound 

transport chain is created on WebSphere z/OS in order to isolate inbound Web 

service SSL calls. A new SSL configuration is defined for both the Web service 

client and the Web service port so that the quality of protection can be modified 

for those SSL configurations. Lastly, we demonstrate using Web service client 

bindings to configure the Web service client to use the SSL configuration, and to 

override the host and port of the service endpoint URL. 

8.2.2 Integrity scenario prerequisites 

To establish trust, the server signer certificate needs to be extracted from the 

WebSphere for z/OS certificate authority and imported into the WebSphere 

distributed truststore. During the SSL handshake, the WebSphere for z/OS 

server sends its signer certificate to be validated. In this section, the RACF 

commands are provided to export the signer certificate from the WebSphereCA 

into a binary HFS file. The certificate is transferred using FTP to WebSphere 

distributed to be imported into the truststore using the admin console. 


Extracting the server signer certificate from z/OS 

Add the WebSphere z/OS signer certificate to the WebSphere client truststore on 

Windows. In this example, we use the default WebSphere Certificate Authority 

WebSphereCA that was created during the installation customization jobs. 

1. Use the following sample RACF command to export the signer certificate: 

RACDCERT CERTAUTH EXPORT(LABEL('WebSphereCA')) DSN(CERTAUTH.DER) 

FORMAT(CERTDER) PASSWORD('XXXXX') 

2. From TSO, copy the certificate from a data set to a binary file: 

OPUT CERTAUTH.DER '/tmp/certauth.der' binary convert(no) 

3. FTP the certificate in binary to the client. 

Importing the server signer certificate in the client 

In the admin console of the distributed WebSphere Application Server, to add the 

certificate, select SSL certificate and key management → SSL 

configurations → NodeDefaultSSLSettings → Key stores and 

certificates → NodeDefaultTrustStore → Signer certificates. 

Specify the absolute path to where the certificate was downloaded in binary and 

provide a new alias name for the certificate. The data type indicates whether the 

certificate was downloaded as Binary Der Data or base64. The certificate was 

exported with a format option CERTDER, and must be imported using the same 

binary der format. 


In this example: 

► Alias: webspherezos_ca 

► File name: C:\TEMP\certauth.der 

► Data type: Binary DER data 

Figure 8-6 Importing the signer certificate 

8.2.3 Configuring the z/OS Web service provider SSL configuration 

In this section, the admin console steps are provided in order to isolate the 

security setup from the default node level SSL configuration: 

1. Create a new SSL configuration. 

An SSL configuration contains the attributes that you need to control the 

behavior of client and server SSL endpoints. You create SSL configurations 

with unique names within specific management scopes on the inbound and 

outbound tree in the configuration topology. 

2. Create new SSL inbound channel. 

An SSL inbound channel is used to associate an SSL configuration with a 

transport chain. This channel is only available when SSL support is enabled 

for the transport chain. 

A transport chain consists of one or more types of channels, each of which 

supports a different type of I/O protocol, such as TCP, DCS, or HTTP. 


Network ports can be shared among all of the channels within a chain. The 

channel framework function automatically distributes a request arriving on 

that port to the correct I/O protocol channel for processing. 

3. Create a new SSL port for use with the SSL inbound channel. 

The new SSL port is where the Web service provider receives incoming 

SOAP requests. 

The goal of this step is to create a new SSL configuration that does not affect the 

existing default node-level SSL settings. Creating a new SSL configuration, SSL 

inbound channel, and SSL port provides this isolation. 

Creating a new SSL configuration on WebSphere for z/OS 

In the admin console of the WebSphere Application for z/OS server, follow the 

path to configure a new SSL Configuration: Security → Secure Administration, 

applications, and infrastructure → SSL Configurations. 

Click New JSSE Configuration: 

► Name: WebServiceSSLConfig 

► Trust store name: NodeDefaultTrustStore 

► Keystore name: NodeDefaultKeyStore 


Click Get certificate Aliases and then click OK. 

Figure 8-7 WebServiceSSLConfig SSL config 

Creating an SSL inbound channel and SSL port 

A new SSL inbound channel is created to isolate the SSL configuration for this 

endpoint so that it can be changed without affecting any other endpoints. 

In the admin console of the WebSphere Application Server for z/OS, follow the 

path to create a new transport chain: Severs → Application Servers → 

servername → Web Container Settings → Web Container Transport 

Chains. 

► Transport chain name: SecureWebServiceInbound 

► Transport chain template: WebContainer-Secure 


Be sure to select the WebContainer-Secure transport chain template to ensure 

that an SSL-enabled transport chain is created (Figure 8-8). 

Figure 8-8 Transport chain selection 

Select a port for the Web service to accept inbound SSL calls to. In this example: 

► Port name: SecureWebServicePort 

► Host: * 

► Port: 19445 

Click Finish to confirm the new transport chain creation. 


At this point, a new transport chain is created, however, the transport chain 

defaults to the default SSL configuration, in our case NodeDefaultSSLSetttings. 

The SSL configuration for the inbound transport chain needs to be changed to 

the new SSL configuration WebServiceSSLConfig that was created in the 

previous steps. 

1. Select the SecureWebServiceInbound transport chain. 

2. Click SSL inbound channel (SSL_4). 

3. Check the radio button Centrally Managed (Figure 8-9). 

Figure 8-9 Centrally managed SSL configuration for transport chain 

Follow the path in the admin console to: SSL certificate and key 

management → Manage endpoint security configurations → 

SecureWebServicePort. 


It is necessary to expand the tree in the local topoly view to find the 

SecureWebServicePort: 

► Override inherited values: checked 

► SSL configuration: WebServiceSSLConfig 

► Certificate alias in key store: defaultwascert.sc58 

Figure 8-10 Choosing the WebServiceSSLConfig for SecureWebServicePort 

In this step, the newly created port SecureWebServicePort needs to be added to 

the virtual host. Select Environment → Virtual Hosts → default_host. 

Under Additional Properties select Host Aliases → New: 

► Hostname: * 

► Port: 19445 

The user may be wondering whether it was necessary to create a new transport 

chain and SSL configuration instead of using the centrally managed SSL 

configuration that is defined at the node level from the WebSphere installation. 

The forthcoming steps involve changing the ciphers for an SSL configuration. 

Changing the ciphers for the node-level SSL configuration can result in problems 

accessing the admin console in a base server configuration since it also uses 


SSL and the admin console requires confidentiality. By creating a new SSL 

configuration and transport chain, the SSL changes are isolated to the Web 

service only. 

8.2.4 Configuring the Web service requestor SSL configuration 

In this section, a new SSL configuration is created for the client so that the quality 

of protection setting, specifically the ciphers, can be modified without affecting 

the admin console or any applications using SSL. The Web service requestor’s 

client binding is modified to use the new SSL configuration, and the Web service 

requestor’s endpoint URL is modified to connect to the Web service provider’s 

SSL port. 

Creating a new Web service requestor SSL configuration 

In the admin console of the distributed WebSphere Application Server, follow the 

path to create a new SSL configuration: Security → Secure Administration, 

applications, and infrastructure → SSL Configurations. 

Click New JSSE Configuration: 

► Name: WebServiceConfig 

► Trust store name: NodeDefaultTrustStore 

► Keystore name: NodeDefaultKeyStore 


Click Get certificate Aliases and then OK. 

Figure 8-11 WebServiceConfig SSL configuration 

Configuring the Web service requestor to use SSL 

configuration 

In the admin console of the distributed WebSphere Application Server, follow the 

path to the ServiceCallerEJB’s HTTP SSL binding in order to select the new SSL 

configuration WebServiceConfig. 

In this example, the Web service requestor uses an SSL configuration that is 

specific to this Web service port rather than a centrally manage SSL 

configuration. The reason for choosing the SSL configuration that is specific to 

the this Web service port is that the client binding only affects this Web service’s 

outbound SSL call. Choosing a centrally managed SSL configuration would 

require setting up an SSL configuration for an outbound port, which could affect 


all applications using that port. Select Enterprise Applications → 


services deployment descriptor Extension → Web services client 

bindings → Web services: Client security bindings → HTTP SSL 

configuration. See Figure 8-12. 

Figure 8-12 Selecting the SSL configuration for Web service client binding 

Follow the path in the admin console to override the endpoint URL to reflect the 

host name and port of the WebSphere z/OS system. The port should be the 

same port you defined for the SSL inbound transport chain 

SecureWebServicePort. Select Enterprise Applications → 


services deployment descriptor Extension → Web services client 

bindings → SecurityInfoService:SecurityCallerEJB. 


Configuring the Web service requestor endpoint URL 

In this example, the endpoint URL was changed to: 

https://wtsc58.itso.ibm.com:19445/SecurityInfoRouterWS/services/Security 

Info 

Figure 8-13 Changing the endpoint URL in Web service client binding 

8.2.5 Configuring the z/OS Web service provider for integrity 

In the admin console for WebSphere for z/OS, follow the path to set the cipher 

suite group. Select Security → Secure Administration, applications, and 

infrastructure → SSL Configurations. 

1. Choose the WebServiceSSLConfig for the Web service on z/OS. 

2. Under Additional Properties, select quality of protection (Qop) settings. 

3. Change the cipher suite groups to Weak. 

Figure 8-14 on page 265 illustrates the quality of protection panel for both 

platforms. 

8.2.6 Configuring the Web service requestor for integrity 

In both, the distributed WebSphere admin console follow the path to set the 

cipher suite group. Select Security → Secure Administration, applications, 

and infrastructure → SSL Confirugrations. 

1. Choose the WebServiceConfig for the Web service client. 


3. Change the cipher suite groups to Weak. 


Figure 8-14 illustrates the quality of protection panel for both platforms. 

Figure 8-14 Quality of protection with weak cipher for Integrity 

Restart both application servers to pick up the changes. 

8.2.7 Validating integrity with SSL 

Execute the SecurityInfo application. The output should look similar to when you 

ran the SecurityInfo application with no security. 


Looking at the output in the TCP/IP monitor, the output is still visible, as the data 

is not encrypted. However, you will notice SSL information preceding the header 

and soap message. 

Example 8-3 TCP/IP output 

.....0G1.0...U....WebSphere for zOS1)0'..U... WAS CertAuth for Security 

Domain0.. 

040604040000Z. 

110101035959Z0G1.0...U....WebSphere for zOS1)0'..U... WAS CertAuth for 

Security Domain0..0 

..*.H.. 

.........0.......D.3]j.F....A...N 

....b.ec|.Te...t.*."f......U.b.>..38..i.F.)T.X...... 

(.&3..R}{?.|*...u...TQ.&.....o.yVv3..N..!..+....;vcXV...'........0..0?. 

.`.H...B. 

.2.0Generated by the Security Server for z/OS 

(RACF)0...U...........0...U.......0....0...U......q..GP...}2..5.../...0 

..*.H.. 

......... 

......E.h!........o.ov......\.k......POST 

/SecurityInfoRouterWS/services/SecurityInfo HTTP/1.1 











 

ITSO1916(....[xU.n..........QHTTP/1. 

1 200 OK 


Content-Language: en-US 





 

ITSO1 

916Fri Nov 10 15:25:13 GMT+00:00 

2006WTSC589.12.4.8UN 

AUTHENTICATEDz/OS01.08.00...K.....g.\..o 

Note: With the cipher suite group set to weak, you may not be able to access 

the service endpoint URI from your Web browser directly to see the following 

message since the browser does not support this cipher suite group: 



Enforcing integrity with the Web service descriptor 

At this point your Web service can still be invoked from the default non-SSL port 

defined for your system, as well as the new transport chain configured with a 

weak cipher suite group for integrity. In order to enforce that integrity be 

mandatory for any calls to this Web service, the Security Constraint can be 

updated in the Web deployment descriptor for SecurityInfoRouterWS. 



2. Select the Security tab, and then select your security constraint 


3. Under User Data Constraint, change the type to INTEGRAL. 

Example 8-4 shows the xml that will be added to the web.xml. 

Example 8-4 Integrity requirement for Web service 

 

INTEGRAL 

 


Re-deploy the application to WAS for z/OS to pick up the change. 

8.3 Confidentiality with SSL 

Confidentiality involves encrypting the data flowing across the HTTP transport 

such that the data cannot be viewed. WebSphere accomplishes this encryption 

using a set of ciphers. 

8.3.1 Confidentiality with SSL scenario description 

The user client invokes a servlet from a static Web page running in the 

WebSphere distributed system. The WebSphere distributed run time initiates an 

SSL handshake with the WebSphere for z/OS run time. During the handshake 

the WebSphere for z/OS certificate is sent to the WebSphere application server 

on Windows. WebSphere on distributed validates this certificate against its 

truststore. A strong cipher algorithm is negotiated between WebSphere on 

distributed and WebSphere on z/OS. Finally, an SSL connection with encryption 

is established between the client and server endpoints. Once the transport is 

secure, the SOAP message flows from client to server. 

Figure 8-15 Web services transport security confidentiality scenario 

Using the previous setup from 8.2, “Integrity with SSL” on page 252, 

confidentiality can be provided by switching the cipher suite group from weak to 

medium or strong. Selecting a medium cipher suite group, WebSphere uses 

40-bit encryption algorithms for providing confidentiality, and with a strong cipher 

suite group, WebSphere uses 128-bit encryption algorithms. Both the medium 

and strong cipher suite groups maintain data integrity as well as provide 


confidentiality. The stronger the encryption algorithm the more secure the 

connection. However, more processing is needed to encrypt and decrypt the 

information. 


If it has not already been done, create a new z/OS Web service provider SSL 

configuration, a new SSL inbound channel, and a new SSL port to provide 

isolation from other SSL configurations. The steps for this process are described 

in 8.2.3, “Configuring the z/OS Web service provider SSL configuration” on 

page 255. 


If it has not already been done, create a new Web service requestor SSL 

configuration, and configure it to use the SSL configuration. In addition, update 

the Web service requestor’s endpoint URL to point to the host and port of the 

Web service provider. The steps for this process are described in 8.2.4, 

“Configuring the Web service requestor SSL configuration” on page 261. 

8.3.4 Configuring the z/OS Web service provider for confidentiality 

In this example, the cipher suite group was changed to strong in the WebSphere 

for z/OS admin console. Select Security → Secure Administration, 

applications, and infrastructure → SSL Confirugrations. 

1. Choose the WebServiceSSLConfig. 


3. Change the cipher suite groups to Strong. 

Figure 8-16 on page 270 illustrates changing the cipher suite in the admin 

console for both platforms. 

8.3.5 Configuring the Web service requestor for confidentiality 

In this example, the cipher suite group was changed in the distributed 

WebSphere admin console. Select Security → Secure Administration, 


1. Choose WebServiceConfig. 


3. Change the cipher suite groups to Strong. 


Figure 8-16 illustrates changing the cipher suite in the admin console for both 

platforms. 

Figure 8-16 Quality of protection with strong cipher for confidentiality 

Restart both servers to pick up the change. 

Note: If there is a change to the cipher suite groups, the WebSphere 

Application Server needs to be restarted to pick up the change. 


8.3.6 Validating confidentiality with SSL 

Execute the SecurityInfo application. The output should look like the same as 

when you ran the SecurityInfo application with no security. 

Looking at the output in the TCP/IP Monitor, the HTTP header and SOAP 

message are no longer visible, as the data is now encrypted. 

Note: You can also invoke the Web service from a browser using the Web 

service endpoint URL, as the browser supports the cipher suite group: 

https://wtsc58.itso.ibm.com:19445/SecurityInfoRouterWS/services/ 

SecurityInfo 

The browser output shows: 



Enforcing confidentiality with the Web service descriptor 

At this point your Web service can still be invoked from the default non-SSL port 

defined for your system, as well as the new transport chain configured with a 

strong cipher suite group for confidentiality. In order to enforce that confidentiality 

be mandatory for any calls to this Web service, the security constraint can be 

updated in the Web deployment descriptor for SecurityInfoRouterWS. 



2. Select the Security tab, and then select your security constraint 


3. Under User Data Constraint change the type to CONFIDENTIAL. 

Example 8-5 shows the xml that will be added to the web.xml. 

Example 8-5 Confidentiality requirement for Web service 

 

CONFIDENTIAL 

 

The application must be redeployed after making the change to the deployment 

descriptor. 


8.4 Confidentiality with SSL using hardware crypto 

The SecurityInfo Web service can take advantage of hardware cryptographic 

support to help accelerate SSL communication. This section assumes that ICSF 

is active and initialized. The WebSphere steps are provided to show one way to 

set up WebSphere for accessing keys in hardware. Further information about 

enabling hardware can be found in z/OS Cryptographic Services Integrated 

Cryptographic Service Facility Administrator’s Guide, SA22-7521. This manual 

has references to other publications and sources of information as well. 

8.4.1 Confidentiality with SSL using hardware crypto prerequisites 

In this section a new certificate authority, personal certificate, and keyring are 

created and connected to the control and servant region user IDs. The reason for 

doing this is to separate the certificate and keyring setup from the default keyring 

that comes from running the customization jobs to set up WebSphere on z/OS. 

The certificate authority and personal certificate setup are created with the ICSF 

keyword appended to the commands to specify that RACF should store the 

private key associated with the certificate in ICSF. The signer certificate is 

exported on WebSphere V6.1 for z/OS and imported into WebSphere distributed 

to be used by the Web service requestor during an SSL handshake. 

Creating keyring and certificates 

Create a new certificate authority called HDCA with its keys stored in ICSF, as 

follows: 

RACDCERT CERTAUTH GENCERT SUBJECTSDN(CN('HDwtsc58.itso.ibm.com') 

OU('IBM')) WITHLABEL('HDCA') TRUST NOTAFTER(DATE(2010/12/20)) ICSF 

Create a new keyring called WASKeyring.HD for the control user ID ASCR1 and 

servant user ID ASSR1: 

RACDCERT ADDRING(WASKeyring.HD) ID(ASCR1) 

RACDCERT ADDRING(WASKeyring.HD) ID(ASSR1) 

Connect the certificate authority HDCA to WASKeyring.HD for ASCR1 and 

ASSR1: 

RACDCERT ID(ASCR1) CONNECT (RING(WASKeyring.HD) LABEL('HDCA') CERTAUTH) 

RACDCERT ID(ASSR1) CONNECT (RING(WASKeyring.HD) LABEL('HDCA') CERTAUTH) 


Create a new personal certificate HDPersonal signed by HDCA with its key in 

ICSF: 

RACDCERT ID (ASCR1) GENCERT SUBJECTSDN(CN('HDPersonal') O('IBM')) 

WITHLABEL('HDPersonal') SIGNWITH(CERTAUTH LABEL('HDCA')) TRUST 

NOTAFTER(DATE(2010/12/20)) ICSF 

Connect the new personal certificate to the control region’s keyring: 

RACDCERT ID(ASCR1) CONNECT (LABEL('HDPersonal') RING(WASKeyring.HD) 

DEFAULT) 

As an additional verification step, display the contents of the certificate authority 

HDCA, and personal certificate HDPersonal. Notice that the private key type 

indicates ICSF to indicate that the keys are ICSF managed and that there is a 

new PKDS label. 

Issue the following commands to view the certificate authority information: 

RACDCERT CERTAUTH LIST(LABEL('HDCA')) 

Example 8-6 Signer certificate HDCA information 

Digital certificate information for CERTAUTH: 

Label: HDCA 

Certificate ID: 2QiJmZmDhZmjgcjEw8FA 

Status: TRUST 

Start Date: 2006/11/21 00:00:00 

End Date: 2010/12/20 23:59:59 


>00< 





Key Usage: CERTSIGN 



PKDS Label: IRR.DIGTCERT.CERTIFAUTH.SC58.BFBDE7690EF01249 



Ring: 


Ring Owner: ASSR1 

Ring: 



The private key type should be ICSF and a PKDS label should exist for the 

personal certificate as well. 

Issue the following command to view the personal certificate information: 

RACDCERT LIST (label('HDPersonal')) ID(ASCR1) 

Example 8-7 HDPersonal certificate information 

Digital certificate information for user ASCR1: 

Label: HDPersonal 

Certificate ID: 2QXB4sPZ8cjE14WZopaVgZNA 

Status: TRUST 

Start Date: 2006/11/21 00:00:00 

End Date: 2010/12/20 23:59:59 


>02< 




>CN=HDPersonal.O=IBM< 



PKDS Label: IRR.DIGTCERT.ASCR1.SC58.BFBDE9BD1F5C88CC 



Ring: 


Extracting the signer certificate from z/OS 

Export the HDCA signer certificate (with public key) to an HFS file: 

1. Use the following sample RACF command to export the signer certificate: 

RACDCERT CERTAUTH EXPORT(LABEL('HDCA')) DSN(CERTAUTH.DER) 

FORMAT(CERTDER) PASSWORD('XXXXX') 

2. From TSO, copy the certificate from a data set to a binary file: 

OPUT CERTAUTH.DER '/tmp/certauth.der' binary convert(no) 

3. FTP the certificate in binary to the client. 

Importing the signer certificate into WebSphere distributed 

In the admin console of the distributed WebSphere application server, follow the 

path to add a signer certificate. Select SSL certificate and key management → 


SSL configurations → NodeDefaultSSLSettings → Key stores and 

certificates → NodeDefaultTrustStore → Signer certificates. 

Specify the absolute path to where the certificate was downloaded in binary and 

provide a new alias name for the certificate. The data type indicates whether the 

certificate was downloaded as binary data or base64. In this example: 

► Alias: HDCA 

► File name: C:\TEMP\certauth.der 

► Data type: Binary DER Data 

Once imported, follow the admin console path SSL certificate and key 

management → SSL configurations → WebServiceSSLConfig. 

Click Get certificate aliases and then Save. 

8.4.2 Installing the unrestricted Java policy jars 

These unrestricted jars must be installed to access the keys in hardware using a 

strong encryption. To obtain the Java unrestricted policy jars and place them on 

the WebSphere z/OS system: 

1. Obtain the unrestricted policy jars from: 


2. Make a backup of the original restricted local_policy.jar and 

US_export_policy.jar. 

3. Download the unrestricted local_policy.jar and US_export_policy.jar to your 

WebSphere z/OS system in: 

/AppServer/java/lib/security 

4. After copying the local_policy.jar and US_export_policy.jar, change the 

permissions so that the control and servant region address spaces can 

access the jar files, as follows: 

chmod 644 local_policy.jar 

chmod 644 US_export_policy.jar 

8.4.3 Updating the JVM to use the IBMJCECCA provider 

The java.security file located in the WebSphere HFS needs to be updated with 

the IBMJCECCA provider as the first provider in the list of providers. The 

java.security file is in an ASCII, so it may be necessary to convert the file to 

EBCDIC before making changes. 


Example 8-8 illustrates the addition made to the java.security file. 

Example 8-8 Updating the java.security file for IBMJCECCA 




security.provider.3=com.ibm.jsse.IBMJSSEProvider2 

security.provider.4=com.ibm.jsse2.IBMJSSEProvider 






The admin console in WebSphere V6.1 obtains the list of providers dynamically 

from this file. Restart the application server to pick up the changes. 


To configure the z/OS Web service provider to use the certificates with keys 

managed by ICSF, a new SSL configuration, JCECCRACFKS keystore, and SSL 

inbound channel and port are created to isolate the configuration. 

Creating a new JCECCARACFKS keystore 

In the WAS admin console, follow the path SSL certificate and key 

management → Key stores and certificates → New. 

If the java.security file was updated with the IBMJCECCA provider, the admin 

console shows two new types, JCECCARACFKS and JCECCAKS, in the 

drop-down menu, as shown in Figure 8-17. 

Figure 8-17 Certificate store types 


Figure 8-18 HDCertStore 

Create the new certificate store with the values below and click Apply. 

► Name: HDCertStore 

► Path: safkeyringhw:///WASKeyring.HD 

► Change password: password 


► Type: JCECCARACFKS 

Notice that the safkeyring URI has been changed to safkeyringhw:/// to indicate 

that the keys are stored in hardware. See Figure 8-18. 

Since the HDCA was added to the keyring for both control and servant region 

user IDs, the signer certificate HDCA is viewable from the admin console. 


Verify that you can see the HDCA signer certificate by following the admin 

console path: SSL certificate and key management → SSL configurations → 

New → Key stores and certificates → HDCertStore → Signer certificates → 

hdca. See Figure 8-19. 

Figure 8-19 HDCA signer certificate information in admin console 

The personal certificate will not be viewable since it was only added to the 

keyring for the control region user ID. 

Creating a new SSL configuration 

Create a new SSL configuration to be used by the Web service port 

SecureWebServicePort. Follow the path in the admin console: SSL certificate 

and key management → SSL configurations → New. 

► Name: HDWebServiceSSLConfig 

► Trust store name: HDCertStore 

► Keystore Name: HDCertStore 

► Default server certificate alias: none 

► Default client certificate alias: none 


Click the Get Certificate aliases button, and then click Apply (Figure 8-20). 

Figure 8-20 SSL configuration HDWebServiceSSLConfig 

Create a new SSL inbound channel and SSL port 

If it has not already been done, create a new SSL inbound channel and SSL port, 

as described in “Creating an SSL inbound channel and SSL port” on page 257, 

to isolate SSL changes for the Web service provider. 

Update SecureWebServicePort to use the new SSL configuration, using the 

following path in the admin console: SSL certificate and key management → 

Manage endpoint security configurations → SecureWebServicePort. 


Under Specific SSL configuration for this endpoint, click the check box to 

Override inherited values, and choose HDWebServiceSSLConfig in the 

drop-down for SSL configuration (Figure 8-21). 

Figure 8-21 Specific SSL configuration for SecureWebServicePort 








8.4.6 Configuring the z/OS Web service provider for confidentiality 

In this example, the cipher suite group was changed to strong in the WebSphere 

for z/OS admin console. Select Security → Secure Administration, 


1. Choose the WebServiceSSLConfig. 


3. Change the cipher suite groups to strong. 

8.4.7 Configuring the Web service requestor for confidentiality 

In this example, the cipher suite group was changed in the distributed 

WebSphere admin console. Select Security → Secure Administration, 


1. Choose the WebServiceConfig. 


3. Change the cipher suite groups to strong. 

8.4.8 Validating confidentiality with SSL using hardware crypto 

Execute the SecurityInfo application. The output should be similar to when you 

ran the SecurityInfo application with no security. 

If you are on a test system, stopping the ICSF address space and executing the 

SecurityInfo application results in an SSLException: 

javax.net.ssl.SSLException: Received close_notify during handshake 

The application executes successfully after restarting the ICSF address space. 

In a non-test environment, an RMF report can be viewed to see the ICSF 

address space’s CPU activity. 


Note: It is also possible to invoke the Web service provider’s URL from a Web 

browser: 

https://wtsc58.itso.ibm.com:19445/SecurityInfoRouterWS/services/ 

SecurityInfo 

Depending on your browser settings, you may be prompted with a security 

alert. If so, click View Certificate to see who the certificate was issued by and 

issued to. The certificate should match what you have defined for the 

WebSphere control region user ID’s keyring. The output on the Web page 

should show: 



8.5 Confidentiality and basic authentication 

Configuring basic authentication over SSL is accomplished by combining the 

steps in 8.1, “Authentication with HTTP” on page 246 and 8.3, “Confidentiality 

with SSL” on page 268. The steps have been outlined in order below: 

1. “Configuring the z/OS Web service provider with authentication” on page 247 

2. “Configuring the Web service requestor to authenticate” on page 249 

3. “Configuring the z/OS Web service provider SSL configuration” on page 255 

4. “Configuring the Web service requestor SSL configuration” on page 261 

5. “Configuring the z/OS Web service provider for confidentiality” on page 269 

6. “Configuring the Web service requestor for confidentiality” on page 269 

8.6 Confidentiality and client certificate authentication 

Client certificate authentication occurs during an SSL handshake when the 

server sends a certificate request after sending its own certificate. The client 

provides its certificate with a public key to the server. During the certificate verify 

step, the client sends a certificate verify message in which it encrypts a known 

piece of plain text using its private key. The server uses the client certificate to 

decrypt the message, therefore confirming that the client has the private 

key.“SSL Flow” on page 95 illustrates where the steps for client certificate 

authentication occur during an SSL handshake. 


8.6.1 Confidentiality and client certificate scenario description 

The user client invokes a servlet from a static Web page running in the 

WebSphere distributed system. The WebSphere distributed run time initiates an 

SSL handshake with the WebSphere for z/OS run time. During the handshake, 

the WebSphere for z/OS certificate is sent to the WebSphere Application Server 

on Windows. WebSphere on distributed validates this certificate against its 

truststore. Additionally, a client certificate and encrypted message is sent from 

WebSphere on Windows to WebSphere for z/OS to authenticate the client. A 

strong cipher algorithm is negotiated between WebSphere on distributed and 

WebSphere on z/OS. Finally, an SSL connection is established between the 

client and server endpoints. Once the transport is secure, the SOAP message 

flows from client to server. 

Figure 8-22 Client certificate authentication scenario 

8.6.2 Confidentiality and client certificate prerequisites 

During the SSL handshake the client authenticates to the server by sending an 

encrypted message that can only be decrypted by the server’s public key. The 

client must possess the personal certificate and private key for doing this 

encryption. In this section, a personal certificate is created and signed by the 

WebSphereCA, and then transferred to the WebSphere distributed system to be 

used by the Web service requestor for client certificate authentication. 


Creating certificate authority and personal certificate in RACF 

To create this: 

RACDCERT ADDRING(WASKeyring.CL6581) ID(WINSERV) 

RACDCERT ID(WINSERV) GENCERT SUBJECTSDN(CN('WINSERV') O('IBM') 

OU('ITSO')) WITHLABEL('WINSERVCERT') SIGNWITH(CERTAUTH 

LABEL('WebSphereCA')) NOTAFTER(DATE(2010/12/29)) 

RACDCERT ID(WINSERV) CONNECT (LABEL('WINSERVCERT') 

RING(WASKeyring.CL6581) DEFAULT) 

RACDCERT ID(WINSERV) EXPORT(LABEL('WINSERVCERT')) DSN(WINSERV.P12BIN) 

FORMAT(PKCS12DER) PASSWORD('XXXX') 

OPUT WINSERV.P12BIN '/tmp/winserv.p12' binary convert(no) 

FTP the user certificate in binary to the client. 

Import personal certificate into client keystore 

In the admin console of the distributed WebSphere application server, follow the 

path to import the certificate from a key file. Select SSL certificate and key 

management → SSL configurations → WebServiceConfig → Key stores 

and certificates → NodeDefaultKeyStore → Personal certificates. 

► Key file name: C:\TEMP\winserv.p12 

► Type: PKCS12 

► Key file password: Specify the password that you exported the certificate 

with. 

► Imported certificate alias: winserv 


Click the Get key file aliases button. The certificate alias to import should fill in 

with winservcert (Figure 8-23). 

Figure 8-23 Importing the certificate from a key file 


Important: WebSphere for z/OS uses a high level of encryption. Download 

the unrestricted local_policy.jar and US_export_policy.jar to your WebSphere 

distributed system in the path: 

\AppServer\java\jre\lib\security 

Otherwise, you will not be able to import the personal certificate exported from 

WebSphere for z/OS. 

Refer to: 


Comparing the personal certificate on z/OS and Windows 

At this point you may want to confirm that the certificate that you exported from 

RACF matches the certificate imported in Windows. The following RACF 

command lists information about your certificate, such as serial number, issuer, 

subject, and expiration, that can be used to compare with the certificate imported 

into WebSphere distributed: 

RACDCERT LIST (label('WINSERVCERT')) ID(WINSERV) 

Example 8-9 Listing certificate information 

Digital certificate information for user WINSERV: 

Label: WINSERVCERT 

Certificate ID: 2QfmydXixdnl5snV4sXZ5cPF2eNA 

Status: TRUST 

Start Date: 2006/11/21 00:00:00 

End Date: 2010/12/29 23:59:59 


>24< 


>CN=WAS CertAuth for Security Domain.OU=WebSphere for zOS< 


>CN=WINSERV.OU=ITSO.O=IBM< 

Private Key Type: Non-ICSF 



Ring Owner: WINSERV 

Ring: 

>WASKeyring.CL6581< 


In the Windows admin console follow the path to SSL certificate and key 


Personal certificates → winserv. See Figure 8-24. 

Figure 8-24 Personal certificate display on Windows 


If it has not already been done, create a new z/OS Web service provider SSL 

configuration, a new SSL inbound channel, and a new SSL port to provide 

isolation from other SSL configurations. The steps for this process are described 

in 8.2.3, “Configuring the z/OS Web service provider SSL configuration” on 

page 255. 








1. Change the SSL configuration WebServiceConfig to now point to the winserv 

certificate, as follows: SSL certificate and key management → SSL 

configurations → WebServiceConfig. 

2. Click the Get certificate aliases button. 

3. Under Default client certificate alias select winserv. See Figure 8-25. 

Figure 8-25 Setting default client certificate alias 


8.6.5 Configuring z/OS Web service provider for authentication 

The process for configuring transport-level client certificate authentication for a 

Web service is similar to that described in 8.1.1, “HTTP basic authentication 

scenario description” on page 246. The Web service endpoint resides in a WAR 

file and can be configured using the Web deployment descriptor editor. 

1. In the J2EE perspective, traverse the tree under Dynamic Web Projects and 


2. Select the Security tab. Under the Security Roles, add a role named 

SecureCustomer. 

3. Under Security Constraints, add a security constraint named 


– Set Resource Name to Secure Web Resource. 

– Select the check box for “GET, and POST” HTTP Methods. 

– Add the pattern /*. 

4. Under Authorized Roles, add SecureCustomer. 

5. Select the Pages tab. Under Authentication Method, select CLIENT_CERT. 

Example 8-10 Client certificate authentication setup in web.xml 

 

 

Security Constraint 

 

Security Resource 

/* 

GET 

PUT 

POST 

 

 

 

 


 

 

 

CLIENT-CERT 

 

 


 


Deploy the SecurityInfo ear file in the admin console, accepting the default 

settings presented during deployment. 

Enable client certificate authentication for SSL config 

Follow the path Security → Secure Administration, applications, and 

infrastructure → SSL Confirugrations. 

1. Choose WebServiceSSLConfig. 


3. Change the client authentication to Required. 

Figure 8-26 Setting client authentication for SSL configuration 


8.6.6 Validating client certificate authentication 

Successful output from the application should show the user principal of the user 

ID associated with the personal certificate in the Web page table Remote 

SecurityInfoBean Information. In this scenario WINSERV is seen as the user 

principal. See Figure 8-27. 

Figure 8-27 Client certificate authentication validation 

Attention: For the client certificate scenario to work successfully, the fix for 

PK31729 needed to be applied, which corrected a problem with authorization 

errors when creating native credentials. 



Chapter 9. Security attribute 

propagation and CSIv2 

9 

As J2EE applications are deployed in many different application servers across 

the enterprise, there is a need to not only have single sign-on, but also to 

propagate additional security context information. This way static or dynamic 

security attributes flow among application servers following user requests. 

In this chapter we describe security attribute propagation and CSIv2 identity 

assertion. The following topics are discussed: 

► “Introduction, logins, and tokens” on page 294 

► “Horizontal attribute propagation” on page 298 

► “CSIv2 standard identity assertion” on page 305 

► “Vertical attribute propagation with CSIv2” on page 328 


9.1 Introduction, logins, and tokens 

This section presents what security attribute propagation is and introduces 

technical concepts pertaining to attribute propagation. 

9.1.1 Security attribute propagation 

To better understand security attribute propagation, we first introduce identity 

propagation. 

Identity propagation refers to the basic level capability of passing the user 

identity from one server to another server. In the context of WebSphere 

Application Server for z/OS, a user initially authenticates to one server. This 

WebSphere server creates a JAAS subject that contains a principal that 

possesses the user identity. If there is any following request to another 

WebSphere server, the user identity is propagated to this other server so that 

single sign-on occurs and so that the other server’s principal gets populated with 

the user identity. 

Attribute propagation refers to the more advanced capability of passing the 

complete user security context from one server to another server. The complete 

user security context includes the user identity, tokens, and any attribute 

collected or created by the login module. These attributes may be groups, 

location, department name, IP address, and so on. In the context of WebSphere 

Application Server for z/OS, an user initially authenticates to one server. This 

WebSphere server creates a JAAS subject that contains a principal and 

credentials. The principal possesses the user identity. Credentials possess 

tokens and attributes. If there is any following request to another WebSphere 

server, the complete user security context is propagated to this other server so 

that single sign-on occurs and so that the other server’s subject gets populated 

with the user identity, eventually with tokens, and all other attributes. 

Security attribute propagation enables propagation of security attributes (user 

identity, authenticated subject content, and security context information) between 

application servers. Alternatively, servers would have to query the user registry 

or use a custom login module to get the attributes. This can be expensive from a 

performance view point and may increase the complexity of the solution. 


There are two different security attribute propagation styles: 

► Horizontal propagation 

Propagation occurs across front-end servers for Web application HTTP 

requests. Propagation relies on DynaCache and JMX. 

► Vertical propagation 

Propagation occurs between a front-end server and a back-end server for 

EJB application RMI-IIOP requests. Propagation relies on RMI-IIOP and 

CSIv2. This vertical attribute propagation style is also called downstream 

propagation. 

WebSphere Application Server for z/OS may obtain security attributes from 

either an enterprise user registry, which queries static attributes, or a custom 

login module, which can query static or dynamic attributes. WebSphere 

propagates only the objects within the subject that it can serialize. This means 

that it propagates custom objects on a best-effort basis. 

The propagation of security attributes in WebSphere Application Server for z/OS 

has significant benefits. Some benefits of using security attribute propagation 

are: 

► Performing registry lookups at each hop along an invocation is eliminated. 

► In your environment, you may use a Reverse Proxy Security Server (RPSS) 

such as WebSEAL to perform user authentication and gather group 

information and other security attributes. Prior to Version 6.0.x, the 

WebSphere Application Server for z/OS could only use the identity of the user 

and disregarded all the other security attributes. Since then, information that 

is obtained from the RPSS can be used by WAS and propagated downstream 

to other server resources without additional calls to the user registry. 

► Another significant benefit of the security attribute propagation is that the user 

switches that occur because of J2EE run-as configurations do not cause the 

WebSphere Application Server to loose the original caller information. This 

information is stored in the propagation token that is located on the running 

thread. 

9.1.2 Initial login versus propagation login 

When a request is being authenticated, a determination is made by the login 

modules as to whether this request is an initial login or a propagation login. 

An initial login is the process of WebSphere Application Server for z/OS 

authenticating the user information. Typically, the user proves his identity 

through a credential, which may be a user ID and password or a certificate, and 

Chapter 9. Security attribute propagation and CSIv2 295

WebSphere Application Server for z/OS then validates the user against the user 

registry and looks up secure attributes that represent the user access rights. 

A propagation login is the process of validating the user information, typically a 

Lightweight Third Party Authentication (LTPA) token, and then deserializing a 

set of tokens that constitute both custom objects and token objects known to the 

WebSphere Application Server. See Figure 9-1. 

Figure 9-1 Horizontal and vertical propagation - initial and propagation login 

When an user connects to a Web infrastructure for the first time, he typically 

does an initial login with WebSphere Application Server for z/OS. His credentials 

are validated against the user registry and the JAAS subject is created by the 

login module. This request might make a remote EJB call, and vertical security 

attribute propagation would happen. A following user request can reach the 

same server or a different server. Because the user already provided his 


credentials, a propagation login happens. If the request reaches a server 

different from the original server, then horizontal security attribute propagation 

happens. 

9.1.3 Token framework 

Security attribute propagation provides propagation services using Java 

serialization for any objects that are contained in the JAAS subject. However, 

Java code must be able to serialize and deserialize these objects. The Java 

programming model specifies the rules for how Java code can serialize an 

object. Because problems can occur when dealing with different platforms and 

versions of software, WebSphere Application Server for z/OS offers a token 

framework that enables custom serialization functionality. The token framework 

has other benefits that include the ability to identify the uniqueness of the token. 

This uniqueness determines how the JAAS subject gets cached and the purpose 

of the token. The token framework defines four marker token interfaces that 

enable the WebSphere Application Server for z/OS run time to determine how to 

propagate the token. 

The WebSphere token framework consists of the following tokens: 

► Subject-based tokens 

– Authentication token (old LtpaToken) 

This token contains the identity of the user only. It is converted to a cookie 

and sent to the browser. It is the same as the old LtpaToken for backwards 

compatibility with previous WebSphere versions. 

– Single sign-on (SSO) token (new LtpaToken2) 

This token is converted to a cookie and sent to the browser. It represents 

the unique authentication. It contains stronger encryption than the 

LtpaToken and enables you to add multiple attributes to the token. It 

contains the authentication identity and attributes that are used for 

contacting the original login server and the unique cache key for looking 

up the JAAS subject. 

– Authorization token 

This token contains most of the authorization-related security attributes 

that are propagated. It is used by WebSphere to make J2EE authorization 

decisions. 

► Thread-based token 

– Propagation token 

This token is not user specific and thus not part of the JAAS subject. It 

represents the thread context. It is used to implement chaining support. 


This allows servers in the invocation hop to add information that can be 

retrieved downstream. This token is not associated with the subject, since 

the subject may change. Instead, it is stored with the thread. The default 

propagation token monitors and logs all user switches and host switches. 

Each of the WebSphere Application Server tokens discussed above can be 

customized by implementing the appropriate interface. This customization may 

be done in two ways. You can add custom attributes to the default token or you 

can create your own implementation of the token by extending the specific token 

interface. The token framework serves as a way to notify WebSphere that you 

want these custom tokens propagated in a particular way. 

For example, service providers can use custom authorization token 

implementations to isolate their data in a different token, perform custom 

serialization and de-serialization, and make custom authorization decisions using 

the information in their token at the appropriate time. 

Custom tokens added by other servers and front end are not used by 

WebSphere for authorization or authentication. Any custom tokens that are used 

in this framework are not used by WebSphere Application Server for 

authorization or authentication. WebSphere Application Server handles the 

propagation details, but does not handle serialization or deserialization of custom 

tokens. Serialization and deserialization of these custom tokens are carried out 

by the implementation and handled by a custom login module. 

For front-end custom login modules, the WEB_INBOUND login configuration is 

modified. For upstream to downstream custom login modules, the 

RMI_OUTBOUND and RMI_INBOUND login configuration are modified. 

For more information about how to develop a custom token, refer to IBM 

WebSphere Application Server V6.1 Security Handbook, SG24-6316. 

9.2 Horizontal attribute propagation 

This section presents horizontal attribute propagation. It describes the concept, 

how it works, the implementation, and highlights some cross-cell considerations. 

9.2.1 Horizontal attribute propagation description 

In horizontal propagation, security attributes are propagated among front-end 

servers. The serialized security attributes, which are the JAAS subject contents 

and the propagation tokens, can contain both static and dynamic attributes. The 

single sign-on (SSO) token stores additional system-specific information that is 

needed for horizontal propagation. The information contained in the SSO token 


tells the receiving server where the originating server is located and how to 

communicate with that server. Additionally, the SSO token also contains the key 

to look up the serialized attributes. 

The benefit of using horizontal attribute propagation is that you do not need to 

perform any remote user registry calls during a propagation login because the 

application server can regenerate the JAAS subject from the serialized 

information. Without this ability, the application server might make five to six 

separate remote calls. It is also very useful if you need to gather dynamic 

security attributes set at the original login server that cannot be regenerated at 

the other front-end server. 

The serialized information of the security attributes is automatically propagated 

to all the servers within the same Data Replication Service (DRS). 

For making horizontal attribute propagation a reality, WebSphere Application 

Server for z/OS relies on two mechanisms: 

► DynaCache 

WebSphere creates a private security cache in DynaCache. All JAAS 

subjects are placed in this cache and replicated in the replication domain 

(such as the application server cluster). During a propagation login, 

WebSphere retrieves the unique cache key from the single sign-on token. 

WebSphere is then able to retrieve the JAAS subject from the replicated 

security cache. The security cache lifetime is the same as the single sign-on 

token lifetime. 

► JMX 

During a propagation login, if WebSphere cannot find the JAAS subject in the 

security cache, it uses JMX to query the server where the initial login 

happened and that created the original JAAS subject. JMX is the fallback 

solution. WebSphere finds the original server address in the single sign-on 

token. 

If JMX fails, WebSphere falls back to an initial login in order to recreate the JAAS 

subject. In this case security attribute propagation does not occur, but identity 

propagation (or single sign-on) still occurs because the user identity is stored in 

the single sign-on token. The login modules are called to recreate the JAAS 

subject but the user does not have to re-authenticate. 

There are some performance implications of enabling horizontal propagation. 

Enabling Web inbound propagation eliminates some user registry calls. 

However, the deserialization and the decryption of tokens are intensive tasks 

and may impact performance. We recommended that you run performance tests 

in your environment with a typical number of users with the propagation enabled 


and with propagation disabled to determine the performance implications and the 

best solution to implement. 

9.2.2 Horizontal attribute propagation in action 

In this section we describe how horizontal attribute propagation works with an 


Figure 9-2 Horizontal security attribute propagation in action 

In this example, server 1 and server 2 are part of the same data replication 

service. Server 3 and server 4 are part of the same data replication service. 

The example scenario goes through the following steps: 

1. An user accesses a Web application in server 1. He first authenticates with 

server 1. This is an initial login. The user provides his credentials. 

2. Server 1 creates a JAAS subject with the login module. 

3. Server 1 converts this JAAS subject in serialized tokens and places it in 

DynaCache and in the security cache. 

4. The JAAS subject is replicated via data replication service (DRS), if this is 

configured (within a WebSphere cluster for example). 


5. Server 1 creates the single sign-on token that represents this subject. It 

contains the user uniqueid and time stamp, optional custom key information, 

and the application server’s JMX administrative endpoint. 

6. Server 1 sends this single sign-on token to the user’s browser in the form of a 

cookie (LtpaToken2). 

7. The user then accesses another Web application in server 3. This is a 

propagation login. The browser sends the single sign-on token along with the 

request. 

8. Server 3 retrieves the user identity, and retrieves the uniqueid and the original 

server JMX endpoint from the single sign-on token. 

9. Server 3 tries to find the security context information in the local security 

cache. Because the user did not use this server 3 before, it cannot find it. 

10.Server 3 tries to find the security context information in the DynaCache. 

Because DRS is not configured between server 1 and server 3, it cannot find 

it. 

11.Server 3 then makes a JMX call to the original server to retrieve the serialized 

JAAS subject. 

12.Server 3 creates the subject containing all the security context information 

found in the original server 1. 

9.2.3 Horizontal attribute propagation implementation 

To enable horizontal propagation, you must configure the single sign-on token 

and the Web inbound security attribute propagation features. You can configure 

both of these features using the admin console. 

Complete the following steps to configure WebSphere Application Server for 

z/OS for horizontal propagation. This configuration has to be done on every 

WebSphere server participating in the horizontal attribute propagation. 

1. Launch the administrative console and log in. 

2. Navigate to Security → Secure administration, applications, and 

infrastructure → Web security → Single Sign-On (SSO). 

3. If not already checked, check the Enabled check box so that single sign-on 

occurs using an LTPA token. 

4. Earlier versions of WebSphere Application Server did not support security 

attribute propagation. They used an old LTPA token for single sign-on 

purposes. If you need to interoperate with such servers, select the 

Interoperability Mode option. WebSphere Application Servers that do not 

support security attribute propagation receive the LTPA token and the 

propagation token, but ignore the security attribute information that they do 


not understand. The interoperability mode option generates the 

authentication token (old LtpaToken) containing the user identity only. 

5. Check the option for Web inbound security attribute propagation. This 

option enables horizontal propagation. This option generates the single 

sign-on token (new LtpaToken2) containing the user identity, the uniqueid, 

and the original server JMX address. 

6. Click Apply and save the configuration in the master repository. 

Figure 9-3 Horizontal attribute propagation configuration 

With the Web inbound security attribute propagation enabled, the security 

attributes of the originating server where the initial login occurred will get 

propagated to the receiving server. These security attributes include any custom 

attributes or tokens that are set in the custom login modules in the login server. 

9.2.4 Cross-cell considerations 

Single sign-on and security attribute propagation rely on the usage of LTPA 

tokens. These tokens are encrypted using LTPA keys. By default these keys are 

automatically generated and shared among all application servers in the same 

cell. This is the reason why all application servers in one cell are able to generate 

and encrypt or decrypt and read any LTPA token generated by another. Single 

sign-on and security attribute propagation happens sharing one set of LTPA keys 


in the cell. In a deployment manager configuration, the LTPA keys generated at 

the deployment manager level are automatically replicated to all servers’ 

members of the same cell. 

In a multiple-cell environment, LTPA keys and security configurations are likely 

to be different by default and need some adjustment to be able to communicate. 

Cross-cell identity propagation or single sign-on 

As described before, identity propagation or single sign-on relies on the single 

sign-on token (new LtpaToken2) or on the authentication token (old LtpaToken) 

for backwards compatibility. The user identity is stored encrypted in this token. 

For cross-cell single sign-on to happen, all servers must be able to decrypt the 

single sign-on token (new LtpaToken2). Hence, they must all share the same 

LTPA key. If LTPA keys are generated separately in every cell, then all LTPA 

keys are different, and servers from one cell are not able to decrypt single 

sign-on tokens coming from other cells. See Figure 9-4. 

Figure 9-4 Cross-cell identity propagation or single sign-on and LTPA tokens 

To share the same LTPA key, it is necessary to generate the LTPA key once in 

one cell, to export this LTPA key, and to import this LTPA key in any other cell 

that you want to single sign-on with. Then all servers share the same LTPA, and 

they are all able to decrypt the LTPA token coming from another. 

This applies to identity propagation among front-end servers (horizontal with 

HTTP and cookies) and for identity propagation to back-end servers (vertical or 

downstream with RMI-IIOP or Web services and tokens). 


In order to have all cells share the same LTPA keys, follow these steps: 

1. Generate the LTPA keys in one initial cell. From the deployment manager 

administrative console, navigate to Secure administration, applications, 

and infrastructure → Authentication mechanisms and expiration and 

click Generate. Save the changes to the master configuration. 

2. Export the LTPA keys from this initial cell. From the deployment manager 


and infrastructure → Authentication mechanisms and expiration. Under 

Cross-cell single sign-on, specify a password for the key file. Enter a key file 

name and path in an HFS. Click Export. 

Figure 9-5 Cross-cell single sign-on key transfer 

3. Transfer the key file in binary format to the deployment manager of the target 

cell. 

4. Import the LTPA keys to this target cell. From the deployment manager 


and infrastructure → Authentication mechanisms and expiration. Under 

Cross-cell single sign-on, specify the same password for the key file. Enter 

the transferred key file name and path in an HFS. Click Import. Save the 

changes to the master configuration. 

5. Repeat the last two steps with any other cell that you want to single sign-on 

with. 

Attention: If you choose to use automatically generated keys in Secure 

administration, applications, and infrastructure → Authentication mechanisms 

and expiration → Key set groups → NodeLTPAKeySetGroup, then every time 

a new set of keys is generated, you have to redo this process. 


Cross-cell horizontal attribute propagation 

For cross-cell attribute propagation to happen, identity propagation or single 

sign-on is a prerequisite. Hence, the process described in the preceding section 

has to be executed. 

Horizontal attribute propagation implies the usage of JMX calls. If you are using 

JMX across cells then a great deal of trust is implied between the cells. In 

addition to the requirement for shared LTPA encryption keys, the cell level server 

identities end up with substantial authority across the cell boundaries. This is 

because, as with any administrative call, the JMX call requires authentication 

and authorization. 

For the remote JMX administration call across the cell to succeed, the two cells 

must share a common security infrastructure, registries, SSL Keys, and so on. 

Also, the cell’s security server ID must have administrative access to the remote 

cell. All cells must completely trust each other. Each has administrative authority 

over the other. The same behavior holds with propagation within a cell, but in that 

case there is no issue because servers within a cell already trust each other and 

share a common administrative identity. 

9.3 CSIv2 standard identity assertion 

9.3.1 CSIv2 

Note: This does not apply when vertical or downstream attribute propagation 

occurs using IIOP. In that case the upstream server simply sends the 

complete serialized subject to the downstream server. No JMX callbacks are 

required. 

This section presents CSIv2 standard identity assertion. It describes CSIv2, 

CSIv2 identity assertion, how identity assertion works, and the implementation. 

This section also presents the scenario we implemented in our environment. 

Common Secure Interoperability version 2 (CSIv2) is a standard security 

protocol for RMI-IIOP communication. CSIv2 defines the Security Attribute 

Service (SAS) that enables interoperable authentication, delegation, and 

privileges. CSIv2 supports SSL and interoperability across J2EE vendors. CSIv2 

is the authentication protocol of choice for the EJB container. 


The following Common Secure Interoperability Version 2 features are available 

in WebSphere Application Server for z/OS: 

► Transport layer authentication 

This authenticates credential information and sends that information at the 

transport layer across the network so that a receiving server can interpret it. 

► Message layer authentication 

This authenticates credential information and sends that information at the 

message layer across the network so that a receiving server can interpret it. 

► Identity assertion 

This supports a downstream server in accepting the client identity that is 

established on an upstream server, without having to authenticate again. The 

downstream server trusts the upstream server. We describe this feature in 

9.3.2, “CSIv2 standard identity assertion description” on page 307. 

► Security attribute propagation 

This supports the use of tokens to propagate serialized subject contents. 

Propagating security attributes prevents downstream logins from having to 

make user registry calls to look up these attributes. Propagating security 

attributes is also useful when the security attributes contain information that is 

only available at the time of authentication. This information cannot be 

located using the user registry on downstream servers. We describe this 

feature in 9.4, “Vertical attribute propagation with CSIv2” on page 328. 

The standard CSIv2 protocol defines three layers: the transport layer, the 

message layer, and the attribute layer, as shown in Figure 9-6. 

Figure 9-6 CSIv2 layers and authentication possibilities 


CSIv2 offers multiple authentication mechanisms depending on the layer being 

used: 

► At the transport layer level, SSL client certificate authentication (mutual 

authentication) can be used. This authentication occurs during the connection 

handshake using SSL certificates. The advantage of using a certificate is 

increased authentication performance. The disadvantage is the complexity of 

configuring each client with the proper keystore. 

► At the message layer level, basic authentication or mechanism-specific 

format tokens such as the LTPA token can be used. 

► At the attribute layer level, an identity token when doing identity assertion can 

be used. 

Authentication mechanisms from different layers can be used simultaneously. 

When several mechanisms are being used simultaneously, the target JAAS 

subject contains the identity provided at the attribute layer if any, or at the 

message layer if any, or at the transport layer of any. For example, when doing 

identity assertion, basic authentication can be used at the message layer level to 

create the trust relationship, and the user identity would flow at the attribute 

layer. Hence, the JAAS subject contains the identity provided at the attribute 

layer. 

CSIv2 authentication can be used by a J2EE thick client on an user workstation 

to authenticate to an EJB container. Or it can be used between J2EE servers to 

authenticate to an EJB container. 

9.3.2 CSIv2 standard identity assertion description 

Identity assertion (or ID assertion) is a mechanism that allows the propagation of 

an already authenticated identity from one server to another. ID assertion is 

different from the other authentication methods in that it is based on a trust 

relationship between the sender of the identity and the receiver. The receiver can 

assume that the identity has been authenticated, because he trusts the sender. 

You can use ID assertion when an intermediary server must invoke a service 

from a downstream server on behalf of the client. The intermediary server 

establishes a trust relationship with the downstream server (using authentication, 

for instance, but not necessarily) and then is recognized as a trusted partner by 

the downstream server. The intermediary server can then assert the client 

identity to the downstream server. 

Identity assertion is particularly well suited for end-to-end security solutions. 

CSIv2 identity assertion is standard. This means that it can be used across J2EE 

vendor application servers. 


CSIv2 allows a client identity to be asserted to a downstream server. This is 

beneficial when propagating user identities from one server to a downstream 

server using RMI-IIOP. This can also be beneficial when there is no common 

authentication token that can be sent at the message layer for interoperability. 

With identity assertion, the authenticated user in one server is validated by the 

downstream server. Hence, users’ identities must be known by both servers. 

Asserted identity 

The asserted identity flows in the attribute layer. WebSphere Application Server 

for z/OS supports the following identity formats: 

► SAF identity 

This is a raw user identity. It is typically used with the local operating system 

user registry. 

► Distinguished name 

This is typically used when LDAP is the user registry. 

► Certificate 

This is typically used when client certificate authentication is configured in the 

front-end server. 

Trust relationship 

Identity assertion relies on the trust relationship between an intermediary server 

and a downstream server. Because of this, the downstream server trusts the 

intermediary server and accepts the asserted identity. 

With CSIv2 standard identity assertion, the trust relationship can be established 

in different ways: 

► At the message layer level using basic authentication or a LTPA token. 

► At the transport layer level using client certificate authentication (mutual 

authentication). 

► Outside of the CSIv2 protocol, assuming that the trust is enforced outside of 

the CSIv2 flow itself. Trust can be enforced at the network level, for instance. 

For example, network appliances such as firewalls can be used to create a 

secured zone in which servers trust each others. 


9.3.3 CSIv2 standard identity assertion in action 

During a CSIv2 identity assertion between an upstream server (outbound server) 

and a downstream server (inbound server), the following happens: 

► The outbound server authenticates to the inbound server to establish trust 

with one of the following mechanisms: 

– Client certificate authentication 

The outbound server’s client certificate must be verifiable by the inbound 

server. The client certificate authority must be connected to the inbound 

server’s keyring. The outbound server’s certificate must be mapped to an 

identity in the inbound server registry. 

– Basic authentication 

The outbound server identity and password must be in the inbound 

server’s registry. 

► The outbound server provides the attribute layer asserted identity only with no 

password. This identity can be a RACF ID, an LDAP DN, a certificate, and so 

on. 

► The inbound server receives the outbound server identity and the asserted 

identity. 

► The inbound server checks whether the outbound server (from the outbound 

server identity) is in its list of trusted servers. If so, it authenticates the 

upstream server. You can use the System Authorization Facility (SAF) CBIND 

class to indicate that a process is trusted to assert identities to WebSphere 

Application Server for z/OS. 

► The inbound server accepts the asserted identity and creates credentials by 

querying the registry. No validation is performed on the asserted identity (no 

password, token, and so on). 

For CSIv2 stateful connections, this checking is done only once. All subsequent 

requests are made through a session ID. 


9.3.4 CSIv2 standard identity assertion implementation 

The CSIv2 protocol requires that the two discussing parties have coherent CSIv2 

configurations. Each communication endpoint needs to be configured for CSIv2. 

For example, a J2EE thick client CSIv2 outbound configuration must match the 

server CSIv2 inbound configuration. And a J2EE server CSIv2 outbound 

configuration must match the receiving server CSIv2 inbound configuration. See 

Figure 9-7. 

Figure 9-7 CSIv2 configuration endpoints 

For a J2EE thick client, the CSIv2 outbound configuration is done in a 

sas.client.props file. Because identity assertion occurs between two servers, we 

focus in this section on how to configure server outbound and inbound endpoints. 

CSIv2 outbound transport 

On the CSIv2 upstream server side, using the administrative console, click 

Security → Secure administration, applications, and infrastructure. Under 

Authentication, click RMI/IIOP security → CSIv2 outbound transport. 


Consider the following options: 

► TCP/IP 

If you select this option, the server opens TCP/IP connections with 

downstream servers only. 

► SSL required 

If you select this option, the server opens SSL connections with downstream 

servers. 

► SSL supported 

If you select this option, the server opens SSL connections with any 

downstream server that supports them and opens TCP/IP connections with 

any downstream servers that do not support SSL. 


For identity assertion, depending on the trust relationship mechanism you want 

to use, you have to choose the transport accordingly. For example, if you want to 

create a trust relationship with SSL client certificate authentication, then you 

need to choose SSL required. If you want to create a trust relationship with basic 

authentication, you may simply use TCP/IP as a transport, although you may 

choose to use SSL for encrypting the communication flow so that identities and 

passwords do not flow in clear. See Figure 9-8. 

Figure 9-8 CSIv2 outbound transport 

If you choose SSL required or supported, you can configure the SSL settings you 

wish to use. 

CSIv2 outbound authentication 

On the CSIv2 upstream server side, using the administrative console, click 


Authentication, click RMI/IIOP security → CSIv2 outbound transport. 


Consider how to create the trust relationship for identity assertion: 


If you select Required for this option, then message-layer authentication 

occurs. This can be basic authentication user ID and password or it can be an 

LTPA token being sent. 

► Client certificate authentication 

If you select Required for this option, then transport-layer SSL client 

certificate authentication occurs. Typically, client certificate authentication has 

a higher performance than message-layer authentication, but requires some 

additional setup. These additional steps include verifying that this server has 

a personal certificate and that the downstream server has the signer 

certificate of this server. 


Figure 9-9 CSIv2 outbound authentication 

For identity assertion to occur, select the Identity assertion check box. The 

identity asserted is the client identity. If there are multiple identity types to assert, 

the identity is asserted in the following order: client certificate, distinguished 

name (DN), System Authorization Facility (SAF) user ID. 

Once you check the Identity assertion check box, choose between “Use server 

trusted identity” and “Specify an alternative trusted identity.” 


“Use server trusted identity” specifies the server identity that the application 

server uses to establish trust with the target server. The server identity can be 

sent using a server ID and password when the server password is specified in 

the registry configuration, or using a server ID in an LTPA token when the 

internal server ID is used. 

For interoperability with application servers other than WebSphere, configure the 

server ID and password in the registry, then select the Specify an alternative 

trusted identity option and specify the trusted identity and password so that an 

interoperable Generic Security Services Username Password (GSSUP) token is 

sent instead of an LTPA token. 

“Specify an alternative trusted identity” specifies an alternative user as the 

trusted identity that is sent to the target server instead of sending the server 

identity. This option is recommended for identity assertion. The identity is 

automatically trusted when it is sent within the same cell and does not need to be 

in the trusted identities list within the same cell. However, this identity must be in 

the registry of the target server in an external cell, and the user ID must be on the 

trusted identities list or the identity is rejected during trust evaluation. 

On z/OS systems, the stateful sessions option is ignored. The sending server 

prefers stateful sessions and uses them if the receiving server supports them. 

“Login configuration” specifies the type of system login configuration that is used 

for outbound authentication. You can add custom login modules before or after 

this login module. “Custom outbound mapping” enables the use of custom RMI 

outbound login modules. The custom login module maps or performs other 

functions before the predefined RMI outbound call. 

“Security attribute propagation” enables the application server to propagate the 

subject and the security context to other application servers. We describe this 

feature in detail in 9.4, “Vertical attribute propagation with CSIv2” on page 328. 

CSIv2 inbound transport 

On the CSIv2 downstream server side, using the administrative console, click 


Authentication, click RMI/IIOP security → CSIv2 inbound transport. 


Consider the following options: 

► TCP/IP 

If you select this option, the server opens a TCP/IP listener port only and all 

inbound requests do not have SSL protection. 

► SSL required 

If you select this option, the server opens an SSL listener port only and all 

inbound requests are received using SSL. You might want to take advantage 

of the CBIND class in RACF so that the certificate-mapped user identity must 

be allowed to this facility class. 

► SSL supported 

If you select this option, the server opens both a TCP/IP and an SSL listener 

port. 

This configuration has to match the CSIv2 client server configuration. 


For identity assertion, depending on the trust relationship mechanism you want 

to use, you have to choose the transport accordingly. For example, if you want to 

create a trust relationship with SSL client certificate authentication, then you 

need to choose SSL required. If you want to create a trust relationship with basic 

authentication, you may simply use TCP/IP as a transport, although you may 

choose to use SSL for encrypting the communication flow so that identities and 

passwords do not flow in clear. 

Figure 9-10 CSIv2 inbound transport 

If you choose SSL required or supported, you can configure the SSL settings you 

wish to use. 

CSIv2 inbound authentication 



Authentication, click RMI/IIOP security → CSIv2 inbound transport. 


Consider how to create the trust relationship for identity assertion: 


If you select Required for this option, then message-layer authentication 

occurs. This can be a basic authentication user ID and password or it can be 

an LTPA token being sent. 

► Client certificate authentication 

If you select Required for this option, then transport layer SSL client certificate 

authentication occurs. Typically, client certificate authentication has higher 

performance than message layer authentication, but requires some additional 

setup. These additional steps include verifying that this server has a personal 

certificate and that the downstream server has the signer certificate of this 

server. When the certificate is authenticated to a local OS user registry, the 

certificate is mapped to the user ID in the registry. 


This configuration has to match the CSIv2 client server configuration. See 

Figure 9-11. 

Figure 9-11 CSIv2 inbound authentication 

For identity assertion to occur, select the Identity assertion check box. The 

identity asserted is the client identity. 

In Trusted identities, specify a semicolon-separated (;) or comma-separated (,) 

list of trusted server IDs, which are trusted to perform identity assertion to this 

server. 

On z/OS systems, the stateful sessions option is ignored. The sending server 

prefers stateful sessions and uses them if the receiving server supports them. 


Login configuration specifies the type of system login configuration to use for 

inbound authentication. You can add custom login modules. 

“Security attribute propagation” enables the application server to propagate the 

subject and the security context to other application servers. We describe this 

feature in detail in 9.4, “Vertical attribute propagation with CSIv2” on page 328. 



Authentication, click RMI/IIOP security → CSIv2 inbound transport → z/OS 

Additional Settings. 

Choose the type of client identities allowed to be asserted from the upstream 

server: 

► System Authorization Facility (SAF) user names 

► Distinguished names (LDAP user identities, for example) 

► X.509 certificates 

This configuration has to match the CSIv2 client server configuration. See 

Figure 9-12. 

Figure 9-12 CSIv2 inbound authentication z/OS additional settings 


9.3.5 Our CSIv2 identity assertion scenario 

We present in this section our CSIv2 identity assertion scenario in our 

environment. 

Our scenario environment 

This section uses an application that helps demonstrate secured RMI-IIOP calls. 

The application is called ejbMagic. See Figure 9-13. 

Figure 9-13 Our environment and the ejbMagic application 

We have two WebSphere Application Servers installed on two different LPARs. 

The ejbMagic application is deployed to the two WebSphere servers. Both 

WebSphere servers use the local operating system user registry (RACF). In this 

scenario, WebSphere Application Server v6.0 is used. Note that some 

configuration panels differ from WebSphere Application Server v6.1. 

The ejbMagic application does some local EJB calls and some remote EJB calls. 

It can be deployed into multiple WebSphere cells, and then used to call itself to 

help verify inter-WebSphere cell communication. The SnoopMagicEjb EJB 

consists of a method called snoopInfo. This is the method that gathers the 

information such as Java principal, and so on, and calls the remote EJB. In 

addition, four other EJB methods allow the testing of different RunAs settings 

(siNoRunAs, siRunAsServer, siRunAsCaller, siRunAsRoleWorker). 

Our CSIv2 setup for identity assertion 

The sending server needs to be configured to allow identity assertion, and the 

receiving server needs to be configured to allow it to receive an asserted identity. 

In this configuration, the trust relationship is presumed and is not configured at 

the CSIv2 message layer or transport layer. So, default values are used at the 


transport and at the message-layer level. Basic authentication and client 

certificate authentication are supported. But because they are not configured in 

this scenario, they are not used. 

On the upstream server, we check the Identity Assertion check box. Because 

we use the local operating system user registry (RACF), a SAF identity is 

asserted in the CSIv2 attribute layer. See Figure 9-14. 

Figure 9-14 Scenario CSIv2 outbound authentication 

For more information about how to configure this panel, refer to 9.3.4, “CSIv2 

standard identity assertion implementation” on page 310. 


On the downstream server, we check the Identity Assertion check box to 

enable identity assertion. See Figure 9-15. 

Figure 9-15 Scenario CSIv2 inbound authentication 

For more information about how to configure this panel, refer to 9.3.4, “CSIv2 

standard identity assertion implementation” on page 310. 


In the z/OS additional settings for the downstream server, we choose SAF 

identity assertion so that WebSphere Application Server for z/OS can validate 

the incoming identity against the SAF user registry (RACF). See Figure 9-16. 

Figure 9-16 Scenario CSIv2 inbound additional settings 


Our EJBMagic scenario in action 

In our scenario, a servlet calls a local EJB and then this local EJB calls a remote 

EJB, as shown in Figure 9-17. 

Figure 9-17 Scenario EJBMagic in action 

The servlet is secured and requires authentication. The user authenticating is 

daubman. Hence, the JAAS principal of the running servlet is daubman. The 

servlet calls the local EJB with a runAs role of worker. This worker role is 

associated with the TIWARI identity. This is done within RACF using the 

APPLDATA field of the EJBROLE profile. Hence, the JAAS principal of the 

running local EJB is TIWARI. The local EJB calls the remote EJB with runAs set 

to caller. This remote EJB call relies on CSIv2 identity assertion to propagate the 

identity in the attribute layer. Hence, the TIWARI SAF identity flows with the 

CSIv2 secured RMI-IIOP call. There is no password flowing. On the downstream 

server side, the asserted identity is validated against the user registry (RACF). 

Because this identity is asserted, WebSphere sets the JAAS principal of the 

running remote EJB to TIWARI. 

We now show the EJBMagic displays that confirm this scenario. 


After authenticating, the EJBMagic choice menu appears. Figure 9-18 shows the 

choice menu. 

Figure 9-18 EJBMagic display 

With our scenario, the local EJB is called by the servlet with the runAs role of 

worker and the remote EJB is called by the local EJB with runAs caller. 

The JNDI value we use for the remote EJB call is the following: 

corbaname::9.12.4.34:22809/NameServiceServerRoot#cell/nodes/nd6622/serv 

ers/ws6622/ejb/itso/em/ejb/SnoopMagicEjbHome 

This value tells the ejbMagic application running in the ws6611 server to pass 

this lookup value to WebSphere to locate the remote EJB in the ws6622 server. 

The 22809 port is the Boostrap port of the ws6622 server. More information 

about how to find the initial context is available in the InfoCenter: 


com.ibm.websphere.zseries.doc/info/zseries/ae/rnam_example_prop1.html 


We then click the Let’s do some magic button. 

Figure 9-19 shows that the servlet JAAS principal is daubman. This is the user 

who authenticates to the upstream server. 

Figure 9-19 EJBMagic servlet information 

Figure 9-20 shows that the local EJB JAAS principal is TIWARI. It also shows 

that the caller (the servlet) identity was daubman. TIWARI is the runAs role 

worker identity set in the APPLDATA field of the EJBROLE RACF profile. 

Figure 9-20 EJBMagic local EJB information 


Figure 9-21 shows that the remote EJB JAAS principal is TIWARI. It also shows 

that the caller (the local EJB) identity was TIWARI. 

Figure 9-21 EJBMagic remote EJB information 

CSIv2 identity assertion flowed the runAs identity from the upstream server to the 

downstream server. 

9.4 Vertical attribute propagation with CSIv2 

This section presents vertical attribute propagation. It describes the concept, how 

it works, the implementation, and highlights some cross-cell considerations. It 

also shows the differences between CSIv2 identity assertion and vertical 

attribute propagation. 

9.4.1 Vertical attribute propagation with CSIv2 description 

In vertical propagation (also called downstream propagation) security attributes 

are propagated from an upstream server to a downstream server. The serialized 

security attributes, which are the JAAS Subject contents, can contain both static 

and dynamic attributes. Vertical attribute propagation relies on the Remote 

Method Invocation (RMI) over the Internet Inter-ORB Protocol (RMI over IIOP). 

Vertical attribute propagation can then be used when accessing Enterprise Java 

Beans (EJBs) running on a back-end, that is, a downstream server. The security 


attributes are passed to the EJB running on the downstream server by using the 

CSIv2 protocol that is established between the WebSphere Application Servers. 

Basically, vertical attribute propagation enables an upstream server to propagate 

the complete security context, including the client identity and other security 

information and tokens to a downstream server. 

If no attribute propagation is used, servers have to query the user registry or a 

custom login module to get the attributes, and this can be expensive from a 

performance view point. 

Attribute propagation has the benefit of enabling third-party providers to plug in 

custom tokens. It provides the ability to have multiple tokens of the same type 

within a JAAS subject created by different providers. 

CSIv2 is the authentication mechanism used for EJBs, and hence the vertical 

security propagation is enabled in the CSIv2 inbound and outbound panels in the 


9.4.2 Vertical attribute propagation versus CSIv2 identity assertion 

CSIv2 identity assertion propagates the J2EE identity only (JAAS subject 

principal). 

CSIv2 identity assertion is standard. This means it can be used across J2EE 

vendors’ application servers. 

Vertical attribute propagation propagates the full security context (complete 

JAAS subject including the principal and credentials). 

Vertical attribute propagation is WebSphere specific. It relies on a WebSphere 

token framework. Interoperability across J2EE application servers of different 

vendors cannot be guaranteed. Nevertheless, WebSphere provides some login 

configuration (RMI_INBOUND and RMI_OUTBOUND) that can be customized to 

facilitate interoperability. 


9.4.3 Vertical attribute propagation with CSIv2 in action 

In this section, we describe how vertical attribute propagation works with an 


Figure 9-22 Vertical security attribute propagation in action 

In this example there is no data replication service configured between server 1 

and server 5. The example scenario goes through the following steps: 

1. A user accesses a Web application in server 1. He first authenticates with 

server 1. This is an initial login. The user provides his credentials. 

2. Server 1 creates a JAAS subject with the login module. 

3. Server 1 creates the single sign-on token that represents this subject. 


4. The user request accesses a remote EJB located on server 5 with CSIv2. 

Server 1 serializes the complete JAAS subject content with all attributes and 

tokens within the RMI-IIOP request. 

5. Server 5 receives the request and, because tokens are found, executes a 

propagation login. If no token was found it would execute an initial login 

asking for credentials. The propagation login deserializes the complete JAAS 

subject content with all attributes and tokens. 

6. Server 5 creates the subject containing all the security context information 

similar to the security context in the original server 1. This hydrated subject is 

associated with the CSIv2 session for the following requests. 

9.4.4 Vertical attribute propagation with CSIv2 implementation 

To enable vertical propagation, you must configure CSIv2 and security attribute 

propagation. You can configure both of these features using the administrative 

console. Actually, vertical security attribute propagation is configured within the 

CSIv2 configuration. 

Refer to 9.3.4, “CSIv2 standard identity assertion implementation” on page 310 

for a description of the CSIv2 configuration. The CSIv2 identity assertion feature 

does not need to be enabled for vertical security attribute propagation. You can 

uncheck the Identity assertion check box. 

On the upstream server side: 



infrastructure. Under Authentication, click RMI/IIOP security → CSIv2 

outbound authentication. 


3. Check the option for Security attribute propagation (Figure 9-23). This 

option enables vertical or downstream propagation. It serializes the full 

security context within the RMI-IIOP call. 


Figure 9-23 Upstream server vertical attribute propagation configuration 

On the downstream server side: 



infrastructure. Under Authentication, click RMI/IIOP security → CSIv2 

inbound authentication. 


3. Check the option for Security attribute propagation (Figure 9-24). This 

option enables vertical or downstream propagation. It deserializes the full 

security context within the RMI-IIOP call. 


Figure 9-24 Downstream server vertical attribute propagation configuration 

With the security attribute propagation enabled, the security attributes of the 

originating server where the initial login occurred get propagated to the 

downstream server. These security attributes include any custom attributes or 

tokens that are set in the custom login modules in the login server. 


9.4.5 Cross-cell considerations 

Security attribute propagation relies on the usage of LTPA tokens. These tokens 

are encrypted using LTPA keys. By default, these keys are automatically 

generated and shared among all application servers in the same cell. This is the 

reason why all application servers in one cell are able to generate and encrypt or 

decrypt and read any LTPA token generated by another. Security attribute 

propagation happens sharing one set of LTPA keys in the cell. In a deployment 

manager configuration, the LTPA keys generated at the deployment manager 

level are automatically replicated to all servers’ members of the same cell. 

In a multiple cells environment, LTPA keys and security configurations are likely 

to be different by default and need some adjustment to be able to communicate. 

Refer to “Cross-cell identity propagation or single sign-on” on page 303 for how 

to configure LTPA keys across cells. 

“Cross-cell horizontal attribute propagation” on page 305 does not apply to 

vertical security attribute propagation because no JMX call is involved in vertical 

attribute propagation. 


Chapter 10. User registries 

User registries or repositories are essential to security architectures. They 

contain critical users and groups information. WebSphere Application Server for 

z/OS v6.1 provides some flexible features to access different types of registries. 

The new federated repositories functionality extends even more its capabilities. 

This chapter describes the following topics: 

► “Introduction to user registries” on page 336 

► “Our scenario and our environment” on page 339 

► “Standalone LDAP registry” on page 340 

► “Federated repositories” on page 363 

► “z/OS local operating system registry” on page 382 

10 


10.1 Introduction to user registries 

In WebSphere Application Server for z/OS, a user registry or repository 

authenticates a user and retrieves information about users and groups to 

perform security-related functions, including authentication and authorization. 

The information about users and groups resides within a registry or repository. 

WebSphere Application Server for z/OS v6.1 provides implementations that 

support multiple types of registries and repositories: 

► Local operating system 

► Standalone LDAP registry 

► Standalone custom registry 

► Federated repositories 

With WebSphere Application Server for z/OS, a user registry or repository is 

used for: 

► Authenticating a user using basic authentication, identity assertion, client 

certificates, tokens 

► Retrieving information about users and groups to perform security-related 

administrative functions, such as mapping users and groups to security roles 

Although the WebSphere Application Server supports different types of user 

registries, only one user registry can be active. This active registry is shared by 

all of the product server processes within a cell. 

Local operating system registry 

WebSphere Application Server for z/OS uses the System Authorization Facility 

(SAF) interfaces. SAF interfaces are defined by z/OS to enable applications to 

use system authorization services or registries to control access to resources 

such as data sets and z/OS commands. SAF allows security authorization 

requests to be processed directly through the Resource Access Control Facility 

(RACF) or a third-party z/OS security provider. 

Unlike the distributed platforms, the local operating system registry on the z/OS 

platform can be used in a multiserver z/OS environment, since the security 

database can be easily shared across the sysplex. In such a configuration, 

multiple WebSphere z/OSs on different LPARs share the same security 

database. 

The local operating system registry on z/OS is compatible with z/OS Enterprise 

Information Systems such as CICS, IMS, and DB2. This is major benefit when 

flowing the original identity from WebSphere Application Server for z/OS to 

back-end EIS. 


When should you use a local operating system registry? 

► When the authenticated users are present in the local security subsystem 

(intranet) 

► When the best performance available is mandatory 

► When comprehensive end-to-end security is needed (user ID existing in the 

Web server, Web container, EJB container, and back-end system) 

► When good auditing support is needed 

► When the users and application security need to be managed by the RACF 

security administrators 

► When OS thread security or thread identity support are needed 

Standalone LDAP registry 

Lightweight Directory Access Protocol (LDAP) is widely used in a distributed 

environment where multiple servers need access to a central user registry. This 

is an option on z/OS as well. 

This functionality allows a more versatile WebSphere environment, making room 

for cross-platform integration by allowing the use of existing user registries and 

authorization tables with the security functions in WebSphere Application Server. 

LDAP servers act as a repository for user and group information. WebSphere 

Application Server for z/OS binds to the LDAP server to retrieve this user and 

group information. This support is provided by using different user and group 

filters. These filters are highly configurable to be able to access all sorts of LDAP 

servers. 

LDAP servers are incompatible with z/OS Enterprise Information Systems such 

as CICS, IMS, and DB2. Hence, some more complex steps are required to 

access these systems with the user identity. 

When should you use a LDAP registry? 

► When a single sign-on solution with a distributed system is needed 

► When a registry on other platforms should be used 

► When a cross-platform authentication mechanism is mandatory 

► When only one user identity must be maintained across multiple 

environments 

► When RACF identities have to be used on distributed platforms through a 

central z/OS LDAP SDBM back end. 

► When RACF passwords need to be checked on distributed platforms through 

a central z/OS LDAP TDBM back end with native authentication 

Chapter 10. User registries 337

Standalone custom registry 

A standalone custom registry is a customer-implemented registry that 

implements the UserRegistry Java interface, as provided by the product. A 

custom-implemented registry can support virtually any type of account 

repositories from relational databases to flat files and so on. The custom user 

registry provides flexibility in adapting product security to various environments 

where some form of a registry or repository other than federated repositories, a 

standalone Lightweight Directory Access Protocol (LDAP) registry, or a local 

operating system registry already exists in the operational environment. 

It allows you to plug in any kind of registry whose support is not implemented by 

WebSphere Application Server security. 

A custom registry is written as a Java program that implements a WebSphere 

Application Server for z/OS supplied com.ibm.websphere.security.UserRegistry 

interface. The implementation should not be dependent on WebSphere 

Application Server resources (for example, datasources). 

Federated repositories 

This registry type is new with WebSphere Application Server for z/OS v6.1. 

Federated repositories enable us to use simultaneously multiple repositories with 

WebSphere Application Server for z/OS. These repositories, which can be 

file-based repositories, LDAP repositories, or a sub-tree of an LDAP repository, 

are defined combined under a single realm. All of the user repositories that are 

configured under the federated repository functionality are transparent to 


The federated repositories functionality in WebSphere Application Server for 

z/OS supports the logical joining of entries across multiple user repositories 

when the application server searches and retrieves entries from the repositories. 

For example, when an application calls for a sorted list of people whose age is 

greater than twenty, WebSphere Application Server for z/OS searches all of the 

repositories in the federated repositories configuration. The results are combined 

and sorted before the application server returns the result to the application. 

Unlike the local operating system, standalone LDAP registry, or custom registry 

options, federated repositories provide user and group management with read 

and write capabilities. If you do not configure the federated repositories 

functionality or do not enable federated repositories as the active repository, you 

cannot use the user management capabilities that are associated with federated 

repositories. 

More information about federated repositories is provided in 10.4.1, “What 

federated repositories are” on page 363. 


10.2 Our scenario and our environment 

This chapter focuses on showing how to configure WebSphere Application 

Server for z/OS with different registry types. For this purpose we define a LDAP 

tree whose goal is to be accessed by WebSphere Application Server for z/OS in 

different manners, illustrating typical WebSphere configurations. This LDAP tree 

is shown in Figure 10-1. 

Figure 10-1 Our scenario LDAP tree and supporting LDAP servers 


This LDAP tree common root organization is o=itso. This LDAP tree possess 

three organization units, which are ou=itsoitds, ou=itsotdbm, and ou=itsoracf, as 

follows: 

► The itsoitds organization unit is supported by a IBM Tivoli Directory Server v6 

(ITDS). DB2 v8.2 is used as a back end. This server runs on a Windows 

server. The suffix of this subtree is ou=itsoitds,o=itso. 

► The itsotdbm organization unit is supported by a z/OS LDAP TDBM server. 

DB2 z/OS v8 is used as a back end. This server runs on z/OS v1r8. The suffix 

of this subtree is ou=itsotdbm,o=itso. This server has one user configured for 

native authentication, which means that his password is checked against the 

RACF database. 

► The itsoracf organization unit is supported by a z/OS LDAP SDBM server. 

The RACF database is used as a back end. This server runs on z/OS v1r8. 

The suffix of this subtree is ou=itsoracf,o=itso. 

These organization units possess one or two users. 

In this chapter we describe how to configure WebSphere Application Server for 

z/OS v6.1 to use some parts of this LDAP tree as a user registry. More 

specifically we explain how to configure: 

► A standalone LDAP registry with WebSphere and z/OS LDAP SDBM back 

end (RACF). 

► A standalone LDAP registry with WebSphere and z/OS LDAP TDBM back 

end (DB2). 

► A standalone LDAP registry with WebSphere and z/OS LDAP TDBM native 


► A federated repositories including Federated z/OS LDAP with TDBM back 

end (DB2) and Federated IBM Tivoli Directory Server. 

10.3 Standalone LDAP registry 

The Standalone LDAP registry feature in WebSphere Application Server for z/OS 

v6.1 is similar to the LDAP registry feature existing in v5 and v6.0. 

In this section we show how to configure the WebSphere Standalone LDAP 

registry with z/OS LDAP SDBM, with z/OS LDAP TDBM with Native 

Authentication or not, and with ITDS. 


10.3.1 WebSphere and z/OS LDAP SDBM back end (RACF) 

z/OS LDAP can handle many different types of back ends. One of them is SDBM, 

and it uses the RACF database as a data repository. 

With a SDBM back end, RACF user profiles, group profiles, and user to groups 

connections appear as LDAP entries with distinguished name to LDAP clients. All 

binds are authenticated with a RACF distinguished name and a RACF password. 

z/OS LDAP SDBM supports add, modify, delete, and search operations. The 

access controls for user and group profiles are the RACF privileges of the 

authenticated user. 

z/OS LDAP SDBM configuration 

The z/OS LDAP installation is described in Distributed Security and High 

Availability with Tivoli Access Manager and WebSphere Application Server for 

z/OS, SG24-6760. In this section we focus on the configuration part. 

1. For configuring z/OS LDAP with an SDBM back end, find the LDAP 

configuration that should be in the SLAPDCNF member of the LDAP 

customization data set. In our environment, the z/OS LDAP configuration file 

is WTSC58.LDAP1.CNTL(SLAPDCNF). In this LDAP configuration file, 

uncomment or set up the following parameters: 

database sdbm GLDBSDBM 

suffix "ou=itsoracf,o=itso" 

where the suffix is the top of the LDAP tree you want for your organization. 

We choose ou=itsoracf,o=itso in our environment. The suffix does not 

necessarily need to have an organization unit (ou=). It may contain an 

organization only (o=). 

Example 10-1 shows an extract of our z/OS LDAP configuration for using a 

SDBM back end. 

Example 10-1 z/OS LDAP configuration with a SDBM back end 

listen ldap://:3389 

maxConnections 60 

adminDN "cn=LDAP Administrator" 

adminPW "secret" 

# SDBM-specific CONFIGURATION SETTINGS 

database sdbm GLDBSDBM 

suffix "ou=itsoracf,o=itso" 


2. Restart the z/OS LDAP server from SDSF, for instance. If your LDAP server is 

configured properly with a SDBM back end, there should be a message 

similar to Example 10-2 in the LDAP log at startup. 

Example 10-2 z/OS LDAP log with a SDBM back end 

Backend type: sdbm, Backend ID: SDBM BACKEND 

SDBM BACKEND manages the following suffixes: 

Backend suffix: OU=ITSORACF,O=ITSO 

End of suffixes managed by SDBM BACKEND. 

Capability: LDAP_Backend_ID Value: SDBM BACKEND 

Capability: LDAP_Backend_BldDateTime Value: 

2006-04-18-15.18.14.000000 

Capability: LDAP_Backend_APARLevel Value: OA15948 

Capability: LDAP_Backend_Release Value: R 6.0 

Capability: LDAP_Backend_Version Value: V 1.0 

Capability: LDAP_Backend_Dialect Value: DIALECT 1.0 

Capability: LDAP_Backend_BerDecoding Value: STRING 

Capability: LDAP_Backend_ExtGroupSearch Value: YES 

Capability: LDAP_Backend_krbIdentityMap Value: YES 

Capability: supportedControl Value: 2.16.840.1.113730.3.4.2 

Capability: supportedControl Value: 1.3.18.0.2.10.2 

End of capability listing for Backend type: sdbm, Backend ID: SDBM 

BACKEND. 

Backend capability listing ended. 

Configuration file successfully read. 

3. We now validate that the SDBM is functional by accessing it from an LDAP 

client. 

The native LDAP commands are cumbersome to run from UNIX System 

Services. A simpler way to access LDAP is to use an independently 

developed LDAP browser client, which you can download from: 

http://www-unix.mcs.anl.gov/~gawor/ldap/ 

Configure the LDAP client connection such as the following: 

Host : wtsc58.itso.ibm.com 

Port : 3389 

Base DN : ou=itsoracf,o=itso 

User DN : racfid=valence,profiletype=user,ou=itsoracf,o=itso 

User password : xxxxxxx 

The SDBM schema requires the RACF user distinguished name to follow this 

template: 

racfid=,profiletype=user, 


The RACF user ID being used (valence in our example) must have the proper 

access to list users and groups from the RACF database. It should be a 

RACF user ID with the AUDITOR attribute, a valid OMVS segment (specific 

or implied by a defaulted segment), and it does not need a TSO segment. 

See Figure 10-2. 

Figure 10-2 LDAP client connection configuration for SDBM back end 

Using this configuration, we access the RACF content displayed as an LDAP 

tree. All the RACF user IDs and groups can be accessed. See Figure 10-3. 

Figure 10-3 LDAP client showing z/OS LDAP SDBM back-end (RACF) content 


WebSphere z/OS configuration for z/OS LDAP SDBM 

WebSphere Application Server for z/OS supports accessing z/OS LDAP with a 

SDBM back end (RACF) when configured as a Standalone LDAP registry. In this 

section we explain how to configure WebSphere in order to access z/OS LDAP 

SDBM. 

1. Within the administrative console, click Security → Secure administration, 

applications and infrastructure. Under User account repository, select 

Standalone LDAP registry and then click Set as current. The Standalone 

LDAP registry then appears in the Current realm definition field (Figure 10-4). 

Figure 10-4 WebSphere user account repository 

Verify that administrative security is enabled and also that application security 

is enabled if necessary. Click Apply on this page to keep these settings. 

2. Click Configure and set up the general properties for the z/OS LDAP server: 

– Primary administrative user name: This ID is the security server ID, which 

is only used for WebSphere Application Server administrative security and 

is not associated with the system process that runs the server. We use 

racfid=valence,profiletype=user,ou=itsoracf,o=itso in our environment. 

This primary user name will be used to log on to the administrative 

console, for example. 

– Server user identity: Select Automatically generated server identity in a 

WebSphere 6.1 only environment. 

– Type of LDAP server: Select Custom. 

– Host and port: Enter the full DNS host name and TCP port to access z/OS 

LDAP. We use wtsc58.itso.ibm.com and 3389 in our environment. 

– Base distinguished name (DN): The base DN indicates the starting point 

for searches in this LDAP directory server. It is the suffix ou=itsoracf,o=itso 

in our environment. 

– Bind distinguished name (DN) and password: The bind DN is required if 

anonymous binds are not possible on the LDAP server to obtain user and 

group information. We use 

racfid=mogos,profiletype=user,ou=itsoracf,o=itso in our environment. This 


is a technical user identity to connect to LDAP. This identity is allowed to 

list RACF users and groups. 

– Make sure that Ignore case for authorization is selected. RACF user 

names and group names are not case-sensitive. 

Then click Apply. 

Figure 10-5 WebSphere configuration for z/OS LDAP SDBM 


3. In the same window, under Additional Properties, click Advanced 

Lightweight Directory Access Protocol (LDAP) user registry setting and 

configure the properties: 

– Change user filter and group filter to racfid=%v. 

– Change user ID map and group ID map to *:racfid. 

– Change group member ID map to 

racfconnectgroupname:racfgroupuserids. 

Click OK. 

Figure 10-6 WebSphere advanced configuration for z/OS LDAP SDBM 

4. Save the changes in the master repository and restart WebSphere 


WebSphere and z/OS LDAP SDBM back-end validation 

After restarting WebSphere Application Server for z/OS, log in to the 

administration console with the primary administrative user name defined earlier. 

It is possible to use the full distinguished name 

(racfid=valence,profiletype=USER,ou=itsoracf,o=itso in our example) or the user 

name only (valence). The user name only is a RACF identity. 


It is also possible to validate the user registry being used with the snoop servlet, 

which is bundled in WebSphere for z/OS. With application security enabled, the 

snoop servlet requires basic authentication. Call the snoop with a URL such as 

the following: 

http://wtsc58.itso.ibm.com:49080/snoop/ 

Authenticate providing a z/OS LDAP SDBM user name and password (RACF 

user name and password) (Figure 10-7). The snoop servlet then appears and 

shows the authenticatedprincipal. 

Figure 10-7 Snoop servlet authentication with a RACF user ID 

Once authenticated, the snoop servlet displays lots of information and more 

specifically the authenticated user (valence in our example). See Figure 10-8. 

Figure 10-8 Snoop servlet showing authenticated RACF user ID 


WebSphere, LDAP SDBM, and SAF authorization 

When LDAP is the configured user registry it is common to bind users and 

groups to J2EE roles at application deploy time. Bindings to administrative and 

naming roles are usually done through the admin console. These bindings are 

referred to as WebSphere bindings. In the case of LDAP SDBM, all users and 

groups need to be existing RACF identities. 

z/OS has a strong tradition in security and security administration. RACF 

administrators might not agree with the fact that a deployer (or even the 

development team, if users and groups are already mapped to J2EE roles in the 

applications’ descriptors) has the authority to decide which RACF group or user 

ID can be authorized to which J2EE role. The mapping of users and groups to 

roles at deploytime, or searching for users and groups in the RACF database, is 

done under credentials of the bind distinguished name (BDN), which the user ID 

must have the AUDITOR attribute for. Therefore audit trails only lead to that BDN 

identity, not the identity of the deployer. 

This section describes how to set up SAF authorization as an alternative to 

WebSphere bindings in combination with LDAP SDBM as the configured user 

registry. 

Note: SAF authorization combined with LDAP SDBM UR has been 

successfully tested on WebSphere for z/OS v6.0.2. Configuration steps are 

described for v6.0.2, but are similar to v6.1. Differences between the two 

versions are highlighted. 

Only a few steps are required to configure SAF authorization: 

1. Configure WebSphere to use SAF authorization: 

– v6.0: Go to Security → Global Security. Under User registries choose 

LDAP → custom properties. Set the value of 

com.ibm.security.SAF.authorization to true. 

– v6.1: Go to Security → Secure administration, applications, and 

infrastructure → External authorization providers. Select the System 

Authorization Facility (SAF) authorization radio button. 

A key component in configuring SAF authorization in combination with LDAP 

SDBM authentication is a mapping module. The function of such a module is 

to map the LDAP distinguished name to a SAF identity. There is no need to 

write such a JAAS module yourself. The SampleSAFMappingModule is 

provided in the WebSphere run time (v6.0: in wssec.jar, v6.1: in 

com.ibm.ws.runtime_6.1.0.jar) and functions perfectly in combination with 

LDAP SDBM provided credentials. In an LDAP SDBM constructed DN, the 


SAF ID is already part of the DN. LTPA is assumed to be the authentication 

mechanism. SWAM has been deprecated as of v6.1. 

2. Add SampleSAFMappingModule to JAAS login. This configuration is identical 

in V6.0 and V6.1. Only the admin console path is different. 

– v6.0: Go to Security → Global Security. 

– v6.1: Go to Security → Secure administration, applications, and 

infrastructure. Under Authentication expand JAAS Configuration on 

v6.0 and Java Authentication and Authorization Service on v6.1. 

Click System Logins. 

3. Modify DEFAULT, RMI_INBOUND, and WEB_INBOUND. Modification is 

identical for all three system login configurations. Make sure that you alter all 

three of them. Click the Alias name, click JAAS login modules, click New. 

For the module class name enter 

com.ibm.websphere.security.SampleSAFMappingModule and check the Use 

login module proxy check box. Verify that the authentication strategy is set 

to REQUIRED. Click OK. The SampleSAFMappingModule needs to be 

searched just before the MapPlatformSubject module. The ltpaLoginModule 

is at search order one. The MapPlatformSubject should occupy the last 

position. Since a newly added login module is always placed at the last 

position, we need to change the login module search order. Click Set Order. 

Select the just added 

com.ibm.websphere.security.SampleSAFMappingModule and click the 

Move up button, then click OK. See Figure 10-9. 

Figure 10-9 Change login module load order (WAS v6.0.2 illustration) 

4. Verify that SampleSAFMappingModule is loaded just before 

MapPlatformSubject by looking at the module order number. In this case 


SampleSAFMappingModule is in search order 3, as shown in Figure 10-10. 

You can also click the Module order column to have the login modules 

displayed in ascending search order. 

Figure 10-10 JAAS login modules on a system login alias (WAS v6.0.2 illustration) 

5. Make sure that the EJBROLE class is active and RACLISTed. Optionally, 

configure the grouping class GEJBROLE. Define all administrative and 

naming roles as explained in 13.1.3, “Administrative security with SAF 

authorization” on page 450, and 13.3.2, “Mapping users or groups to 

CosNaming roles” on page 468, and permit the appropriate user IDs and 

groups to the profiles. If you already have applications deployed, examine the 

J2EE roles and define them as well in the EJBROLE class, with the 

appropriate access list. Both administrative and application security must be 

enabled. Remove all WebSphere bindings from the configuration. If you are 

migrating from WebSphere bindings to SAF authorization (SAF bindings), we 

recommend that you define all EJBROLE class profiles and permits in 

advance. 

Now bring down the cell or base server and restart. One difference between 

WebSphere and SAF bindings to be aware off is the possibility that more than 

one application could specify the same J2EE role name. In the case of SAF 

bindings, authorization checks to the roles in those applications would result in a 

SAF call to one and the same profile in the EJBROLE class, and therefore would 

grant access to all applications with identical role names. In the case of 

WebSphere bindings the mapping is at application level. We always recommend 

having development discuss role naming with RACF security administrators. 

10.3.2 WebSphere and z/OS LDAP TDBM back end (DB2) 

z/OS LDAP can handle many different types of back ends. One of them is TDBM, 

and it uses DB2 z/OS as a data repository. 


z/OS LDAP TDBM configuration 

The z/OS LDAP installation is described in Distributed Security and High 

Availability with Tivoli Access Manager and WebSphere Application Server for 

z/OS, SG24-6760. In this section we focus on the configuration part. 

1. For configuring z/OS LDAP with an TDBM back end, find the LDAP 

configuration that should be in the SLAPDCNF member of the LDAP 

customization data set. In our environment, the z/OS LDAP configuration file 

is WTSC58.LDAP1.CNTL(SLAPDCNF). In this LDAP configuration file, 

uncomment or set up the following parameters: 

database tdbm GLDBTDBM 

suffix "ou=itsotdbm,o=itso" 

servername DB2B 

dbuserid GLDSRV 

databasename GLDDB 

dsnaoini WTSC58.LDAP1.CNTL(DSNAOINI) 

attroverflowsize 255 

where the suffix is the top of the LDAP tree that you want for your 

organization. We choose ou=itsotdbm,o=itso in our environment. the suffix 

does not necessarily need to have an organization unit (ou=). It may contain 

an organization only (o=). The DB2 back-end configuration refers to the DB2 

setup made at z/OS LDAP installation time. 

Example 10-3 shows an extract of our z/OS LDAP configuration for using a 

TDBM back end. 

Example 10-3 z/OS LDAP configuration with a TDBM back end 





# TDBM-specific CONFIGURATION SETTINGS 









2. Restart the z/OS LDAP server from SDSF, for instance. If your LDAP server is 

configured properly with a TDBM back end, there should be a message 

similar to Example 10-4 in the LDAP log at startup. 

Example 10-4 z/OS LDAP log with a TDBM back end 

Backend type: tdbm, Backend ID: TDBM BACKEND 

TDBM BACKEND manages the following suffixes: 

Backend suffix: OU=ITSOTDBM,O=ITSO 

End of suffixes managed by TDBM BACKEND. 

Capability: LDAP_Backend_ID Value: TDBM BACKEND 

Capability: LDAP_Backend_BldDateTime Value: 

2006-07-25-22.56.16.000000 

Capability: LDAP_Backend_APARLevel Value: OA17138 

Capability: LDAP_Backend_Release Value: R 6.0 

Capability: LDAP_Backend_Version Value: V 1.0 

Capability: LDAP_Backend_Dialect Value: DIALECT 1.0 

Capability: LDAP_Backend_BerDecoding Value: BINARY 

Capability: LDAP_Backend_ExtGroupSearch Value: YES 

Capability: LDAP_Backend_krbIdentityMap Value: YES 

Capability: supportedControl Value: 2.16.840.1.113730.3.4.2 

Capability: supportedControl Value: 1.3.18.0.2.10.2 

... 

Capability: LDAP_Backend_SupportedCapabilities Value: 

1.3.18.0.2.32.3 

Capability: LDAP_Backend_SupportedCapabilities Value: 

1.3.18.0.2.32.31 

... 

Capability: LDAP_Backend_EnabledCapabilities Value: 1.3.18.0.2.32.31 

End of capability listing for Backend type: tdbm, Backend ID: TDBM 

BACKEND. 

3. Copy the following files to the LDAP working directory /etc/ldap: 

– /usr/lpp/ldap/etc/schema.user.ldif 

– /usr/lpp/ldap/etc/schema.IBM.ldif 

4. Edit these files and change the line cn=schema, to reflect the TDBM 

suffix that is defined in the z/OS LDAP configuration file. For example: 

dn: cn=schema,ou=itsotdbm,o=itso 

Attention: There are no spaces between the comma (,) and o=. Those 

schema files contain the objects and attributes used to organize data 

following IBM schema and for the SAF native authentication object class. 


5. From Unix System Services, use the ldapmodify command to load the 

schema files into z/OS LDAP: 

ldapmodify -h wtsc58 -p 3389 -D "cn=LDAP Administrator" -w secret -f 

/etc/ldap/schema.user.ldif 


/etc/ldap/schema.IBM.ldif 

Load schema.user.ldif followed by schema.IBM.ldif. The options here are: 

– -h host name: defines the host name where LDAP is running 

– -p portnumber: defines the port on which LDAP is listening 

– -D adminDN: defines the administrator distinguished name (DN) 

– -w password: administrator password 

6. We now add entries to the z/OS LDAP with a TDBM back end because it is 

empty. We add a suffix entry and a person entry. For this purpose create a 

new schema.suffix.ldif that contains the following: 

dn: ou=itsotdbm,o=itso 

objectclass: organizationalUnit 

objectclass:top 

ou: itsotdbm 

dn: cn=UserTdbm,ou=itsotdbm,o=itso 

objectClass: inetOrgPerson 

objectClass: ePerson 

objectClass: organizationalPerson 

objectClass: person 

objectClass: top 

cn: UserTdbm 

uid: UserTdbm 

sn: 2006 

description: Test user for TDBM 

Customize the above entries to match your suffix and the user name you want 

for a first user. 

Use a command similar to the following to add the entries to the LDAP tree: 

ldapadd -h wtsc58 -p 3389 -D "cn=LDAP Administrator" -w secret -f 

schema.suffix.ldif 

7. We set up a password for the above new user creating a file called 

user.password.ldif, which contains the following: 

dn: cn=UserTdbm,ou=itsotdbm,o=itso 

changetype:modify 

replace:userpassword 

userpassword: usertdbm 


Use a command similar to the following to modify the user entry in the LDAP 

tree: 


user.password.ldif 

8. We now validate that the TDBM is functional by accessing it from an LDAP 

client. 

The native LDAP commands are cumbersome to run from UNIX System 

Services. A simpler way to access LDAP is to use an independently 

developed LDAP browser client, which you can download from: 

http://www-unix.mcs.anl.gov/~gawor/ldap/ 

Configure the LDAP client connection such as the following: 

– Host: wtsc58.itso.ibm.com 

– Port: 3389 

– Base DN: ou=itsotdbm,o=itso 

– User DN: cn=LDAP Administrator 

– User password: secret 

Figure 10-11 LDAP client connection configuration for TDBM back end 


Using this configuration we access the z/OS LDAP TDBM content. We can 

see the suffix entry and the UserTdbm entry. See Figure 10-12. 

Figure 10-12 LDAP client showing z/OS LDAP TDBM back-end content 

WebSphere z/OS configuration for z/OS LDAP TDBM 


TDBM back end (DB2) when configured as a Standalone LDAP registry. In this 

section we explain how to configure WebSphere in order to access z/OS LDAP 

TDBM. 



Standalone LDAP registry and then click Set as current. The Standalone 

LDAP registry then appears in the Current realm definition field 

(Figure 10-13). 

Figure 10-13 WebSphere user account repository 

Verify that administrative security is enabled and also the application security 

is enabled if necessary. Click Apply on this page to keep these settings. 

2. Click Configure and set up the general properties for the z/OS LDAP server: 

– Primary administrative user name: This ID is the security server ID, which 

is only used for WebSphere Application Server security and is not 

associated with the system process that runs the server. We use 


cn=UserTdbm,ou=itsotdbm,o=itso in our environment. This primary user 

name will be used to log on to the administration console, for example. 

– Server user identity: Select Automatically generated server identity in a 

WebSphere 6.1 only environment. 

– Type of LDAP server: Select IBM Tivoli Directory Server. This choice set 

up the default filters for retrieving users and groups in the Advanced 

Lightweight Directory Access Protocol (LDAP) user registry settings. 

– Host and port: Enter the full DNS host name and TCP port to access z/OS 

LDAP. We use wtsc58.itso.ibm.com and 3389 in our environment. 

– Base distinguished name (DN): The base DN indicates the starting point 

for searches in this LDAP directory server. It is ou=itsotdbm,o=itso in our 

environment. 

– Bind distinguished name (DN) and password: The bind DN is required if 

anonymous binds are not possible on the LDAP server to obtain user and 

group information. We use cn=LDAP Administrator in our environment. 


Then click Apply. 

Figure 10-14 WebSphere configuration for z/OS LDAP TDBM 

3. Save changes in the master repository and restart WebSphere Application 



WebSphere and z/OS LDAP TDBM back-end validation 




(cn=UserTdbm,ou=itsotdbm,o=itso) or the user name only (usertdbm). Using our 

ldif file, the password is usertdbm also. 

Also, it is possible to validate the user registry being used with the snoop servlet, 

which is bundled in WebSphere for z/OS. With the application security enabled, 

the snoop servlet requires basic authentication. Call the snoop servlet with a 

URL such as the following: 



Authenticate providing the user name and password defined earlier. The snoop 

servlet then appears and shows the authenticated principal. Once authenticated, 

the snoop servlet displays lots of information and more specifically the 

authenticated user (usertdbm in our example). See Figure 10-15. 

Figure 10-15 Snoop servlet showing authenticated z/OS LDAP TDBM user ID 

10.3.3 WebSphere and z/OS LDAP TDBM native authentication 

LDAP has the ability to authenticate to RACF through TDBM by supplying a 

RACF password on a simple bind to a TDBM back end. Authorization information 

is still gathered by the LDAP server based on the distinguished name that 

performed the bind operation. The LDAP entry that contains the bind DN should 

contain either the ibm-nativeId attribute or uid attribute to specify the ID that is 

associated with this entry. Note that the SDBM back end does not have to be 

configured. The ID and password are passed to RACF, and the verification of the 

password is performed by RACF. Another feature of native authentication is the 

ability to change your RACF password by issuing an LDAP modify command. 


Why should you enable native authentication? 

► You have the need for a central user registry with RACF identities (single 

sign-on). 

► You want the ability to reuse RACF user IDs and passwords using an LDAP 

interface. 

► You are looking to front-end WebSphere Application Server for z/OS with a 

security product like Tivoli Access Manager. 

z/OS LDAP TDBM native authentication configuration 

First configure LDAP z/OS with a TDBM back end, as described in 10.3.2, 

“WebSphere and z/OS LDAP TDBM back end (DB2)” on page 350. 

Additional modification is needed in the LDAP configuration file. Specify the 

native authentication options in this configuration file in the TDBM section. To do 

this, uncomment the following directives: 

► useNativeAuth: This line defines which attribute uses native authentication. 

We use the selected value, which means that only the ibm-nativeId attribute is 

subject to native authentication. 

► nativeUpdateAllowed: This defines whether LDAP can modify attributes such 

as the password for the native authentication system. We choose on. 

► nativeAuthSubtree: This defines in which subtree in the LDAP tree native 

authentication occurs. 

Example 10-5 shows an extract of our z/OS LDAP configuration for using 

native authentication with a TDBM back end. 

Example 10-5 z/OS LDAP configuration for native authentication 





# TDBM-specific CONFIGURATION SETTINGS 








useNativeAuth selected 

nativeUpdateAllowed on 


Restart the LDAP server to activate these configuration modifications. You 

should now see the following message in the LDAP JOBLOG: 

The useNativeAuth configuration option SELECTED has been enabled. 

When using the TDBM back end for native authentication, users need to have 

the ibm-nativeAuthentication objectclass and ibm-nativeId attribute. If you have 

existing users in your LDAP TDBM back end, you need to modify their definition 

to include the ibm-nativeAuthentication objectclass and ibm-nativeId attribute. 

For our configuration we create a new user with such an attribute and objectclass 

using a file called newuser.ldif, which contains the following: 

dn: cn=valence,ou=itsotdbm,o=itso 

objectClass: inetOrgPerson 

objectClass: ePerson 

objectClass: organizationalPerson 

objectClass: person 

objectClass: top 

cn: valence 

uid: valence 

sn: 2006 

description: Test user for TDBM Native 

ibm-nativeId: VALENCE 

objectclass: ibm-nativeAuthentication 


ldapadd -h wtsc58 -p 3389 -D "cn=LDAP Administrator" -w secret -f 

newuser.ldif 

This ldif entry does not have any password. The password will be verified against 

the VALENCE entry in the RACF database. 

The ibm-nativeId attribute specifies the user ID to which the entry binds to in the 

RACF database. In this example, the valence LDAP entry binds to the user 

VALENCE in the RACF database. 


Using the z/OS LDAP TDBM connection configuration for the LDAP client, we 

access the z/OS LDAP TDBM content. We can see the new user entry with the 

proper objectcall and attribute (Figure 10-16). 

Figure 10-16 LDAP client showing z/OS LDAP TDBM native authentication entry 

WebSphere z/OS configuration for LDAP native authentication 

From a WebSphere Application Server for z/OS perspective, using native 

authentication with z/OS LDAP is transparent. 

Consequently, the configuration is the same as with no native authentication. 

Refer to 10.3.2, “WebSphere and z/OS LDAP TDBM back end (DB2)” on 

page 350 for configuring WebSphere. 

WebSphere z/OS and LDAP native authentication validation 

We validate the user registry used with the snoop servlet, which is bundled in 

WebSphere for z/OS. With application security enabled, the snoop servlet 

requires basic authentication. Call the snoop servlet with a URL such as the 

following: 



Authenticate providing the user name and password defined earlier with the 

native authentication attribute and objectclass. The distinguished name 

(cn=valence,ou=itsotdbm,o=itso) or the common name only (valence) can be 

used. The RACF password corresponding to the ibm-nativeId attribute has to be 

provided. If the common name and the ibm-nativeId match, credentials provided 

are RACF credentials. The snoop servlet then appears and shows the 

authenticated principal. See Figure 10-17. 

Figure 10-17 Snoop servlet showing authenticated z/OS LDAP TDBM native 

authentication user ID 

10.4 Federated repositories 

Federated repositories is a new feature provided with WebSphere Application 

Server for z/OS v6.1. Federated repositories allows, for example, you to access 

simultaneously intranet users and Internet users stored in different registries. In 

this section, we describe what federated repositories are and we show how to 

configure federated repositories with our scenario. 

10.4.1 What federated repositories are 

Inclusion of federated repositories in this WebSphere release provides a single 

model for managing organizational entities. You can configure a realm that 

consists of identities in the file-based repository that is built into the system, in 

one or more external repositories, or in both the built-in, file-based repository and 

in one or more external repositories. 


Currently, most WebSphere applications have their own models and 

components for managing organizational entities, and they provide different 

levels of security. Most applications are dependent on specific types and brands 

of repositories, assume a specific schema for the data in those repositories, and 

are not able to use repositories with existing data. Federated repositories helps 

these applications by providing them with a common model, secure access to 

various brands and types of repositories, and the ability to use repositories with 

existing data. The single model includes a set of organizational entity types and 

their properties, a repository-independent application programming interface 

(API), and a service provider programming interface (SPI) for plugging in 

repositories. XPath is chosen as the search language in the API and SPI. 

Federated repository configuration uses multiple repositories simultaneously and 

recognizes the entries in the different repositories as entries representing distinct 

entities. By configuring an entry mapping repository, a federated repository 

configuration can use both LDAP and the database at the same time. The 

federated repository configuration hierarchy and constraints for identifiers 

provide the aggregated namespace for both of those repositories and prevent 

identifiers from colliding. 

A federated repository configuration provides a property extension repository, 

which is a database regardless of the type of main profile repositories for a 

property-level join configuration. When an application uses the federated 

repository configuration to retrieve an entry for a person, the federated repository 

configuration transparently joins the properties of the person that is retrieved 

from either the LDAP or the customer’s database with the properties of the 

person that is retrieved from the property extension repository into a single 

logical person entry. 

When you configure a property extension repository, you can supply a valid data 

source, a direct connection configuration, or both. WebSphere first tries to 

connect by way of the data source. If the data source is not available, then the 

system uses the direct access configuration. 


Figure 10-18 presents the WebSphere federated repositories architecture 

overview. The federated repository feature is also called Virtual Member 

Manager (VMM). 

Figure 10-18 Federated repositories or Virtual Member Manager architecture overview 

Federated repositories supports multiple user repositories in the cell’s security 

realm: 

► Built-in file-based repository 

► Multiple federated LDAP servers 

► Database that can be federated by CLI 

The federation creates a single namespace for identities. Database 

repositories are supported using the command line only. 


Also, federated repositories provides some user and group management 

features. This is possible because federated repository is accessed with read 

and write permissions. This user and group management is available through the 

administrative console, through command-line utilities, or using public APIs. 

Table 10-1 Federated repositories versus other user registry options 

Supported registries File-based 

LDAP 

DB (via wsadmin) 

Simultaneous 

multi-registry support 

Registry read/write 

support 

When you use the federated repositories functionality, all of the configured 

repositories, which you specify as part of the federated repository configuration, 

become active. It is required that the user ID, and the distinguished name (DN) 

for an LDAP repository, be unique in multiple user repositories that are 

configured under the same federated repository configuration. 

10.4.2 Our federated repositories scenario 

Federated repositories Other user registry 

options 

Yes No 

Read/write Read only 

Our federated repositories scenario relies on the LDAP tree and on the 

environment that we described in 10.2, “Our scenario and our environment” on 

page 339. 


Local operating system 

Standalone LDAP 

Standalone custom

In this section we focus on configuring WebSphere Application for z/OS for a 

federated repository composed of z/OS LDAP TDBM and IBM Tivoli Directory 

Server. See Figure 10-19. 

Figure 10-19 Our federated repositories scenario 

The itsoitds organization unit is supported by ITDS. The itsotdbm organization 

unit is supported by z/OS LDAP TDBM. In this scenario we federate those two 

subtrees in order to make them available to WebSphere as one LDAP tree 

whose root organization is itso. 

This federation is transparent to WebSphere Application Server for z/OS. Users 

and groups can be accessed in both subtrees simultaneously. 

In the following section we start to federate z/OS LDAP TDBM. Then we validate 

that it works also with native authentication, and finally we federate ITDS. At the 


end of this federation configuration, all three users defined in our scenario can 

access the WebSphere application simultaneously. 

10.4.3 Federated z/OS LDAP with TDBM back end (DB2) 

In this section we describe how to federate a z/OS LDAP with a TDBM back end. 

Note: WebSphere Application Server for z/OS v6.1 does not currently support 

federated repositories with a z/OS LDAP SDBM back end. For accessing a 

z/OS LDAP SDBM back end, WebSphere can use a Standalone LDAP 

registry configuration. 


Configure z/OS LDAP with a TDBM back end, as described in 10.3.2, 

“WebSphere and z/OS LDAP TDBM back end (DB2)” on page 350. 

WebSphere z/OS configuration for LDAP TDBM 


TDBM back end (DB2) when configured as a federated repository LDAP registry. 

In this section we explain how to configure WebSphere in order to access z/OS 

LDAP TDBM. 



Federated repositories and then click Configure. Under the Related Items 

section, select Manage repositories. The default InternalFileRepository 

should appear in the list. Click Add to define a new repository. 

Configure the new repository with the parameters for the z/OS LDAP TDBM 

back end: 

– Repositoty identifier: name of the repository in the WebSphere 

configuration. We choose itsotdbm in our configuration. 

– As a directory type, select z/OS Integrated Security Services LDAP 

Server. 

– Enter the primary host name and port for the z/OS LDAP server. These 

are wtsc58.itso.ibm.com and 3389 in our environment. 

– It is possible to specify failover servers for high availability purposes. 

– Specify the bind distinguished name and password. This should be an 

LDAP user ID that is allowed to scan and update the LDAP tree. We 

choose the administrator identity for our LDAP server in our environment, 

which is cn=LDAP Administrator. 


– For a TDBM back end with the schema loaded, leave uid in the Login 

properties field. 

– It is possible to configure SSL for securing the connection to the LDAP 

server. We do not implement this feature in our environment. 

Then click Apply and save to the master configuration. WebSphere validates 

that it can access the LDAP server. 

Figure 10-20 WebSphere configuration for z/OS LDAP TDBM as a federated repository 

2. Within the Administrative Console, click Security → Secure administration, 


Federated repositories and then click Configure. Under Repositories in the 

Realm, click Add Base entry to Realm. 

a. Select your new repository name. This is itsotdbm in our example. 

b. Specify the distinguished name of a base entry that uniquely identifies this 

set of entries in the realm. If multiple repositories are included in the realm, 


it is necessary to define a different distinguished name that uniquely 

identifies this set of entries within the realm. We choose 

ou=itsotdbm,o=itso in our configuration. 

c. Specify the distinguished name of the base entry within the repository. 

The entry and its descendents are mapped to the subtree that is identified 

by the unique base name entry field. If this field is left blank, then the 

subtree defaults to the root of the LDAP repository. We set up 

ou=itsotdbm,o=itso for our configuration. 

Then click OK and save to the master configuration. 

Figure 10-21 WebSphere repository reference for z/OS LDAP TDBM 



Federated repositories and then click Configure. 

a. Enter a realm name of your choice. We choose itso in our example. 

b. Specify the name of the user who will have WebSphere administrative 

privileges. This distinguished name has to be an existing identity in the 

z/OS LDAP TDBM repository. We choose 

cn=UserTdbm,ou=itsotdbm,o=itso in our environment. 

c. Select an automatically generated server identity. 


d. Remove the existing file-based InternalFileRepository by selecting it and 

clicking Remove. 


that it can find the administrative user identity. 

Figure 10-22 WebSphere federated repositories base entries 


applications and infrastructure. 

a. Under User account repository, select Federated repositories and then 

click Set as current. 

b. Select Administrative security and unselect Java2 security if not 

necessary. 


c. Then click Apply and save to the master configuration (Figure 10-23). 

Figure 10-23 WebSphere federated repositories main security panel 

5. Restart WebSphere Application Server for z/OS. 

Federated z/OS LDAP TDBM validation 







Also, it is possible to validate the user registry being used with the snoop servlet, 

which is bundled in WebSphere for z/OS. With the application security enabled, 

the snoop servlet requires basic authentication. Call the snoop servlet with a 

URL such as the following: 


Authenticate providing the user name and password defined earlier. The snoop 

servlet then appears and shows the authenticated principal (Figure 10-24). 

Figure 10-24 Snoop servlet showing authenticated z/OS LDAP TDBM user ID 

10.4.4 Federated z/OS LDAP TDBM native authentication 

In this section we describe how to federate a z/OS LDAP TDBM with native 


Why you may choose to enable native authentication is explained in 10.3.3, 

“WebSphere and z/OS LDAP TDBM native authentication” on page 359. 


Configure z/OS LDAP with a TDBM back end, as described in 10.3.3, 

“WebSphere and z/OS LDAP TDBM native authentication” on page 359. 


WebSphere z/OS configuration for LDAP TDBM 

Native authentication does not imply configuration changes at the WebSphere 

level. Hence, configure WebSphere z/OS for a z/OS LDAP TDBM back end, as 

described in 10.4.3, “Federated z/OS LDAP with TDBM back end (DB2)” on 

page 368. 

You can now access your secured applications with user IDs and password in 

RACF. For example, in our environment, the valence user can access the snoop 

servlet providing his RACF password. See Figure 10-25. 

Figure 10-25 Snoop servlet showing authenticated z/OS LDAP TDBM native 

authorization user ID 

In order to access the administrative console, users need to be added to the list 

of administrative roles. 


For example, access the administrative console with the existing administrative 

user ID (usertdbm in our example), then add any new user (valence in our 

example) with an administrative role. See Figure 10-26. 

Figure 10-26 WebSphere administrative user roles 

10.4.5 Federated IBM Tivoli Directory Server 

In this section we describe how to federate a IBM Tivoli Directory Server. 

IBM Tivoli Directory Server (ITDS) configuration 

How to install IBM Tivoli Directory Server is described in the InfoCenter: 

http://publib.boulder.ibm.com/infocenter/tivihelp/v2r1/index.jsp?topic= 

/com.ibm.IBMDS.doc/install04.htm 

In this section we focus on configuring it. 

On the Windows platform, ITDS can be configured using the idsxcfg utility. This 

utility is available using the following command: 

C:\Program Files\IBM\LDAP\V6.0\sbin\idsxcfg.cmd 

We configure ITDS to handle the following suffix: 

o=itsoitds,o=itso 


The LDAP administrator is cn=LDAP Administrator and the password is secret. 

Figure 10-27 IBM Tivoli Directory Server idsxcfg current configuration display 

We now add entries to ITDS because it is empty. We add a suffix entry and a 

person entry. For this purpose create a new schema.suffix.ldif that contains the 

following: 

dn: ou=itsoitds,o=itso 

ou: itsoitds 

objectclass: organizationalUnit 

objectclass: top 

dn: cn=UserItds, ou=itsoitds,o=itso 

uid: UserItds 

description: Test user for ITDS 

objectclass: inetOrgPerson 

objectclass: ePerson 

objectclass: organizationalPerson 

objectclass: person 

objectclass: top 

sn: 2007 

cn: UserItds 


Customize the above entries to match your suffix and the user name you want for 

a first user. 


C:\Program Files\IBM\LDAP\V6.0\bin>ldapadd -D "cn=LDAP Administrator" 

-w secret -i schema.suffix.ldif 

We set up a password for the above new user, creating a file called 

user.password.ldif, which contains the following: 

dn: cn=UserItds,ou=itsoitds,o=itso 

changetype:modify 

replace:userpassword 

userpassword: useritds 

Use a command similar to the following to modify the user entry in the LDAP tree: 

C:\Program Files\IBM\LDAP\V6.0\bin>ldapmodify -D "cn=LDAP 

Administrator" -w secret -i user.password.ldif 

We now validate that ITDS is functional by accessing it from a LDAP client. 

Configure the LDAP client connection such as the following (Figure 10-28): 

Host : itds.itso.ibm.com 

Port : 389 

Base DN : ou=itsoitds,o=itso 

User DN : cn=LDAP Administrator 

User password : secret 

Figure 10-28 LDAP client connection configuration for ITDS 


Using this configuration we access ITDS content. We can see the suffix entry 

and the UserItds entry (Figure 10-29). 

Figure 10-29 LDAP client showing ITDS content 

WebSphere z/OS configuration for ITDS 

WebSphere Application Server for z/OS supports accessing IBM Tivoli Directory 

Server (ITDS) when configured as a federated repository LDAP registry. In this 

section we explain how to configure WebSphere in order to access ITDS. 



Federated repositories and then click Configure. Under the Related Items 

section, select Manage repositories. The default InternalFileRepository 

should appear in the list. Click Add to define a new repository. 

Configure the new repository with the parameters for ITDS. 

a. Repositoty identifier: name of the repository in the WebSphere 

configuration. We choose itsoitds in our configuration. 

b. As a directory type, select IBM Tivoli Directory Server Version 6. 

c. Enter the primary host name and port for the z/OS LDAP server. These 

are itds.itso.ibm.com and 389 in our environment. 

d. It is possible to specify failover servers for high availability purposes. 

e. Specify the bind distinguised name and password. This should be an 

LDAP user ID that is allowed to scan and update the LDAP tree. We 

choose the administrator identity for our LDAP server in our environment, 

which is cn=LDAP Administrator. 

f. Leave uid in the Login properties field. 


g. It is possible to configure SSL for securing the connection to the LDAP 

server. We do not implement this feature in our environment. 


that it can access the LDAP server. 

Figure 10-30 WebSphere configuration for ITDS as a federated repository 



Federated repositories and then click Configure. Under Repositories in the 

Realm, click Add Base entry to Realm. 

a. Select your new repository name. This is itsoitds in our example. 

b. Specify the distinguished name of a base entry that uniquely identifies this 

set of entries in the realm. If multiple repositories are included in the realm, 

it is necessary to define a different distinguished name that uniquely 

identifies this set of entries within the realm. We choose ou=itsoitds,o=itso 

in our configuration. 


c. Specify the distinguished name of the base entry within the repository. 

The entry and its descendents are mapped to the subtree that is identified 

by the unique base name entry field. If this field is left blank, then the 

subtree defaults to the root of the LDAP repository. We set up 

ou=itsoitds,o=itso for our configuration. 

Then click OK and save to the master configuration (Figure 10-31). 

Figure 10-31 WebSphere repository reference for ITDS 



Federated repositories and then click Configure. 


In our configuration we federate z/OS LDAP with ITDS. Because we already 

configured this panel for z/OS LDAP, we do not need to do any further 

configuration. This means that the primary administrative user name stays a 

user name from our first registry (cn=UserTdbm,ou=itsotdbm,o=itso). The 

realm name is the one for all federated registries. See Figure 10-32. 

Figure 10-32 WebSphere federated repositories base entries 


applications and infrastructure. 

If this has not been done before, under User account repository, select 

Federated repositories and then click Set as current. Select 

Administrative security, and unselect Java2 security if not necessary. Then 

click Apply and save to the master configuration. 


Federated ITDS validation 

To log into the administrative console, use the primary administrative user name 

defined earlier. It is possible to use the full distinguished name 




It is possible to validate the federated user registry with the snoop servlet, which 

is bundled in WebSphere for z/OS. With the application security enabled, the 

snoop servlet requires basic authentication. Call the snoop servlet with a URL 

such as the following: 


Authenticate providing the user name and password defined ealier for the last 

federated repository (UserItds in our example). The snoop servlet then appears 

and shows the authenticated principal. See Figure 10-33. 

Figure 10-33 Snoop servlet showing authenticated ITDS user ID 

Because user registries are now federated, the user from z/OS LDAP TDBM 

(UserTdbm) can also be used with the same configuration at the same time. 

All this validates the federated repositories set up with a z/OS LDAP TDBM and 

IBM Tivoli Directory Server. Native authentication can also be used. 

10.5 z/OS local operating system registry 

When using the local operating system registry with WebSphere Application 

Server for z/OS, the z/OS security product is accessed for user and group 

information. 


In this section we describe specific z/OS options available when using the local 

operating system registry. 

10.5.1 System Authorization Facility (SAF) authorization 

When using the local operating system user registry on z/OS, it is possible to 

choose SAF authorization. Choosing SAF authorization is not mandatory. 

Use SAF authorization to have EJBROLE security enforced by the z/OS security 

product, such as RACF. In that case, SAF EJBROLE profiles are used for 

user-to-role authorization for both J2EE applications and the role-based 

authorization requests (naming and administration) that are associated with 

application server run time. WebSphere Application Server for z/OS uses the 

authorization policy that is stored in the z/OS security product for authorization. 

This option is available when your environment contains z/OS nodes only. It is 

available using the Administrative Console in Secure administration, applications, 

and infrastructure → External authorization providers, as shown in Figure 10-34. 

Figure 10-34 System Authorization Facility authorization 


Defining EJBROLES belongs to the application deployment process. If the user 

ID has at least READ access to the defined EJBROLE profile that corresponds to 

the J2EE role defined by the application, the user ID is considered to be in role. 

(Do not be confused by the name EJBROLE. It is used for J2EE roles in both 

enterprise beans and Web applications.) 

Here is an example of how to define a EJBROLE in RACF and how to authorize 

a user ID: 

RDEFINE EJBROLE PRODCELL.bankTeller UACC(NONE) 

PERMIT PRODCELL.bankTeller CLASS(EJBROLE) ID(JOHN) ACCESS(READ) 


In this example, the domain name is PRODCELL. The role name is bankTeller. 

The authorized user ID is JOHN. 

If a Lightweight Access Directory Protocol (LDAP) registry or custom registry is 

configured and SAF authorization is specified, a mapping to a z/OS principal is 

required at each login for any protected methods to run. If the authentication 

mechanism is Lightweight Third Party Authentication, we recommend that you 

update all of the following configuration entries to include a mapping to a valid 

z/OS principal (such as WEB_INBOUND, RMI_INBOUND, and DEFAULT). 

Table 10-2 Authorization providers characteristics 

Authorization providers Characteristics 

Default authorization 

(WebSphere bindings) 

System Authorization 

Facility authorization 

► Access to servlets or EJB methods is based upon the role (job title, 

function, and so on) of the user or caller. 

► Roles are associated with servlets or EJBs at assembly time. 

► Roles are stored in the application's .ear file: application.xml. 

► Which users and groups have which roles is also stored in the 

application's .ear file: ibm-application-bnd.xmi. 

► Roles are managed by the application developer and the application 

deployer. 

► RACF only provides user and group information. 




► Roles are represented in the application's .ear file: application.xml. 

► Which users and groups have which roles is determined in RACF by 

profiles in the EJBROLE class. 

► If a user is in the access list of an EJBROLE profile, he has that role. 

► If a group is in the access list of an EJBROLE profile, users in that 

group have that role. 

► Roles are managed through RACF. 


Authorization providers Characteristics 

External authorization 

using a JACC provider 




► Roles are represented in the application's .ear file: application.xml. 

► Which users and groups have which roles is determined in the JACC 

provider. 

► Roles are managed through the JACC provider. 

SAF delegation 

System Authorization Facility delegation minimizes the need to store user IDs 

and passwords in many locations in the configuration. SAF delegation is used in 

conjunction with the RunAs feature. 

WebSphere Application Server for z/OS supports the function of delegation. 

Delegation allows a user identity to be represented as a J2EE role. For example, 

you can establish an application to be run with a RunAs role of RoleA. RoleA can 

then be mapped as UserA. WebSphere then establishes the principal as UserA, 

and RoleA is defined in the deployment descriptor. With such a configuration, 

SAF delegation uses the specified J2EE role, RoleA, to determine the user 

identity and then set the Java principal with the user ID, UserA. UserA is 

specified in the SAF EJBROLE profile's APPLDATA value of the RDEFINE RACF 

command. The RDEFINE command in this example would be as follows: 

RDEFINE EJBROLE rolea UACC(NONE) APPLDATA(usera) 

SAF delegation requires that the SAF authorization be enabled. The SAF security 

administrator would be responsible for the assignment of users to the role. 

This option is available using the administrative console in Secure 

administration, applications, and infrastructure → External authorization 

providers → SAF authorization options. 

SAF profile mapper 

WebSphere Application Server for z/OS supports the use of a custom SAF EJB 

role mapper. The custom SAF EJB role mapper allows an installation to map 

J2EE role names to SAF EJBRole profile names. Without the SAF EJB role 

mapper, you must deploy an application by using a role in the deployment 

descriptor of a component that is identical to the name of an EJBROLE class 

profile. The security administrator defines EJBROLE profiles and provides the 

permission to these profiles to SAF users or groups. 

Using SAF EJBROLE class profiles can conflict with the standard J2EE role 

naming conventions. J2EE role names are Unicode strings of any length. RACF 


class profiles are restricted to 240 characters in length and cannot be defined if 

these profiles contain any white spaces or extended code page characters. If a 

J2EE role name for an installation conflicts with these RACF restrictions, an 

installation can use the SAF EJB role mapper exit to map the desired J2EE role 

name to an acceptable class profile name. 

The custom SAF role mapper is a Java-based exit to replace the EJBROLE class 

profile construction algorithm. The custom SAF role mapper is called to generate 

a profile for authorization and delegation requests. The role mapper passes the 

name of the application, and the name of the role then passes back the 

appropriate class profile name. Information about the server name, cell name, 

and the z/OS security domain name prefix is provided to the implementation 

during initialization. 

This option is available using the administrative console in Secure 

administration, applications, and infrastructure → External authorization 

providers → SAF authorization options. 

10.5.2 OS thread security support 

OS thread security refers to the WebSphere on z/OS’s unique ability to 

synchronize the OS thread identity with the J2EE identity. In other words, it 

allows the switching of the security context of the servant region’s Task Control 

Block (TCB level ACEE) to the current JAAS principal (J2EE identity). 

This feature can be used in the middle of a J2EE application with Synch-to-OS 

Thread to access z/OS system-level ressources, or it can be used in a connector 

with Connection Manager RunAs Identity to access some Enterpsie Information 

Systems (EIS) such as DB2 or IMS JDBC. 

Synch to OS Thread 

Sync-to-OS Thread (or z/OS thread identity synchronization) applies when the 

application requires access to system resources (for example, HFS files, TCP/IP 

sockets, and so on). The application requests this function and the container 

changes the OS thread identity to the J2EE identity. 

This option indicates whether an operating system thread identity is enabled for 

synchronization with the J2EE identity that is used in the application server run 

time if an application is coded to request this function. 

Synchronizing the operating system identity to the J2EE identity causes the 

operating system identity to synchronize with the authenticated caller, or 

delegated RunAs identity in a servlet or Enterprise JavaBeans (EJB). This 

synchronization or association means that the caller or security role identity, 


ather than the server region identity, is used for z/OS system service requests 

such as access to files. 

For the SyncToOS function to be active, the following conditions must all be true: 

► An application includes within its deployment descriptor an env-entry of 

com.ibm.websphere.security.SyncToOSThread set to true. 

► z/OS thread identity synchronization is enabled in the administrative console. 

► The configured user registry is the local operating system. 

► The BBO.SYNC facility class is defined in RACF, and the control region user 

ID has control or read access to it. Use the optional SURROGAT facility class 

for finer-grained access controls. 

When these conditions are true, the OS thread identity is set to the authenticated 

caller identity of a Web or EJB request. The OS thread is modified each time the 

J2EE identity is modified. The J2EE identity can be modified either by a RunAs 

specification on the deployment descriptor or a programmatic WSSubject.doAs() 

request. See Figure 10-35. 

Figure 10-35 Administrative Console Synch to OS Thread option 

This “Enable application server and z/OS thread identity synchronization” option 

is available using the administrative console in Secure administration, 

applications, and infrastructure → z/OS security options. 


Connection manager RunAs identity 

Connection manager RunAs identity applies to connections to back-end 

Enterprise Information Systems such as DB2 and IMS JDBC. It allows the 

changing of the OS thread identity to the J2EE identity at the connector level. 

Thread security support for DB2 and IMS JDBC is enabled when: 

► Connection manager RunAs thread identity is enabled. 

► A local connection is used between the application server and the EIS. 

► Res-auth=Container is specified for the resource reference defined in the 

deployment descriptor. 

► The connection factory does not specify a JAAS authentication alias. 


► The BBO.SYNC facility class is defined in RACF and the control region user 

ID has control or read access to it. Use the optional SURROGAT facility class 

for finer-grained access controls. 

With such a configuration, the connection manager synchronizes the OS thread 

identity with the J2EE identity before obtaining the EIS connection. See 

Figure 10-36. 

Figure 10-36 Administrative console connection manager RunAs identity option 

This “Enable the conection manager RunAs thread identity” option is available 

using the administrative console in Secure administration, applications, and 

infrastructure → z/OS security options. 


10.5.3 Thread identity support 

Thread identity support is the ability to pass the identity of the Java principal 

within the subject (J2EE identity) through a JCA connector or a JDBC ressource 

adapter to an Enterprise Information System. Depending on the connector being 

used, thread identity support may or may not require you to configure connection 

manager RunAs identity. Some connectors can accomplish thread identity 

support without synchronizing the J2EE identity with the OS thread identity. 

Some connectors accomplish thread identity support by synchronizing the J2EE 

identity with the OS thread identity. 

WebSphere Application Server for z/OS allows you to assign an identity as an 

owner of a connection when you first obtain the connection. This thread identity 

function only applies to J2EE Connector Architecture (JCA) resource adapters 

and Relational Resource Adapter (RRA) wrappered Java Database Connectivity 

(JDBC) providers that support the use of thread identity for connection 

ownership. 

Thread identity support is enabled when: 

► A local connection is used between the application server and the EIS (CICS, 

IMS, DB2, and so on). 

► Res-auth=Container is specified for the resource reference defined in the 

deployment descriptor. 

► The connection factory does not specify a JAAS Authentication Alias. 

► You are using an SAF-based user registry. 

Table 10-3 lists the JCA resource adapter and JDBC provider processes that 

support thread identity and thread security. It also provides the level of thread 

identity support. 

Table 10-3 Connectors thread identity and OS thread security support 

Connectors Thread 

identity 

support 

OS thread 

security 

support 

IMS Connector - local ConnectionFactory configuration Allowed Not supported 

IMS Connector - remote ConnectionFactory configuration Not allowed Not supported 

CTG CICSECIConnector - local ConnectionFactory configuration Allowed Not supported 

CTG CICSECIConnector - remote ConnectionFactory configuration Not allowed Not supported 

IMS JDBC Connector - local ConnectionFactory configuration (By 

default, IMS JDBC only supports this type of configuration.) 

Required Supported 


Connectors Thread 

identity 

support 

RRA DB2 for z/OS local JDBC provider - data sources configured to 

the local DB2 

The level of thread identity support can be: 

► Allowed, which indicates that thread identity for connection ownership is 

allowed for this configuration. 

► Not allowed, which indicates that thread identity for connection ownership is 

not allowed for this configuration. 

► Required, which indicates that thread identity for connection ownership is 

required. 


Allowed Supported 

RRA DB2 Universal JDBC Driver Provider using Type 2 connectivity Allowed Supported 

RRA DB2 Universal JDBC Driver Provider using Type 4 connectivity Not allowed Not supported 

WebSphere MQ JMS Provider: Connection Factory (TransportType = 

BINDINGS) 

WebSphere MQ JMS Provider - Connection Factory (TransportType 

= CLIENT) 

WebSphere JMS Provider (such as Integral JMS Provider): 

Connection Factory 

OS thread 

security 

support 

Allowed Supported 

Not allowed Not supported 

Not allowed Not supported

Chapter 11. SPNEGO and Windows 

single sign-on 

11 

A new feature provided in WebSphere Application Server for z/OS v6.1 is the 

ability to single sign-on to WebSphere applications from a Microsoft Windows 

desktop using Simple and Protected GSS-API Negotiation Mechanism 

(SPNEGO). This single sign-on is transparent for the user. 

In this chapter we introduce several technologies relating to SPNEGO, we 

describe some solution designs, and we explain how to implement a single 

sign-on solution between a Microsoft Windows domain and WebSphere 


This chapter discusses the following topics: 

► “Introducing the SPNEGO TAI” on page 392 

► “Designing single sign-on with Microsoft Windows domain” on page 397 

► “Implementing single sign-on using SPNEGO TAI” on page 400 

► “Validating single sign-on using the SPNEGO TAI” on page 424 


11.1 Introducing the SPNEGO TAI 

Single sign-on (SSO) throughout an enterprise is the ultimate goal of many 

security organizations today. One aspect of single sign-on is user desktop 

authentication. It is desirable for users to authenticate to their desktops and then 

have implicit authenticated access from those desktops to other enterprise 

resources, such as Web applications. This chapter describes a solution that is 

available today to solve that matter when using Microsoft Windows Active 

Directory® (AD) domains, Windows client desktops, and WebSphere Application 

Server for z/OS v6.1. 

In this section we introduce several technologies involved in the SPNEGO TAI 

single sign-on solution. We present Kerberos, the Trust Association Interceptor, 

SPNEGO, and finally the SPNEGO TAI. 

11.1.1 An introduction to Kerberos 

Utilizing Kerberos tokens has become more and more common, especially since 

Microsoft started supporting Kerberos Version 5 as the default network 

authentication protocol in their Windows 2000 operating system. 

Kerberos realm and principal 

A Kerberos realm is often referred to as an administrative domain. A realm 

consists of members, which can be users, servers, services, or network 

resources that are registered within a KDC’s database. Each of these members 

has a unique identifier that is called a principal. The Kerberos realm is made up 

of the KDC and all of its principals. 

The principal is a unique identifier that the KDC can assign tickets to. There are 

three parts in a principal name: 

primaryname/instancename@REALM 

► The primary name: It can be either the user’s name, the word host, or the 

name of the service. An example of a principal in the ITSO.IBM.COM realm 

could be fdevalence@ITSO.IBM.COM. 

► The instance name: This is optional. It is used to further define the primary 

name, for example, fdevalence/admin@ITSO.IBM.COM. Note that the 

principals fdevalence and fdevalence/admin are two completely separate 

principals with different passwords and possibly a different set of authorities. 

The instance component is also used when specifying a host or a service 

principal. In this case, it can be the fully qualified domain name of the host 

such as telnet/wtsc58.itso.ibm.com@ITSO.IBM.COM. 


► The realm name: The realm portion of the principal’s name is the name of the 

Kerberos realm, which is usually the domain name in uppercase. 

Key Distribution Center (KDC) 

Three different functions are performed in the Key Distribution Center. There is 

an authentication server (AS), a ticket granting server (TGS), and the KDC 

database that holds shared secret information about each principal in the 

Kerberos realm. Since these functions are incorporated into the KDC, and are 

also linked by the services provided to the principals, they usually reside on the 

same machine. 

The two primary functions of the KDC are to grant ticket granting tickets and to 

grant service tickets. 

Kerberos ticket 

The word ticket is used to describe how authentication data is transmitted in the 

Kerberos environment. Tickets are essentially an encrypted data structure that 

uses shared keys issued by the KDC to communicate in a secure fashion. The 

purpose of the ticket depends on where it has been created. 

When a principal requests an initial authentication, the authentication server 

gives him a ticket granting ticket (TGT). This ticket is used to request tickets for 

other services in the network. 

When the principal wants to use a service in the network, it sends a request 

including his TGT to the ticket granting server. The TGS responds by issuing and 

sending a service ticket (ST). 

When the principal uses a service in the network, it sends a request including his 

ST to the server hosting the service. The server accepts the ST and executes the 

service. 

Each ticket can also contain options that give you more control over the use of 

the tickets. 

Kerberos authentication protocol 

The Kerberos system consists of three components: a client, a server, and a 

trusted third party, which is the Key Distribution Center. KDC interacts with both 

a client and a server to accept the client’s request, authenticate its identity, and 

issue tickets to it. 

Chapter 11. SPNEGO and Windows single sign-on 393

Although the Kerberos protocol consists of several sub protocols, three 

exchanges are the most interesting, as shown in Figure 11-1. 

Figure 11-1 Kerberos authentication protocol overview 

The Kerberos protocol executes the following steps: 

► Steps 1 and 2: The first exchange takes place between a client and the 

authentication server, in which a client asks the AS that knows the secret 

keys of all clients in the realm to authenticate itself and gives it a ticket called 

ticket-granting ticket. The TGT is used to get a secret shared with an 

application server the client wants to access. 

► Steps 3 and 4: Upon receiving the TGT, the client sends a request, which 

contains the TGT, for a service ticket to the ticket-granting server, and waits 

for a service ticket (ST) to be returned. 

► Steps 5 and 6: Having the service ticket available, the client is allowed to 

communicate with the server that is providing a service he wants to use. The 

application server can verify the service ticket without the need to contact the 

KDC. 

Kerberos and Microsoft Windows 

Kerberos is implemented in Microsoft Windows Server® 2000 and later. The 

implementation of Kerboros on a Windows server is composed of two elements, 


which are the Kerberos service and Active Directory (AD). AD is Microsoft’s 

implementation of the LDAP protocol. 

When a user logs onto the Windows domain, the information entered by the user 

is captured by the logon program and is transmitted to the computer’s local 

security authority (LSA). The LSA is a Windows component that authenticates 

users to the local system. This LSA then communicates with the network’s KDC 

in order to receive ticket granting tickets and service tickets so that this user can 

access kerberized services on the Windows domain. 

Kerberos on Windows server platforms use the Active Directory for all 

information about principals on the Kerberos network. The encryption key used 

in communicating with principals is stored in the Active Directory database in the 

user’s profile. 

Active Directory not only plays the role of an LDAP server on a Windows server, 

it is also used as the KDC database. This can be a great benefit to an 

organization in terms of one central store, but can be equally devastating in the 

event of system failure. 

11.1.2 An introduction to trust association interceptor (TAI) 

The trust association feature is a point in the WebSphere HTTP authentication 

process where an organization can insert its own code to achieve whatever 

authentication outcome it desires. 

The trust association interceptor relies on a trust relationship with a front-end 

party. Once this trust is established, the TAI retrieves the identity from the 

incoming request and returns it as a principal to WebSphere. 

Trust association applies for Web requests where some other servers, like 

Reverse Proxy Security Servers (RPSS), authenticate the request and forward 

the request to the application server. The WebSphere Application Server TAI 

only validates the trust relationship with the RPSS and retrieves the identity from 

the incoming request and returns it as a principal. 

Some examples of Reverse Proxy Security Servers are IBM Tivoli Access 

Manager WebSeal or IBM Datapower, and so on. 

It can be coded so that only some requests are validated by the TAI. That is, the 

TAI can decide that it will not perform a trust association operation on a request, 

in which case the authentication process returns to WebSphere for processing. 

You can develop your own TAI, but WebSphere Application Server for z/OS v6.1 

comes with four trust association interceptors. These can be found with the 


Administrative Console in Secure administration, applications, and 

infrastructure → Trust association → Interceptors: 

► com.ibm.ws.security.spnego.TrustAssociationInterceptorImpl 

► com.ibm.ws.security.web.WebSealTrustAssociationInterceptor 

► com.ibm.ws.security.web.TAMTrustAssociationInterceptorPlus 

► com.ibm.ws.sip.security.digest.DigestTAI 

The TAMTrustAssociationInterceptorPlus TAI was introduced in WebSphere 

Application Server V5.1. It is a new TAI Interface that has significantly enhanced 

features. This new interface introduced new performance benefits that allowed 

the TAI module to return credential information to the application server. This 

means that no additional user registry searches are required by the login 

modules, thus reducing authentication overhead. This can be combined with 

WebSphere Application Server’s downstream security attribute propagation 

services to allow security context propagation. 

The spnego.TrustAssociationInterceptorImpl TAI is the centerpiece of the single 

sign-on solution we describe in this chapter. We present the SPNEGO TAI in 

11.1.4, “The WebSphere SPNEGO TAI” on page 396. 

11.1.3 An introduction to SPNEGO 

SPNEGO is a standard specification defined in The Simple and Protected 

GSS-API Negotiation Mechanism (IETF RFC 2478). 

Microsoft Windows, when configured to use an Active Directory domain, is based 

upon a security infrastructure that is at its core Kerberos. Kerberos has 

supported distributed authentication for a long time. Microsoft has extended a 

protocol known as Simple and Protected GSS-API Negotiation Mechanism 

(SPNEGO) for sharing Windows credentials with Web servers. This protocol 

defines a way via negotiation for the client workstation to send authentication 

data to the Web server. If the Web server understands the SPNEGO tokens, this 

can then be used to implement secure single sign-on. Thus, the user’s identity is 

transferred in a secure manner to the Web server. 

SPNEGO is a protocol defined for exchanging credentials from a client to a 

server. Microsoft has extended this protocol and used it as its authentication 

mechanism for HTTP usage. The Kerberos service ticket is wrapped in a 

SPNEGO token. 

11.1.4 The WebSphere SPNEGO TAI 

The goal of the SPNEGO TAI is to leverage the Kerberos distributed 

authentication through the SPNEGO protocol. 


SPNEGO supports both Active Directory credentials (based on Kerberos) and 

the older style (and less secure) NTLM credentials. The WebSphere SPNEGO 

TAI supports only the Active Directory credentials. 

The WebSphere SPNEGO TAI handles the SPNEGO handshake requests, 

retrieves the identity from the SPNEGO token, and transfers this identity to 

WebSphere run time as a principal. 

Essentially, when WebSphere Application Server (WAS) receives an inbound 

request that requires authentication, the TAI is invoked. If the requests meets 

certain customizable filter criteria, the TAI responds with a SPNEGO challenge to 

the Web browser. If a proper SPNEGO token is returned, the TAI uses the WAS 

and JDK built-in JGSS services and the SPNEGO provider to parse the token 

and determine the user’s identity. This information is then provided to the WAS 

run time. WAS uses this information to create an LTPA cookie, which is sent to 

the browser. The user is now authenticated. Future requests within the same 

SSO domain do not invoke the TAI since the LTPA cookie now represents the 

user’s authentication. 

The SPNEGO TAI can work with Web services clients for HTTP transport-level 

security with SPNEGO tokens. The SPNEGO TAI is for Web client authentication 

and is not relevant for EJB clients. 

11.2 Designing single sign-on with Microsoft Windows 

domain 

In this section we present two solutions for single sign-on between a Microsoft 

Windows Active Directory domain and WebSphere Application Server for z/OS. 

11.2.1 Single sign-on with Microsoft Windows KDC only 

The benefits of having WebSphere Application Server for z/OS use the SPNEGO 

TAI single sign-on solution include: 

► The cost of administering a large number of IDs and passwords is reduced. 

► A secure and mutually authenticated transmission of security credentials from 

the Web browser or .NET clients is established. 

► Interoperability with Web services and .NET applications that use SPNEGO 

authentication at the transport level is achieved. 

Previously, this could only be achieved through third-party software such as 

Tivoli Access Manager. This can now be achieved by having a SPNEGO 

protocol enabled client such as a .NET application or SPNEGO enabled 


owsers such as Microsoft Internet Explorer 5.5 and later or Mozilla Firefox 1.0. 

These clients establish trust and pass credentials to WebSphere Application 

Server for z/OS using Kerberos tickets wrapped in SPNEGO tokens issued from 

a Microsoft Windows 2000 or 2003 Active Directory domain controller. 

In a simple solution, there is one Microsoft Windows Active Directory domain with 

one Kerberos KDC. The WebSphere Application Server for z/OS service is 

defined as kerberized in the Windows Kerberos KDC and the corresponding 

principal keytab file is transferred to the WebSphere for z/OS configuration. 

The Windows client workstation authenticates to the Windows domain and 

interacts with the Windows Kerberos KDC. When this Windows client workstation 

accesses the z/OS Web application, it uses a Kerberos service ticket wrapped in 

a SPNEGO token to single sign-on with WebSphere Application Server for z/OS. 

See Figure 11-2. 

Figure 11-2 Single sign-on with Microsoft Windows KDC only 


When designing such a solution, the WebSphere Application Server for z/OS 

repository need to be considered. For single sign-on to occur, users identities 

need to be known to both Active Directory and the WebSphere registry. 

It is easy to use the Windows domain’s Active Directory registry as either a 

standalone LDAP or federated into the federated repositories. This way all users 

are known the same in the Windows environment and in WebSphere. 

You may choose to use RACF as a local operating system registry for 

WebSphere. This is the configuration we choose for our scenario. In that case, it 

is necessary to synchronize the Windows identities with the RACF identities. We 

do this manually in our scenario. 

If you decide to use another registry then, depending on your environment, you 

may need to do some name mapping for users presented. Also, a process must 

be implemented to make sure that there is user mapping between registries. This 

mapping may be one-to-one or many-to-one, depending upon the environments 

architecture. 

We describe the detailed step-by-step implementation of this solution in this 

chapter. 

11.2.2 Single sign-on with z/OS KDC and Microsoft Windows KDC 

The Kerberos protocol is designed to operate across organizational boundaries. 

Each organization wanting to run a Kerberos server can establish its own realm. 

The name of the realm in which a client is registered is part of the client's name 

and can be used by the application server to decide whether to honor a request. 

By establishing cross-realm keys, the administrators of two realms can allow a 

client authenticated in one realm to use its credentials in the other realm. The 

exchange of cross-realm keys registers the ticket-granting service of each realm 

as a principal in the other realm. A client is then able to obtain a ticket-granting 

ticket for the remote realm's ticket-granting service from its local ticket-granting 

service. Tickets issued to a service in the remote realm indicate that the client 

was authenticated from another realm. 

You may already have a z/OS KDC in your organization. You may want to take 

advantage of the strong z/OS KDC capabilities such as sysplex awareness. You 

may choose z/OS as your trusted security vault. In these cases, it is possible to 

have WebSphere Application Server for z/OS defined as a kerberized service in 

the z/OS KDC Kerberos realm (zOSKerbRealm). 

The Microsoft Windows Active Directory KDC still has its own Windows Kerberos 

realm (WinKerbRealm). The user client workstation authenticates to this 

Kerberos realm. 


With such a configuration, a cross-realm trust is created between the 

zOSKerbRealm and the WinKerbRealm by establishing cross-realm keys. 

Consequently, the user client workstation can access the z/OS Web application 

using a Kerberos service ticket wrapped in a SPNEGO token to single sign-on 

with WebSphere Application Server for z/OS. See Figure 11-3. 

Figure 11-3 Single sign-on with z/OS KDC and Microsoft Windows KDC 

The detailed step-by-step implementation of this solution is described in an 

article on developerWorks: 

http://www.ibm.com/developerworks/websphere/techjournal/0707_rogers/070 

7_rogers.html 

11.3 Implementing single sign-on using SPNEGO TAI 

From a technical perspective, the overall goal of this section is to enable the 

WebSphere Application Server for z/OS SPNEGO TAI to trust requests and 


validate user credentials that come from SPNEGO-enabled clients that are part 

of a Microsoft Windows Active Directory domain. 

In this section we first describe our environment and our scenario, then we 

explain in detail how to configure the three main components of this solution, 

which are WebSphere Application Server for z/OS, Windows Active Directory 

KDC, and the user workstation browser, and finally we provide hints about how 

to troubleshoot this solution. 

11.3.1 Our environment and our scenario 

The solution we implement in our environment is based on the solution design 

described in 11.2.1, “Single sign-on with Microsoft Windows KDC only” on 

page 397. The three main components for this single sign-on solution are: 

► The Web application server: WebSphere Application Server for z/OS v6.1.0.2 

Build Number: cf20633.22. It runs on z/OS v1r8. 

► The Kerberos KDC: Microsoft Windows Server 2003 SP1 with Active 

Directory KDC. The Windows 2003 Support Tools are installed. 

► The user workstation: Microsoft Windows XP Professional 2002 SP2. The 

Windows Server 2003 Resource Kit Tools are installed. It runs Microsoft 

Internet Explorer v6.0.29000 and Mozilla Firefox v1.0.7. 

The user logs onto the Microsoft Windows Active Directory domain with an 

identity known in Active Directory (USER1). He then accesses a Web application 

using his browser, and his identity is propagated to WebSphere Application 

Server for z/OS. This identity is mapped to a known RACF identity (USER1). 

Single sign-on occurs between the Windows domain and the WebSphere 

application server. 


Figure 11-4 shows the detailed steps of this scenario. 

Figure 11-4 SPNEGO TAI and Windows single sign-on scenario 

At the very beginning the user logs onto the Windows domain from the 

workstation. After the user enters a user name and password, Winlogon sends 

the information to the workstation local security authority, which passes the 

request to the Kerberos authentication package. The client sends an initial 

authentication request (AS_REQ), which includes the user’s credentials and an 

encrypted time stamp to the KDC. This is a request for authentication and a ticket 

granting ticket. The first domain controller in the domain generates the 

krbtgt/domain_name ticket. The KDC uses the secret key to decrypt the time 

stamp and issues a TGT to the client. The AS_REP is encrypted with the user’s 

key and returned to the user. The ticket is encrypted with the KDC’s key and 

enclosed in the AS_REP. 


When the user accesses the Web application, the scenario executes the 

following steps for single sign-on: 

1. The user requests a secured Web resource using a browser. This sends a 

HTTP get request to WebSphere Application Server for z/OS. 

2. WebSphere Application Server for z/OS and SPNEGO TAI answer to the 

client browser with an HTTP challenge header 401 containing the 

Authenticate: Negotiate status. 

3. The client browser recognizes the negotiate header because it has been 

configured to support integrated Windows authentication. The client parses 

the requested URL for the host name. The client uses the host name as an 

attribute to request a valid Kerberos Service Ticket from the Kerberos ticket 

granting service in Active Directory KDC (TGS_REQ). The TGS then issues a 

service ticket (TGS_REP) to the client. 

4. The client puts this Kerberos service ticket in an SPNEGO token. The service 

ticket proves both the user’s identity and permissions to the service, and the 

service’s identity to the user. The client responds to the WebSphere 

Application Server for z/OS Authenticate: Negotiate challenge with the 

SPNEGO token in the request HTTP header. 

5. WebSphere Application Server for z/OS and SPNEGO TAI see the HTTP 

header with the SPNEGO token. It extracts the Kerberos service ticket and 

gets the identity (principal) of the user. 

6. The SPNEGO TAI maps the identity to a valid RACF identity and validates 

this identity against RACF. This identity is set in the principal of the JAAS 

subject. Once the identification process is executed, WebSphere executes 

the related Java code (servlets, JSPs, EJBs, and so on) and checks 

authorizations. 

7. If all access is granted, WebSphere Application Server for z/OS sends back 

the response with an HTTP 200. WebSphere also includes in the response a 

LTPA token (in the form of a cookie). 

For all subsequent requests, the LTPA token is used to access resources 

securely. Hence, the SPNEGO protocol is executed once for the first request. 

The key point to notice here is that the user is not prompted to authenticate to 

WebSphere Application Server for z/OS in this scenario. The solution flows the 

user’s existing Active Directory credentials to the WebSphere server. The user's 

access is via his Windows credentials. This is single sign-on between Windows 

and WebSphere Application Server for z/OS using the SPNEGO. 


11.3.2 Configuring the Microsoft Windows server 

In this section, we describe how to configure the Microsoft Windows Active 

Directory and its Kerberos KDC. 

Before configuring 

A working domain controller and at least one client computer in that domain are 

required for this solution, as trying to use SPNEGO from the domain controller 

does not work. 

We recommend making sure that you have the following before configuring: 

► A functioning Microsoft Windows 2000/2003 Active Directory Domain 

including: 

– Domain controller 

– Client workstation 

– Users that can log into the client workstation 

► A functioning WebSphere Application Server for z/OS with application 

security enabled. 

► The users from the Active Directory should be able to successfully access 

WebSphere Application Server’s protected resources using a native 

authentication mechanism such as basic authentication (BA) or forms 


► Windows 200x Support Tools must be installed on the Microsoft Windows 

Server. These include the setspn, the ktpass, and the adsiedit tools. These 

support tools are available on the Windows Server installation CD or from the 

Microsoft Web site: 

http://www.microsoft.com/downloads/details.aspx?familyid=6EC50B78-8B 

E1-4E81-B3BE-4E7AC4F0912D 

► The SPNEGO TAI configuration requirements must be satisfied. These are 

described in the InfoCenter at: 

http://publib.boulder.ibm.com/infocenter/wasinfo/v6r1/index.jsp?topic 

=/com.ibm.websphere.zseries.doc/info/zseries/ae/rsec_SPNEGO_tai_reqs. 

html 

We also recommend installing the Windows Server 2003 Resource Kit Tools, 

which provide the kerbtray.exe utility to see Kerberos tickets. This package can 

be installed on the user workstation: 

http://www.microsoft.com/downloads/details.aspx?FamilyID=9d467a69-57ff- 

4ae7-96ee-b18c4790cffd 


Creating the WebSphere service principal name 

Create a user account for WebSphere Application Server for z/OS in the 

Microsoft Active Directory. This account is mapped to the Kerberos service 

principal name (SPN). This identifies the WebSphere Application Server for z/OS 

installation as a kerberized service. 

In order to create this SPN for WebSphere, follow these steps: 

1. Log on as an administrator to the Windows 2003 Server machine that serves 

as the domain controller. 

2. Invoke the Active Directory users and computers snap-in by typing the 

following command in the Start/Run menu: 

dsa.msc /server=localhost 

Figure 11-5 Windows Run display 


3. Create a user account for WebSphere Application Server for z/OS. We create 

a wtsc58a user account. 

Figure 11-6 Windows New Object - User display 


The new user account then appears in the list of Windows users and 

computers (Figure 11-7). 

Figure 11-7 Windows Active Directory Users and Computers display 


4. Right-click this new user account and select Properties. Go to the Account 

tab and scroll down the account options. Check the Use DES encryption 

types for this account check box. Then click OK to validate. We choose to 

use DES encryption for compatibility reasons. See Figure 11-8. 

Figure 11-8 Windows user properties Account tab 


5. Invoke the Active Directory service interface snap-in by typing the following 

command in the Start/Run menu: 

adsiedit.msc 

Note: In order to use the Active Directory service interface snap-in 

(adsiedit.msc), the Windows Server Support Tools have to be installed, as 

described in the tip at the beginning of this section. 

Figure 11-9 Windows Active Directory Service Interface display 

Verify that the new user (wtsc58 in our case) has been created and check its 

distinguished name (CN=wtsc58a,CN=Users,DC=kkdc,DC=test,DC=com in 

our example). 

6. Map the user account to the Kerberos service principal name. This user 

account represents the WebSphere Application Server as being a kerberized 

service with the Kerberos key distribution center. 

Use the following setspn command for this task: 

setspn -a HTTP/ 

We run the following command for our environment: 

setspn -a HTTP/wtsc58a.kkdc.test.com wtsc58a 


List SPNs defined for the user account with the following command: 

setspn -l wtsc58a 

Example 11-1 setspn command output 

C:\>setspn -a HTTP/wtsc58a.kkdc.test.com wtsc58a 

Registering ServicePrincipalNames for 

CN=wtsc58a,CN=Users,DC=kkdc,DC=test,DC=com 

HTTP/wtsc58a.kkdc.test.com 

Updated object 

C:\>setspn -l wtsc58a 

Registered ServicePrincipalNames for 

CN=wtsc58a,CN=Users,DC=kkdc,DC=test,DC=com: 

HTTP/wtsc58a.kkdc.test.com 

Tip: More information about the setspn tool can be found here: 

http://technet2.microsoft.com/WindowsServer/en/library/318642de-15a3 

-4478-beb0-8022696def511033.mspx?mfr=true 

Creating the Kerberos keytab file 

Use the ktpass tool to set up the Kerberos keytab file (krb5.keytab) for the 

previously created service principal name. 

Ktpass allows you to configure a non Windows Server 2003 Kerberos service 

(like WebSphere applications on a z/OS platform) as a security principal in the 

Windows Server 2003 Active Directory. This tool generates a keytab file 

containing the shared key of the service. This keytab file is then transferred over 

to the WebSphere server so that the SPNEGO TAI can use it. 

Use the following ktpass command for this task: 

ktpass -princ HTTP/@ -out 

-pass password -mapUser -crypto 

DES-CBC-MD5 -mapOp set 

The most common options are (use the -help switch to get a full list of switches): 

► princ principal_name specifies the principal name. The Windows Domain can 

be found on the Active Directory service interface snap-in displayed before. It 

has to be all upper-case. 

► out filename specifies the keytab to produce. 

► pass password specifies the password to use. 

► mapuser username maps princ to the user. 


► crypto specifies the type of cryptographic system to use. With the wtsc58a 

Windows account we set up, DES-CBC-MD5 has to be selected. 

Tip: More information about the keytab files and the ktpass command can be 

found here: 

http://technet2.microsoft.com/WindowsServer/en/library/5090598d-a735 

-4c73-9e37-1a95a4651fa51033.mspx?mfr=true 

We run the following command for our environment: 

ktpass -princ HTTP/wtsc58a.kkdc.test.com@KKDC.TEST.COM -out 

c:\wtsc58a.keytab -pass password -mapUser wtsc58a -crypto DES-CBC-MD5 

-mapOp set -ptype KRB5_NT_PRINCIPAL 

The realm name has to be written in uppercase letters for the ktpass command. 

We choose the DES-CBC-MD5 encryption algorithm for compatibility reasons. 

Restriction: Microsoft Windows Active Directory supports two different 

Kerberos encryption types: RC4-HMAC and DES-CBC-MD5. IBM Java 

Generic Security Service (JGSS) library (and SPNEGO library) support both 

of these encryption types. RC4-HMAC encryption is only supported with a 

Windows 2003 Server key distribution center. RC4-HMAC encryption is not 

supported when using a Windows 2000 Server as a Kerberos KDC. 

There might be a warning regarding the account type and the ptype, but that can 

safely be ignored. 

Example 11-2 ktpass command output 

C:\>ktpass -princ HTTP/wtsc58a.kkdc.test.com@KKDC.TEST.COM -out 

c:\wtsc58a.keytab -pass password -mapUser wtsc58a -crypto DES-CBC-MD5 

-mapOp set -ptype KRB5_NT_PRINCIPAL 

Targeting domain controller: sec05.kkdc.test.com 

Using legacy password setting method 

Successfully mapped HTTP/wtsc58a.kkdc.test.com to wtsc58a. 

Key created. 

Output keytab to c:\wtsc58a.keytab: 

Keytab version: 0x502 

keysize 67 HTTP/wtsc58a.kkdc.test.com@KKDC.TEST.COM ptype 1 

(KRB5_NT_PRINCIPAL) 

vno 8 etype 0x3 (DES-CBC-MD5) keylength 8 (0x13bfe54345ea08d3) 


11.3.3 Configuring WebSphere Application Server for z/OS 

The WebSphere Application Server for z/OS SPNEGO TAI configuration requires 

some Kerberos configuration within z/OS Unix System Services, then some TAI 

configuration within WebSphere, and finally some JVM configuration within 

WebSphere. 

Configuring the Kerberos configuration file 

The Kerberos configuration properties must be updated to the relevant values for 

the Kerberos key distribution center (KDC) and its port, the location of the actual 

Kerberos keytab file that has been copied from the Windows 2003 server, as well 

as the Kerberos realm name that is the related Microsoft domain controller. 

WebSphere Application Server for z/OS has a wsadmin utility to generate the 

Kerberos configuration file. 

1. Transfer in binary format the previously generated keytab file from the 

Windows server to the z/OS partition in UNIX System Services. We put the 

keytab file in the existing z/OS Kerberos directory in /etc/skrb. A Kerberos 

keytab configuration file contains a list of keys that are analogous to user 

passwords. It is important for hosts to protect their Kerberos keytab files. 

2. If Kerberos is not already used by another component in z/OS, rename the 

existing Kerberos configuration with a command such as the following in 

UNIX System Services: 

mv krb5.conf krb5.conf.backup20061115 

3. The SPNEGO TAI expects the configuration file to be in the /etc/krb5 

directory. Create a symbolic link from /etc/krb5 to the /etc/skrb directory with 

the following command: 

ln -s /etc/skrb /etc/krb5 

You can specify another location by using the JVM system property 

java.security.krb5.conf. 


4. The following steps use the wsadmin utility to create a Kerberos configuration 

file. An administrator user is needed to be able to connect to WebSphere with 

the wsadmin utility. Make sure that the user is declared as an administrator in 

the administrative console administrative user roles list. In our environment 

we use the wsadmin user for wsadmin scripting. See Figure 11-10. 

Figure 11-10 Administrative User Roles display 

5. Create a createKrbConfigFile.jacl file in the /tmp directory, for instance. Enter 

the following command in the file (all on one line) and customize it to your 

environment: 

$AdminTask createKrbConfigFile {-krbPath /etc/skrb/krb5.conf -realm 

KKDC.TEST.COM -kdcHost sec05.kkdc.test.com -dns kkdc.test.com 

-keytabPath /etc/skrb/wtsc58a.keytab -encryption des-cbc-md5} 

We choose des-cbc-md5 for encryption, as Windows tickets come encrypted 

with this algorithm. 

6. Use wsadmin to run the above jacl script with a command such as the 

following: 

wsadmin.sh -user wsadmin -password wsadmin1 -f 

/tmp/createKrbConfigFile.jacl 

The output of this command in shown in Example 11-3. 

Example 11-3 wsadmin command execution output 

VALENCE:/WebSphereBS4/V6R1/AppServer/bin $ wsadmin.sh -user wsadmin 

-password wsadmin1 -f /tmp/createKrbConfigFile.jacl 

WASX7209I: Connected to process "ws6584" on node nd6584 using SOAP 

connector; The type of process is: UnManagedProcess 

7. Make sure that WebSphere users (controller region and servant region) have 

sufficient read access to the /etc/krb5/krb5.conf file. 


The /etc/skrb/krb5.conf is now created, and its content is shown in Example 11-4. 

Example 11-4 krb5.conf file content 

[libdefaults] 

default_realm = KKDC.TEST.COM 

default_keytab_name = FILE:/etc/skrb/wtsc58a.keytab 

default_tkt_enctypes = des-cbc-md5 

default_tgs_enctypes = des-cbc-md5 

kdc_default_options = 0x54800000 

# forwardable = true 

# proxiable = true 

# noaddresses = true 

[realms] 

KKDC.TEST.COM = { 

kdc = sec05.kkdc.test.com:88 

default_domain = kkdc.test.com 

} 

[domain_realm] 

.kkdc.test.com = KKDC.TEST.COM 

Configuring the SPNEGO TAI in WebSphere 

This section configures the SPNEGO TAI in WebSphere Application Server. 

Make sure that all the preceding steps in the previous section have been 

executed. 

1. Log on to the WebSphere Application Server administrative console. 

2. Make sure that administrative security and application security are enabled in 

your WebSphere Application Server for z/OS configuration. 


3. Click Security → Secure administration, applications, and infrastructure. 

Expand Web security. Under the General Properties heading, select the 

check box to Enable trust association and click Apply. See Figure 11-11. 

Figure 11-11 Enable Trust Association window 

4. Click Interceptors and then click the SPNEGO TAI in the list of interceptors, 

com.ibm.ws.security.spnego.TrustAssociationInterceptorImpl, then click 

Custom properties, then click Add to set up properties as follows: 

– com.ibm.ws.security.spnego.SPN.hostName: This attribute is 

required. It specifies the full DNS host name in the SPN used by the 

SPNEGO TAI to establish a Kerberos secured context. It is the host name 

used with the ktpass command. 

– com.ibm.ws.security.spnego.SPN.filter: This attribute is optional. It 

specifies the conditions that are matched against the HTTP request 

headers to determine whether the HTTP request is selected for SPNEGO 

authentication. In a WebSphere Standalone server configuration, we 

strongly recommend using this option so that the SPNEGO TAI does 

operate when accessing the administrative console. 


Tip: The complete list of available custom properties for the SPNEGO TAI 

is available in the InfoCenter at the following URL: 

http://publib.boulder.ibm.com/infocenter/wasinfo/v6r1/index.jsp? 

topic=/com.ibm.websphere.zseries.doc/info/zseries/ae/rsec_SPNEGO_ 

tai_attribs.html 

In our environment we add the following properties with the following values: 

com.ibm.ws.security.spnego.SPN1.hostName : wtsc58a.kkdc.test.com 

com.ibm.ws.security.spnego.SPN1.filter : request-url%=snoop 

In our example, we use the WebSphere embedded snoop servlet to verify our 

configuration setup. 

Figure 11-12 SPNEGO TAI custom properties display 

5. After you finish defining your custom properties, click Save to store the 

updated SPNEGO TAI configuration. 

Configuring the JVM for the SPNEGO TAI 

The following steps configure the JVM for use with the SPNEGO TAI. 


2. For the Control region, navigate to Servers → Application servers → 

server_name → Java and Process management → Process Definition → 


Control → Java Virtual Machine and locate the Generic JVM arguments 

text box. Add the following option in this text box: 

-Dcom.ibm.ws.security.spnego.isEnabled=true 

3. For the Servant region, navigate to Servers → Application servers → 


Servant → Java Virtual Machine and locate the Generic JVM arguments 

text box. Add the following option in this text box: 

-Dcom.ibm.ws.security.spnego.isEnabled=true 

Tip: To enable the JGSS and KRB5 traces, add the following to the 

Generic JVM arguments text box: 

-Dcom.ibm.security.jgss.debug=all 

-Dcom.ibm.security.krb5.Krb5Debug=all 

Figure 11-13 Java Virtual Machine properties display 


Verifying security in WebSphere 

The following steps may have already been done in your environment: 


2. Verify that you have Lightweight Third-Party Authentication (LTPA) as the 

authentication mechanism. You can verify that you use LTPA in Security → 

Secure administration, applications, and infrastructure → 

Authentication mechanisms and expiration. LTPA is now the default 

authentication mechanism. The “Use SWAM-no authenticated 

communication between servers” check box should not be checked. The 

Enabled check box should be checked under Security → Secure 

administration, applications, and infrastructure → single sign-on (SSO). 

3. Verify that you have administrative and application security on under 

Security → Secure administration. 

4. In our configuration, we use the local operating system user registry 

(LocalOS), which is RACF. It is also possible to use Active Directory as a 

LDAP user registry. 

5. Make sure that the user identities used within the Active Directory domain are 

also known by the user registry used by WebSphere. This is mandatory for 

single sign-on to happen. 


At server startup, the servant region log should appear the SPNEGO TAI 

initialization and parameters. Example 11-5 shows our servant region log. 

Example 11-5 SPNEGO TAI servant region log 

BossLog: { 0021} 2006/11/16 04:03:02.713 01 SYSTEM=SC58 SERVER=WS6584 

./bborjtr.cpp+953 ... CWSPN0006I: SPNEGO Trust Association Interceptor 

initialialization is complete. Configuration follows: 

TAI configuration (JVM) properties: 

com.ibm.ws.security.spnego.isEnabled=true 

Server configuration: 

Kerberos ServicePrincipalName=HTTP/wtsc58a.kkdc.test.com@KKDC.TEST.COM 

com.ibm.ws.security.spnego.SPN.filter=request-url%=snoop 

com.ibm.ws.security.spnego.SPN.filterClass=com.ibm.ws.security.spnego.H 

TTPHeaderFilter@641c641c 

com.ibm.ws.security.spnego.SPN.NTLMTokenReceivedPage=null 

com.ibm.ws.security.spnego.SPN.spnegoNotSupportedPage=null 


11.3.4 Configuring the Web browser 

In this section, we describe how to configure the Web browser on the user 

workstation. We show how to configure Microsoft Internet Explorer and Mozilla 

Firefox. 

Configuring Microsoft Internet Explorer 

Complete the following steps to ensure that Internet Explorer is enabled to 

perform SPNEGO authentication: 

1. Using the user workstation, log onto the Active Directory domain. 

2. Launch Microsoft Internet Explorer. 

3. Within Internet Explorer, click Tools → Internet Options and select the 

Security tab. Select the Local intranet icon and click Sites. In the Local 

intranet window, ensure that the check box to include all local (intranet) not 

listed in other zones is selected, then click Advanced. 


4. In the Local intranet window, fill in the Add this Web site to the zone field with 

the Web address of the host name so that the single sign-on can be enabled 

to the Web sites shown in the Web sites field. We put 

http://wtsc58a.kkdc.test.com in our configuration. Click OK to complete this 

step and close the Local intranet window. See Figure 11-14. 

Figure 11-14 Internet Explorer Local intranet window 


5. On the Internet Options window, click the Advanced tab and scroll to Security 

settings. Ensure that the Enable Integrated Windows Authentication (requires 

restart) box is selected. Click OK. See Figure 11-15. 

Figure 11-15 Internet Explorer Internet Options window 

6. Restart Microsoft Internet Explorer to activate this configuration. 

Configuring Mozilla Firefox 

Complete the following steps to ensure that Mozilla Firefox is enabled to perform 

SPNEGO authentication. 

1. Using the user workstation, log on to the Active Directory domain. 

2. Launch Mozilla Firefox. 

3. In the browser address field, type about:config. 

4. In the filter field, type network.n. 


5. Double-click network.negotiate-auth.trusted-uris. This preference lists the 

sites that are permitted to engage in SPNEGO authentication with the 

browser. Enter a comma-delimited list of trusted domains or URLs. We enter 

http://wtsc58a.kkdc.test.com in our environment. See Figure 11-16. 

Figure 11-16 Mozilla Firefox configuration window 

If the deployed SPNEGO solution uses the advanced Kerberos feature of 

credential delegation double-click network.negotiate-auth.delegation-uris. 

This preference lists the sites for which the browser may delegate user 

authorization to the server. Enter a comma-delimited list of trusted domains or 

URLs. 

6. Click OK and the configuration appears as updated. 

7. Restart the Firefox browser to activate this configuration. 

11.3.5 Tips for troubleshooting the SPNEGO TAI configuration 

For troubleshooting the SPNEGO TAI configuration on the WebSphere side, we 

recommend turning on the following traces: 

► With the Administrative Console in Troubleshooting → Logging and 

Tracing → → Change Log Detail Levels: 

com.ibm.ws.security.spnego.* 


► With the Administrative Console in Servers → Application servers → 


Servant → Java Virtual Machine, locate the Generic JVM arguments text 

box. Add the following options in this text box to enable JGSS and KRB5 

traces: 

-Dcom.ibm.security.jgss.debug=all 

-Dcom.ibm.security.krb5.Krb5Debug=all 

The trace appears in the Servant region. 

Here are some ideas for troubleshooting a new SPNEGO TAI configuration: 

► Make sure that you are trying to access WebSphere Application Server with a 

user that is logged into the domain. 

► Make sure that you are not trying to access the application server from the 

domain controller. 

► Make sure that the TAI initialized successfully with a message such as the 

following in the servant region: 

CWSPN0006I: SPNEGO Trust Association Interceptor initialialization 

is complete. 

► Make sure that you have the correct encryption types specified in your 

Kerberos configuration file and that all encryption type configurations match. 

► Make sure that you have the same time on the WebSphere Application 

Server host and the domain controller. 

► On the user workstation side, use kerbtray.exe to see what tickets have been 

granted to the user logged in. This utility is provided with the Windows Server 

2003 Resource Kit Tools. 

► Restart the user workstation. Sometimes if the client was brought up before 

the domain controller, then this can have adverse affects. 

► Remove any filters you have specified for the TAI. Try to get a connection 

working before you start filtering requests. 

► Make sure that you have SPNEGO authentication enabled on the client’s 

browser. 

Some other good tips are available in the InfoCenter at the following URL: 


com.ibm.websphere.zseries.doc/info/zseries/ae/rsec_SPNEGO_trouble_shoot 

.html 


11.4 Validating single sign-on using the SPNEGO TAI 

In this section we validate the single sign-on scenario between a Windows 

workstation. 

Using the user workstation, log on to the Windows Active Directory domain. We 

use the Valence user ID in our configuration. This user ID exists both in Active 

Directory and in RACF. 

Using the kerbtray.exe utility, it is possible to see the Kerberos tickets acquired 

by the user. The kerbtray.exe utility is available from the Windows Server 2003 

Resource Kit Tools. Right after logon, we can verify that the workstation obtained 

the ticket granting ticket from the Windows KDC. 

This TGT is named krbtgt/KKDC.TEST.COM in our example (Figure 11-17). 

Figure 11-17 User Kerberos tickets after logon 

Launch a Web browser such as Microsoft Internet Explorer. Enter the URL 

address of the application that you want to single sign-on with. We use the 

WebSphere embedded snoop servlet in our example at the following address: 

http://wtsc58a.kkdc.test.com:49080/snoop/ 

When security is on with WebSphere, the embedded snoop servlet asks for 

authentication. Because we use the SPNEGO TAI, because we configured the 


owser accordingly, because the Windows KDC, the browser asks the KDC for 

a Service Ticket to use the HTTP service with wtsc58a. Then the browser sends 

the HTTP request including a SPNEGO token with the user identity (Valence) to 


The detailed communication steps are described in the scenario description 

shown in Figure 11-4 on page 402. 

Figure 11-18 Internet Explorer Snoop servlet display 

The browser displays the snoop servlet, which shows the authenticated user. 

The WebSphere authenticated user (Valence) is the Windows domain 

authenticated user. Single sign-on occurred between the Windows domain and 

WebSphere Application Server for z/OS using the SPNEGO TAI. 


The same behavior happens with another Web browser such as Mozilla Firefox, 

as shown on Figure 11-19. 

Figure 11-19 Mozilla Firefox Snoop servlet display 

The WebSphere for z/OS servant region log confirms this scenario, shows that 

the SPNEGO token is processed, and highlights the authenticated user. 

Example 11-6 shows this log. 

Example 11-6 WebSphere z/OS servant region log with traces on 

Trace: 2006/11/16 14:26:31.280 01 t=8C7718 c=UNK key=P8 (13007002) 

ThreadId: 00000029 

FunctionName: handleRequest 

SourceId: com.ibm.ws.security.spnego.SpnegoHandler 

Category: FINER 

ExtendedMessage: SPNEGO request token successfully processed. 



FunctionName: handleRequest 


Category: INFO 

ExtendedMessage: CWSPN0023I: Username VALENCE@KKDC.TEST.COM Token 

size 1662. 




FunctionName: trimUsername 



ExtendedMessage: Principal name was trimmed to: VALENCE 



FunctionName: negotiateValidateandEstablishTrust 

SourceId: com.ibm.ws.security.spnego.TrustAssociationInterceptorImpl 


ExtendedMessage: Authenticated user: VALENCE Subject: Subject: 

Principal: VALENCE@KKDC.TEST.COM 

It is also interesting to look at the Kerberos tickets acquired by the user 

workstation after running the HTTP request. Using the kerbtray.exe utility, it is 

possible to see the Kerberos tickets acquired by the user. The kerbtray.exe utility 

is available from the Windows Server 2003 Resource Kit Tools. This utility shows 

that the user obtained a service ticket to access the WebSphere for z/OS 

kerberized service. 

This ST is named HTTP/wtsc58a.kkdc.test.com in our example (Figure 11-20). 

Figure 11-20 User Kerberos tickets after HTTP request 


We use Ethereal software to sniff the network and see the communication flows 

between the user workstation and the other parties. It shows the first 

unauthorized HTTP request to WebSphere, then the service ticket request to the 

ticket granting server (TGS-REQ and TGS-REP) and the single sign-on HTTP 

request to WebSphere. Figure 11-21 shows the communications from the user 

workstation. 

Figure 11-21 Etheral output showing single sign-on steps 

All this validates the scenario described in Figure 11-4 on page 402 and confirms 

the single sign-on between the Windows domain and WebSphere Application 



Chapter 12. Operating system security 

In this chapter we introduce some new security features for WebSphere 

Application Server Version 6.1 for z/OS administrative security. 

We cover the following topics: 

► “Out-of-the-box administrative security” on page 430 

► “Automatically generated server IDs” on page 441 

► “RACF - mixed-case password support” on page 443 

► “Sync-to-OS thread update” on page 444 

12 


12.1 Out-of-the-box administrative security 

When installing WebSphere Application Server Version 6.1 for z/OS you may 

notice some differences from previous versions. WebSphere Application Server 

Version 6.1 for z/OS contains improved security features. One of the most 

remarkable new options is out-of-the-box administrative security. Out-of-the-box 

administrative security gives you the option to enable administrative security at 

installation and configuration time to prevent unauthorized access to the 


In previous versions of WebSphere Application Server the initial installation of 

the server did not have a security configuration (yet). Access to the 

administrative system and its configuration data were not protected by default. If 

you needed security enabled, you had to activate global security, which 

activates security for both administration and applications. 

In WebSphere Application Server V6.1 for z/OS, global security has been split 

into administrative and application security. By enabling administrative security 

by default, you can keep unauthorized users from accessing the administrative 

console and your business applications. Administrative security should be 

enabled to restrict access. 

In this section we introduce the new configuration options in the installation 

process from a security point of view. 

There are two installation/customization tools to install WebSphere Application 

Server Version 6.1 for z/OS: the ISPF (Interactive System Productivity Facility) 

Customization Dialog and the zPMT(z/OS Profile Management Tool), which is 

AST (Eclipse) based. They both generate batch jobs, scripts, and data files that 

you use to perform WebSphere Application Server for z/OS customization tasks. 

The panels shown in this chapter to illustrate the security setup options are 

based on the ISPF Customization Dialog. 

12.1.1 Cell-wide common user groups and IDs 

Before introducing the WebSphere Application Server security options we first 

provide common definitions of groups and users. 

In earlier versions of WAS for z/OS, cell-wide security information is set up in the 

Security domain configuration option. It defines user groups and user IDs 

including the application server administrator, SSL customization, security 

domain name, and more. In Version 6.1, this is now done in the “Configure 

common MVS groups and users” option, and its parameters have been changed. 

In Figure 12-1, all the definitions are shown. Note that they are cell-wide. Other 


security values, which were part of the security domain configuration in the 

previous version of WAS, are now specified in the process of the application 

server configuration. There you can specify additional detailed security settings 

for each application server in the same cell. 

------------ WebSphere Application Server for z/OS Customization -------- 

Option ===> 

Configure common MVS groups and users (1 of 1) 

Specify the following to configure common MVS groups and users, 

then press Enter to continue. 

WebSphere Application Server Configuration Group Information 

Group....: WSCFG1 GID..: 2500 

WebSphere Application Server HFS Owner Information 

User ID..: WSOWNER UID..: 2405 

WebSphere Application Server Servant Group Information 

Group....: WSSR1 GID..: 2501 

WebSphere Application Server Local User Group Information 

Group....: WSCLGP GID..: 2502 

WebSphere Application Server user ID home directory: 

/var/WebSphere/home 

Figure 12-1 Common MVS groups and users customization panel 

WebSphere Application Server HFS owner is a new user ID added in WAS V6.1. 

This user ID owns many of the cell's files in the configuration file system. It 

should have the WebSphere Application Server configuration group (see the 

example below) as its default group. 

The following is an example of a RACF group and user ID set up by a RACF 

command. You can find these commands in hlq.DATA(BBOSBRAK), which is 

one of the generated customization jobs. 

Create a new WebSphere Application Server configuration group: 

ADDGROUP WSCFG1 OMVS(GID(2500)) 

Chapter 12. Operating system security 431

Add a new HFS owner user ID: 

ADDUSER WSOWNER DFLTGRP(WSCFG1) OMVS(UID(2405) 

HOME(/var/WebSphere/home/WSCFG1) PROGRAM(/bin/sh)) NAME('WAS HFS 

OWNER') NOPASSWORD NOOIDCARD 

The NOPASSWORD parameter sets the PROTECTED attribute. 

12.1.2 Security configuration options 

There are three administration security options. Figure 12-2 shows the security 

customization options. 


Option ===> 

Security Customization 

Specify a number and press Enter to customize security for WebSphere 

Application Server for z/OS. You should review all of the variables in 

in the section you select, even if you are using all of the 

IBM-supplied defaults. Press PF3 to return to the main menu. 

How do you want to manage user identities and authorization policy? 

1 - Use a z/OS security product 

The z/OS security product manages users, groups, and the 

authorization policy. 

2 - Use WebSphere Application Server 

WebSphere Application Server manages users, groups, and the 

authorization policy. 

3 - Do not enable security 

Figure 12-2 Security Customization panel 

In the following sections we explain the features of each option. 


Option 1: Use a z/OS security product 

If you want to enable administrative security and use a local z/OS repository for 

authentication and authorization, you must choose this option. These are the 

characteristics of this option: 

► Each WebSphere Application Server user and group identity corresponds to a 

user ID or group in the z/OS system's SAF-compliant security server, such as 

RACF. 

► Access to WebSphere Application Server J2EE roles is controlled using the 

SAF EJBROLE class profiles in conjunction with the GEJBROLE class, if you 

choose to use the grouping class. 

► Digital certificates for SSL communication are stored in the z/OS security 

product. 

On z/OS, RACF is always used to control WebSphere Application Server started 

task identities and the digital certificate of the location service daemon. However, 

when the “Use a z/OS security product” option is selected, all WebSphere 

Application Server administrators and administrative groups must be defined to 

SAF as well. Later, when (and if) application security is enabled, the SAF security 

database will need to hold J2EE roles and identities permitted to these 

applicative roles. 

The “Use a z/OS security product” option is appropriate when servers or cells 

reside entirely on z/OS systems, with SAF as the user registry. Customers who 

plan to implement an LDAP or a custom user registry and plan to map 

LDAP/CUR identities to SAF identities and use SAF authorization should also 

choose this option so that initial SAF EJBROLE setup is performed. 

The following SAF user IDs are created: 

► WebSphere Application Server Administrator user ID 

► WebSphere Application Server unauthenticated user ID (to represent a 

WebSphere Application Server ID that has not been authenticated, also 

referred to as the public user ID) 

The server ministration user ID needs to be defined with a password. The expiry 

policies for passwords need to be checked with your security administrators. It is 

advisable to either assign a non expiring password or have good password reset 

policies. Your cell will not function if the administrators password has expired. 


It is common practice to define the unauthenticated user ID with both the 

restricted and protected attributes. See Figure 12-3. 


Option ===> 

z/OS security product 

Specify the following to customize your system environment, then 

press Enter to continue. 

Use security domain identifier in RACF profiles: N 

Security domain identifier.................: 

WebSphere Application Server Administrator Information 

User ID..: WSADMIN UID..: 2403 

WebSphere Application Server Unauthenticated User Information 

User ID..: WSGUEST UID..: 2402 

Figure 12-3 Use a z/OS security product panel 

If you want to prefix the EJBROLE class RACF profiles with a security domain 

and include this domain in CBIND profiles (see below), set “Use security domain 

identifier in RACF profiles” to Y and enter the security domain name. 

The following is an example of the RACF command if no security domain is used: 

RDEFINE CBIND CB.BIND.** UACC(READ) 

PERMIT CB.BIND.** CLASS(CBIND) ID(WSCFG1) ACCESS(CONTROL) 

If you set “Use security domain identifier” to Y and specify the security domain 

identifier, the domain name is added to the profile. The resulting RACF command 

would be: 

RDEFINE CBIND CB.BIND..** UACC(READ) 

PERMIT CB.BIND..** CLASS(CBIND) ID(WSCFG1) ACCESS(CONTROL) 


You can verify the current WebSphere Application Server security settings via 

the administrative console by clicking Security → Secure Administration, 

applications, and infrastructure. Figure 12-4 shows the current z/OS security 

settings for option 1. 

Figure 12-4 Security configuration page using a z/OS security product 

Option 2: Use WebSphere Application Server security 

In option 1 the user authentication and authorization policy is managed through 

SAF. In option 2, as in options 1 and 3, RACF is used to control WebSphere 

Application Server for z/OS started task identities, as well as the location service 

daemon's digital certificate. However, users and groups are defined in the 

WebSphere Application Server user registry and authorization is managed by 

WebSphere Application Server. These are the characteristics of option 2: 

► Each WebSphere Application Server user and group identity corresponds to 

an entry in a WebSphere Application Server user registry. The initial user 

registry is a federated repository, a simple file-based user registry created 

during customization and residing in the configuration file system. 


► Access to WebSphere Application Server roles is controlled using 

WebSphere role bindings. In particular, administrative role bindings are set 

through the Administrative User Roles and Administrative Group Roles 

settings in the admin console. 

► Digital certificates for SSL communication are stored in the configuration file 

system. 

Self-signed digital certificates for servers are created in the configuration file 

system automatically by WebSphere Application Server. 

When selecting option 2 you will be presented with the customization panel, as 

shown in Figure 12-5. The user ID that you specify here is stored in the 

file-based user registry and used as initial administrative user. The sample user 

ID is optional. This field appears once you have selected to install the sample 

application. 


Option ===> 

WebSphere Application Server Security 

Specify a user name and password to login to the administrative console 

and perform administrative tasks. 

User ID.: WSADMIN 

Password: 

Confirm Password: 

The Sample applications require an account in the profile. Assign a 

password to the samples user account. 

User ID.: samples 

Password: 

Confirm Password: 

Figure 12-5 WebSphere Application Server security panel 


You can verify the current WebSphere Application Server security settings via 

the administrative console by clicking Security → Secure Administration, 

applications, and infrastructure. Figure 12-6 shows the current settings of 

option 2. 

Figure 12-6 Security configuration page using WebSphere Application Server security 

Option 3: Do not enable security 

If you select Do not enable security, administrative security will not be activated. 

Note: If you aim to enable SAF security for your application server 

environment in the future, but choose to do initial setup with security disabled, 

you should reconsider. Contrary to previous versions of WebSphere, where 

security was disabled by default, choosing option 3 in Version 6.1 would mean 

having to configure the complete security infrastructure without the help of 

generated installation jobs. Refer to Technote swg1237841: 

http://www-1.ibm.com/support/docview.wss?uid=swg21237841 


12.1.3 Security customization jobs 

Regardless of the administrative security option selected, you submit the 

customization jobs to define the desired security infrastructure as part of the 

server configuration process. Profiles in the STARTED class, for instance, need 

to be defined in any case when running WebSphere on z/OS. In the process of 

configuring a base application server member hlq.DATA(BBOWBRAK) contains 

all RACF commands. The commands in BBOWBRAK are generated by 

submitting hlq.CNTL(BBOCBRAJ). If you browse hlq.DATA(BBOWBRAK) you 

can examine the generated RACF commands. 

The RACF commands generated are: 

► Common RACF security setup, which is required regardless of security 

option: 

– Activate RACF SERVER, STARTED, and FACILITY classes. 

– Add user for WebSphere Application Server regions. 

– Add default asynchronous admin task user. 

– Connect servants to the WebSphere configuration group. 

– Define and permit access for the log stream profile. 

– Define and permit access for SERVER CB profiles. Determine whether a 

servant region can initialize. 

– Define FACILITY BPX.WLMSERVER profiles. Authorize servants to use 

WLM services. 

– Assign user IDs to STARTED tasks. 

– Define permissions to work with certificates. 

– Create a certificate authority certificate. 

– Create SSL keyring (WAS CA certificates/commercial CAs) for the location 

service daemon. 

– Generate a certificate for the location service daemon. 

– Connect a certificate to the keyring for the location service daemon. 

► Additional security setup for z/OS product security use: 

– Activate RACF CBIND and SURROGAT classes. The SURROGAT class 

profile relating to the Sync-to-OS feature is new in WAS Version 6.1. 

– Create a WAS administrator user ID and an unauthenticated user ID. 

– Set up the RACF APPL class profile. 

– Set up CBIND class profiles. CBIND profiles are created, and granted to 

the configuration group. 


– Set up EJBROLE class profiles: 

Administrative roles (administrator, monitor, configurator, operator, 

deployer, and adminSecurityManager) are created, and the 

administrator user ID is granted the administrator role. 

Naming roles (CosNamingRead, CosNamingWrite, CosNamingCreate, 

and CosNamingDelete) are created. You should permit the 

configuration group for WebSphere Application Server (servers and 

administrators) READ access to all of these profiles. 

– Create an SSL keyring (WAS CA certificates/commercial CAs) for the 

application server. Digital keyrings are created for the administrator, 

controller, controller region adjunct, and server user IDs. 

– Generate a certificate. Digital certificates are created for each server 

controller. 

– Connect the certificate to the keyring. 

– Create Sync-to-OS thread profile (new in WAS Version 6.1). See 

“Sync-to-OS thread update” on page 444 for more information. 

– Create a facility class profile for trusted applications (new in WAS Version 

6.1) 

A trusted application is an application that requires WebSphere 

Application Server to build SAF credentials without an authenticator, for 

instance, a TCB level ACEE being created if SyncToOSthread is enabled. 

The facility class profile is BBO.TRUSTEDAPPS... The 

control region user ID needs to be permitted with access READ and the 

custom property EnableTrustedApplications needs to be set to true in 

Security → Secure administration, applications and infrastructure. 


12.1.4 Comparison of security settings 

For a clear comparison of WebSphere Application Server security configurations 

see Table 12-1. 

Table 12-1 Comparison of default security settings 

User account 

repository 

Authorization 

technology 

(external 

authenticated 

provider 

security) 

Administrative 

role definition 

z/OS security WebSphere Application 

Server security 

Local operating system 

User IDs, groups, and 

passwords are stored in RACF. 

System Authorization Facility 

(SAF) authorization 

Use the authorization policy that 

is stored in RACF. 

RACF EJBROLE profile 

Mapping information is stored in 

RACF. 

Definition of EJBROLE profiles 

is required. (Default roles are 

defined during server 

installation process.) 

Key store type System Authorization Facility 

keyring 

Stored in RACF DB 

Key store PATH: safkeyring:/// 

 

Type: JCERACFKS 


Federated repository 

User IDs and passwords are 

stored in file-based placed 

UNIX System Service. 

User IDs and passwords are 

stored in fileRegistry.xml 

Default authorization 

Use WebSphere Security 


WebSphere Admin Role 

Mapping information is stored in 

UNIX System Services. 

► Information of user IDs and 

roles is stored in 

admin-auth.xml. 

► Primary admin user ID, 

which is used to log on to 

the administrative console, 

is stored in security.xml. 

File-based key store 

Stored in UNIX System 

Services. 

Key store PATH: 

${CONFIG_ROOT}/cells//nodes//< 

key_file> 

Type: PKCS12

Application 

deployment 

(role mapping) 

z/OS security WebSphere Application 

Server security 

Security Authorization 

Facility (SAF)-based mapping 

► Need to define new 

EJBROLE profiles in RACF. 

► The “Map security roles to 

users or groups” step in the 

deployment of an 

application is ineffective. 

In addition to the mentioned application deployment on Table 12-1, when you 

deploy an application that has security constraints defined on servlets, EJBs, or 

something else, one of the deployment steps consists of mapping users and 

groups to security roles. Remember that only administrative security is enabled 

initially (if chosen). Application security must be enabled as well in order to have 

the mapping take effect. 

If you want only to enable administrative security, we recommend choosing 

security using a z/OS security product for the following two reasons: 

► Risk of falsification of data 

RACF user control is much more difficult to be falsified than WebSphere 

Application Server Security user control, in which case information is stored in 

flat files. 

► Easy to change security configuration 

It is easier to change from z/OS security to another option than the other way 

around regarding RACF setup. 

12.2 Automatically generated server IDs 

File-based mapping 

Need to map user and role in 

the “Map security roles to users 

or groups” step in the 

deployment of application. 

Server IDs are used for authentication on server-to-server communication. 

Automatically generated server IDs support improved auditability for cells. 

In previous versions the administrative user ID and password are used not only 

for administrative purposes but also for internal server-to-server communication. 

There was a possibility of password exposure during server-to-server 

communication. WebSphere V6.1 makes a distinction between the 

administrative user ID and the server ID. Automatically generated server IDs do 

not require a password and are not stored in any registry. By default, the server 

ID is the cell name. The administrative user ID is stored in a registry. This ID is 

used to log on to the administrative console when administrative security is 


enabled and no console users or groups are defined yet. As a result of 

separating the function of server IDs and the administrative ID, administrative 

actions can be audited. 

Using internally generated server IDs is a default setting in WebSphere V6.1. To 

maintain backwards compatibility in a mixed cell environment you will need to 

specify the server ID and its password in the WebSphere configuration. 

To change from the internally generated server ID to the z/OS started task 

identity follow the next steps. 

1. Go to Security → Secure administration, applications, and 

infrastructure. 

2. Click the Available realm definitions drop-down list and select your 

repository under User account repository. 

3. Click Configure. 

This configuration option differs for each registry. Figure 12-7 illustrates the 

server identity setting for the local operating system user registry. 

Figure 12-7 Server user identity configuration for local operating system registry 


12.3 RACF - mixed-case password support 

The password is important in protecting users, applications, and systems. The 

harder it is to guess a password the better the protection level. Mixed case 

passwords provide a higher level of security and are harder to break. 

WebSphere for z/OS V6.1 supports multiple user registries. Both file-based 

repositories and a Lightweight Directory Access Protocol repository support 

case-sensitive passwords. In z/OS v1.7 RACF mixed-case password support 

has been introduced. 

WebSphere Application Server V6.1 for z/OS supports RACF mixed-case 

passwords. The support applies both to a local OS User Registry and LDAP 

TDBM native authentication or SDBM. With both LDAP back ends passwords are 

validated in RACF. 

RACF mixed-case password support is disabled by default. To enable 

mixed-case password support you must comply with the following prerequisites: 

► Use z/OS Version 1.7 or later. 

► In WebSphere, either local operating system registry LDAP TDBM NA or 

LDAP SDBM is the configured registry. 

The SETROPTS option to enable or disable mixed-case passwords is not 

available through the RACF panels. You need to issue one of the following 

commands. 

To turn on the MIXEDCASE option: 

SETROPTS PASSWORD(MIXEDCASE) 

To turn off the MIXEDCASE option: 

SETROPTS PASSWORD(NOMIXEDCASE) 

To display the current system-wide RACF options for your environment issue: 

SETROPTS LIST 


PASSWORD PROCESSING OPTIONS: 

PASSWORD CHANGE INTERVAL IS 90 DAYS. 

PASSWORD MINIMUM CHANGE INTERVAL IS 0 DAYS. 

MIXED CASE PASSWORD SUPPORT IS IN EFFECT 

NO PASSWORD HISTORY BEING MAINTAINED. 

USERIDS NOT BEING AUTOMATICALLY REVOKED. 

PASSWORD EXPIRATION WARNING LEVEL IS 10 DAYS. 

NO INSTALLATION PASSWORD SYNTAX RULES ARE PRESENT. 

Figure 12-8 Password excerpt of the SETROPTS LIST command output 

Note: The use of mixed-case passwords on your z/OS systems needs to be 

very carefully planned. Instructing your users is of utmost importance to avoid 

confusion after having entered a new password. Falling back to 

NOMIXEDCASE has an even bigger impact, since all mixed-case passwords 

will need to be reset. 

12.4 Sync-to-OS thread update 

The Sync-To-OS thread security concept is unique to WebSphere Application 

Server on z/OS. It allows the current J2EE thread identity to be propagated to the 

OS thread for use by z/OS resource managers outside the scope of the J2EE 

container. It effectively sets the servant regions TCB level ACEE to the current 

JAAS principal. On other platforms this would always be the user ID that the EJB 

container is running under. In the case of WebSphere Application Server on 

z/OS, the user ID under which the servant region STC is running would be used 

to access back-end systems (also referred to Enterprise Information Systems, or 

EIS) or other resources on z/OS if the Sync-To-OS thread option is set to false. 

Prior to WebSphere V6.1, Sync-to-OS thread was controlled in two ways. 

► The WebSphere Application Server developer had to configure the 

application to declare that it needs to run with application Sync-to-OS thread. 

► The WebSphere Application Server administrator had to configure the 

application server to enable application Sync-to-OS thread allowed. 

What is new in Version 6.1 

Additional controls have been added to secure thread security and thread 

identity support. A new FACILITY class profile must be defined in order for 

Sync-to-OS thread to be allowed. The control region user ID need READ or 

CONTROL access to enable Sync-to-OS thread. With READ access, only 


security environments representing users in the SURROGAT class are allowed, 

while CONTROL allows for security environments to represent any RACF 

defined user ID. 

For this function, the following conditions must all be true: 

► The Sync-to-OS thread allowed value is true. 

If set through the administrative console, go to Security → Secure 

administration, applications, and infrastructure → z/OS security 

options. 

Figure 12-9 Enable z/OS thread identity synchronization 

► An application includes within its deployment descriptor an env-entry of 

com.ibm.websphere.security.SyncToOSThread=true. 


► The new FACILITY class profile and optional SURROGAT class profiles are 

defined. 

Define the new controls in RACF 

To enable Sync-to-OS thread you need to define new RACF profiles. If you 

create an application server with the local operating system option, the 

generated customization job contains the command to define the FACILITY class 

profile but it does not contain permit commands to that profile, nor the define and 

permit commands for the SURROGAT class profiles. 


Create the Sync-to-OS thread profile: 

RDEFINE FACILITY BBO.SYNC.. UACC(NONE) 

PERMIT BBO.SYNC.. CLASS(FACILITY) 

ID(CR_user_id) ACC(READ or CONTROL) 

Create the SURROGAT class profile to optionally establish permission to allow 

Sync-to-OS thread: 

RDEFINE SURROGAT BBO.SYNC. UACC(NONE) 

PERMIT BBO.SYNC. CLASS(SURROGAT) ID(J2EE identity) 

ACC(READ) 

The Java principal (J2EE identity) requesting the synchronization of the OS 

thread needs READ access to a surrogat profile in the form as described above, 

where SR_user_id stands for the user ID under which the application server’s 

servant region is running. Again, this SURROGAT profile is optional. It will only 

be checked if the control region user ID has READ access to the BBO.SYNC 

FACILITY class profile. 


Chapter 13. WAS administrative security 

On the z/OS platform the term administrative security refers to the security 

configuration that is in effect for the WebSphere Application Server cell. 

The configuration of administrative security for a security domain encompasses 

authentication of HTTP clients, authentication of IIOP clients, administrative 

console security, and naming security. 

In this chapter we focus on configuring administrative roles, resource instance 

access, and naming service security. 

These subtopics are addressed: 

► “Security configuration and administration” on page 448 

► “Role-based administrative security” on page 460 

► “Naming service security” on page 467 

13 


13.1 Security configuration and administration 

In this section we introduce the helpful security administration tools provided in 

V6.1 and show an example of a security implementation using the security 

wizard. 

13.1.1 Simplified security administration 

WebSphere Application Server V6.1 has an improved administrative console 

interface, which is different from V6.0. A more user-friendly interface simplifies 

the configuration of security settings and administrative operations. 

After installation and initial configuration of an application server environment 

you would normally first customize your security environment. The security 

wizard is helpful for basic security customization if your server is running with 

security disabled. The security configuration reporting tool is useful to display an 

overview of your current security settings. 

Security wizard 

The security wizard helps you to configure an existing user registry and to enable 

administrative, application, and resource security. 

Security configuration reporting tool 

The security configuration reporting tools’ output is somewhat limited, but it does 

display the core security settings as defined in your WebSphere environment. 

The report is divided into four columns: 

► Console Name 

► Security Configuration Name 

► Value 

► Console Path Name 

The console name entry is the name of the security setting or variable as it is 

presented in the admin console. The security configuration name is the name of 

the same variable as used internally by WebSphere. The security configuration 

name is what you would find in the configuration file system if you browse files 

like security.xml. 


Figure 14-1 shows an example of a security configuration report. 

Figure 13-1 Security configuration report, example 

13.1.2 Administrative security implementation 

The installation dialogs offer two options to configure administrative security: 

► Provider configuration with the z/OS security product option in the ISPF 

panels (or zPMT) 

► Provider configuration with the WebSphere Application Server option in the 

ISPF panels (or zPMT) 

We strongly recommend enabling administrative security in order to restrict 

access to the administrative console. Sometimes WebSphere environments with 

Chapter 13. WAS administrative security 449

disabled security may be required, for instance, in a developer environment. In 

that case it might be a good idea to restrict access to the administrative console’s 

TCP/IP port by means of the TCP/IP SAF keyword in the TCP/IP PORT 

configuration and SERVAUTH class profiles, or by means of other IP-elated 

SERVAUTH profiles. 

Before enabling administrative security you need to choose an authorization 

provider. Authorization information determines whether a user or group has the 

necessary privileges to access resources. WebSphere Application Server for 

z/OS supports the following three authorization providers: 

► Default authorization 

Default authorization does not require special setup. The default authorization 

engine makes all of the authorization decisions. 

► External authorization using a JACC provider 

The JACC-based authorization provider enables third-party security providers 

(like Tivoli Access Manager) to handle the J2EE authorization. 

► System Authorization Facility (SAF) authorization 

SAF-based authorization uses the SAF EJBROLE class to control client 

access to Java 2 Enterprise Edition (J2EE) roles in EJBs and Web 

applications. 

13.1.3 Administrative security with SAF authorization 

Here we show the necessary steps to enable administrative security. We did not 

enable administrative security during the installation process. 

In order to enable z/OS product security you have to decide on your 

authorization provider. If you choose default authorization, RACF is used as the 

user registry but it is not used as user-to-role mapping repository. If you choose 

SAF as your authorization provider, RACF is used both as the user registry and 

for user-to-role mapping. 

If you choose default authorization provider, follow these steps: 

1. Log on to the administrative console. 



3. Click the Security Configuration Wizard button. 

a. Specify the extent of protection (see Figure 13-2). Optionally, enable 

application security and Java 2 security. 

Figure 13-2 Specify extent of protection 


. Select user repository (see Figure 13-3). Select Local operating system. 

Figure 13-3 Select user repository 

c. Configure the user repository (see Figure 13-4). Enter the primary (RACF 

defined) administrative user ID. 

Figure 13-4 Specify primary administrative user for z/OS security default authorization 

d. Verify your settings in the summary. 


e. Click Finish. 

4. Select the authorization provider. 

a. Click Security → Secure administration, applications, and 

infrastructure → External authorization providers. 

b. Verify that Default authorization is selected. 

5. Save your changes. 

You can review which files are updated before saving changes. 

Administrative security will be active after restarting the server. When logging on 

to the admin console you will need to provide the primary administrative user ID 

and its password. 

If you choose the SAF authorization provider, follow these steps. Follow the 

same steps as for the default provider. In addition, RACF setup is required. 

Follow steps 1–3 of the default authorization provider. 




The primary administrative user specified in step 3 (c) is invalid when 

choosing SAF authorization provider. The administrative user ID needs to be 

defined in RACF. 

4. Select the authorization provider: 

a. Click Security → Secure administration, applications, and 

infrastructure →> External authorization providers. 

b. Select the SAF authorization provider. 

Important: The security configuration wizard turns off SAF 

authorization. If you run the security configuration wizard after having 

enabled SAF authorization, you need to manually turn on SAF 

authorization again. 

5. Save the changes. 

6. Optional: Create an administrative user ID. 

If you plan to create a new administrative user ID for the SAF authorization 

provider, define it in RACF. 

7. Define the RACF administrative roles. 


EJBROLE class profiles are case sensitive. If you have a security domain 

enabled, prefix the administrative role names by the domain name. 

Otherwise, specify only the role name. 

RDEFINE EJBROLE administrator UACC(NONE) 

RDEFINE EJBROLE monitor UACC(NONE) 

RDEFINE EJBROLE configurator UACC(NONE) 

RDEFINE EJBROLE operator UACC(NONE) 

RDEFINE EJBROLE deployer UACC(NONE) 

RDEFINE EJBROLE adminsecuritymanager UACC(NONE) 

For a description of each administrative role see 13.2.1, “Administrative roles” 

on page 460. 

8. Permit access to the administrative role profiles. READ access is sufficient. 

Be careful granting ALTER access on a discrete resource profile. A user with 

ALTER access can alter the access list (ACL) of that profile. 

PERMIT role_name CLASS(EJBROLE) ID(user_id or group_id) 

ACCESS(READ) 

9. Refresh the RACLISTed class in order to activate the changes: 


To display an EJBROLE profile and its ACL execute the following command 

RLIST EJBROLE administrative_role ALL 

We recommend using JCL to execute RACF commands for ease of viewing the 

resulting output. A sample JCL to list all EJBROLE class profiles is shown in 

Example 13-1. 

Example 13-1 Sample JCL to display all profiles in the EJBROLE class 

//LSTRACF EXEC PGM=IKJEFT01 

//SYSLBC DD DSN=SYS1.BRODCAST,DISP=SHR 

//SYSTSPRT DD SYSOUT=* 

//SYSPRINT DD SYSOUT=* 

//SYSOUT DD SYSOUT=* 

//SYSIN DD DUMMY 

//SYSTSIN DD * 

RLIST EJBROLE * ALL 

/* 

Note that all security-related changes to the WebSphere configuration need a 

restart of your base server or network deployed cell in order to get activated. 


13.1.4 Administrative security with default authorization provider 

Here we show the necessary steps to enable administrative security. We did not 

enable administrative security during the installation process. 




a. Specify the extent of protection. Enable application security and Java 2 

security, if you need them. 

b. Select the user repository. Select federated repositories. 

c. Configure the user repository (see Figure 13-5). Specify an administrative 

user name. The administrative user ID and password are stored in the 

WebSphere Application Server file-based repository. 

Figure 13-5 Specify primary administrative user and password 


d. Click Finish. 

4. Select an authorization provider. Click Security → Secure administration, 

applications, and infrastructure → External authorization providers. 

Verify that Default authorization is selected. 


You can review which files are updated before saving changes. In this case 

the security.xml file is updated (Figure 13-6) and the fileRegistry.xml file is 

created (Figure 13-7 on page 457). 

 

 

: 

 

: 

 

Figure 13-6 Updated security.xml 


 

 

 

 

 

 

 

2006-11-28T15:33:24.449+00:00 

U0hBLTE6ZW9oYTM4dnYxc3l6OnEwK2FFN2RRMUtVTldiVlVNdFJtdE5HWlZt 

dz0K 

itsouser 

itsouser 

itsouser 

 

 

 

Figure 13-7 Created fileRegistry.xml 

Administrative security is active after restarting your server. You need to log in to 

the admin console using the primary administrative user ID and its password. 

Disable administrative security 

If anything went wrong during the configuration of administrative security you 

might not be able to log on to the administrative console, or other security-related 

problems might occur. There are two ways to disable administrative security. 

If you can still log on to the administrative console you can disable security 

through the administrative console. 


2. Uncheck the Enable administrative security check box. 

3. Save the changes and restart the server. 

If you cannot log on to the administrative console, you can disable the 

administrative security using the wsadmin command-line interface, as follows: 

1. Bring down the server. 

2. Log in to a UNIX System Services shell. 


3. Go to the profile_root/bin directory. 

4. Enter wsadmin by entering the command wsadmin.sh -conntype NONE (never 

connect to conntype NONE when the server is still running. If you have a 

network deployed cell configured, execute the wsadmin.sh from the 

deploymentmanagers’ node bin subdirectory.). 

5. Enter securityoff and then exit wsadmin. 

6. Start the server. 

Example 13-2 shows an example of wsadmin execution output. The 

/WebSphereBS2/V6R1/AppServer/profiles/default directory is 

server_profile_root in this example. 

Example 13-2 Command execution output of disabling security 

/WebSphereBS2/V6R1/AppServer/profiles/default/bin # ./wsadmin.sh 

-conntype NONE 

WASX7357I: By request, this scripting client is not connected to any 

server process. Certain configuration and application operati 

ons will be available in local mode. 

WASX7029I: For help, enter: "$Help help" 

wsadmin>securityoff 

LOCAL OS security is off now but you need to restart server1 to make it 

affected. 

wsadmin>exit 

/WebSphereBS2/V6R1/AppServer/profiles/default/bin # 

Security trace 

When you have administrative security enabled but administrative operations fail 

to execute, you must search for the cause of the problem. Setting a security trace 

helps you identify the security configuration problem. If administering the server 

was without problems before enabling security, it is safe to assume that a 

problem exists in the security configuration. 

Three ways to set a security trace are: 

► Change the trace option through the administrative console: 

– Click Troubleshooting → Log and Trace → server_name → Change 

Log Detail Levels. 

– Change the trace level in the Configuration tab. 

► Change the trace level in the Runtime tab. 


Figure 13-8 shows a trace options and trace level example. 

Figure 13-8 Trace options and levels 

► Change trace options/level using the MVS modify command: 

F CR_short_name,TRACEDETAIL=E 

This command is one of the available security trace options on the MVS 

modify command. For more information about the available modify command 

options refer to the InfoCenter at: 


=/com.ibm.websphere.zseries.doc/info/zseries/ae/rxml_mvsmodify.html 

Note: The Runtime trace tab and the MVS modify command change trace 

options dynamically. The Configuration trace tab sets trace options 

permanently and requires a restart of the server. 


13.2 Role-based administrative security 

WebSphere Application Server implements an extension to the Java 2 Platform, 

Enterprise Edition (J2EE) security role-based access control to protect the 

product administrative and naming subsystems. 

In this section we introduce the following topics: 

► Administrative roles. 

► Fine-grained administrative role security. 

13.2.1 Administrative roles 

Three new roles to secure administrative tasks have been added in WebSphere 

V6.1: iscadmins, Deployer, and AdminSecurityManager. Table 13-1 shows a 

description of each role. These roles are only in effect when administrative 

security is enabled. 

Table 13-1 Administrative roles description 

Role Description 

Monitor Least amount of privileges. A monitor is granted the 

following tasks: 

► View the WebSphere Application Server configuration. 

► View the current state of the application server. 

Configurator Monitor privilege plus the ability to change the WebSphere 

Application Server configuration. The configurator can 

perform all the day-to-day configuration tasks. For 

example, a configurator can do the following tasks: 

► Create a resource. 

► Map an application server. 

► Install and uninstall an application. 

► Deploy an application. 

► Assign users and groups to role mapping for 

applications. 

Operator Monitor privileges plus the ability to change the runtime 

state. For example, an operator can complete the following 

tasks: 

► Stop and start the server. 

► Monitor the server status in the administrative console, 

and so on. 



Administrator Operator and configurator privileges plus additional 

privileges that are granted solely to the administrator role. 

For example, an administrator can complete the following 

tasks: 

► Modify the server user ID and password. 

► Configure authentication and authorization 

mechanisms. 

► Enable or disable administrative security, Java2 

security, application security. 

► Create, update, or delete users/groups in the federated 

repositories configuration. 

Note: An administrator cannot map users and groups to the 

administrator roles. 

iscadmins (New in V6.1) 

Only available for administrative console users 

The iscadmins role grants administrator privileges to 

manage users and groups in federated repositories. 

For example, a user of the iscadmins role can complete the 

following tasks: 

► Create, update, or delete users in the federated 


► Create, update, or delete groups in the federated 


Deployer (New in V6.1) 

Only available for wsadmin users 

Configuration actions and runtime operations on 

applications. 

adminsecuritymanager (New in V6.1) 

Only available for wsadmin users 

When using wsadmin, being able to map users to 

administrative roles. Also, when fine-grained admin 

security is used, users granted this role can manage 

authorization groups. See the AdminSecurityManager role 

section for more details. 

The primary administrative user ID, specified when enabling administrative 

security using the default authorization provider, is automatically mapped to the 

administrator role. You do not need to map this ID manually to the administrator 

role. 

If you install your application server with the z/OS security product option, all but 

one administrative role profile are defined in the SAF EJBROLE class. The 

iscadmins role is not defined because the purpose of this role is to secure the 


management of users and groups in federated repositories. Therefore, there is 

no relation between SAF and the iscadmins role. 

When using the default authorization provider, users and groups are mapped to 

the administrative roles through the admin console (WebSphere bindings). When 

SAF is your authorization provider you need to permit users and groups to the 

EJBROLE administrative profiles (SAF bindings) with access READ. 

Permit users and groups to the appropriate role and refresh the RACLISTed 

class: 

PERMIT role_name CLASS(EJBROLE) ID(user_id or group_id) 

ACCESS(READ) 


13.2.2 Fine-grained administrative security 

In previous WebSphere versions, administrative roles allowed users to 

administer all WebSphere artifacts or resource instances (cell, nodes, servers, 

clusters, applications) in the realm of the cell. WebSphere Application Server 

V6.1 fine-grained administrative security gives you the possibility to define 

scopes of authorization at, for instance cell, node, or server level. 

The authorization group outlines the scope of authorization. Users can then be 

granted an administrative role in an authorization group. In this way users are 

only allowed to administer a delimited scope of resources. 

The following resource instances can be added to an authorization group: 

► Cell 

► Node 

► Server cluster 

► Server 

► Application 

► NodeGroup 

Note: A resource instance can only belong to one authorization group. 

The administrative roles are granted per authorization group and therefore per 

resource instance rather than to the entire cell. However, there is a cell-wide 

authorization group for compatibility with previous versions. Users assigned to 

administrative roles in the cell-wide authorization group can still access all of the 

resources within the cell. 


Fine-grained administrative security can also be used in single-server 

environments. Various applications in the single server can be grouped and 

placed in different authorization groups. 

Note: The standalone server itself cannot be part of any authorization group. 

The AdminSecurityManager role is only available through wsadmin. Users 

granted this role can map users to administrative roles. Also, when fine-grained 

admin security is used, users granted this role can manage authorization groups. 

There is no on-off switch to activate fine-grained administrative security. Once 

you have set up an authorization group, it is active. In WebSphere Application 

Server for z/OS there are two ways to implement fine-grained administrative 

security control, just as there is in standard administrative security. One is 

through WebSphere Application security, which is used when selecting default 

authorization as the authorization provider, and the other is through RACF, which 

is used when SAF is the authorization provider. 

Fine-grained access is granted by performing the following steps: 

1. Connect to the application server with wsadmin. 

2. Create an authorization group. 

3. Add resource instances to the authorization group. 

4. Map users/groups to administrative roles at the authorization group level. 

Users and groups need to exist in the configured user registry. 


6. Restart the application server/cell to activate the changes. 

Steps 1 to 3, 5, and 6 are common for all authorization providers. 

Step 4 varies according to the chosen external authorization provider. We 

illustrate how to map users/groups to roles for both SAF authorization with the 

z/OS security product option and default authorization with WebSphere 

Application Server security by means of a scenario. 

This is the scenario setup, a user is granted deployer access to a specific 

resource only (an application). This user should not be able to administer any 

other resources outside of his authorization group. Users assigned to 

administrative roles in the cell-wide authorization group can still access all of the 

resources within the cell. 


These are the values used in the following steps: 

[Users/Groups and resource instance] 

administrator role user: ITSOUSER is assigned cell level administrator 

role: create authorization group, add resources to the authorization 

group, etc. 

authorization group: APPG 

resource instance: an application named HelloApplication is added to 

APPG. 

security role user: APPUSER1 is mapped to the deployer role in the APPG 

authorization group 

[server environment] 

cell name: cl6582 

node name: nd6582 

server name: ws6582 

server_profile_root: /WebSphereBS2/V6R1/AppServer/profiles/default/bin 

The wsadmin commands are in the jython scripting language. 

Note: WebSphere administrative (wsadmin) scripting support for the JACL 

language is deprecated as of V6.1. 

1. Connect to the application server with wsadmin: 

wsadmin.sh -lang jython -user ITSOUSER -password pswd 

2. Create an authorization group: 

AdminTask.createAuthorizationGroup('[-authorizationGroupName APPG]') 

3. Add resource instances to the authorization group: 

AdminTask.addResourceToAuthorizationGroup('[-authorizationGroupName 

APPG -resourceName Application=HelloApplication]') 

Example 13-3 shows the commands and output of step 1 to 3. 

Example 13-3 Execution output of creating new security group 

/WebSphereBS2/V6R1/AppServer/profiles/default/bin: >wsadmin.sh -lang 

jython -user ITSOUSER -password pswd 



WASX7031I: For help, enter: "print Help.help()" 

wsadmin>AdminTask.createAuthorizationGroup('[-authorizationGroupName 

APPG]') 

'cells/cl6582/authorizationgroups/APPG|authorizationgroup.xml#Authoriza 

tionGroup_1164863617316' 


wsadmin>AdminTask.addResourceToAuthorizationGroup('[-authorizationGroup 

Name APPG -resourceName Application=HelloApplication]') 

'' 

4. Map users/groups to roles at authorization group scope. 

If you are using the default authorization provider as the authorization 

provider you need to issue this command: 

AdminTask.mapUsersToAdminRole ('[-authorizationGroupName APPG 

-roleName deployer -userids APPUSER1]') 

Example 13-4 execution output of role mapping 

wsadmin>AdminTask.mapUsersToAdminRole ('[-authorizationGroupName APPG 

-roleName deployer -userids APPUSER1]') 

'true' 

If you are using the SAF authorization provider as the authorization provider 

you need to define additional profiles to the EJBROLE class, as follows: 

a. Define . profiles in EJBROLE (again, 

prefix those profiles with your domain identifier if you have one 

configured): 

RDEFINE EJBROLE APPG.administrator UACC(NONE) 

RDEFINE EJBROLE APPG.configurator UACC(NONE) 

RDEFINE EJBROLE APPG.operator UACC(NONE) 

RDEFINE EJBROLE APPG.monitor UACC(NONE) 

RDEFINE EJBROLE APPG.deployer UACC(NONE) 

RDEFINE EJBROLE APPG.adminsecuritymanager UACC(NONE) 

Note: EJBROLE profiles for all of the roles in each authorization group 

should be created regardless of whether any user is mapped to its role, 

or at least define an appropriate catching profile at authorization group 

level. 

b. Permit the user to access the EJBROLE class profile: 

PERMIT APPG.deployer CLASS(EJBROLE) ID(APPUSER1) 

ACCESS(READ) 

c. Refresh the RACLISTed class in order to activate the changes: 



5. Save the changes: 

AdminConfig.save() 

Example 13-5 Execution output of save command 

wsadmin>AdminConfig.save() 

'' 

6. Restart the application server to activate the changes. 

APPUSER1 is assigned the deployer role for HelloApplication, but does not have 

administrative authority for other applications. Example 13-6 and Example 13-7 

show that the setup works well. ITSOUSER can list and control all deployed 

applications. APPUSER1 can list and control only the authorized resource. 

Example 13-6 ITSOUSER execution output 

/WebSphereBS2/V6R1/AppServer/profiles/default/bin # wsadmin.sh -lang 

jython -user ITSOUSER -password pswd 

WASX7209I: Connected to process "ws6582" on node nd6582 using 

SOAP connector; The type of process is: UnManagedProcess 


wsadmin>print AdminApp.list() 

DefaultApplication 

HelloApplication 

ivtApp 

query 

wsadmin>appManager = AdminControl.queryNames('type=ApplicationManager,* 

') 

wsadmin>AdminControl.invoke(appManager,'stopApplication','HelloApplicat 

ion') 

'' 

wsadmin>AdminControl.invoke(appManager,'stopApplication','DefaultApplic 

ation') 

'' 

wsadmin> 

Example 13-7 APPUSER1 execution output 

/WebSphereBS2/V6R1/AppServer/profiles/default/bin # wsadmin.sh -lang 

jython -user APPUSER1 -password pswd 




wsadmin>print AdminApp.list() 

HelloApplication 


wsadmin>appManager = AdminControl.queryNames('type=ApplicationManager,* 

') 

wsadmin>AdminControl.invoke(appManager,'stopApplication','HelloApplicat 

ion') 

'' 

wsadmin>AdminControl.invoke(appManager,'stopApplication','DefaultApplic 

ation') 

WASX7015E: Exception running command: 

"AdminControl.invoke(appManager,'startApplication','DefaultApplication' 

)"; exception information: 

javax.management.JMRuntimeException: ADMN0022E: Access is denied for 

the startApplication operation on ApplicationManager MBean because of 

insufficient or empty credentials. 

wsadmin> 

For more information about the AdminTask object related to fine-grained security 

refer to the InfoCenter. More information about implementing fine-grained 

security can be found in TechDoc TD103324: 

http://www-03.ibm.com/support/techdocs/atsmastr.nsf/WebIndex/TD103324 

13.3 Naming service security 

The naming service is used by clients of WebSphere Application Server 

applications to obtain references to objects related to these applications. These 

objects are bound into a mostly hierarchical structure, referred to as a name 

space. The name space structure consists of a set of name bindings, each 

consisting of a name relative to a specific context and the object bound with that 

name. 

The concept of role-based authorization has been extended to protect the 

WebSphere Common Object Request Broker Architecture (CORBA) naming 

service (CosNaming). 

13.3.1 CosNaming roles description 

CosNaming security offers increased granularity of security control. CosNaming 

functions are available on CosNaming servers. These functions affect the 

content of the WebSphere Application Server name space. 


You can access and manipulate the name space through a name server. Users 

of a name server are referred to as naming clients. Naming clients typically use 

two interfaces: 

► Java Naming and Directory Interface (JNDI) Interface 

► Common object request broker architecture (CORBA) Naming Interface 

You can control access to the name space using CosNaming roles. All 

CosNaming roles are shown in Table 13-2. 

Table 13-2 CosNaming security roles description 


CosNamingRead Query the WebSphere Application Server name space 

using, for example, the JNDI lookup method. 

The EVERYONE special-subject is the default policy for 

this role. 

CosNamingWrite Perform write operations such as JNDI bind, rebind, or 

unbind, and CosNamingRead operations. 

The ALL_AUTHENTICATED special-subject is the default 

policy for this role. 

CosNamingCreate Create new objects in the name space through such 

operations as JNDI createSubcontext and 

CosNamingWrite operations. 



CosNamingDelete Destroy objects in the name space, for example, using the 

JNDI destroySubcontext method and CosNamingCreate 

operations. 



The CosNaming authorization policy is valid only when administrative security is 

enabled. When administrative security is enabled, attempts to do CosNaming 

operations without the proper role assignment result in an 

org.omg.CORBA.NO_PERMISSION exception from the CosNaming server. 

13.3.2 Mapping users or groups to CosNaming roles 

There are two ways to map users or groups to CosNaming roles: through the 

administrative console or through SAF EJBROLE profiles, depending on the 

authorization provider setting. 


In the administrative console, CosNaming roles mapping can be defined at the 

following panel: Environment → Naming → CORBA Naming Service Users 

or CORBA Naming Service Groups. 

Figure 13-9 shows a default role definition granting read access to EVERYONE. 

Figure 13-9 Default setting of the CosNamingRead role 

Users, groups, or the special-subjects ALL_AUTHENTICATED and EVERYONE 

can be added or removed at any time. However, a server restart is required for 

the changes to take effect. 

The role mappings that are added through the administrative console are ignored 

if SAF authorization is enabled. If you use SAF as the authorization provider, 

access to the naming role is controlled by RACF. 

These are the commands to define the naming profiles in the EJBROLE class. 

Prefix the profiles with your security domain identifier if you have one configured. 

RDEFINE EJBROLE CosNamingRead UACC(READ) 

PERMIT CosNamingRead CLASS(EJBROLE) ID(WSGUEST) ACCESS(READ) 

RDEFINE EJBROLE CosNamingWrite UACC(NONE) 

RDEFINE EJBROLE CosNamingCreate UACC(NONE) 

RDEFINE EJBROLE CosNamingDelete UACC(NONE) 

PERMIT CosNamingWrite CLASS(EJBROLE) ID(WSCFG1) ACCESS(READ) 


PERMIT CosNamingCreate CLASS(EJBROLE) ID(WSCFG1) ACCESS(READ) 

PERMIT CosNamingDelete CLASS(EJBROLE) ID(WSCFG1) ACCESS(READ) 


WSGUEST is the unauthenticated user ID and WSCFG1 is the WebSphere 

Application Server Configuration Group name, as defined in the server 

configuration process. CosNamingRead is defined with UACC(READ), which is 

the closest thing in RACF to the EVERYONE special-subject. Note that we 

permit the unauthenticated user ID specifically to the CosNamingRead role 

because it has been defined with the RESTRICTED attribute. The server 

special-subject WSCFG1 should be permitted to all of the four CosNaming roles, 

because it provides processes that run under the server identity access to all the 

CosNaming operations. 

We recommend mapping groups or one of the special-subjects to naming roles. 

That is more flexible than mapping specific users and is easier to administer. 

When SAF authorization is the chosen authorization provider, you benefit from 

the fact that servers do not need to be restarted in order to activate changes in 

bindings to the naming roles. 


Appendix A. Additional material 

This book refers to additional material that can be downloaded from the Internet 

as described below. 

Locating the Web material 

The Web material associated with this System Authorization Facility is available 

in softcopy on the Internet from the IBM Redbooks Web server. Point your Web 

browser to: 

ftp://www.redbooks.ibm.com/redbooks/SG247384 

Alternatively, you can go to the IBM Redbooks Web site at: 


A 

Select the Additional materials and open the directory that corresponds with 

the book form number, SG247384. 


Using the Web material 

The additional Web material that accompanies this book includes the following 

files: 

File name Description 

SG7348.zip Zipped code samples 

How to use the Web material 

Create a subdirectory (folder) on your workstation, and unzip the contents of the 

Web material zip file into this folder. This creates a directory tree with various 

.ear files. Locate the .ear file you wish to use and import it into your favorite J2EE 

application development workbench. 

Attention: We have developed and used the samples with IBM Rational 

Application Developer. We strongly recommend using this tool for using the 

samples. The samples are developed at the J2EE 1.4 level. 


Related publications 

IBM Redbooks 

The publications listed in this section are considered particularly suitable for a 

more detailed discussion of the topics covered in this book. 

For information about ordering these publications, see “How to get IBM 

Redbooks” on page 475. Note that some of the documents referenced here may 

be available in softcopy only. 

► Understanding LDAP - Design and Implementation, SG24-4986 

► WebSphere for z/OS V6 Connectivity Handbook, SG24-7064 

► WebSphere Application Server for z/OS V5 and J2EE 1.3 Security Handbook, 

SG24-6086 

► Implementation and Practical Use of LDAP on the IBM eServer iSeries 

Server, SG24-6193 

► Using LDAP for Directory Integration, SG24-6163 

► Secure Production Deployment of B2B Solutions using WebSphere Business 

Integration Connect, SG24-6457 

► WebSphere Version 6 Web Services Handbook Development and 

Deployment, SG24-6461 

► Distributed Security and High Availability with Tivoli Access Manager and 

WebSphere Application Server for z/OS, SG24-6760 

► IBM WebSphere Application Server V6.1 Security Handbook, SG24-6316 


► Security with IBM Tivoli Access Manager V6 and IBM WebSphere Application 

Server V6 on IBM z/OS, REDP-4205 

► Enabling security after initial customization in Version 6.1, Technote 1237841 

► Configuration of WebSphere Application Server Security, TIPS0206 


Other publications 

Online resources 

These publications are also relevant as further information sources: 

► WebSphere MQ Clients, GC34-6590-01 

► z/OS V1R6.0 ICSF Administrator's Guide, SA22-7521-07 

► Security Server RACF Command Language Reference, SA22-7687-09 

► WebSphere MQ Security, SC34-6588 

These Web sites are also relevant as further information sources: 

► The specification for XML Signatures 

http://www.w3.org/Signature/ 

► XML Encryption WG 


► WebSphere Application Server Version 6 and later support Organization for 

the Advancement of Structured Information (OASIS) Web services Security 

(WS-Security) specifications 


=/com.ibm.websphere.zseries.doc/info/zseries/ae/cwbs_supportfunction. 

html 

► What is new for securing Web services 


=/com.ibm.websphere.zseries.doc/info/zseries/ae/cwbs_welcwebsvcsec. 

html 

► IBM HTTP Server - setting up a secure server 

http://www-306.ibm.com/software/webservers/httpservers/doc/v51/icswg 

003.html 

► WebSphere Application Server documentation 


=/com.ibm.websphere.zseries.doc/info/welcome_nd.html 

► IBM Education Assistant - CSIv2 


topic=/com.ibm.iea.doc/welcome.htm&tab=search&searchWord=csiv2&maxHi 

ts=50 


► IBM WebSphere Developer Technical Journal: Securing connections 

between WebSphere Application Server and WebSphere MQ 


ratnasinghe/0601_ratnasinghe.html 

► IBM SDKs - security information 

http://www-128.ibm.com/developerworks/java/jdk/security/index.html 

► IBM Tivoli Directory Server, Version 6.0 - Quick installation path for a server 

http://publib.boulder.ibm.com/infocenter/tivihelp/v2r1/index.jsp?topic 

=/com.ibm.IBMDS.doc/install04.htm 

► Windows Server 2003 Service Pack 1 32-bit Support Tools 

http://www.microsoft.com/downloads/details.aspx?familyid=6EC50B78-8B 

E1-4E81-B3BE-4E7AC4F0912D 

► Windows Server 2003 Resource Kit Tools 

http://www.microsoft.com/downloads/details.aspx?FamilyID=9d467a69-57 

ff-4ae7-96ee-b18c4790cffd 

► SPNEGO TAI configuration requirements 


=/com.ibm.websphere.zseries.doc/info/zseries/ae/rsec_SPNEGO_tai_reqs. 

html 

► SPNEGO TAI custom configuration attributes 


=/com.ibm.websphere.zseries.doc/info/zseries/ae/rsec_SPNEGO_tai_ 

attribs.html 

► SPNEGO trust association interceptor (TAI) troubleshooting tips 


=/com.ibm.websphere.zseries.doc/info/zseries/ae/rsec_SPNEGO_trouble_ 

shoot.html 

How to get IBM Redbooks 

You can search for, view, or download Redbooks, Redpapers, Hints and Tips, 

draft publications and Additional materials, as well as order hardcopy Redbooks 

or CD-ROMs, at this Web site: 


Related publications 475

Help from IBM 

IBM Support and downloads 

ibm.com/support 

IBM Global Services 

ibm.com/services 


Index 

Numerics 

128-bit encryption algorithm 268 

40-bit encryption algorithm 268 

A 

administration security 

options 432 

do not enable security 437 

use a z/OS security product 433 

use a z/OS security product, user IDs created 

433 

use WAS security 435 

Administrative Console 

Accessing ITDS configuration 378 

administrative security 449 

Certificate 

manage certificate expiration 218 

change internal server user id 442 

Configuring the JVM for the SPNEGO TAI 416 

Develop your own TAI 396 

LDAP 

TDBM 

Federate Repositories 368 

z/OS LDAP SDBM 344 

z/OS LDAP TDBM 355 

RunAs thread identity 388 

SAF authorization 383, 385 

Security Attribute Propagation 

Vertical propagation 331 

security configuration reporting tool 448 

Security role-based 

AdminSecurityManager 461 

Deployer 461 

iscadmins 461 

security wizard 448 

SPNEGO configuration 414 

z/OS thread identity synchronization 387 

administrative roles 

added in WAS V6.1 460 

Administrator 461 

AdminSecurityManager 460 

Configurator 460 

Deployer 460 

iscadmins 460 

Monitor 460 

Operator 460 

administrative security 72 

default authorization provider 455 

disabling 

using admin console 457 

disabling, using wsadmin 457 

options 449 

security trace 458 

administrative security, fine-grained 462 

options to implement 463 

adminstrative security 

what does it protect? 72 

Application Security 

enabling, in admin console 73 

application security 72 

asymmetric cipher algorithm 30 

Auditing 4 

authDataAlias 48 

Authentication 3 

authentication keys 32 

Authorization 3 

Default authorization 384 

External authorization using JACC provider 385 

SAF authorization 384 

authorization group 462 

authorization providers 450 

default authorization 450 

Java Contract for Containers (JACC) 

external authorization 450 

System Authorization Facility (SAF) 450 

authorization, SAF-based 25 

B 

base64 254 

Basic Authentication 72, 98, 246 

Identity assertion 193 

basic authentication 51 

Binary Der Data 254 

C 

CA - Top Secret 228 


callbackhandler 114 

caller part 114 

CBIND class 309 

Certificate 

Comparing the personal certificate 286 

Certificate Authority (CA) 117 

certificates 

comparing between z/OS and Windows 286 

extracting the z/OS signer certificate 254 

extracting the z/OS signer certificate, RACF 

command 254 

importing the server signer certificate into the client 

254 

CICS 336–337 

authorization and authentication support, in 

WAS 23 

CICS Transaction Gateway (CTG) 

CICSECIConnector 389 

JCA custom principal mapping 48 

cipher suite group, medium 268 

cipher suite group, strong 268 

Client Certificate Authentication 72, 98, 282 

Common Client Interface (CCI) 23 

Common Object Request Broker Architecture 

(CORBA) 467 

Common Secure Inter operability Version 2 (CSIv2) 

17 

Common Secure Interoperability Specification v2 

(CSIv2) 18 

Common Secure Interoperability Version 2 (CSIv2) 

98 

features in WAS for z/OS 306 

Common Secure Interoperability version 2 (CSIv2) 

5, 44, 305 

authentication mechanisms 307 

Basic Authentication 307 

client certificate authentication 307 

identity assertion 305–307 

configuration 

inbound authentication 317 


client certificate authentication 

318 

client identity types 320 

inbound transport 315 

outbound authentication 312 

Basic authentication 313 

client certificate authentication 

313 

outbound transport 310 

example 321 

identity formats supported in WAS for z/OS 

308 

certificate 308 

Distinguished Name 308 

SAF identity 308 

trust relationship 308 

ways of establishing trust 308 

J2EE server authentication using CSIv2 

logical flow 45 

layers 306 

message layer authentication 306 

security attribute propagation 306 

transport layer authentication 306 

Confidentiality 3, 268 

CosNaming 467 

CosNaming security 467 

create 237 

cryptography 164 

CSIv2 5 

CSIv2 - Common Secure Interpretability 

What is CSIv2? 41 

custom login module 16 

D 

data encryption method algorithm 176 

Data Encryption Standard (DES) 164 

Data Replication Service (DRS) 299 

DB2 336–337, 340, 386, 388 

Universal JDBC Driver Provider 

type 2 390 

type 4 390 

z/OS local JDBC provider 390 

DefaultPrincipalMapping 48 

deployment descriptor 10 

digest code 88 

Digital Signature 


Digital signature 

how is it created? 88 

E 

EIS - Enterprise Information Systems 336–337, 

386, 388–389 


EJB 

execution identity 33 

Runas identity 33 

security identity 33 

security role 33 

EJB container 

programmatic security APIs 11 

ejbActivate() method 23 

ejbCreate() method 23 

ejbLoad() method 23 

Enterprise Information Systems (EIS) 22 

errors 

creating native credentials 291 

External Authorization Server 

Authorization using external authorization server 

configuration tasks 57 

F 

Federated 25 

Federated Repositories 363 

ITDS 378 

SPNEGO 399 

what are federated repositories? 363 

fingerprint 88 

fixes 

PK31729 291 

Form based authentication 72 

G 

General Inter-ORB Protocol (GIOP) 44 

Generic Security Services Username Password 

(GSSUP) token 315 

global security 71, 430 

group 430 

H 

Hardware Cryptography 

IBMJCE 

characteristics 227 


characteristics 227 

hardware cryptography 192 

HFS owner user ID, adding 432 

HTTP Server 

Authenticating in HTTP server 


HTTP server 

authenticating in HTTP server 

logic al flow 36 

HTTP(s) 13 

Hypertext Transfer Protocol (HTTP) 90 

Hyptertext Transfer protocol over SSL (HTTPS) 91 

I 

IBM SDKs 475 

IBM Tivoli Access Manager 3, 48, 360, 395, 397 

principal mapping module 48 

IBM Tivoli Access Manager for e-business (TAMeb) 

17 

IBM Tivoli Directory Server v6 (ITDS) 340, 356, 

367, 375, 475 

Configuration 375 

How to install 375 

WebSphere z/OS configuration 378 

IBMJCECCA 192, 222, 275 

ibm-webservices-bnd.xmi 112 

ibm-webservices-bnd.xml 110 

ibm-webservicesclient-bnd.xmi 111 

ibm-webservicesclient-ext.xmi 111 

ibm-webservices-ext.xmi 111 

ibm-webservices-ext.xml 110 

ICSF managed keys 192 

Identity Assertion 

Configuration 

z/OS provider 199 


IMS 336–337, 386, 388 

authorization and authentication support, in 

WAS 24 

Connector 389 

JDBC Connector 389 

INADDR_ANY parameter 14 

Integrity 3 

Intermediaries 80 

Internet 29 

Interoperable Inter-ORB Protocol (IIOP) 44 

IP/UDP layer 29 

J 

J2C 

application contract 23 

connector components 23 

container contract 23 

contracts 23 

system contract 23 

Index 479

J2EE 9 

Security 5 

J2EE client 13 

J2EE client authentication using CSIv2 40 



J2EE Connector Architecture (JCA) 

custom mapping 47 

JCA custom principal mapping 46 

J2EE deployment descriptor files 112 

J2EE security 10 

declarative security 10 

programmatic security 10 

J2EE security,architecture 11 

J2EE server 

J2EE server authentication using CSIv2 43 

JAAS login module 59 

JACC - Java Contract for Containers 

External authorization 385 

Java 2 security 5, 9 

Java Authentication and Authorization Service 

(JAAS) 19 

Java Authorization Contract for Containers (JACC) 

25 

Java Contract for Containers (JACC) 

authorization using external authorization server 

56 

Java Cryptography Extension (JCE) 222 

Java Cryptography Extension (JCE), IBM version 

222 

Java Message Service (JMS) 91 

Java security 5 

java.security file 223, 275 

JAX-RPC 91–92 

JCA - J2EE Connector Architecture 

JCA custom principal mapping 


resource adapter 389 

JCE - Java Cryptography Extension 


227 

What is JCE? 222 

JCECCRACFKS 276 

K 

KDC - Key Distribution Center 392–393, 395, 398, 

402, 412 

z/OS 399 

Kerberos 392, 397 

Authentication protocol 393 

Encryption types 411 

Keytab file 410 

Realm 

WinKerbRealm 399–400 

zOSKerbRealm 399–400 

Service Principal Name (SPN) 405 

key encryption method algorithm 177 

key information 114 

key locator 114 

key store path, WebSphere default 175 

keystore 226 

L 

LDAP - Lightweight Directory Access Protocol 

337–338, 378 

336–337, 340 

Active Directory 395 

JOBLOG 361 

messages 361 


SLAPDCNF member 341, 351 

SPNEGO 399 

z/OS 

SDBM 340–341 

schema 342 


TDBM 337, 340, 350, 367 

configuration 351 

Federated Repositories 368 

Native Authentication configuration 360 


WebSphere z/OS configuration for Native 

Authentication 362 

Lightweight Directory Access Protocol (LDAP) 30 

Lightweight Third Party Authentication (LTPA) 16 

link layer, 29 

LSA - Local Security Authority 395, 402 

LTPA token 116, 302 

keys 302 

LtpaToken 297 

LtpaToken2 297 

M 

Message Authentication Code (MAC) 222 

Microsoft Internet Explorer 398 



Microsoft Windows Active Directory (AD) 392, 

395–396, 398 

Create a user account for WebSphere Application 

Server for z/OS 405 

Microsoft Windows Server 2003 475 

SP 1 475 

SP1 401 

Microsoft Windows XP Professional 2002 SP2 401 

Mozilla Firefox 398 


N 

naming service security 467 

Native Authentication 359, 373 

Why to use Native Authentication? 360 

nonce 115 

non-ICSF managed keys 192 

Non-repudiation 4 

NTLM credential 397 

O 

OASIS 21 

Object Management Group (OMG) 5 

Open System Interconnection (OSI) 29 

Operating System (OS) security 4 

org.omg.CORBA.NO_PERMISSION exception 

468 

Organization for the Advancement of Structured Information 

Standards (OASIS) 82 

OS thread identity 386 

P 

Presumed Trust 


R 

RACDCERT 218 

RACF 103 

Access Control Element (ACEE ) 7 

Attribute 

AUDITOR 343 

CLASS 8 

classes, relevant to WAS on z/OS 8 

APPL 8 

CBIND 8 

DIGTCERT 8 

DSNR 8 

EJBROLE 8 

FACILITY 8 

GEJBROLE 8 

KERBLINK 8 

LOGSTRM 8 

SERVAUTH 8 

SERVER 8 

STARTED 8 

SURROGAT 9 

Commands 

ADDUSER 432 

PERMIT 104, 434 

RACDCERT 284 

RDEFINE 104, 384–385, 434 

SETROPTS 104 

Cosnaming EJB Roles 9 

GROUP 7 

How to define an EJBROLE in RACF 384 

keystore 215 

MIXEDCASE option 443 

mixed-case password support, enabling 443 

profile 

segments 7 

profile, attributes 7 

RACO (ENVR Object) 7 

SPNEGO 399 

User Profiles 341 

Redbooks Web Site 475 

Contact us xvi 

Registries 

Introduction 336 

Local Operating System 336, 382 

Configurating WAS to use local z/OS for authorization 

433 

SPNEGO 399 

When 337 

Standalone Custom Registry 336, 338 

How to write a custom registry? 338 


Standalone LDAP Registry 336–337, 340 

SDBM 340–341 


schema 342 


TDBM 337, 340, 350 



Why should you use a LDAP registry? 337 

Remote Method Invocation over Internet Inter-ORB 

Index 481

Protocol (RMI-IIOP) 91 

Repositories 

Federated repositories 336, 338 

Resource Access Control Facility (RACF) 6 

functionality 6 

profile 6 

resource instances 462 

Reverse Proxy Security Server (RPSS) 

authenticating in reverse proxy security server 

37 


forwarding the user id mechanisms 38 


RMI-IIOP 13 

Using jax-rpc to support non-SOAP binding 92 

RPSS - Reverse Proxy Security Server 

TAI 395 

RunAS 33 

S 

SAF - System Authorization Facility 336 

Authorization 383 

Delegation 385 

EJBROLE 385 

Profile mapper 385 

Sample applications 

SecurityInfo 98 

sas.client.props file 310 

SDK 1.5 5 

Secure Hash Algorithm (SHA-1) 164 

Secure Sockets Layer (SSL) 30, 91 

aliases 211 

authentication keys 32 

Basic Authentication 

configuring 282 

centrally managed 210 

certificate request 31 

certificates 

deleting keystores and truststores 222 

deleting or adding to or from RACF keyring 

217 

RACF commands 218 

CERTB64 keyword 220 

CERTDER keyword 220 

connecting a personal certificate 230 

connecting to a ring 229 

creating a personal certificate 229 

creating a ring 229 

deleting a CA signer certificate 222 

deleting a keyring 221 

deleting a personal certificate 222 

exporting a personal certificate 220 

exporting a signer certificate to an HFS 

file 220 

generating a signer certificate 229 

PKCS12B64 keyword 220 

PKCS12DER keyword 220 

removing a CA signer certificate from a 

keyring 221 

removing a personal certificate from a 

keyring 221 

viewing a list of certificates on a keyring 

for a user ID 218 

viewing certificate authority information 

218 

viewing personal certificate information 

for a user ID 218 

viewing in Admin console 217 

WebSphere 

available export formats 221 

certificate expiration monitoring 218 

deleting 221 

expired certificates 218 

expired certificates, email notification 

218 

importing 220 

cipher suite 31 


configuration the z/OS Web Service provider 

255 

configuring the Web Service requestor 261 

configuring the Web Service requestor endpoint 

URL 264 

creating a new SSL Configuration in WAS 256 

creating a new SSL inbound channel in WAS 

257 

enforcing confidentiality 271 

enforcing integrity 267 

errors 

CWPKI0022E 242 

ICSF address space unavailable 242 

signer certificate is from a client’s truststore 

242 

SSLC0008E 242 

starting Websphere using IBMJCECCA provider 

243 

handshake 30 


handshake errors 239 

handshake flow 95 

handshake, common errors 242 

hardware cryptographic support 272 

configuring the Web Service provider for 

confidentiality 281 

configuring the Web Service requestor for 


configuring the Web Service requestor SSL 


connecting a CA to a keyring 272 

connecting a personal certificate to a keyring 

273 

creating a new CA 272 

creating a new keyring 272 

creating a new personal certificate 273 

exporting the signer certificate 274 

HDWebServiceSSLConfig 280 

importing the signer certificate 274 

installing the unrestricted Java policy jars 

275 

JCECCRACFKS 276 

JCECCRACFKS, creating a new keystore 

276 

SSLException 281 

updating the JVM to use IBMJCECCA 275 

validating confidentiality 281 

viewing CA information 273 

viewing the personal certificate information 

274 

hardware cryptography 

Common Cryptographic Architecture (CCA) 

interfaces 222 

creatING a new keystore 237 

diagnosing SSL handshake issues 240 

IBMJCE4758 223 

IBMJCECCA 222 

IBMJCECCA, prereqs 223 

JCECCARACFKS keystore 233 

keys in hardware 234 

safkeyring URI 237 

unrestricted policy jars 236 

unrestricted policy jars, installing in Web- 

Sphere 236 

update the java.security file with the IB- 

MJCECCA provider 236 

IBMJCE provider 

keystore types 

JCECCAKS 226 

JCECCARACFKS 226 

JCEKS 225 

JCERACFKS 225 

JKS 225 

PKCS11 225 

PKCS12 225 

Java Secure Socket Extension (JSSE) 213 

JCE provider 223 

keystore 226 

storage 227 

keystore types 227–228 

JCECCAKS 229 

JCECCARACFKS 228 

JCEKS 228 

JCERACFKS 228 

JKS 228 

PKCS11KS 229 

PKCS12KS 228 

master secret 32 

NodeDefaultSSLSettings 211 

pre-master secret 32 

protocol version 31 

repertoire alias 210 

setting the cipher suite group, for Web Service 

provider 264 

symmetric encryption keys 32 

System SSL (SSSL) 213 

trace, enabling dynamically 242 

trace, JSSE 242 

traces 241 

traces, enabling 241 

transport chain 259 

truststore 227 

WebSphere 

keystores, available 224 

WebSphere V6.0 endpoint details 213 

WebSphere V6.1 210 

WebSphere V6.1 endpoint details 214 

X.509 v.3 certificates 31 

security attribute propagation 294 

attribute propagation 294 

benefits 295 

horizontal propagation 295, 298, 305 


cross-cell considerations 302 

Data Replication Service (DRS) 299 

DynaCache 299 

example 300 

JMX 299 

Index 483

JMX calls 305 

LTPA key, sharing 303 

LTPA keys, sharing 304 

LTPA keys, sharing, automatically generated 

304 

mechanisms, in WebSphere 299 

performance implications 299 

Single Sign On, cross-cell 303 

SSO token 298 

identity propagation 294 

initial login 295 

JAAS Subject 294 

Java serialization 297 

Lightweight Third Party Authentication (LTPA) 

296 

Principal 294 

propagation login 295 

Reverse Proxy Security Server (RPSS) 295 

Run-As 295 

Single Sign On (SSO) 294 

styles 295 

token framework 297 

vertical propagation 295 

Webseal 295 

WebSphere token framework 

authentication token 297 

authorization token 297 

LtpaToken 297 

LtpaToken2 297 

propagation token 297 

Single Sign On 297 

Subject-based tokens 297 

thread-based token 297 

security attribute propoagation 

vertical propagation 328 

cross-cell considerations 334 

implementation 331 

Remote Method Invocation (RMI) over the 

Internet Inter-ORB Protocol (RMI over IIOP) 

328 

Security Attribute Service (SAS) 305 

Security Constraint 267 

security.xml file 218 

server ID 441 

Service Oriented Architecture (SOA) 51 

servlet 

execution identity 33 

Runas identity 33 

security identity 33 

security role 33 

Simple Object Access Protocol (SOAP) 90 


identity assertion 90 

integrity 87 

Web Services authentication 51 

WS-Security standard 82 

Simple WebSphere Authentication Mechanism 

(SWAM) 16 

Single Sign On (SSO) 16 

authenticating in HTTP server 35 

SOA - Service Oriented Architecture 

Introduction to soa and z/OS security 76 

SOAP - Simple Object Access Protocol 

RMI-IIOP with multiprotocol jax-rpc 92 

SPNEGO 391 

Configuring Microsoft Internet Explorer 419 

Configuring Mozilla Firefox 421 

Configuring the JVM 416 

Configuring the Microsoft Windows server 404 

Configuring WebSphere Application Server for 

z/OS 414 

handshake 397 

RACF 399 

Troubleshooting 422 

What is SPNEGO? 396 

SSO - Single Sign On 16 

SPNEGO 392 

WebSphere Application Server for z/OS using 

SPNEGO 397 

z/OS KDC and Microsoft Windows KDC 399 

symmetric algorithm 30 

symmetric encryption keys 32 

Sync-to-OS Thread 386, 444 

activation 387 

defining RACF profile 446 

What’s new in Version 6.1? 444 

System Access Facility(SAF) 6 

System Authorization Facility (SAF) 5 

System Network Architecture (SNA) 29 

system.wssecurity.IDAssertionUsernameToken 

128 

system.wssecurity.PKCS7 128 

system.wssecurity.PkiPath 128 

system.wssecurity.UsernameToken 128 

system.wssecurity.X509BST 128 


T 

TCP layer 29 

Ticket 

Kerberos 392–393 

Ticket Granting Server (TGS) 393 

Ticket Granting Ticket (TGT) 393 

token generator 114 

Top Secret 5 

Trust association 17 

Trust Association Interceptor (TAI) 16, 38, 395 

Trust Relationship 

TAI 395 

trust store path, WebSphere default 180 

truststore 227 

U 

unrestricted policy jars 275 

user 430 

user account repository 440 

User registry 

federated repository 24 

Local Operating System (LocalOS) 24 

standalone custom registry 24–25 

standalone LDAP 24 

V 

Virtual Member Manager (VMM) 365 

W 

WAS - WebSphere Application Server 

Accessing ITDS 378 

Build Number 

cf20633.22 401 

Configuration 

administration security option 

Do not enable security 437 

Use a z/OS security product 433 

Use WebSphere Application Server security 

435 

Create a user account in the AD 405 

JMS Provider 390 

OS thread identity 386 

SPNEGO 391, 396 

Kerberos requirements 412 

trace 422 

z/OS KDC 399 

Web authentication 

for any URI 66 

for protected URIs only 65 

system properties 

com.ibm.wsspi.security.web.webauthreq 

67 

Web authentication behavior 

admin console, settings 65 

Web container 

programmatic security APIs 11 

Web Services 


logic flow 52 

authentication 51 

Confidentiality 

configure z/OS provider 183 

configure z/OS requestor 185 

Identity Assertion 

configure the z/OS provider 199 

Message layer security 21 

message layer security 78 

authentication 

configuring a token for Web Service provider 

123 

configuring a token for Web Service requestor 

119 

custom token 117 

LTPA token 116 

token generator, configuring 120 

token type 119 

custom 119 

Username 119 

X509 certificate token 119 

Username token 116 

X.509 certificate token 116 

XML digital signature 117 

components 

callbackhandler 114 

caller part 114 

key information 114 

key locator 114 

nonce 115 

timestamp 115 

token generator 114 

trust anchor 115 

confidentiality 

164 

asymmetric encryption algorithms 164 

configuring encryption, server 171 

Index 485

configuring provider 178 

configuring requestor 172 

configuring, encryption algorithm 171 

encryption, algorithms 164 

extracting WebSphere for z/OS signer 

certificate 167 

one-way encryption algorithm 164 

support in WS-Security 165 

symmetric encryption algorithms 164 

configuration components 114 

configuration files 111 

deployment descriptors 110 

deployment descriptors, editing tools 110 

deployment descriptors, format in Web- 

Sphere versions 110 

identity assertion 192 

configuring 195 

configuring Web Service requestor 196 

trust modes 193 

trust relationship 203 

WS-Security support 193 

integrity 131 

canonicalization method algorithm 143 

configuring the Web Service provider 

146 

configuring the Web Service requestor 

135 

configuring the z/OS provider for XML 

digital signature 154 

configuring the z/OS requestor for XML 

digital signature 159 

digest method algorithm 144 

signature method algorithm 143 

transform 145 


integritysignature algorithm 133 

security token 116 

SOAP security header 109 

when to use? 80 

WS Binding 113 

WS Extension 113 

security exposures 77 

Transport layer security 21 

transport layer security 78 

Basic Authentication, configuring 247 

Basic Authentication, validating 250 

configuring the requestor to authenticate 

249 

Enterprise Service Bus (ESB) 93 

HTTP(S) 

authentication 94 


Basic Authentication information 94 

benefits 93 


integrity and confidentiality 94 

Universal Resource Identifier (URI) 91 

JMS 

SSL 97 

point-to-point security 93 

Remote Method Invocation over Internet Inter-ORB 

Protocol (RMI-IIOP) 92 

RMI over IIOP 98 

CSIv2 98 

SOAP over HTTP 91 

SOAP over JMS 92 

when to use? 80 

Web Services Interpretability Organization (WS-I) 

84 

Web Services Security (WS-Security) 108 

WebSeal 17 

Webseal 395 

WebSphere Application Server 

What is new in v6.1 security? 2 

WebSphere Application Server (WAS) 

connections 13 

encryption algorithms 268 

security settings 440 

WebSphere Application Server configuration group, 

create 431 

WebSphere Application Server HFS Owner 431 

WebSphere Message Queueing 

WMQ client authentication 53 

WebSphere MQ 19 

communication protocols 97 

WebSphere MQ Extended Security Edition 97 

WebSphere token framework 297 

WebSphereCA 254 

WMQ - WebSphere Message Queueing 

JMS Provider 390 

World Wide Web (WWW) 29 

WS Binding 113 

WS Extension 113 

WS-Authorization 22 

WS-Federation 22 

WS-Policy 22 

WS-Privacy 22 

WS-SecureConversation 22 


WS-Security 

authentication mechanisms 86 

high level architecture 85 

identity assertion 


digital signature 

90 

modes 90 

presumed trust 90 

Kerberos Token Profile 84 

Minimalist Profile (MProf) 84 

Rights Expression Language (REL) Token Profile 

83 

SAML Token Profile 83 

SOAP Message Security 1.0 83 

SOAP Message with Attachments (SwA) Profile 

84 

specifications 82 

support in WAS V6.x 84 

Web Services Security Username Token Profile 

1.0 83 

Web Services Security X.509 Certificate Token 

Profile 1.0 83 

WS-Authorization 83 

WS-Federation 83 

WS-I Basic Profile 84 

support in WAS v6.0 and later 84 

WS-I Basic Security Profile (BSP) v1.0 84 

WS-Policy 82 

WS-Privacy 83 

WS-Secure Conversation 83 

WS-Trust 83 


XML encryption standard 165 

Ws-Security 

XML encryption 89 

WS-Security authentication mechanism 


custom 86 

ID assertion 86 

LTPA 86 

signature 86 

WS-Trust 22 

X 

X.509 certificate token 116 

X.509 v.3 certificates 31 


Z 

z/OS KDC 399 

z/OS thread identity 389 

RunAs 388 

synchronization 386 

activation 387 

Index 487


Security in WebSphere Application Server Version 6.1 and J2EE 1.4 

Security in WebSphere Application Server Version 6.1 and 

Security in WebSphere Application 

Server Version 6.1 and J2EE 1.4 on z/OS 



and J2EE 1.4 on z/OS



Version 6.1 and J2EE 



Version 6.1 and J2EE



and J2EE 1.4 on z/OS 

WAS and J2EE 

security concepts 

and their 

implementation on 

z/OS 

Security integration 

scenarios, including 

SPNEGO and CSIv2 

Web services 

security and SSL in 

WAS V6.1 

SG24-7384-00 ISBN 0738488631 

Back cover 

This IBM® Redbooks® publication was written with the 

objective to provide a technical description of some of the 

most important security scenarios available with 

WebSphere® Application Server Version 6.1 for z/OS®. We 

chose scenarios that are not really documented elsewhere 

and that have had significant changes in Version 6.1. 

In the first two chapters we provide an overview of security 

with WAS on z/OS for those readers who are unfamiliar with 

the security landscape on z/OS. From Chapter 3 onwards we 

go into more technical depth. 

INTERNATIONAL 

TECHNICAL 

SUPPORT 

ORGANIZATION 

® 

BUILDING TECHNICAL 

INFORMATION BASED ON 

PRACTICAL EXPERIENCE 

IBM Redbooks are developed by 

the IBM International Technical 

Support Organization. Experts 

from IBM, Customers and 

Partners from around the world 

create timely technical 

information based on realistic 

scenarios. Specific 

recommendations are provided 

to help you implement IT 

solutions more effectively in 

your environment. 

For more information: 

ibm.com/redbooks

Download PDF - IBM Redbooks

Create successful ePaper yourself

Delete template?

Save as template?