WAS 6.1 Security

Front cover
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
Alex Louwe Kooijmans

Yukari Hanya
Keith Jabcuga
Marc van der Meer
Eran Yona
Gabriel Mogos
Foulques de Valence
ibm.com/redbooks
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) ® DB2® RACF®

developerWorks® IBM® RMF™
eServer™ IMS™ System z™
iSeries® Lotus® Tivoli®
z/OS® MQSeries® VTAM®
zSeries® MVS™ WebSphere®
CICS® Rational®
Domino® Redbooks®
The following terms are trademarks of other companies:
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
1
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
© 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

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
1.2.1 Security terms

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.
Naming, HTML,
WebSphere/Application
Admin Servlet/JSPs,
Resources
EJBs
Access Control
WebSphere Security WebSphere Security
J2EE Security API
CORBA Security / CSIv2

Java Security
Java 2 Security
JVM 5 Security
Platform Security Operating System Security
Figure 1-1 Security layers
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.
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 Security
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
OMVS TCP/IP TSO
Figure 1-2 RACF profile
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
retrieve 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.
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 Web Web EJB CICS

J2EE J2C
Client Server Container Container
Client
0 1
2
3
4
5
0 1
2
3
Figure 1-4 Security checkpoint internal flow
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

Authentication is performed using user information stored in a user account
repository and based on the protocol the user uses to access WAS.
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)
Message Level Security

SOAP SOAP
HTTP JMS HTTP JMS

Transport level security (TLS/SSL)
SSL SSL
TCP Socket
Socket
Port
IP IP address IP address
LINK Mac address Mac address
Requestor Service Provider
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
The Web services security model introduces a set of individual interrelated

specifications to form a layering approach to security. It includes several aspects
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
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.
1.3.7 User registry

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.
򐂰 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.
1.3.8 Authorization
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
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.
WS – Security ( Authentication)
SOAP SOAP
Authentication
HTTP MSG IIOP HTTP MSG IIOP
SSL (Integrity,Confidentiality)
SSL SSL
TCP Socket
Socket
Port
IP address IP address IP address IP address

IP
LINK Mac address Mac address Mac address Mac address
`
Router Router
Client/Requester Server/Service Provider
Figure 2-1 Protocol layering
Chapter 2. WebSphere security design 29

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.
2.3 SSL overview

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.
2.3.1 SSL handshake

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.
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
Client/Requester
11. Change cipher spec
12. Finished Server/Service Provider
Figure 2-2 SSL handshake
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.
z/OS
CICS
IMS
HTTP(s)
HTTP SSO WebSphere
Server Application Server
Web
Client
Authentication Authorization DB2

RACF
Figure 2-3 Scenario 1 - authenticating on HTTP 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
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.
HTTP WAS
Client Server (sso, TAI) RACF
1
2
5
6
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.
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.
z/OS
CICS
IMS
WebSphere
HTTP(s) HTTP(s) Web SSO
RPSS Application
Server
Server
Web client
DB2
Authorization
Authentication Native
LDAP RACF
Authentication
RPSS = Reverse Proxy Security 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.
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.
Web WAS
Client RPSS LDAP Server (sso, TAI) RACF
1
2
3
4
5
7
8
9
10
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.

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.
Configuration tasks
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).
z/OS
CSIv2
WebSphere
DB2
Application
RMI/IIOP Server
J2EE
Client CICS
IMS
Authentication Authorization
RACF
Figure 2-7 Scenario 3 - J2EE client authentication with CSIv2
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
authorization.

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 WAS
RACF
1
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.
Configuration tasks
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.
z/OS
CICS
Identity IMS
J2EE assertion WebSphere
Server CSIv2 Application Server
Client RMI/IIOP
Authorization
DB2
Authentication Native
LDAP RACF
Authentication
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
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.
J2EE z/OS
Client Server LDAP WAS RACF
1
2
3
4
5
6
7
8
9
10
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.

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.
Configuration tasks
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
back-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.
SAF user ID /
password
z/OS z/OS
WebSphere
TAM sso Application Server
WebSEAL JCA CTG CICS
Web Client Mapping
Module
Authentication Authorization
RACF
Authentication TAM
LDAP Policy
Server
Figure 2-11 Scenario 5 - JCA custom principal mapping authentication

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
authorization.
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.
J2C
WAS Principal TAM Policy
TAM (sso, TAI) Mapping server CTG CICS RACF
Client LDAP
WebSeal Module
1
2
3
4
5
8
9
10
11
12
13
14
15
16
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

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.
Configuration tasks
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.
z/OS
Web Service
HTTP(s) WebSphere
WAS ID assertion
Application
Distributed SOAP/HTTP Server
Web
Client
Authentication
Authentication
LDAP
Figure 2-13 Scenario 6 - Web services authentication
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.
WAS z/OS
Client Distributed LDAP WAS RA
1
2
3
4
5
6
7
8
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.
Configuration tasks
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.
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).
z/OS
Message WebSphere CICS

MQ
Application
Client IMS
Server
MDB EJB
Authorization
Authorization
MDB = Message Driven Bean Authentication
EJB = Enterprise JavaBean
RACF
Figure 2-15 Scenario 7 - MQ client authentication
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
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.
Application Server
WMQ 1
Client MDB EJB CICS RACF
1
2
3
4
5
7
8
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.

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.
z/OS
HTTP(s) WebSphere
HTTP(s) HTTP(s) Web
RPSS Application
Server SSO
Web Client Server
Authentication User Registry

Authorization with
JACC
LDAP
RPSS = Reverse Proxy Security Server

Authorization
Server
Figure 2-17 Scenario 8 - authorization using external authorization server
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.
Configuration tasks
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

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.
z/OS
JAAS WebSphere DB2

WAS CSIv2
Login Application
Distributed RMI/IIOP Module
Client Server
Authorization
CICS
Authentication Authentication IMS
Authorization
LDAP RACF
Figure 2-18 Scenario 9 - bridged security between z/OS and distributed
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.

򐂰 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.
z/OS
WebSphere
HTTP(s) Web HTTP(s)
Application
Server
Web Server
Client
Authorization
Authentication
z/OS SDBM
RACF
LDAP
Authentication
WAS distributed
Web
Client
Figure 2-19 Scenario 10 - centralized z/OS LDAP user registry
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
3
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.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 lazy equiv.

uthReq Authenticate only when the URI is
protected option
com.ibm.wsspi.security.web.webA persisting equiv.

uthReq Use available authentication data
when an unprotected URI is
accessed option
com.ibm.wsspi.security.web.webA always equiv.

uthReq Authenticate when any URI is
accessed option

Property name Value Description
com.ibm.wsspi.security.web.failO true equiv.

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

4
Chapter 4. Application security

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
5
Chapter 5. Web services security

introduction
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

receiver 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.
Authentication
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 <wsse:UsernameToken> with
<wsse:Username> and <wsse:Password>.
򐂰 Signature: The security token includes the X.509 certificate of the signer of
the data and is generated as <ds:Signature> with
<wsse:BinarySecurityToken>.
򐂰 ID assertion: ID assertion includes a user name only, since the identity is
asserted, and is generated as <wsse:UsernameToken> with
<wsse:Username> only.
򐂰 Custom: This mechanism includes a custom-defined token.
򐂰 LTPA: Use of an LTPA token is a WebSphere-specific customer token,
generating a <wsse:UsernameToken> with <wsse:Username>.
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
receive 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.
Authentication
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 z/OS 1.8

Service Pack 2)
WebSphere base server WebSphere 6.1.0.2 base server

6.1.0.2 cf20633.22
J2RE 1.5.0 IBM J9 2.3 Windows XP J2RE 1.5.0 IBM z/OS build
x86-32 j9vmwi3223-20060504 pmz31devifx-20060727a
5.6.3 SecurityInfo Web service implementation

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://<hostname>:<http_port>/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

requirements. This means that the request generator, the request consumer, the
response generator, and the response consumer might need some security
configuration.
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
authentication.
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 <wsse:Username> and <wsse:Password>
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
<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<soapenv:Header><wsse:Security soapenv:mustUnderstand="1"
xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wss
ecurity-secext-1.0.xsd">
<wsse:UsernameToken><wsse:Username>WINSERV</wsse:Username><wsse:Passwor
d
Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-
token-profile-1.0#PasswordText">WINSERV</wsse:Password>
</wsse:UsernameToken>
</wsse:Security>
</soapenv:Header>
<soapenv:Body><p98:obtainSecurityInfo
xmlns:p98="http://itso.ibm.com"><input>ITSO136</input></p98:obtainSecur
ityInfo></soapenv:Body></soapenv:Envelope>
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.
b. 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
<soapenv:Envelope
...><soapenv:Header><wsse:Security soapenv:mustUnderstand="1"

ecurity-secext-1.0.xsd"><wsse:BinarySecurityToken
EncodingType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-s
oap-message-security-1.0#Base64Binary"
ValueType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509
-token-profile-1.0#X509" wsu:Id="x509bst_17"
xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wsse
curity-utility-1.0.xsd">MIICEDCCAXmgAwIBAgIERU5DqzANBgkqhkiG9w0BAQUFADB
ucG9rLmlibS5jb20wHhcNMDYxMTA1.............8cUUF4aH9TANBgkqhkiG9w0BAQUFA
AOBgQB7c1icR21nrqiYprRncUn23GivfBLyNNZtKIB+1BohOvrmVzJLS4BRd/AdZxTDLb1J
4CESk2KpeuXsFK6D5WC8AFEzAmVEfBGHyvw==</wsse:BinarySecurityToken><ds:Sig
nature
xmlns:ds="http://www.w3.org/2000/09/xmldsig#"><ds:SignedInfo><ds:Canoni
calizationMethod
Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"><ec:InclusiveNamesp
aces PrefixList="xsi xsd soapenv soapenc wsse ds "
xmlns:ec="http://www.w3.org/2001/10/xml-exc-c14n#"/></ds:Canonicalizati
onMethod><ds:SignatureMethod
Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/><ds:Reference
URI="#wssecurity_signature_id_16"><ds:Transforms><ds:Transform
aces PrefixList="xsi xsd soapenv soapenc wsu p98 "
xmlns:ec="http://www.w3.org/2001/10/xml-exc-c14n#"/></ds:Transform></ds
:Transforms><ds:DigestMethod
Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/><ds:DigestValue>vQa
/lbLPXVv0rFc9PS6+8lHiBmY=</ds:DigestValue></ds:Reference></ds:SignedInf
o><ds:SignatureValue>BmEw84oUOpYzgnh7b2uqDy1JEZQO4qPDNj1J2UYiFcCalDlI+8
5O3E4NnG391TqPoZ/76K/DY2XMxI65dnDeCdYxOluU0pXhSL53+Afri+Y+sJsMQkgVx0Zx4
ALdXEgjE3WjWVTyiZMAYLOfvEAJw3NpO+xDLFLH0ugWvuOnBV4=</ds:SignatureValue>
<ds:KeyInfo><wsse:SecurityTokenReference><wsse:Reference
URI="#x509bst_17"
-token-profile-1.0#X509"/></wsse:SecurityTokenReference></ds:KeyInfo></
ds:Signature></wsse:Security></soapenv:Header>
<soapenv:Body wsu:Id="wssecurity_signature_id_16"
curity-utility-1.0.xsd"><p98:obtainSecurityInfo
xmlns:p98="http://itso.ibm.com"><input>ITSO3036</input></p98:obtainSecu
rityInfo></soapenv:Body></soapenv:Envelope>
HTTP/1.1 200 OK
...
Content-Length: 3276
Date: Fri, 10 Nov 2006 15:48:12 GMT
Server: WebSphere Application Server/6.1
<soapenv:Envelope
...><soapenv:Header><wsse:Security soapenv:mustUnderstand="1"
ecurity-secext-1.0.xsd"><wsse:BinarySecurityToken
EncodingType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-s
oap-message-security-1.0#Base64Binary"
-token-profile-1.0#X509" wsu:Id="x509bst_13"
curity-utility-1.0.xsd">MIICADCCAWmgAwIBAgIERT6FVDANBgkqhkiG9w0BAQUFADA
5MQswCQYDVQQGEwJVUzEMMAoGA1UE..............Hb62hxqB28S29uNKgiMatiySUfG5
8SFsyOTjnQk1UVtud8Y9JLjz7kI1LVTiM1EP6Y++XP+Pq2t8qSNWAN+nVnaE8A4X8EuGRDU
b/DjAjh8LCAWY6Cs</wsse:BinarySecurityToken><ds:Signature
xmlns:ds="http://www.w3.org/2000/09/xmldsig#"><ds:SignedInfo><ds:Canoni
calizationMethod
aces PrefixList="xsi xsd soapenv soapenc wsse ds "
xmlns:ec="http://www.w3.org/2001/10/xml-exc-c14n#"/></ds:Canonicalizati
onMethod><ds:SignatureMethod
Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/><ds:Reference
URI="#wssecurity_signature_id_12"><ds:Transforms><ds:Transform
aces PrefixList="xsi xsd soapenv soapenc wsu p98 "
xmlns:ec="http://www.w3.org/2001/10/xml-exc-c14n#"/></ds:Transform></ds
:Transforms><ds:DigestMethod
Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/><ds:DigestValue>A37
Up9iFTwgagkadxBg4uk5wprQ=</ds:DigestValue></ds:Reference></ds:SignedInf
o><ds:SignatureValue>pO+JYmFGdps3yutO6oUbqggknDagy+0pv1cb7C0SRhdw/jD5Vr
Ixe+9Jp/xqZcNrz+yhuE05cCNwk/QznjHxvQ0L8YB4C88A/uG9k7M4Lnv+Dd0RD+MfFaxbP
v3MQETlPBdV69frKEdz+SjJO5jxFhxb4OomHIFKoXQpMXKcVQQ=</ds:SignatureValue>
<ds:KeyInfo><wsse:SecurityTokenReference><wsse:Reference
URI="#x509bst_13"
-token-profile-1.0#X509"/></wsse:SecurityToken
Reference></ds:KeyInfo></ds:Signature></wsse:Security></soapenv:Header>
<soapenv:Body wsu:Id="wssecurity_signature_id_12"
curity-utility-1.0.xsd"><p98:obtainSecurityInfoResponse
xmlns:p98="http://itso.ibm.com"><obtainSecurityInfoReturn><string>ITSO3
036</string><string>Fri Nov 10 15:48:04 GMT+00:00
2006</string><string>WTSC58</string><string>9.12.4.8</string><string>UN
AUTHENTICATED</string><string>z/OS</string><string>01.08.00</string></o

btainSecurityInfoReturn></p98:obtainSecurityInfoResponse></soapenv:Body
></soapenv:Envelope>
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
reference is used.
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
algorithms are:
• 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
algorithms are:
• 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
configuration.

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.
b. 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.
reference is used.
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
configuration.
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.
reference is used.
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
dialog is similar.
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
dialog is similar.
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

reference is used.
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.
dialog is similar.
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

...
SOAPAction: ""
Content-Length: 1657
Date: Mon, 13 Nov 2006 13:55:34 GMT
<soapenv:Envelope ...><soapenv:Header><wsse:Security
soapenv:mustUnderstand="1"
ecurity-secext-1.0.xsd"><EncryptedKey
xmlns="http://www.w3.org/2001/04/xmlenc#"><EncryptionMethod
Algorithm="http://www.w3.org/2001/04/xmlenc#rsa-1_5"/><ds:KeyInfo
xmlns:ds="http://www.w3.org/2000/09/xmldsig#"><wsse:SecurityTokenRefere
nce><wsse:KeyIdentifier
-token-profile-1.0#X509SubjectKeyIdentifier">SnrZxQvN4uw=</wsse:KeyIden
tifier></wsse:SecurityTokenReference></ds:KeyInfo><CipherData><CipherVa
lue>YLx8JzXGihdnEFtk7NMKxrZ/jO5V2dZWOhXiEL0Y/c72Tf3nkoUmRz3r1xTuSW9fcvn
6LKtKzAM0WNFEzIFpeoOVoUtMWoRNLUBLSI3SyUdBIaS6en6536M2CwFRbFCDDzekPQ6ynY
mxpYxrQiIpkRIsbxMIw6O+66lG43y88rU=</CipherValue></CipherData><Reference
List><DataReference
URI="#wssecurity_encryption_id_1"/></ReferenceList></EncryptedKey></wss
e:Security></soapenv:Header>
<soapenv:Body><EncryptedData Id="wssecurity_encryption_id_1"
Type="http://www.w3.org/2001/04/xmlenc#Content"
Algorithm="http://www.w3.org/2001/04/xmlenc#tripledes-cbc"/><CipherData
><CipherValue>Ngo63Q72UWG0r/Z3zvyFAVTTlAdTlw4+vtumTqZSgvzbLp8/V5pjE7Pru
X1MxUN+arMjxaC0afV7yP+9nKbNgagf+EB5yFVRCju3PzJXYpg6OBWHwfl/6WWwIpbNLVXN
4ntU5dRSQ5+bC6o6lTQk/PuH3LNAWWlm</CipherValue></CipherData></EncryptedD
ata>
</soapenv:Body></soapenv:Envelope>
HTTP/1.1 200 OK
...
Date: Mon, 13 Nov 2006 13:55:55 GMT
<soapenv:Envelope...><soapenv:Header><wsse:Security
soapenv:mustUnderstand="1"
ecurity-secext-1.0.xsd"><EncryptedKey
Algorithm="http://www.w3.org/2001/04/xmlenc#rsa-1_5"/><ds:KeyInfo
xmlns:ds="http://www.w3.org/2000/09/xmldsig#"><wsse:SecurityTokenRefere
nce><wsse:KeyIdentifier
-token-profile-1.0#X509SubjectKeyIdentifier">Q/HFFBeGh/U=</wsse:KeyIden
tifier></wsse:SecurityTokenReference></ds:KeyInfo><CipherData><CipherVa
lue>kB+/NZaPzXVouZYZVa/l991AnRXRMsDkIm/nyJhwWzchOMeE3eaXYHRExjIWCOazJ+G
wZ3tRGLRpkfg9BKJBmQWzKgiGnflgSl+hyqmNnzNb9xzi4Y4zkrvKYuk4Ov6yub7NG94bIS
ndgeSqqBVeMY0KYcAPzx8jo3ES7WghqRk=</CipherValue></CipherData><Reference
List><DataReference
URI="#wssecurity_encryption_id_19"/></ReferenceList></EncryptedKey></ws
se:Security></soapenv:Header>
<soapenv:Body><EncryptedData Id="wssecurity_encryption_id_19"
Type="http://www.w3.org/2001/04/xmlenc#Content"
Algorithm="http://www.w3.org/2001/04/xmlenc#tripledes-cbc"/><CipherData
><CipherValue>M1YgSFnIrz89VFHdPsmVT0PauBHcbxs+qdeLp1/f+BnsDzzz8dCIr1RT5
Sy2fK2nUuW2YRFOjr+0Ryaaw6gWbDDCbG+1FyG3E6YqGvaHng6uM39Hm/Om4wTq8kKYqQaG
HX0lnlieRs04D6iyzk3NfPLXDoxqov4LIuEZaLL5YcxuVmF5+OgPj8mnEe3QN47ENF9Ygjw
mzv2jb21Euz8H0oK5nVBBqMXJH8zakgU2+qOGMsTAUrLd5eCsVqH1jwKmW+VvwXRH65VlZT
o1PV40x5Zn8BpLCA/sfd5GzmtoytAIjxipAVoYw0ebd6IA4msJZ1U/EcLD+rD/bABSSdelF
zHgyw6MZmpWfYgkAC6fw/2p1PrRCCnC12M2xz214TUQgHrljPbtGl73/dz5F77ow8wW+oK9

A4rAxe3jWkLuFZwqgPCbRWXYZeCJBB5vp0L1O8O005Q6OUr784vzTlIqj39VtLDaFcJ4wP8
36yoSa8w=</CipherValue></CipherData></EncryptedData></soapenv:Body></so
apenv:Envelope>
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 <wsse:Username> 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

...
SOAPAction: ""
Content-Length: 650
Date: Mon, 13 Nov 2006 15:19:11 GMT
<soapenv:Envelope
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"><soapenv:Header><
wsse:Security soapenv:mustUnderstand="1"
ecurity-secext-1.0.xsd"><wsse:UsernameToken><wsse:Username>valence</wss
e:Username></wsse:UsernameToken></wsse:Security></soapenv:Header><soape
nv:Body><p98:obtainSecurityInfo
HTTP/1.1 200 OK

Content-Language: en-US
Content-Length: 642
Date: Mon, 13 Nov 2006 15:19:23 GMT
<soapenv:Envelope ...
><soapenv:Header/><soapenv:Body><p98:obtainSecurityInfoResponse
235</string><string>Mon Nov 13 15:19:21 GMT+00:00
2006</string><string>WTSC58</string><string>9.12.4.8</string><string>va
lence</string><string>z/OS</string><string>01.08.00</string></obtainSec
urityInfoReturn></p98:obtainSecurityInfoResponse></soapenv:Body></soape
nv:Envelope>
All this validates that identity assertion occurs between the Web service client
and the Web service provider using WS-Security.
7
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.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 JSSE Application servers → server name →

Connector 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 SSL certificate and key management →

configured Manage endpoint security
(preferred) 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)
RMI-IIOP JSSE Centrally SSL certificate and key management →

CSIV2 configured Manage endpoint security
Alias Secure administration,

applications, and infrastructure →
RMI/IIOP security →
CSIv2 inbound/outbound transport
Daemon SSSL Not Centrally See Alias

SSL configured

z/OS location service daemon
JMX Soap JSSE Centrally SSL certificate and key management →

Connectors configured Manage endpoint security

Administration Services →
JMX connectors → SOAPConnector →
Custom Properties > sslConfig
7.4 SSL RACF certificate management

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
configuration.
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:
򐂰 <WAS_HOME>/java/lib/security (location of java.security file)
򐂰 <WAS_HOME>/java/lib (location of provider jars)
Where <WAS_HOME> 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

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.
Table 7-4 JCE Characteristics

Provider Keystore Certificate Key Use WebSphere Tooling
name type location location HW path
IBMJCECCA JKS File File Yes path/file WAS

IBMJCE JCEKS system ikeyman
PKCS12 keytool
JCECCARACFKS RACF Hardware Yes safkeyring:/// RACF

safkeyringhw:///
JCECCAKS File Hardware Yes path/file hwkeytool
IBMJCE JKS File File No path/file WAS

JCEKS system ikeyman
PKCS12 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:
>WASKeyring.HD<
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
Serial Number:
>01<
Issuer's Name:

Subject's Name:
>CN=HDPersonal.O=IBM<
PKDS Label: IRR.DIGTCERT.ASCR1.SC58.BFCDCD6AB6371A8E
Ring Associations:
Ring Owner: ASCR1
Ring:
>WASKeyring.HD<
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 <WAS_HOME>/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
– 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.
7.9.2 SSL traces

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

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.
7.9.3 Common errors

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)

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

<security-constraint>
<display-name>SecureConstraint</display-name>
<web-resource-collection>
<web-resource-name>Secure Web Resource</web-resource-name>
<url-pattern>/*</url-pattern>
<http-method>GET</http-method>
<http-method>POST</http-method>
</web-resource-collection>
<auth-constraint>
<description>
</description>
<role-name>SecureCustomer</role-name>
</auth-constraint>
<user-data-constraint>
Chapter 8. Web services transport security 247

<transport-guarantee>NONE</transport-guarantee>
</user-data-constraint>
</security-constraint>
<login-config>
<auth-method>BASIC</auth-method>
<realm-name>SecurityInfo Realm</realm-name>
</login-config>
<security-role>
<description>
</description>
</security-role>
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

Pragma: no-cache
SOAPAction: ""
Authorization: Basic V0lOU0VSVjpXSU5TRVJW

Content-Length: 402
Date: Wed, 08 Nov 2006 16:33:48 GMT
<soapenv:Envelope
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"><soapenv:Header/>
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
Pragma: no-cache
SOAPAction: ""
Content-Length: 402
Date: Fri, 10 Nov 2006 15:25:10 GMT
<soapenv:Envelope
rityInfo></soapenv:Body></soapenv:Envelope>(....[xU.n..........QHTTP/1.
1 200 OK
Content-Language: en-US
Content-Length: 650
Date: Fri, 10 Nov 2006 15:25:13 GMT
<soapenv:Envelope
<soapenv:Body><p98:obtainSecurityInfoResponse
916</string><string>Fri Nov 10 15:25:13 GMT+00:00
2006</string><string>WTSC58</string><string>9.12.4.8</string><string>UN
AUTHENTICATED</string><string>z/OS</string><string>01.08.00</string></o
btainSecurityInfoReturn></p98:obtainSecurityInfoResponse></soapenv:Body
></soapenv:Envelope>...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
SecureConstraint.
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

<transport-guarantee>INTEGRAL</transport-guarantee>

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

<transport-guarantee>CONFIDENTIAL</transport-guarantee>
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
Serial Number:
>00<
Issuer's Name:
Subject's Name:
Key Usage: CERTSIGN
PKDS Label: IRR.DIGTCERT.CERTIFAUTH.SC58.BFBDE7690EF01249
Ring Associations:
Ring Owner: ASCR1
Ring:
>WASKeyring.HD<
Ring Owner: ASSR1
Ring:
>WASKeyring.HD<

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
Serial Number:
>02<
Issuer's Name:
Subject's Name:
>CN=HDPersonal.O=IBM<
PKDS Label: IRR.DIGTCERT.ASCR1.SC58.BFBDE9BD1F5C88CC
Ring Associations:
Ring Owner: ASCR1
Ring:
>WASKeyring.HD<
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:
<WAS_HOME>/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
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.
Figure 8-18 HDCertStore
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:
<WAS_HOME>\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
Serial Number:
>24<
Issuer's Name:
>CN=WAS CertAuth for Security Domain.OU=WebSphere for zOS<
Subject's Name:
>CN=WINSERV.OU=ITSO.O=IBM<
Private Key Type: Non-ICSF
Ring Associations:
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
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 CLIENT_CERT.
Example 8-10 Client certificate authentication setup in web.xml

<security-constraint>
<display-name>
Security Constraint</display-name>
<web-resource-collection>
<web-resource-name>Security Resource</web-resource-name>
<url-pattern>/*</url-pattern>
<http-method>GET</http-method>
<http-method>PUT</http-method>
<http-method>POST</http-method>
</web-resource-collection>
<auth-constraint>
<description>
</description>
</auth-constraint>
</security-constraint>
<login-config>
<auth-method>CLIENT-CERT</auth-method>
</login-config>
<security-role>
</security-role>

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.

9
Chapter 9. Security attribute

propagation and CSIv2
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.
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.
9.3 CSIv2 standard identity assertion

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.
9.3.1 CSIv2
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.
10
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.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
authentication.
򐂰 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=<racf_id>,profiletype=user,<sdbm_suffix>
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

listen ldap://:3389
maxConnections 60
adminPW "secret"
# TDBM-specific CONFIGURATION SETTINGS
servername DB2B
dbuserid GLDSRV
databasename GLDDB

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,<suffix> 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

Server for z/OS.

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

listen ldap://:3389
maxConnections 60
adminPW "secret"
# TDBM-specific CONFIGURATION SETTINGS
servername DB2B
dbuserid GLDSRV
databasename GLDDB
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

Federated repositories Other user registry
options
Supported registries File-based Local operating system

LDAP Standalone LDAP
DB (via wsadmin) Standalone custom
Simultaneous Yes No
multi-registry support
Registry read/write Read/write Read only

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

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.
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
authentication.
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 򐂰 Access to servlets or EJB methods is based upon the role (job title,
(WebSphere bindings) 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.
System Authorization 򐂰 Access to servlets or EJB methods is based upon the role (job title,
Facility authorization function, and so on) of the user or caller.
򐂰 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 򐂰 Access to servlets or EJB methods is based upon the role (job title,
using a JACC provider function, and so on) of the user or caller.
򐂰 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,
rather 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 OS thread
identity security
support 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 Required Supported

default, IMS JDBC only supports this type of configuration.)

Connectors Thread OS thread
identity security
support support
RRA DB2 for z/OS local JDBC provider - data sources configured to Allowed Supported
the local DB2
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 = Allowed Supported

BINDINGS)
WebSphere MQ JMS Provider - Connection Factory (TransportType Not allowed Not supported
= CLIENT)
WebSphere JMS Provider (such as Integral JMS Provider): Not allowed Not supported
Connection Factory
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.
11
Chapter 11. SPNEGO and Windows

single sign-on
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

browsers 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
authentication.
򐂰 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/<full_WAS_z/OS_dns_name> <user_account>
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/<full_WAS_z/OS_dns_name>@<windows_Domain> -out
<output_file> -pass password -mapUser <user_account> -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<id>.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<id>.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 → <server_name> → 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
browser 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.
ThreadId: 00000029
FunctionName: handleRequest
Category: INFO
ExtendedMessage: CWSPN0023I: Username VALENCE@KKDC.TEST.COM Token
size 1662.
ThreadId: 00000029
FunctionName: trimUsername
Category: FINER
ExtendedMessage: Principal name was trimmed to: VALENCE
ThreadId: 00000029
FunctionName: negotiateValidateandEstablishTrust
SourceId: com.ibm.ws.security.spnego.TrustAssociationInterceptorImpl
Category: FINER
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
Server for z/OS.
12
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.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.<domain>.** UACC(READ)
PERMIT CB.BIND.<domain>.** 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.<domain>.<cluster>. 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

z/OS security WebSphere Application
Server security
User account Local operating system Federated repository

repository User IDs, groups, and User IDs and passwords are
passwords are stored in RACF. stored in file-based placed
UNIX System Service.
User IDs and passwords are

stored in fileRegistry.xml
Authorization System Authorization Facility Default authorization

technology (SAF) authorization Use WebSphere Security
(external Use the authorization policy that authorization.
authenticated is stored in RACF.
provider
security)
Administrative RACF EJBROLE profile WebSphere Admin Role

role definition Mapping information is stored in Mapping information is stored in
RACF. UNIX System Services.
򐂰 Information of user IDs and
Definition of EJBROLE profiles roles is stored in
is required. (Default roles are admin-auth.xml.
defined during server 򐂰 Primary admin user ID,
installation process.) which is used to log on to
the administrative console,
is stored in security.xml.
Key store type System Authorization Facility File-based key store

keyring Stored in UNIX System
Stored in RACF DB Services.
Key store PATH: safkeyring:/// Key store PATH:
<keyring_name> ${CONFIG_ROOT}/cells/<cell_
Type: JCERACFKS name>/nodes/<node_name>/<
key_file>
Type: PKCS12
z/OS security WebSphere Application
Server security
Application Security Authorization File-based mapping

deployment Facility (SAF)-based mapping Need to map user and role in
(role mapping) 򐂰 Need to define new the “Map security roles to users
EJBROLE profiles in RACF. or groups” step in the
򐂰 The “Map security roles to deployment of application.
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

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.<cell_short_name or
security_domain_prefix>.<cluster_short_name> UACC(NONE)
PERMIT BBO.SYNC.<cell_short_name or
security_domain_prefix>.<cluster_short_name> 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.<SR_user_id> UACC(NONE)
PERMIT BBO.SYNC.<SR_user_id> 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.
13
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.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

b. 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 <domain.>administrator UACC(NONE)
RDEFINE EJBROLE <domain.>monitor UACC(NONE)
RDEFINE EJBROLE <domain.>configurator UACC(NONE)
RDEFINE EJBROLE <domain.>operator UACC(NONE)
RDEFINE EJBROLE <domain.>deployer UACC(NONE)
RDEFINE EJBROLE <domain.>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 <domain.>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 <domain.>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).
<?xml version="1.0" encoding="UTF-8"?>

<security:Security xmi:version="2.0" xmlns:xmi="http://www.omg.org/XMI"
xmlns:orb.securityprotocol="http://www.ibm.com/websphere/appserver/schemas/5.0/orb.
securityprotocol.xmi"
xmlns:security="http://www.ibm.com/websphere/appserver/schemas/5.0/security.xmi"
xmi:id="Security_1" useLocalSecurityServer="true"
useDomainQualifiedUserNames="false" enabled="true" cacheTimeout="600"
issuePermissionWarning="true" activeProtocol="BOTH" enforceJava2Security="false"
enforceFineGrainedJCASecurity="false" appEnabled="false"
dynamicallyUpdateSSLConfig="true" activeAuthMechanism="LTPA_1"
activeUserRegistry="WIMUserRegistry_1" defaultSSLSettings="SSLConfig_nd6582_1">
:
<userRegistries xmi:type="security:WIMUserRegistry" xmi:id="WIMUserRegistry_1"
serverId="" serverPassword="{xor}" realm="defaultWIMFileBasedRealm"
ignoreCase="true" useRegistryServerId="false" primaryAdminId="itsouser"
registryClassName="com.ibm.ws.wim.registry.WIMUserRegistry"/>
:
</security:Security>
Figure 13-6 Updated security.xml
<?xml version="1.0" encoding="UTF-8"?>
<sdo:datagraph xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:sdo="commonj.sdo" xmlns:wim="http://www.ibm.com/websphere/wim">
<wim:Root>
<wim:entities xsi:type="wim:PersonAccount">
<wim:identifier externalId="cc750038-75ad-4454-b9b6-c5bdced553ca" external
Name="uid=itsouser,o=defaultWIMFileBasedRealm"
uniqueId="cc750038-75ad-4454-b9b6-c5bdced553ca" uniqueName="uid=itsous
er,o=defaultWIMFileBasedRealm"/>
<wim:parent>
<wim:identifier uniqueName="o=defaultWIMFileBasedRealm"/>
</wim:parent>
<wim:createTimestamp>2006-11-28T15:33:24.449+00:00</wim:createTimestamp>
<wim:password>U0hBLTE6ZW9oYTM4dnYxc3l6OnEwK2FFN2RRMUtVTldiVlVNdFJtdE5HWlZt
dz0K</wim:password>
<wim:uid>itsouser</wim:uid>
<wim:cn>itsouser</wim:cn>
<wim:sn>itsouser</wim:sn>
</wim:entities>
</wim:Root>
</sdo:datagraph>
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.
Role Description
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 <domain.>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 <authorization group>.<rolename> profiles in EJBROLE (again,
prefix those profiles with your domain identifier if you have one
configured):
RDEFINE EJBROLE <domain.>APPG.administrator UACC(NONE)
RDEFINE EJBROLE <domain.>APPG.configurator UACC(NONE)
RDEFINE EJBROLE <domain.>APPG.operator UACC(NONE)
RDEFINE EJBROLE <domain.>APPG.monitor UACC(NONE)
RDEFINE EJBROLE <domain.>APPG.deployer UACC(NONE)
RDEFINE EJBROLE <domain.>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 <domain.>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

Role 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 <domain.>CosNamingRead UACC(READ)
PERMIT <domain.>CosNamingRead CLASS(EJBROLE) ID(WSGUEST) ACCESS(READ)
RDEFINE EJBROLE <domain.>CosNamingWrite UACC(NONE)
RDEFINE EJBROLE <domain.>CosNamingCreate UACC(NONE)
RDEFINE EJBROLE <domain.>CosNamingDelete UACC(NONE)
PERMIT <domain.>CosNamingWrite CLASS(EJBROLE) ID(WSCFG1) ACCESS(READ)

PERMIT <domain.>CosNamingCreate CLASS(EJBROLE) ID(WSCFG1) ACCESS(READ)
PERMIT <domain.>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.
A
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:

ibm.com/redbooks
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
The publications listed in this section are considered particularly suitable for a
more detailed discussion of the topics covered in this book.
IBM Redbooks
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
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
Online resources
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:
ibm.com/redbooks
Related publications 475

Help from IBM
IBM Support and downloads
ibm.com/support
IBM Global Services

ibm.com/services
Index
iscadmins 460
Numerics Monitor 460
128-bit encryption algorithm 268
Operator 460
40-bit encryption algorithm 268
administrative security 72
default authorization provider 455
A disabling
administration security using admin console 457
options 432 disabling, using wsadmin 457
do not enable security 437 options 449
use a z/OS security product 433 security trace 458
use a z/OS security product, user IDs creat- administrative security, fine-grained 462
ed 433 options to implement 463
use WAS security 435 adminstrative security
Administrative Console what does it protect? 72
Accessing ITDS configuration 378 Application Security
administrative security 449 enabling, in admin console 73
Certificate application security 72
manage certificate expiration 218 asymmetric cipher algorithm 30
change internal server user id 442 Auditing 4
Configuring the JVM for the SPNEGO TAI 416 authDataAlias 48
Develop your own TAI 396 Authentication 3
LDAP authentication keys 32
TDBM Authorization 3
Federate Repositories 368 Default authorization 384
z/OS LDAP SDBM 344 External authorization using JACC provider 385
z/OS LDAP TDBM 355 SAF authorization 384
RunAs thread identity 388 authorization group 462
SAF authorization 383, 385 authorization providers 450
Security Attribute Propagation default authorization 450
Vertical propagation 331 Java Contract for Containers (JACC)
security configuration reporting tool 448 external authorization 450
Security role-based System Authorization Facility (SAF) 450
AdminSecurityManager 461 authorization, SAF-based 25
Deployer 461
iscadmins 461
security wizard 448
B
base64 254
SPNEGO configuration 414
Basic Authentication 72, 98, 246
z/OS thread identity synchronization 387
Identity assertion 193
administrative roles
basic authentication 51
added in WAS V6.1 460
Binary Der Data 254
Administrator 461
AdminSecurityManager 460
Configurator 460 C
Deployer 460 CA - Top Secret 228

callbackhandler 114 client certificate authentica-
caller part 114
tion 313
CBIND class 309
outbound transport 310
Certificate
example 321
Comparing the personal certificate 286
identity formats supported in WAS for z/OS
Certificate Authority (CA) 117
308
certificates
certificate 308
comparing between z/OS and Windows 286
Distinguished Name 308
extracting the z/OS signer certificate 254
SAF identity 308
extracting the z/OS signer certificate, RACF
trust relationship 308
command 254
ways of establishing trust 308
importing the server signer certificate into the cli-
J2EE server authentication using CSIv2
ent 254
logical flow 45
CICS 336–337
layers 306
authorization and authentication support, in
message layer authentication 306
WAS 23
security attribute propagation 306
CICS Transaction Gateway (CTG)
transport layer authentication 306
CICSECIConnector 389
Confidentiality 3, 268
JCA custom principal mapping 48
CosNaming 467
cipher suite group, medium 268
CosNaming security 467
cipher suite group, strong 268
create 237
Client Certificate Authentication 72, 98, 282
cryptography 164
Common Client Interface (CCI) 23
CSIv2 5
Common Object Request Broker Architecture
CSIv2 - Common Secure Interpretability
(CORBA) 467
What is CSIv2? 41
Common Secure Inter operability Version 2 (CSIv2)
custom login module 16
17
Common Secure Interoperability Specification v2
(CSIv2) 18 D
Common Secure Interoperability Version 2 (CSIv2) data encryption method algorithm 176
98 Data Encryption Standard (DES) 164
features in WAS for z/OS 306 Data Replication Service (DRS) 299
Common Secure Interoperability version 2 (CSIv2) DB2 336–337, 340, 386, 388
5, 44, 305 Universal JDBC Driver Provider
authentication mechanisms 307 type 2 390
Basic Authentication 307 type 4 390
client certificate authentication 307 z/OS local JDBC provider 390
identity assertion 305–307 DefaultPrincipalMapping 48
configuration deployment descriptor 10
inbound authentication 317 digest code 88
Basic Authentication 318 Digital Signature
client certificate authentica-
Digital signature
tion 318 how is it created? 88
client identity types 320
inbound transport 315
outbound authentication 312
E
EIS - Enterprise Information Systems 336–337,
Basic authentication 313 386, 388–389
EJB authenticating in HTTP server
execution identity 33 logic al flow 36
Runas identity 33 HTTP(s) 13
security identity 33 Hypertext Transfer Protocol (HTTP) 90
security role 33 Hyptertext Transfer protocol over SSL (HTTPS) 91
EJB container
programmatic security APIs 11
ejbActivate() method 23
I
IBM SDKs 475
ejbCreate() method 23
IBM Tivoli Access Manager 3, 48, 360, 395, 397
ejbLoad() method 23
principal mapping module 48
Enterprise Information Systems (EIS) 22
IBM Tivoli Access Manager for e-business (TAMeb)
errors
17
creating native credentials 291
IBM Tivoli Directory Server v6 (ITDS) 340, 356,
External Authorization Server
367, 375, 475
Authorization using external authorization server
Configuration 375
configuration tasks 57
How to install 375
WebSphere z/OS configuration 378
F IBMJCECCA 192, 222, 275
Federated 25 ibm-webservices-bnd.xmi 112
Federated Repositories 363 ibm-webservices-bnd.xml 110
ITDS 378 ibm-webservicesclient-bnd.xmi 111
SPNEGO 399 ibm-webservicesclient-ext.xmi 111
what are federated repositories? 363 ibm-webservices-ext.xmi 111
fingerprint 88 ibm-webservices-ext.xml 110
fixes ICSF managed keys 192
PK31729 291 Identity Assertion
Form based authentication 72 Configuration
z/OS provider 199
G IMS 336–337, 386, 388
General Inter-ORB Protocol (GIOP) 44
authorization and authentication support, in
Generic Security Services Username Password
WAS 24
(GSSUP) token 315
Connector 389
global security 71, 430
JDBC Connector 389
group 430
INADDR_ANY parameter 14
Integrity 3
H Intermediaries 80
Hardware Cryptography Internet 29
IBMJCE Interoperable Inter-ORB Protocol (IIOP) 44
characteristics 227 IP/UDP layer 29
IBMJCECCA
characteristics 227
hardware cryptography 192 J
J2C
HFS owner user ID, adding 432
application contract 23
HTTP Server
connector components 23
Authenticating in HTTP server
container contract 23
contracts 23
HTTP server
system contract 23
Index 479
J2EE 9 Kerberos 392, 397
Security 5 Authentication protocol 393
J2EE client 13 Encryption types 411
J2EE client authentication using CSIv2 40 Keytab file 410
configuration tasks 43 Realm
logical flow 41 WinKerbRealm 399–400
J2EE Connector Architecture (JCA) zOSKerbRealm 399–400
custom mapping 47 Service Principal Name (SPN) 405
JCA custom principal mapping 46 key encryption method algorithm 177
J2EE deployment descriptor files 112 key information 114
J2EE security 10 key locator 114
declarative security 10 key store path, WebSphere default 175
programmatic security 10 keystore 226
J2EE security,architecture 11
J2EE server
J2EE server authentication using CSIv2 43
L
LDAP - Lightweight Directory Access Protocol
JAAS login module 59
337–338, 378
JACC - Java Contract for Containers
336–337, 340
External authorization 385
Active Directory 395
Java 2 security 5, 9
JOBLOG 361
Java Authentication and Authorization Service
messages 361
(JAAS) 19
SAF authorization 384
Java Authorization Contract for Containers (JACC)
SLAPDCNF member 341, 351
25
SPNEGO 399
Java Contract for Containers (JACC)
z/OS
authorization using external authorization server
SDBM 340–341
56
schema 342
Java Cryptography Extension (JCE) 222
Java Cryptography Extension (JCE), IBM version
TDBM 337, 340, 350, 367
222
configuration 351
Java Message Service (JMS) 91
Federated Repositories 368
Java security 5
Native Authentication configuration 360
java.security file 223, 275
JAX-RPC 91–92
WebSphere z/OS configuration for Native
JCA - J2EE Connector Architecture
Authentication 362
JCA custom principal mapping
Lightweight Directory Access Protocol (LDAP) 30
Lightweight Third Party Authentication (LTPA) 16
resource adapter 389
link layer, 29
JCE - Java Cryptography Extension
LSA - Local Security Authority 395, 402
IBMJCECCA
LTPA token 116, 302
227
keys 302
What is JCE? 222
LtpaToken 297
JCECCRACFKS 276
LtpaToken2 297
K M
KDC - Key Distribution Center 392–393, 395, 398,
Message Authentication Code (MAC) 222
402, 412
Microsoft Internet Explorer 398
z/OS 399
SPNEGO configuration 419
Microsoft Windows Active Directory (AD) 392, EJBROLE 8
395–396, 398 FACILITY 8
Create a user account for WebSphere Applica- GEJBROLE 8
tion Server for z/OS 405 KERBLINK 8
Microsoft Windows Server 2003 475 LOGSTRM 8
SP 1 475 SERVAUTH 8
SP1 401 SERVER 8
Microsoft Windows XP Professional 2002 SP2 401 STARTED 8
Mozilla Firefox 398 SURROGAT 9
SPNEGO configuration 421 Commands
ADDUSER 432
PERMIT 104, 434
N RACDCERT 284
naming service security 467
RDEFINE 104, 384–385, 434
Native Authentication 359, 373
SETROPTS 104
Why to use Native Authentication? 360
Cosnaming EJB Roles 9
nonce 115
GROUP 7
non-ICSF managed keys 192
How to define an EJBROLE in RACF 384
Non-repudiation 4
keystore 215
NTLM credential 397
MIXEDCASE option 443
mixed-case password support, enabling 443
O profile
OASIS 21 segments 7
Object Management Group (OMG) 5 profile, attributes 7
Open System Interconnection (OSI) 29 RACO (ENVR Object) 7
Operating System (OS) security 4 SPNEGO 399
org.omg.CORBA.NO_PERMISSION exception User Profiles 341
468 Redbooks Web Site 475
Organization for the Advancement of Structured In- Contact us xvi
formation Standards (OASIS) 82 Registries
OS thread identity 386 Introduction 336
Local Operating System 336, 382
Configurating WAS to use local z/OS for au-
P
Presumed Trust thorization 433
Identity assertion 193 SPNEGO 399
When 337
Standalone Custom Registry 336, 338
R How to write a custom registry? 338
RACDCERT 218 SAF authorization 384
RACF 103 Standalone LDAP Registry 336–337, 340
Access Control Element (ACEE ) 7 SDBM 340–341
Attribute configuration 341
AUDITOR 343 schema 342
CLASS 8 WebSphere z/OS configuration 344
classes, relevant to WAS on z/OS 8 TDBM 337, 340, 350
APPL 8 configuration 351
CBIND 8 WebSphere z/OS configuration 355
DIGTCERT 8 Why should you use a LDAP registry? 337
DSNR 8 Remote Method Invocation over Internet Inter-ORB
Index 481
Protocol (RMI-IIOP) 91 deleting a CA signer certificate 222
Repositories deleting a keyring 221
Federated repositories 336, 338 deleting a personal certificate 222
Resource Access Control Facility (RACF) 6 exporting a personal certificate 220
functionality 6 exporting a signer certificate to an HFS
profile 6 file 220
resource instances 462 generating a signer certificate 229
Reverse Proxy Security Server (RPSS) PKCS12B64 keyword 220
authenticating in reverse proxy security server PKCS12DER keyword 220
37 removing a CA signer certificate from a
configuration tasks 40 keyring 221
forwarding the user id mechanisms 38 removing a personal certificate from a
logical flow 39 keyring 221
RMI-IIOP 13 viewing a list of certificates on a keyring
Using jax-rpc to support non-SOAP binding 92 for a user ID 218
RPSS - Reverse Proxy Security Server viewing certificate authority information
TAI 395 218
RunAS 33 viewing personal certificate information
for a user ID 218
viewing in Admin console 217
S WebSphere
SAF - System Authorization Facility 336
available export formats 221
Authorization 383
certificate expiration monitoring 218
Delegation 385
deleting 221
EJBROLE 385
expired certificates 218
Profile mapper 385
expired certificates, email notification
Sample applications
218
SecurityInfo 98
importing 220
sas.client.props file 310
cipher suite 31
SDK 1.5 5
client certificate authentication 282
Secure Hash Algorithm (SHA-1) 164
configuration the z/OS Web Service provider
Secure Sockets Layer (SSL) 30, 91
255
aliases 211
configuring the Web Service requestor 261
authentication keys 32
configuring the Web Service requestor endpoint
Basic Authentication
URL 264
configuring 282
creating a new SSL Configuration in WAS 256
centrally managed 210
creating a new SSL inbound channel in WAS
certificate request 31
257
certificates
enforcing confidentiality 271
deleting keystores and truststores 222
enforcing integrity 267
deleting or adding to or from RACF keyring
errors
217
CWPKI0022E 242
RACF commands 218
ICSF address space unavailable 242
CERTB64 keyword 220
signer certificate is from a client’s truststore
CERTDER keyword 220
242
connecting a personal certificate 230
SSLC0008E 242
connecting to a ring 229
starting Websphere using IBMJCECCA pro-
creating a personal certificate 229
vider 243
creating a ring 229
handshake 30
handshake errors 239 JCECCARACFKS 226
handshake flow 95 JCEKS 225
handshake, common errors 242 JCERACFKS 225
hardware cryptographic support 272 JKS 225
configuring the Web Service provider for PKCS11 225
confidentiality 281 PKCS12 225
configuring the Web Service requestor for Java Secure Socket Extension (JSSE) 213
confidentiality 281 JCE provider 223
configuring the Web Service requestor SSL keystore 226
configuration 280 storage 227
connecting a CA to a keyring 272 keystore types 227–228
connecting a personal certificate to a keyring JCECCAKS 229
273 JCECCARACFKS 228
creating a new CA 272 JCEKS 228
creating a new keyring 272 JCERACFKS 228
creating a new personal certificate 273 JKS 228
exporting the signer certificate 274 PKCS11KS 229
HDWebServiceSSLConfig 280 PKCS12KS 228
importing the signer certificate 274 master secret 32
installing the unrestricted Java policy jars NodeDefaultSSLSettings 211
275 pre-master secret 32
JCECCRACFKS 276 protocol version 31
JCECCRACFKS, creating a new keystore repertoire alias 210
276 setting the cipher suite group, for Web Service
SSLException 281 provider 264
updating the JVM to use IBMJCECCA 275 symmetric encryption keys 32
validating confidentiality 281 System SSL (SSSL) 213
viewing CA information 273 trace, enabling dynamically 242
viewing the personal certificate information trace, JSSE 242
274 traces 241
hardware cryptography traces, enabling 241
Common Cryptographic Architecture (CCA) transport chain 259
interfaces 222 truststore 227
creatING a new keystore 237 WebSphere
diagnosing SSL handshake issues 240 keystores, available 224
IBMJCE4758 223 WebSphere V6.0 endpoint details 213
IBMJCECCA 222 WebSphere V6.1 210
IBMJCECCA, prereqs 223 WebSphere V6.1 endpoint details 214
JCECCARACFKS keystore 233 X.509 v.3 certificates 31
keys in hardware 234 security attribute propagation 294
safkeyring URI 237 attribute propagation 294
unrestricted policy jars 236 benefits 295
unrestricted policy jars, installing in Web- horizontal propagation 295, 298, 305
Sphere 236 configuration 301
update the java.security file with the IB- cross-cell considerations 302
MJCECCA provider 236 Data Replication Service (DRS) 299
IBMJCE provider DynaCache 299
keystore types example 300
JCECCAKS 226 JMX 299
Index 483
JMX calls 305 security role 33
LTPA key, sharing 303 Simple Object Access Protocol (SOAP) 90
LTPA keys, sharing 304 confidentiality 89
LTPA keys, sharing, automatically generated identity assertion 90
304 integrity 87
mechanisms, in WebSphere 299 Web Services authentication 51
performance implications 299 WS-Security standard 82
Single Sign On, cross-cell 303 Simple WebSphere Authentication Mechanism
SSO token 298 (SWAM) 16
identity propagation 294 Single Sign On (SSO) 16
initial login 295 authenticating in HTTP server 35
JAAS Subject 294 SOA - Service Oriented Architecture
Java serialization 297 Introduction to soa and z/OS security 76
Lightweight Third Party Authentication (LTPA) SOAP - Simple Object Access Protocol
296 RMI-IIOP with multiprotocol jax-rpc 92
Principal 294 SPNEGO 391
propagation login 295 Configuring Microsoft Internet Explorer 419
Reverse Proxy Security Server (RPSS) 295 Configuring Mozilla Firefox 421
Run-As 295 Configuring the JVM 416
Single Sign On (SSO) 294 Configuring the Microsoft Windows server 404
styles 295 Configuring WebSphere Application Server for
token framework 297 z/OS 414
vertical propagation 295 handshake 397
Webseal 295 RACF 399
WebSphere token framework Troubleshooting 422
authentication token 297 What is SPNEGO? 396
authorization token 297 SSO - Single Sign On 16
LtpaToken 297 SPNEGO 392
LtpaToken2 297 WebSphere Application Server for z/OS using
propagation token 297 SPNEGO 397
Single Sign On 297 z/OS KDC and Microsoft Windows KDC 399
Subject-based tokens 297 symmetric algorithm 30
thread-based token 297 symmetric encryption keys 32
security attribute propoagation Sync-to-OS Thread 386, 444
vertical propagation 328 activation 387
cross-cell considerations 334 defining RACF profile 446
implementation 331 What’s new in Version 6.1? 444
Remote Method Invocation (RMI) over the System Access Facility(SAF) 6
Internet Inter-ORB Protocol (RMI over IIOP) System Authorization Facility (SAF) 5
328 System Network Architecture (SNA) 29
Security Attribute Service (SAS) 305 system.wssecurity.IDAssertionUsernameToken
Security Constraint 267 128
security.xml file 218 system.wssecurity.PKCS7 128
server ID 441 system.wssecurity.PkiPath 128
Service Oriented Architecture (SOA) 51 system.wssecurity.UsernameToken 128
servlet system.wssecurity.X509BST 128
execution identity 33
Runas identity 33
security identity 33
T for any URI 66
TCP layer 29 for protected URIs only 65
Ticket system properties
Kerberos 392–393 com.ibm.wsspi.security.web.webauthreq
Ticket Granting Server (TGS) 393 67
Ticket Granting Ticket (TGT) 393 Web authentication behavior
token generator 114 admin console, settings 65
Top Secret 5 Web container
Trust association 17 programmatic security APIs 11
Trust Association Interceptor (TAI) 16, 38, 395 Web Services
Trust Relationship Authentication
TAI 395 logic flow 52
trust store path, WebSphere default 180 authentication 51
truststore 227 Confidentiality
configure z/OS provider 183
configure z/OS requestor 185
U Identity Assertion
unrestricted policy jars 275
configure the z/OS provider 199
user 430
Message layer security 21
user account repository 440
message layer security 78
User registry
authentication
federated repository 24
configuring a token for Web Service pro-
Local Operating System (LocalOS) 24
vider 123
standalone custom registry 24–25
configuring a token for Web Service re-
standalone LDAP 24
questor 119
custom token 117
V LTPA token 116
Virtual Member Manager (VMM) 365 token generator, configuring 120
token type 119
W custom 119
WAS - WebSphere Application Server Username 119
Accessing ITDS 378 X509 certificate token 119
Build Number Username token 116
cf20633.22 401 X.509 certificate token 116
Configuration XML digital signature 117
administration security option components
Do not enable security 437 callbackhandler 114
Use a z/OS security product 433 caller part 114
Use WebSphere Application Server se- key information 114
curity 435 key locator 114
Create a user account in the AD 405 nonce 115
JMS Provider 390 timestamp 115
OS thread identity 386 token generator 114
SPNEGO 391, 396 trust anchor 115
Kerberos requirements 412 confidentiality
trace 422 164
z/OS KDC 399 asymmetric encryption algorithms 164
Web authentication configuring encryption, server 171
Index 485
configuring provider 178 HTTP(S)
configuring requestor 172 authentication 94
configuring, encryption algorithm 171 Basic Authentication 94
encryption, algorithms 164 Basic Authentication information 94
extracting WebSphere for z/OS signer benefits 93
certificate 167 client certificate authentication 94
one-way encryption algorithm 164 integrity and confidentiality 94
support in WS-Security 165 Universal Resource Identifier (URI) 91
symmetric encryption algorithms 164 JMS
configuration components 114 SSL 97
configuration files 111 point-to-point security 93
deployment descriptors 110 Remote Method Invocation over Internet In-
deployment descriptors, editing tools 110 ter-ORB Protocol (RMI-IIOP) 92
deployment descriptors, format in Web- RMI over IIOP 98
Sphere versions 110 CSIv2 98
identity assertion 192 SOAP over HTTP 91
configuring 195 SOAP over JMS 92
configuring Web Service requestor 196 when to use? 80
trust modes 193 Web Services Interpretability Organization (WS-I)
trust relationship 203 84
WS-Security support 193 Web Services Security (WS-Security) 108
integrity 131 WebSeal 17
canonicalization method algorithm 143 Webseal 395
configuring the Web Service provider WebSphere Application Server
146 What is new in v6.1 security? 2
configuring the Web Service requestor WebSphere Application Server (WAS)
135 connections 13
configuring the z/OS provider for XML encryption algorithms 268
digital signature 154 security settings 440
configuring the z/OS requestor for XML WebSphere Application Server configuration group,
digital signature 159 create 431
digest method algorithm 144 WebSphere Application Server HFS Owner 431
signature method algorithm 143 WebSphere Message Queueing
transform 145 WMQ client authentication 53
XML digital signature 131 WebSphere MQ 19
integritysignature algorithm 133 communication protocols 97
security token 116 WebSphere MQ Extended Security Edition 97
SOAP security header 109 WebSphere token framework 297
when to use? 80 WebSphereCA 254
WS Binding 113 WMQ - WebSphere Message Queueing
WS Extension 113 JMS Provider 390
security exposures 77 World Wide Web (WWW) 29
Transport layer security 21 WS Binding 113
transport layer security 78 WS Extension 113
Basic Authentication, configuring 247 WS-Authorization 22
Basic Authentication, validating 250 WS-Federation 22
configuring the requestor to authenticate WS-Policy 22
249 WS-Privacy 22
Enterprise Service Bus (ESB) 93 WS-SecureConversation 22
WS-Security Z
authentication mechanisms 86 z/OS KDC 399
high level architecture 85 z/OS thread identity 389
identity assertion RunAs 388
basic authentication 90 synchronization 386
digital signature activation 387
90
modes 90
presumed trust 90
Kerberos Token Profile 84
Minimalist Profile (MProf) 84
Rights Expression Language (REL) Token Pro-
file 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 digital signature 87
XML encryption standard 165
Ws-Security
XML encryption 89
WS-Security authentication mechanism
basic authentication 86
custom 86
ID assertion 86
LTPA 86
signature 86
WS-Trust 22
X
X.509 certificate token 116
X.509 v.3 certificates 31
XML digital signature 117
Index 487
Security in WebSphere Application
Server Version 6.1 and J2EE 1.4 on z/OS
Security in WebSphere Application Server Version 6.1 and
Security in WebSphere Application Server Version 6.1 and J2EE 1.4
Application Server
Version 6.1 and J2EE
Application Server
Version 6.1 and J2EE
Back cover ®
WAS and J2EE This IBM® Redbooks® publication was written with the
security concepts objective to provide a technical description of some of the INTERNATIONAL
and their most important security scenarios available with TECHNICAL
implementation on WebSphere® Application Server Version 6.1 for z/OS®. We SUPPORT
z/OS chose scenarios that are not really documented elsewhere ORGANIZATION
and that have had significant changes in Version 6.1.
Security integration
In the first two chapters we provide an overview of security
scenarios, including with WAS on z/OS for those readers who are unfamiliar with BUILDING TECHNICAL
SPNEGO and CSIv2 the security landscape on z/OS. From Chapter 3 onwards we INFORMATION BASED ON
PRACTICAL EXPERIENCE
go into more technical depth.
Web services
security and SSL in IBM Redbooks are developed by
WAS V6.1 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
SG24-7384-00 ISBN 0738488631

WAS 6.1 Security

Загружено:

Сведения о документе

Исходное описание:

Авторское право

Доступные форматы

Поделиться этим документом

Поделиться или встроить документ

Параметры публикации

Этот документ был вам полезен?

Это неприемлемый материал?

Авторское право:

Доступные форматы

WAS 6.1 Security

Загружено:

Авторское право:

Доступные форматы

Front cover

WAS and J2EE security concepts and

Security integration scenarios,

Web services security

Alex Louwe Kooijmans

Security in WebSphere Application Server Version

First Edition (December 2007)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Redbooks (logo) ® DB2® RACF®

The following terms are trademarks of other companies:

The team that wrote this book

Alex Louwe Kooijmans is a Project Leader with the International Technical

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

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

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

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

Become a published author

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

This chapter contains the following sections:

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

As IBM strategic middleware, WebSphere Application Server has been going

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

1.2 WAS and security layers

1.2.1 Security terms

1.2.2 Security layering overview

J2EE Security API

CORBA Security / CSIv2

Platform Security Operating System Security

Figure 1-1 Security layers

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

1.2.3 z/OS security overview

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

User ID Owner Password Attributes Security Groups Segments

OMVS TCP/IP TSO

Figure 1-2 RACF profile

Access Control Element (ACEE)

RACO (ENVR object)

RACF cosnaming EJB roles

1.2.4 Java security overview

You can configure Java 2 security and administrative security independently of

There are two ways of enforcing security under J2EE:

1.2.5 WebSphere security overview

Programmatic security includes actions taken by application program code to

Web applications use these methods:

EJB applications use these methods:

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

1.3 Securing WAS and applications

1.3.1 WAS and security checkpoints

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