Security in WebSphere Application Server Version 6.1 and J2EE … · Application Server Version 6.1...

ibm.com/redbooks

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

Alex Louwe KooijmansYukari Hanya

Keith JabcugaMarc van der Meer

Eran YonaGabriel Mogos

Foulques de Valence

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

Front cover

http://www.redbooks.ibm.com/


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

December 2007

International Technical Support Organization

SG24-7384-00

© Copyright International Business Machines Corporation 2007. All rights reserved.Note to U.S. Government Users Restricted Rights -- Use, duplication or disclosure restricted by GSA ADPSchedule Contract with IBM Corp.

First Edition (December 2007)

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

Note: Before using this information and the product it supports, read the information in “Notices” on page xi.

Contents

Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiTrademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiiiThe team that wrote this book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiiiBecome a published author . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviComments welcome. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvi

Chapter 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.1 Securing WAS for z/OS simplified. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21.2 WAS and security layers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

1.2.1 Security terms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.2.2 Security layering overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41.2.3 z/OS security overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61.2.4 Java security overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91.2.5 WebSphere security overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

1.3 Securing WAS and applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121.3.1 WAS and security checkpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121.3.2 Web client authentication overview. . . . . . . . . . . . . . . . . . . . . . . . . . 151.3.3 EJB client authentication overview . . . . . . . . . . . . . . . . . . . . . . . . . . 181.3.4 MQ client authentication overview . . . . . . . . . . . . . . . . . . . . . . . . . . 191.3.5 Web services security overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201.3.6 Backend connectivity security overview . . . . . . . . . . . . . . . . . . . . . . 221.3.7 User registry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241.3.8 Authorization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Chapter 2. WebSphere security design . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272.1 Chapter objectives. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282.2 Network protocol architecture overview . . . . . . . . . . . . . . . . . . . . . . . . . . 292.3 SSL overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

2.3.1 SSL handshake. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302.4 Authorization and EJB roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332.5 Our scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

2.5.1 Scenario 1 - authentication in HTTP server . . . . . . . . . . . . . . . . . . . 342.5.2 Scenario 2 - authentication in reverse proxy security server . . . . . . 372.5.3 Scenario 3 - J2EE client authentication using CSIv2 . . . . . . . . . . . . 402.5.4 Scenario 4 - J2EE server authentication using CSIv2 . . . . . . . . . . . 432.5.5 Scenario 5 - JCA custom principal mapping . . . . . . . . . . . . . . . . . . . 462.5.6 Scenario 6 - Web services authentication. . . . . . . . . . . . . . . . . . . . . 51

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

2.5.7 Scenario 7 - WMQ client authentication . . . . . . . . . . . . . . . . . . . . . . 532.5.8 Scenario 8 - authorization using external authorization server . . . . . 562.5.9 Scenario 9 - bridged security between z/OS and distributed using JAAS

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

Chapter 3. Web container security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 633.1 Web authentication improvements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

3.1.1 Separate Web authentication and authorization . . . . . . . . . . . . . . . . 643.1.2 Web authentication enhanced control . . . . . . . . . . . . . . . . . . . . . . . . 64

3.2 Implementation with the admin console . . . . . . . . . . . . . . . . . . . . . . . . . . 653.2.1 General settings at the cell level . . . . . . . . . . . . . . . . . . . . . . . . . . . . 653.2.2 Control server level Web authentication behavior. . . . . . . . . . . . . . . 67

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

Chapter 4. Application security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 714.1 Administrative security enablement. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 724.2 Application security enablement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

Chapter 5. Web services security introduction . . . . . . . . . . . . . . . . . . . . . 755.1 SOA, Web services, z/OS, and security . . . . . . . . . . . . . . . . . . . . . . . . . . 765.2 Web services security exposures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 775.3 Web services message and transport security . . . . . . . . . . . . . . . . . . . . . 78

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

5.4 Web services message layer security with WS-Security. . . . . . . . . . . . . . 815.4.1 End-to-end security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 815.4.2 WS-Security standard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 825.4.3 WS-Security support in WebSphere . . . . . . . . . . . . . . . . . . . . . . . . . 835.4.4 WS-I basic security profile support . . . . . . . . . . . . . . . . . . . . . . . . . . 845.4.5 WS-Security high-level architecture . . . . . . . . . . . . . . . . . . . . . . . . . 855.4.6 Message authentication, integrity, confidentiality, ID assertion. . . . . 86

5.5 Web services transport layer security . . . . . . . . . . . . . . . . . . . . . . . . . . . . 905.5.1 Web services transports introduction . . . . . . . . . . . . . . . . . . . . . . . . 905.5.2 Point-to-point security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 935.5.3 The HTTP(S) transport protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . 935.5.4 JMS transport security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 975.5.5 RMI-IIOP security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 985.5.6 Enterprise Service Bus security . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

5.6 Our SecurityInfo Web service application and environment . . . . . . . . . . . 985.6.1 SecurityInfo J2EE architecture in our environment . . . . . . . . . . . . . . 995.6.2 Our test environment. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1005.6.3 SecurityInfo Web service implementation . . . . . . . . . . . . . . . . . . . . 1005.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 . . . . . . . . . . . . . . . . . . 1076.1 How to configure Web services message layer security . . . . . . . . . . . . . 108

6.1.1 Web services message layer security and WS-Security . . . . . . . . . 1086.1.2 Web services message layer security configuration tools. . . . . . . . 1096.1.3 Web services message layer security configuration files . . . . . . . . 1106.1.4 Web services message-layer security configuration components . 114

6.2 Authentication with a security token . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1156.2.1 Authentication support with WS-Security . . . . . . . . . . . . . . . . . . . . 1166.2.2 Authentication scenario description . . . . . . . . . . . . . . . . . . . . . . . . 1176.2.3 Authentication configuration overview. . . . . . . . . . . . . . . . . . . . . . . 1186.2.4 Configuring the Web service requestor for security token . . . . . . . 1196.2.5 Configuring the z/OS Web service provider for security token . . . . 1236.2.6 Validating authentication with a security token . . . . . . . . . . . . . . . . 129

6.3 Integrity with XML digital signature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1316.3.1 Integrity support with WS-Security . . . . . . . . . . . . . . . . . . . . . . . . . 1316.3.2 Integrity scenario description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1326.3.3 Integrity configuration overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . 1336.3.4 Configuring the requestor for request XML digital signature. . . . . . 1356.3.5 Configuring the z/OS provider for request XML digital signature . . 1466.3.6 Configuring the z/OS provider for response XML digital signature . 1546.3.7 Configuring the requestor for response XML digital signature . . . . 1596.3.8 Validating integrity with XML digital signature. . . . . . . . . . . . . . . . . 159

6.4 Confidentiality with XML encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1646.4.1 Confidentiality support with WS-Security . . . . . . . . . . . . . . . . . . . . 1656.4.2 Confidentiality scenario description. . . . . . . . . . . . . . . . . . . . . . . . . 1656.4.3 Confidentiality scenario key prerequisites. . . . . . . . . . . . . . . . . . . . 1676.4.4 Confidentiality configuration overview. . . . . . . . . . . . . . . . . . . . . . . 1716.4.5 Configuring the requestor for request XML encryption . . . . . . . . . . 1726.4.6 Configuring the z/OS provider for request XML encryption. . . . . . . 1786.4.7 Configuring the z/OS provider for response XML encryption . . . . . 1836.4.8 Configuring the z/OS requestor for response XML encryption . . . . 1856.4.9 Validating confidentiality with XML encryption . . . . . . . . . . . . . . . . 1886.4.10 Confidentiality using hardware cryptography . . . . . . . . . . . . . . . . 192

6.5 Identity assertion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1926.5.1 Identity assertion support with WS-Security . . . . . . . . . . . . . . . . . . 1936.5.2 Identity assertion scenario description . . . . . . . . . . . . . . . . . . . . . . 1946.5.3 Identity assertion configuration overview . . . . . . . . . . . . . . . . . . . . 1956.5.4 Configuring the Web service requestor for identity assertion . . . . . 1966.5.5 Configuring the z/OS Web service provider for identity assertion. . 1996.5.6 Configuring the trust relationship for identity assertion . . . . . . . . . . 2036.5.7 Validating identity assertion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204

Contents v

Chapter 7. Secure Sockets Layer (SSL) . . . . . . . . . . . . . . . . . . . . . . . . . . 2097.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2107.2 Centrally managed SSL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2107.3 WebSphere V6.1 for z/OS SSSL to JSSE changes . . . . . . . . . . . . . . . . 2137.4 SSL RACF certificate management . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214

7.4.1 Viewing certificates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2157.4.2 Monitoring certificate expiration . . . . . . . . . . . . . . . . . . . . . . . . . . . 2187.4.3 Importing certificates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2207.4.4 Exporting certificates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2207.4.5 Deleting certificates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2217.4.6 Deleting keystores and truststores . . . . . . . . . . . . . . . . . . . . . . . . . 222

7.5 Hardware crypto and Java crypto providers . . . . . . . . . . . . . . . . . . . . . . 2227.5.1 Choosing a JCE provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2237.5.2 Admin console keystore types . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2247.5.3 Keystores and truststores . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226

7.6 IBMJCECCA and IBMJCE characteristics . . . . . . . . . . . . . . . . . . . . . . . 2277.7 SSL and JCERACFKS keystore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229

7.7.1 Keyring and certificate setup. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2297.7.2 WebSphere admin console setup . . . . . . . . . . . . . . . . . . . . . . . . . . 230

7.8 Hardware crypto using a JCECCARACFKS keystore. . . . . . . . . . . . . . . 2337.8.1 Keyring and certificate setup with keys in hardware . . . . . . . . . . . . 2347.8.2 Installing the unrestricted Java policy jars. . . . . . . . . . . . . . . . . . . . 2367.8.3 Update the java.security file with the IBMJCECCA provider . . . . . . 2367.8.4 Admin console setup. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237

7.9 SSL troubleshooting and traces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2397.9.1 Diagnostic steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2407.9.2 SSL traces. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2417.9.3 Common errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242

Chapter 8. Web services transport security . . . . . . . . . . . . . . . . . . . . . . . 2458.1 Authentication with HTTP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246

8.1.1 HTTP basic authentication scenario description . . . . . . . . . . . . . . . 2468.1.2 Configuring the z/OS Web service provider with authentication . . . 2478.1.3 Configuring the Web service requestor to authenticate . . . . . . . . . 2498.1.4 Validating transport security using HTTP basic authentication . . . . 250

8.2 Integrity with SSL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2528.2.1 Integrity with SSL scenario description . . . . . . . . . . . . . . . . . . . . . . 2528.2.2 Integrity scenario prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2538.2.3 Configuring the z/OS Web service provider SSL configuration. . . . 2558.2.4 Configuring the Web service requestor SSL configuration . . . . . . . 2618.2.5 Configuring the z/OS Web service provider for integrity . . . . . . . . . 2648.2.6 Configuring the Web service requestor for integrity . . . . . . . . . . . . 2648.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. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2688.3.1 Confidentiality with SSL scenario description . . . . . . . . . . . . . . . . . 2688.3.2 Configuring the z/OS Web service provider SSL configuration. . . . 2698.3.3 Configuring the Web service requestor SSL configuration . . . . . . . 2698.3.4 Configuring the z/OS Web service provider for confidentiality . . . . 2698.3.5 Configuring the Web service requestor for confidentiality . . . . . . . . 2698.3.6 Validating confidentiality with SSL . . . . . . . . . . . . . . . . . . . . . . . . . 271

8.4 Confidentiality with SSL using hardware crypto . . . . . . . . . . . . . . . . . . . 2728.4.1 Confidentiality with SSL using hardware crypto prerequisites . . . . 2728.4.2 Installing the unrestricted Java policy jars. . . . . . . . . . . . . . . . . . . . 2758.4.3 Updating the JVM to use the IBMJCECCA provider . . . . . . . . . . . . 2758.4.4 Configuring the z/OS Web service provider SSL configuration. . . . 2768.4.5 Configuring the Web service requestor SSL configuration . . . . . . . 2808.4.6 Configuring the z/OS Web service provider for confidentiality . . . . 2818.4.7 Configuring the Web service requestor for confidentiality . . . . . . . . 2818.4.8 Validating confidentiality with SSL using hardware crypto . . . . . . . 281

8.5 Confidentiality and basic authentication . . . . . . . . . . . . . . . . . . . . . . . . . 2828.6 Confidentiality and client certificate authentication . . . . . . . . . . . . . . . . . 282

8.6.1 Confidentiality and client certificate scenario description . . . . . . . . 2838.6.2 Confidentiality and client certificate prerequisites . . . . . . . . . . . . . . 2838.6.3 Configuring the z/OS Web service provider SSL configuration. . . . 2878.6.4 Configuring the Web service requestor SSL configuration . . . . . . . 2888.6.5 Configuring z/OS Web service provider for authentication . . . . . . . 2898.6.6 Validating client certificate authentication . . . . . . . . . . . . . . . . . . . . 291

Chapter 9. Security attribute propagation and CSIv2 . . . . . . . . . . . . . . . 2939.1 Introduction, logins, and tokens. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294

9.1.1 Security attribute propagation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2949.1.2 Initial login versus propagation login . . . . . . . . . . . . . . . . . . . . . . . . 2959.1.3 Token framework . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297

9.2 Horizontal attribute propagation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2989.2.1 Horizontal attribute propagation description . . . . . . . . . . . . . . . . . . 2989.2.2 Horizontal attribute propagation in action . . . . . . . . . . . . . . . . . . . . 3009.2.3 Horizontal attribute propagation implementation. . . . . . . . . . . . . . . 3019.2.4 Cross-cell considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302

9.3 CSIv2 standard identity assertion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3059.3.1 CSIv2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3059.3.2 CSIv2 standard identity assertion description . . . . . . . . . . . . . . . . . 3079.3.3 CSIv2 standard identity assertion in action . . . . . . . . . . . . . . . . . . . 3099.3.4 CSIv2 standard identity assertion implementation . . . . . . . . . . . . . 3109.3.5 Our CSIv2 identity assertion scenario. . . . . . . . . . . . . . . . . . . . . . . 321

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

Contents vii

9.4.2 Vertical attribute propagation versus CSIv2 identity assertion . . . . 3299.4.3 Vertical attribute propagation with CSIv2 in action . . . . . . . . . . . . . 3309.4.4 Vertical attribute propagation with CSIv2 implementation. . . . . . . . 3319.4.5 Cross-cell considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334

Chapter 10. User registries. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33510.1 Introduction to user registries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33610.2 Our scenario and our environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33910.3 Standalone LDAP registry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340

10.3.1 WebSphere and z/OS LDAP SDBM back end (RACF). . . . . . . . . 34110.3.2 WebSphere and z/OS LDAP TDBM back end (DB2) . . . . . . . . . . 35010.3.3 WebSphere and z/OS LDAP TDBM native authentication . . . . . . 359

10.4 Federated repositories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36310.4.1 What federated repositories are . . . . . . . . . . . . . . . . . . . . . . . . . . 36310.4.2 Our federated repositories scenario . . . . . . . . . . . . . . . . . . . . . . . 36610.4.3 Federated z/OS LDAP with TDBM back end (DB2) . . . . . . . . . . . 36810.4.4 Federated z/OS LDAP TDBM native authentication . . . . . . . . . . . 37310.4.5 Federated IBM Tivoli Directory Server . . . . . . . . . . . . . . . . . . . . . 375

10.5 z/OS local operating system registry. . . . . . . . . . . . . . . . . . . . . . . . . . . 38210.5.1 System Authorization Facility (SAF) authorization . . . . . . . . . . . . 38310.5.2 OS thread security support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38610.5.3 Thread identity support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389

Chapter 11. SPNEGO and Windows single sign-on . . . . . . . . . . . . . . . . . 39111.1 Introducing the SPNEGO TAI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392

11.1.1 An introduction to Kerberos. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39211.1.2 An introduction to trust association interceptor (TAI) . . . . . . . . . . 39511.1.3 An introduction to SPNEGO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39611.1.4 The WebSphere SPNEGO TAI . . . . . . . . . . . . . . . . . . . . . . . . . . . 396

11.2 Designing single sign-on with Microsoft Windows domain . . . . . . . . . . 39711.2.1 Single sign-on with Microsoft Windows KDC only. . . . . . . . . . . . . 39711.2.2 Single sign-on with z/OS KDC and Microsoft Windows KDC . . . . 399

11.3 Implementing single sign-on using SPNEGO TAI . . . . . . . . . . . . . . . . . 40011.3.1 Our environment and our scenario . . . . . . . . . . . . . . . . . . . . . . . . 40111.3.2 Configuring the Microsoft Windows server . . . . . . . . . . . . . . . . . . 40411.3.3 Configuring WebSphere Application Server for z/OS . . . . . . . . . . 41211.3.4 Configuring the Web browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41911.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. . . . . . . . . . . . . . . . . . . . . . . . . . . 42912.1 Out-of-the-box administrative security. . . . . . . . . . . . . . . . . . . . . . . . . . 430

12.1.1 Cell-wide common user groups and IDs . . . . . . . . . . . . . . . . . . . . 43012.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. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43812.1.4 Comparison of security settings . . . . . . . . . . . . . . . . . . . . . . . . . . 440

12.2 Automatically generated server IDs . . . . . . . . . . . . . . . . . . . . . . . . . . . 44112.3 RACF - mixed-case password support . . . . . . . . . . . . . . . . . . . . . . . . . 44312.4 Sync-to-OS thread update. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 444

Chapter 13. WAS administrative security . . . . . . . . . . . . . . . . . . . . . . . . . 44713.1 Security configuration and administration . . . . . . . . . . . . . . . . . . . . . . . 448

13.1.1 Simplified security administration . . . . . . . . . . . . . . . . . . . . . . . . . 44813.1.2 Administrative security implementation. . . . . . . . . . . . . . . . . . . . . 44913.1.3 Administrative security with SAF authorization . . . . . . . . . . . . . . . 45013.1.4 Administrative security with default authorization provider . . . . . . 455

13.2 Role-based administrative security . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46013.2.1 Administrative roles. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46013.2.2 Fine-grained administrative security . . . . . . . . . . . . . . . . . . . . . . . 462

13.3 Naming service security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46713.3.1 CosNaming roles description . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46713.3.2 Mapping users or groups to CosNaming roles . . . . . . . . . . . . . . . 468

Appendix A. Additional material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 471Locating the Web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 471Using the Web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 472

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

Related publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 473IBM Redbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 473Other publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 474Online resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 474How to get IBM Redbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 475Help 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

TrademarksThe following terms are trademarks of the International Business Machines Corporation in the United States, other countries, or both:

Redbooks (logo) ®developerWorks®eServer™iSeries®z/OS®zSeries®CICS®Domino®

DB2®IBM®IMS™Lotus®MQSeries®MVS™Rational®Redbooks®

RACF®RMF™System z™Tivoli®VTAM®WebSphere®

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 bookThis 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 BariRich ConwayFranck InjeyAl SchwabInternational Technical Support Organization, Poughkeepsie Center

Tom HackettIBM System z, Poughkeepsie, NY

Tim HefeleWebSphere z/OS Performance

Preface xv

Ut V. Le WebSphere Security Development, Austin, TX

Bill O’DonnellWebSphere Security Development, Madison, WI

Gary PuchkoffWebSphere Application Server for z/OS Design and Development

Ben Rogers IBM STG System z Lab Services, Poughkeepsie, NY

Wade WallaceInternational Technical Support Organization, Austin Center

Nigel WilliamsIBM Montpellier

Become a published authorJoin 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 welcomeYour 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

http://www.redbooks.ibm.com/residencies.html

http://www.redbooks.ibm.com/residencies.html



� Send your comments in an e-mail to:

System Authorization [email protected]

� Mail your comments to:

IBM Corporation, International Technical Support OrganizationDept. HYTD Mail Station P0992455 South RoadPoughkeepsie, NY 12601-5400

Preface xvii

http://www.redbooks.ibm.com/contacts.html

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

Chapter 1. Introduction

Because of the rapid growth of e-business and the integration of different organizations, securing and managing information technology (IT) infrastructures has become very complex and demanding. Protecting sensitive and confidential data from malicious intruders, deadly viruses, and worms is not an easy task. It requires constant monitoring of the daily IT business operations and deploying the latest security technology.

WAS for z/OS security and the underlying operating system infrastructure security can provide customers running enterprise applications with secure and reliable services.

In this chapter, we introduce new and upgraded security features that are implemented in WebSphere Application Server WAS for z/OS V6.1 to secure WAS and e-business applications.

This chapter contains the following sections:

� “Securing WAS for z/OS simplified” on page 2� “WAS and security layers” on page 3� “Securing WAS and applications” on page 12

1

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

1.1 Securing WAS for z/OS simplified

Securing an e-business application on the z/OS platform demands good knowledge of the underlying infrastructure and the areas that could be exposed to security attacks. It requires periodic review of the security system put in place to protect the network resources (files, databases, user accounts, and so on) and you to take the necessary action to improve the overall system operations.

Needless to say, it is very tough out there. The competition has never been more intense than today. To survive in this highly competitive global market, companies must be innovative and come up with new ways of doing things within a short period of time. If they do not, they become obsolete and fade away.

The product life cycle has now been shortened. To beat the competition, companies must invent, re-invent, and upgrade their products every six months to a year in order to stay in business and be successful.

As IBM strategic middleware, WebSphere Application Server has been going through many changes, starting from Lotus® Go Domino® Webserver V4.6.1 in the late 1990s to what we have now (WebSphere Application Server for z/OS Version 6.1). In each version milestone achievements have been made, and like the previous versions, Version 6.1 has made great enhancements in securing WAS and the applications running in WAS. These enhancements are in the areas of ease of use, manageability, interoperablity, and compatibility.

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

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

� RACF® enhancements such as mixed password support and sync to OS thread control.

� Simplified key and certificate management.

� New user registry - federated repository.

� Web authentication enhancements.

� Interoperability support - protected GSS-API Negotiation Mechanism Protocol support.

� Web services security - messaging and transport security.

� JCA 1.5 connectivity to back-end applications support.

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

� Securing applications - identity assertion with trust validation.

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

Note that these new and enhanced v6.1 security features have been made available to the public in the WebSphere Application Server for z/OS InfoCenter. In addition, these features are described in detail in this book in later chapters.

1.2 WAS and security layers

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.

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.

Platform Security

Java Security

WebSphere Security

WebSphere/Application Resources

Operating System Security

JVM 5 Security

Java 2 Security

CORBA Security / CSIv2

J2EE Security API

WebSphere Security

HTML,Servlet/JSPs,

EJBs

Naming,Admin

Access Control


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

Figure 1-2 RACF profile

User ID Owner Attributes SecurityClassifications

Groups Segments

OMVS TCP/IP TSO

Password


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 GROUPGroups 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 CLASSThis 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 rolesThese 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 securityJava 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.


J2EE securityThe 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

Attention: Java 2 security is very CPU consuming and therefore not recommended for a production environment.


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.

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.

J2EEClient

EJB Container

J2CWebServer

CICSWebClient

WebContainer

1

23

45

1

23

0

0


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.

� Trust Association Interceptor (TAI)

The Web authentication options are:

� Basic� Form based� Client certificate

Single sign-onSingle 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 propagationWith 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.

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


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 assertionIdentity 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:

http://www-128.ibm.com/developerworks/websphere/techjournal/0601_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.


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

http://www.redbooks.ibm.com/abstracts/redp4203.html?Open

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)

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

Socket

Mac address

IP address

HTTP

LINK

IP

TCP

SOAP

JMS

SSL

IP address

Mac address

SocketPort

SSL

JMSHTTP

SOAP

Requestor Service Provider

Transport level security (TLS/SSL)

Message Level Security




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 componentsJ2C 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 supportEach 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 supportIMS 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.



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


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.

Figure 2-1 Protocol layering

Socket

Mac address

IP address

HTTP

LINK

IP

TCP

IIOP

SOAP

MSG

SSL

Mac address

IP address IP address

Mac address

SocketPort

SSL

IIOPMSGHTTP

SOAP

IP address

Mac address

`

Client/Requester Server/Service Provider

Router Router

SSL (Integrity,Confidentiality)

Authentication

WS – Security ( Authentication)

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.

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.

Client/Requester

Server/Service Provider

1. Client Hello

2. Server Hello3. Server certificate4. Certificate Request5. Certificate done

6. Client certificate 7. Client key exchange8. Certificate verify9. Change cipher spec

10. Finished

11. Change cipher spec12. Finished


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.

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

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

RACF

WebSphere Application Server

HTTP Server

CICSIMS

HTTP(s)

z/OS

Authentication Authorization DB2

Web Client

SSO


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.

We would like to inform the reader that data integrity and confidentiality is implied by the fact that the connection is over SSL.

Important: Note that form-based authentication is not possible for this configuration.


Logical flowThe 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.

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.

ClientHTTPServer

WAS(sso, TAI) RACF

12

3

4

5

6

7


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.

ReferencesRefer to:

� IBM HTTP Server Web site at:

http://www-306.ibm.com/software/webservers/httpservers/doc/v51/icswg003.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.



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

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.

RACF

WebSphereApplication

ServerWeb

ServerHTTP(s)

z/OS

Authentication

Authorization

RPSS

LDAP

HTTP(s)

Authentication

CICSIMS

SSO

DB2

Web client

Native

RPSS = Reverse Proxy Security Server


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

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.

Client RPSS LDAPWeb

ServerWAS

(sso, TAI) RACF1

23

4

5

6

7

8

910


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 tasksHere we provide the 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:

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

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


DescriptionFigure 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).

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

RACF


ServerCICSIMS

RMI/IIOP

z/OS

Authorization

DB2CSIv2

J2EEClient

Authentication


Figure 2-8 shows a flow of a J2EE client accessing WAS on z/OS and the events that take place at each step.

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.

J2EE Client WAS RACF1

2

3

4


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.

ReferencesRefer to:

� IBM Redbooks Technote: Configuration of WebSphere Application Server Security, TIPS0206, at:

http://www.System Authorization 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&maxHits=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.


http://www.redbooks.ibm.com/abstracts/TIPS0206.html?Open


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

Figure 2-9 Scenario 4 - J2EE server authentication using CSIv2

The Common Secure Interoperability Version 2 protocol is designed to exchange its protocol elements in the service context of General Inter-ORB Protocol (GIOP) request and reply messages that are communicated over a connection-based transport. The protocol is intended for use in environments where transport layer security, such as that available through Secure Sockets Layer (SSL) and Transport Layer Security (TLS), is used for providing message protection (that is, integrity and or confidentiality) and server-to-client authentication. The protocol provides client authentication, delegation, and privilege functionality that might be applied to overcome security deficiencies in an underlying transport.

CSIv2 authentication protocols used by WebSphere Application Server are add-on Interoperable Inter-ORB Protocol (IIOP) services. IIOP is a request-and-reply communications protocol used to send messages between two object request brokers (ORBs).

For each request made by a client ORB to a server ORB, an associated reply is made by the server ORB back to the client ORB. Prior to any request flowing, a connection between the client ORB and the server ORB must be established over secured TCP/IP transport (SSL is a secure version of TCP/IP).

An identity assertion is a way for one server to trust another server without the need to re-authenticate or re-validate the originating client. In this case, WAS for

RACF

WebSphereApplication Server

z/OS

Authentication

Authorization

J2EEServer

LDAP

CSIv2

Authentication

CICSIMS

DB2

Client RMI/IIOP

Native

Identity assertion


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

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.

Client

J2EEServer RACF

1

23

6

z/OSWAS

45

7

8

LDAP

910


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 Here we provide the 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 the client to RACF.� Define EJBROLES in RACF to enable application authorization.� Enable CSIv2 (inbound/outbound) via the admin console on z/OS.� Enable identity assertion via the WebSphere administrative console on z/OS.

ReferencesRefer to:

� IBM Redbooks Technote: Configuration of WebSphere Application Server Security, TIPS0206, at:

http://www.System Authorization Facilitys.ibm.com/abstracts/TIPS0206.html?Open

� IBM Education Assistant at:


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



http://www.redbooks.ibm.com/abstracts/TIPS0206.html?Open

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.

DescriptionFigure 2-11 to shows J2C custom principal mapping.

Figure 2-11 Scenario 5 - JCA custom principal mapping authentication

TAMWebSEAL

LDAPTAMPolicyServer

z/OS z/OS

CTG CICSsso

RACF

Authentication

Authentication

Web Client

SAF user ID / password

WebSphere Application Server

Authorization

JCAMappingModule


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

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

Client TAMWebSeal LDAP

WAS(sso, TAI) CTG

J2CPrincipal Mapping Module

TAM Policy server CICS RACF

12

34

5

6

7

89

10

11 12

1314

1516


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 tasksTo 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

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

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.

LDAP

WebSphere Application

Server

HTTP(s)

z/OS

Authentication

WAS Distributed

Authentication

SOAP/HTTPWeb Client

Web ServiceID assertion


Logical flowThe 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.

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

Client

WASDistributed RA

1

23

6

z/OSWAS

45

78

LDAP


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


DescriptionThe configuration described below (Figure 2-15) focuses on security-related issues regarding messages that trigger a message-driven bean (MDB).

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

RACF


Server

CICSIMS

Authentication

MQClient

Message

Authorization

z/OS

MDB = Message Driven BeanEJB = Enterprise JavaBean

Authorization

MDB EJB


permits should reflect the identities related to the work being done after a message has been processed by an MDB.

Logical flowBy 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.

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.

WMQ Client MDB RACF

1

2

3

6

EJB

45

7

8

CICS

9

Application Server

1


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.

ReferenceRefer 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:


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.

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

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

AuthorizationServer


ServerWeb

ServerHTTP(s)

z/OS

AuthenticationAuthorization with

JACC

RPSS

LDAP

HTTP(s)

Web Client

RPSS = Reverse Proxy Security Server

HTTP(s)

User Registry

SSO


ReferencesRefer to:

� IBM WebSphere Application Server V6.1 Security Handbook, SG24-6316� WebSphere Application Server on z/OS and Security Integration, REDP-4161

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.


DescriptionBridging, 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.

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.

RACF


ServerCICSIMSAuthentication

Authorization

DB2WASDistributed

LDAP

Client

CSIv2

RMI/IIOP

JAASLogin

Module

Authentication

Authorization

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.

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

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.

z/OSLDAP

WebSphere Application

ServerWeb

ServerHTTP(s)

z/OS

WAS distributed

Authentication

Authorization

RACF

HTTP(s)

Web Client

Web Client

SDBM

Authentication


ReferencesTo learn more about LDAP and RACF integration on z/OS, refer to:

� Understanding LDAP - Design and Implementation, SG24-4986

� Implementation and Practical Use of LDAP on the IBM eServer iSeries Server, SG24-6193

� Using LDAP for Directory Integration, SG24-6163


Chapter 3. Web container security

The Web container processes servlets, JSPs, and other types of server-side includes. Requests are sent by the Web client. Web clients use the HTTP or HTTPS protocol to send the authentication information. Web authentication is required for Web clients when they access protected resources and is performed by the Web authentication module.

In WAS V6.1, Web container security is improved. We introduce the Web authentication improvements in this chapter:

� “Web authentication improvements” on page 64� “Implementation with the admin console” on page 65� “Why you should use these options” on page 69

3


3.1 Web authentication improvements

An authentication mechanism defines rules about security information, for example, whether a credential is forwardable to another process, and the format security information is stored in.

In V6.1, the Web authentication mechanism is improved. We introduce the following Web authentication improvements in this chapter:

� Separate Web authentication and authorization, discussed in “Separate Web authentication and authorization” on page 64

� Enhanced control over Web authentication behavior, discussed in “Web authentication enhanced control” on page 64

3.1.1 Separate Web authentication and authorization

In WebSphere Application Server V6.1, Web authentication and authorization are separated.

Before supporting this new function, in order for a request to be authenticated, it had to be a Uniform Resource Identifier (URI) requiring authorization, too.

Now, Web authentication can be performed with or without Web authorization, and the Web client’s authenticated identity is available whether or not Web authorization is required. An authenticated identity is persisted both for protected and unprotected resources. Without the separation of Web authentication and Web authorization, a Web authenticated identity is not available when Web authorization is not required, and programmatic security cannot work independently without container declarative security.

3.1.2 Web authentication enhanced control

WebSphere Application Server provides enhanced control over the authentication behavior of a Web client.

Depending upon the option that you select, WebSphere Application Server can retain the authentication data for future use. This adds flexibility to the handling of authentication for Web applications:

� To allow failed certificate authentication to fall back to basic authentication (user ID/password challenge).

� To allow the retention of an authenticated identity and make it available to Web applications running under an unprotected URI. Without this capability,


such Web applications would not be able to use getRemoteUser(), isUserInRole(), or getUserPrincipal().

3.2 Implementation with the admin console

You can configure the Web authentication behavior with the WebSphere administrative console.

3.2.1 General settings at the cell level

Through the following setting, Web authentication behavior is controlled. This setting affects the entire cell. Remember that it affects all applications deployed to the cell.

In order to set up the Web authentication behavior:

1. Click Security → Secure administration and applications.2. Under Authentication, select Web security → General settings (Figure 3-1).

Figure 3-1 Web security settings in WebSphere admin console

The following options exist to change the behavior of Web authentication when accessing a URI:

� Authenticate only when the URI is protected.

This is a default option, and is the same as in the previous version of WebSphere. The Web client can retrieve an authenticated identity only when it accesses a protected URI. WebSphere Application Server challenges the

Chapter 3. Web container security 65

Web client to provide authentication data when the Web client accesses a URI that is protected by a J2EE role.

� Authenticate when any URI is accessed.

The Web client must provide authentication data regardless of whether the URI is protected.

Figure 3-2 URI access authentication behavior

The following options are available for Web authentication enhanced control:

� Use available authentication data when an unprotected URI is accessed.

The Web client is authorized to call the getRemoteUser, isUserInRole, and getUserPrincipal methods. It retrieves an authenticated identity from either a protected or an unprotected URI. Although the authentication data is not used when you access an unprotected URI, the authentication data is retained for future use. This option is available when you select the “Authenticate only when the URI is protected” check box.

� Default to basic authentication when certificate authentication for the HTTPS client fails.

The WebSphere Application Server challenges the Web client for a user ID and password when the required HTTPS client certificate authentication fails.


Figure 3-3 Web authentication enhanced control

3.2.2 Control server level Web authentication behavior

The settings introduced in 3.2.1, “General settings at the cell level” on page 65 control Web authentication behavior on the cell level. If you wish to control it on the server level, you can specify the system properties given in Table 3-1.

Table 3-1 Web authentication system property values

Property name Value Description

com.ibm.wsspi.security.web.webAuthReq

lazy equiv.Authenticate only when the URI is protected option


persisting equiv.Use available authentication data when an unprotected URI is accessed option


always equiv.Authenticate when any URI is accessed option


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

com.ibm.wsspi.security.web.failOverToBasicAuth

true equiv.Default to basic authentication when certificate authentication for the HTTPS client fails option

Property name Value Description


Figure 3-5 shows that a new property has been added.

Figure 3-5 Example of server level control for Web security

You can override the general settings of Web security by specifying a system property on the server level.

3.3 Why you should use these options

The following are good reasons to use the options discussed:

� As an alternative to using a role with all authenticated.All authenticated specifies whether to map all of the authenticated users to a specified role. When you map all authenticated users to a specified role, all of the valid users in the current registry who have been authenticated can access resources that are protected by this role.

� Do your own authorization with no role.

� Use SAF EJBROLEs.



Chapter 4. Application security

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


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.

Application security can be enabled or disabled in the administrative console by following the path Security → Secure administration, applications, and infrastructure.

Attention: Administrative security must be enabled in order to enable application security.

Chapter 4. Application security 73

Figure 4-1 illustrates the application security enablement check box in the administrative console.

Figure 4-1 Enabling application security


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


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 WebSphere Application Server for z/OS.


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:

http://publib.boulder.ibm.com/infocenter/wasinfo/v6r1/index.jsp?topic=/com.ibm.websphere.zseries.doc/info/zseries/ae/cwbs_supportfunction.html

http://publib.boulder.ibm.com/infocenter/wasinfo/v6r1/index.jsp?topic=/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.

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


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

ConfidentialityConfidentiality 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 assertionIdentity 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 HTTPThe 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 JMSSOAP 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-RPCRemote 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 protocolHTTP(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 securityThe 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.

AuthenticationWeb 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 providerThe 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 requestorThe 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

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

Test environment

Web service requestor Web service provider

Windows XP (version 5.1 build 2600 Service Pack 2)

z/OS 1.8

WebSphere base server6.1.0.2 cf20633.22

WebSphere 6.1.0.2 base server

J2RE 1.5.0 IBM J9 2.3 Windows XP x86-32 j9vmwi3223-20060504

J2RE 1.5.0 IBM z/OS build pmz31devifx-20060727a


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 WindowsThe 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/SecurityInfo

Figure 5-9 Overridden endpoint UR


Deployment of SecurityInfo ear file on z/OSThe 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



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


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.

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

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.


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

CallbackHandlerThe 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 partOn 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 locatorThe 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 informationThe 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 anchorA 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.

NonceNonce 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 stampA 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 tokenA 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 tokenThe 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 tokenA 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 signatureUsing 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 sideTo 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 sideTo 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:

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.

Attention: Administrative security and application security have to both be enabled on the Web service provider side for Web service authentication to operate.


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 = ITSO3967ITSO SecurityCallerBean - Timestamp = Wed Nov 08 11:37:27 EST 2006ITSO SecurityCallerBean - Hostname = windowsbaxITSO SecurityCallerBean - ipaddress = 9.56.23.149ITSO SecurityCallerBean - Principal = UNAUTHENTICATEDITSO SecurityCallerBean - OSName = Windows XPITSO 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 2006ITSO 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.1Host: wtsc58.itso.ibm.com:49080Accept: application/soap+xml,multipart/related,text/*User-Agent: IBM WebServices/1.0Cache-Control: no-cachePragma: no-cacheSOAPAction: ""Connection: Keep-AliveContent-Type: text/xml; charset=utf-8Content-Length: 790Date: 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-wssecurity-secext-1.0.xsd"><wsse:UsernameToken><wsse:Username>WINSERV</wsse:Username><wsse:Password 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:obtainSecurityInfo></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:


6.3.2 Integrity 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 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 application. Hence, the principal of the client EJB is unauthenticated. This client 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.

On the Web service provider side (WebSphere for z/OS), the Web service 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 sideTo 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 sideTo 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.

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

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.

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.


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

Open the SecurityInfoEJB webservices.xml deployment descriptor. Select the Extensions tab. Expand the Request Consumer Service Configuration 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.

Select the Binding Configurations tab. Expand the Request 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 IntegrityTokene. 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).

Open the SecurityInfoEJB webservices.xml deployment descriptor. Select the 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.


Figure 6-28 Response generator Key locator dialog


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


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

The configuration for this section is similar to the configuration in 6.3.5, “Configuring the z/OS provider for request XML digital signature” on page 146.

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 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 service client side is unauthenticated.

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 - RequestID = ITSO3036ITSO SecurityCallerBean - Timestamp = Fri Nov 10 10:47:57 EST 2006ITSO SecurityCallerBean - Hostname = windowsbaxITSO SecurityCallerBean - ipaddress = 9.56.23.149ITSO SecurityCallerBean - Principal = UNAUTHENTICATEDITSO SecurityCallerBean - OSName = Windows XPITSO 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 unauthenticated, as shown in Example 6-5.


ITSO SecurityInfoBean - RequestID = ITSO3036 ITSO SecurityInfoBean - Timestamp = Fri Nov 10 15:48:04 GMT+00:00 2006ITSO SecurityInfoBean - Hostname = WTSC58 ITSO SecurityInfoBean - ipaddress = 9.12.4.8 ITSO SecurityInfoBean - Principal = UNAUTHENTICATED 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 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

POST /SecurityInfoRouterWS/services/SecurityInfo HTTP/1.1Host: wtsc58.itso.ibm.com:49080...Date: Fri, 10 Nov 2006 15:47:56 GMT<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" ...><soapenv:Header><wsse:Security soapenv:mustUnderstand="1"


xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"><wsse:BinarySecurityToken EncodingType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-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-wssecurity-utility-1.0.xsd">MIICEDCCAXmgAwIBAgIERU5DqzANBgkqhkiG9w0BAQUFADBucG9rLmlibS5jb20wHhcNMDYxMTA1.............8cUUF4aH9TANBgkqhkiG9w0BAQUFAAOBgQB7c1icR21nrqiYprRncUn23GivfBLyNNZtKIB+1BohOvrmVzJLS4BRd/AdZxTDLb1J4CESk2KpeuXsFK6D5WC8AFEzAmVEfBGHyvw==</wsse:BinarySecurityToken><ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#"><ds:SignedInfo><ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"><ec:InclusiveNamespaces PrefixList="xsi xsd soapenv soapenc wsse ds " xmlns:ec="http://www.w3.org/2001/10/xml-exc-c14n#"/></ds:CanonicalizationMethod><ds:SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/><ds:Reference URI="#wssecurity_signature_id_16"><ds:Transforms><ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"><ec:InclusiveNamespaces 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:SignedInfo><ds:SignatureValue>BmEw84oUOpYzgnh7b2uqDy1JEZQO4qPDNj1J2UYiFcCalDlI+85O3E4NnG391TqPoZ/76K/DY2XMxI65dnDeCdYxOluU0pXhSL53+Afri+Y+sJsMQkgVx0Zx4ALdXEgjE3WjWVTyiZMAYLOfvEAJw3NpO+xDLFLH0ugWvuOnBV4=</ds:SignatureValue><ds:KeyInfo><wsse:SecurityTokenReference><wsse:Reference URI="#x509bst_17" ValueType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509"/></wsse:SecurityTokenReference></ds:KeyInfo></ds:Signature></wsse:Security></soapenv:Header><soapenv:Body wsu:Id="wssecurity_signature_id_16" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"><p98:obtainSecurityInfo xmlns:p98="http://itso.ibm.com"><input>ITSO3036</input></p98:obtainSecurityInfo></soapenv:Body></soapenv:Envelope>

HTTP/1.1 200 OK...Content-Length: 3276Date: Fri, 10 Nov 2006 15:48:12 GMTServer: WebSphere Application Server/6.1


<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" ...><soapenv:Header><wsse:Security soapenv:mustUnderstand="1" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"><wsse:BinarySecurityToken EncodingType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-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_13" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">MIICADCCAWmgAwIBAgIERT6FVDANBgkqhkiG9w0BAQUFADA5MQswCQYDVQQGEwJVUzEMMAoGA1UE..............Hb62hxqB28S29uNKgiMatiySUfG58SFsyOTjnQk1UVtud8Y9JLjz7kI1LVTiM1EP6Y++XP+Pq2t8qSNWAN+nVnaE8A4X8EuGRDUb/DjAjh8LCAWY6Cs</wsse:BinarySecurityToken><ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#"><ds:SignedInfo><ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"><ec:InclusiveNamespaces PrefixList="xsi xsd soapenv soapenc wsse ds " xmlns:ec="http://www.w3.org/2001/10/xml-exc-c14n#"/></ds:CanonicalizationMethod><ds:SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/><ds:Reference URI="#wssecurity_signature_id_12"><ds:Transforms><ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"><ec:InclusiveNamespaces 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>A37Up9iFTwgagkadxBg4uk5wprQ=</ds:DigestValue></ds:Reference></ds:SignedInfo><ds:SignatureValue>pO+JYmFGdps3yutO6oUbqggknDagy+0pv1cb7C0SRhdw/jD5VrIxe+9Jp/xqZcNrz+yhuE05cCNwk/QznjHxvQ0L8YB4C88A/uG9k7M4Lnv+Dd0RD+MfFaxbPv3MQETlPBdV69frKEdz+SjJO5jxFhxb4OomHIFKoXQpMXKcVQQ=</ds:SignatureValue><ds:KeyInfo><wsse:SecurityTokenReference><wsse:Reference URI="#x509bst_13" ValueType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509"/></wsse:SecurityTokenReference></ds:KeyInfo></ds:Signature></wsse:Security></soapenv:Header><soapenv:Body wsu:Id="wssecurity_signature_id_12" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"><p98:obtainSecurityInfoResponse xmlns:p98="http://itso.ibm.com"><obtainSecurityInfoReturn><string>ITSO3036</string><string>Fri Nov 10 15:48:04 GMT+00:00 2006</string><string>WTSC58</string><string>9.12.4.8</string><string>UNAUTHENTICATED</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 algorithmThis 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

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 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 application. Hence, the principal of the client EJB is unauthenticated. This client 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.

On the Web service provider side (WebSphere for z/OS), the Web service 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 encryptionIn 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 encryptionIn 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 management → Key stores and certificates → NodeDefaultKeyStore → 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 sideTo 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 WS-Security configuration:

� 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 sideTo 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 WS-Security configuration:

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

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



Open the SecurityCallerEJB deployment descriptor. Select the WS Binding tab. Expand the Security Request Generator Binding 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 XML digital signature” on page 135.


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.

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.

Tip: The WebSphere default key store path can be found with the administrative console in Security → SSL certificate and key management → SSL configurations → NodeDefaultSSLSettings → Key stores and certificates → NodeDefaultKeyStore.

The personal key description can be found in Security → SSL certificate and key management → SSL configurations → NodeDefaultSSLSettings → Key stores and certificates → NodeDefaultKeyStore → Personal certificates.



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

Open the SecurityInfoEJB webservices.xml deployment descriptor. Select the Extensions tab. Expand the Request Consumer Service Configuration 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).

Select the Binding Configurations tab. Expand the Request Consumer 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.


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 XML digital signature” on page 135.

Tip: The WebSphere default trust store path can be found with the administrative console in Security → SSL certificate and key management → SSL configurations → NodeDefaultSSLSettings → Key stores and certificates → NodeDefaultTrustStore.

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.



a. Enter a name such as ConfidentialityKeyLocator.

b. Select KeyStoreKeyLocator as the class name. The class to retrieve a key implements the com.ibm.wsspi.wssecurity.keyinfo.KeyLocator interface.

c. Select Use key store and specify a client key store. We choose the WebSphere z/OS default key store.

d. Click Add under Key to define the key. Enter the provider key alias, a key password, and the provider key name. We choose the wtsc58 Alias.



Figure 6-47 Request consumer Key Information dialog

To specify a key information, refer to 6.3.4, “Configuring the requestor for request XML digital signature” on page 135.


a. Enter a name such as ConfidentialityKeyInfo.

b. Select a type (KEYID) from the Key information type list.


c. Select Use key locator, and then select the key locator and the key name you defined before.

5. Configure encryption information (Figure 6-48).

Expand Encryption Information, click Add, and specify how to encrypt.

Figure 6-48 Request consumer Encryption Information

To specify encryption information, refer to 6.4.5, “Configuring the requestor for request XML encryption” on page 172.

Configure the encryption information:

a. Enter a name such as ConfidentialityEncryptionInfo.

b. Select a data encryption method algorithm from the list. If no algorithm is selected, the encryption key is not encrypted.

c. Enter any key information name. This specifies the key information reference. We specify ConfidentialityKeyInfo.


d. Select a key information element from the list of the key information that was defined. The selected key information is used for encryption. In our case, we select ConfidentialityKeyInfo from the list.

e. Select a confidentiality part from the list of confidentiality parts that were defined in the extensions. In our case, we select ConfidentialityBody from the list.

f. Click OK and the encryption information is created. Save the configuration.

6.4.7 Configuring the z/OS provider for response XML encryption

The configuration for this section is similar to the configuration in 6.4.5, “Configuring the requestor for request XML encryption” on page 172. We only point out differences in this section.

1. Configure the confidentiality.

Open the SecurityInfoEJB webservices.xml deployment descriptor. Select the 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 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.



Open the SecurityInfoEJB webservices.xml deployment descriptor. Select the 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

Refer to 6.4.5, “Configuring the requestor for request XML encryption” on page 172 for details about this dialog configuration.




Figure 6-50 Response generator Key Information dialog

Refer to 6.4.5, “Configuring the requestor for request XML encryption” on page 172 for details about this dialog configuration.

4. Configure encryption information.

Expand Encryption Information and click Add and specify how to encrypt.

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.

6.4.8 Configuring the z/OS requestor for response XML encryption

The configuration for this section is similar to the configuration in 6.4.6, “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.


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 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 page 178, for details about this dialog configuration. The configuration of this 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

Refer to 6.4.6, “Configuring the z/OS provider for request XML encryption” on 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

Refer to 6.4.6, “Configuring the z/OS provider for request XML encryption” on page 178 for details about this dialog configuration.




Figure 6-53 Response consumer Key Information dialog

Refer to 6.4.6, “Configuring the z/OS provider for request XML encryption” on page 178, for details about this dialog configuration.

5. Configure encryption information.

Expand Encryption Information and click Add and specify how to encrypt.

Refer to 6.4.6, “Configuring the z/OS provider for request XML encryption” on page 178, for details about this dialog configuration. The configuration of this dialog is similar.

6.4.9 Validating confidentiality with XML encryption

We validate the confidentiality 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-54).

Figure 6-54 SecurityInfo application confidentiality display

The display shows that the user did not authenticate, as theprincipal on the Web service client side is unauthenticated.

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 - RequestID = ITSO2069ITSO SecurityCallerBean - Timestamp = Mon Nov 13 08:55:35 EST 2006ITSO SecurityCallerBean - Hostname = windowsbaxITSO SecurityCallerBean - ipaddress = 9.56.23.149ITSO SecurityCallerBean - Principal = UNAUTHENTICATEDITSO SecurityCallerBean - OSName = Windows XPITSO 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 unauthenticated, as shown in Example 6-8.


ITSO SecurityInfoBean - RequestID = ITSO2069 ITSO SecurityInfoBean - Timestamp = Mon Nov 13 13:55:47 GMT+00:00 2006ITSO SecurityInfoBean - Hostname = WTSC58 ITSO SecurityInfoBean - ipaddress = 9.12.4.8 ITSO SecurityInfoBean - Principal = UNAUTHENTICATED 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 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

POST /SecurityInfoRouterWS/services/SecurityInfo HTTP/1.1Host: wtsc58.itso.ibm.com:49080...SOAPAction: ""Connection: Keep-AliveContent-Type: text/xml; charset=utf-8Content-Length: 1657Date: Mon, 13 Nov 2006 13:55:34 GMT

<soapenv:Envelope ...><soapenv:Header><wsse:Security soapenv:mustUnderstand="1" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-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:SecurityTokenReference><wsse:KeyIdentifier ValueType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509SubjectKeyIdentifier">SnrZxQvN4uw=</wsse:KeyIdentifier></wsse:SecurityTokenReference></ds:KeyInfo><CipherData><CipherValue>YLx8JzXGihdnEFtk7NMKxrZ/jO5V2dZWOhXiEL0Y/c72Tf3nkoUmRz3r1xTuSW9fcvn6LKtKzAM0WNFEzIFpeoOVoUtMWoRNLUBLSI3SyUdBIaS6en6536M2CwFRbFCDDzekPQ6ynYmxpYxrQiIpkRIsbxMIw6O+66lG43y88rU=</CipherValue></CipherData><Reference


List><DataReference URI="#wssecurity_encryption_id_1"/></ReferenceList></EncryptedKey></wsse:Security></soapenv:Header><soapenv:Body><EncryptedData Id="wssecurity_encryption_id_1" Type="http://www.w3.org/2001/04/xmlenc#Content" xmlns="http://www.w3.org/2001/04/xmlenc#"><EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#tripledes-cbc"/><CipherData><CipherValue>Ngo63Q72UWG0r/Z3zvyFAVTTlAdTlw4+vtumTqZSgvzbLp8/V5pjE7PruX1MxUN+arMjxaC0afV7yP+9nKbNgagf+EB5yFVRCju3PzJXYpg6OBWHwfl/6WWwIpbNLVXN4ntU5dRSQ5+bC6o6lTQk/PuH3LNAWWlm</CipherValue></CipherData></EncryptedData></soapenv:Body></soapenv:Envelope>

HTTP/1.1 200 OK...Date: Mon, 13 Nov 2006 13:55:55 GMTServer: WebSphere Application Server/6.1<soapenv:Envelope...><soapenv:Header><wsse:Security soapenv:mustUnderstand="1" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-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:SecurityTokenReference><wsse:KeyIdentifier ValueType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509SubjectKeyIdentifier">Q/HFFBeGh/U=</wsse:KeyIdentifier></wsse:SecurityTokenReference></ds:KeyInfo><CipherData><CipherValue>kB+/NZaPzXVouZYZVa/l991AnRXRMsDkIm/nyJhwWzchOMeE3eaXYHRExjIWCOazJ+GwZ3tRGLRpkfg9BKJBmQWzKgiGnflgSl+hyqmNnzNb9xzi4Y4zkrvKYuk4Ov6yub7NG94bISndgeSqqBVeMY0KYcAPzx8jo3ES7WghqRk=</CipherValue></CipherData><ReferenceList><DataReference URI="#wssecurity_encryption_id_19"/></ReferenceList></EncryptedKey></wsse:Security></soapenv:Header><soapenv:Body><EncryptedData Id="wssecurity_encryption_id_19" Type="http://www.w3.org/2001/04/xmlenc#Content" xmlns="http://www.w3.org/2001/04/xmlenc#"><EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#tripledes-cbc"/><CipherData><CipherValue>M1YgSFnIrz89VFHdPsmVT0PauBHcbxs+qdeLp1/f+BnsDzzz8dCIr1RT5Sy2fK2nUuW2YRFOjr+0Ryaaw6gWbDDCbG+1FyG3E6YqGvaHng6uM39Hm/Om4wTq8kKYqQaGHX0lnlieRs04D6iyzk3NfPLXDoxqov4LIuEZaLL5YcxuVmF5+OgPj8mnEe3QN47ENF9Ygjwmzv2jb21Euz8H0oK5nVBBqMXJH8zakgU2+qOGMsTAUrLd5eCsVqH1jwKmW+VvwXRH65VlZTo1PV40x5Zn8BpLCA/sfd5GzmtoytAIjxipAVoYw0ebd6IA4msJZ1U/EcLD+rD/bABSSdelFzHgyw6MZmpWfYgkAC6fw/2p1PrRCCnC12M2xz214TUQgHrljPbtGl73/dz5F77ow8wW+oK9


A4rAxe3jWkLuFZwqgPCbRWXYZeCJBB5vp0L1O8O005Q6OUr784vzTlIqj39VtLDaFcJ4wP836yoSa8w=</CipherValue></CipherData></EncryptedData></soapenv:Body></soapenv: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

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

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 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 sideTo 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 sideTo 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).

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

Open the SecurityCallerEJB deployment descriptor. Select the WS Binding tab. Expand the Security Request Generator Binding Configuration 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).

Open the SecurityInfoEJB webservices.xml deployment descriptor. Select the Extensions tab. Expand the Request Consumer Service Configuration 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).

Select the Binding Configurations tab. Expand the Request Consumer 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.IDAssertionUsernameLoginModule 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 securityAs 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 securityIf 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 trustIf 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, “Our SecurityInfo Web service application and environment” on page 98.




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 example. See Figure 6-61.

Figure 6-61 SecurityInfo application secured servlet display

The servlet runs, calls the client EJB, makes the Web service call, and displays the results.


The application displays the principal on Web service client side and also on the 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 - RequestID = ITSO1235ITSO SecurityCallerBean - Timestamp = Mon Nov 13 10:19:11 EST 2006ITSO SecurityCallerBean - Hostname = windowsbaxITSO SecurityCallerBean - ipaddress = 9.56.23.149ITSO SecurityCallerBean - Principal = valenceITSO SecurityCallerBean - OSName = Windows XPITSO 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 valence, as shown in Example 6-11.


ITSO SecurityInfoBean - RequestID = ITSO1235 ITSO SecurityInfoBean - Timestamp = Mon Nov 13 15:19:21 GMT+00:00 2006ITSO SecurityInfoBean - Hostname = WTSC58 ITSO SecurityInfoBean - ipaddress = 9.12.4.8 ITSO SecurityInfoBean - Principal = valence 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 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

POST /SecurityInfoRouterWS/services/SecurityInfo HTTP/1.1Host: wtsc58.itso.ibm.com:49080...SOAPAction: ""Connection: Keep-AliveContent-Type: text/xml; charset=utf-8Content-Length: 650Date: Mon, 13 Nov 2006 15:19:11 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-wssecurity-secext-1.0.xsd"><wsse:UsernameToken><wsse:Username>valence</wsse:Username></wsse:UsernameToken></wsse:Security></soapenv:Header><soapenv:Body><p98:obtainSecurityInfo xmlns:p98="http://itso.ibm.com"><input>ITSO1235</input></p98:obtainSecurityInfo></soapenv:Body></soapenv:Envelope>

HTTP/1.1 200 OKContent-Type: text/xml; charset=utf-8


Content-Language: en-USContent-Length: 642Date: Mon, 13 Nov 2006 15:19:23 GMTServer: WebSphere Application Server/6.1

<soapenv:Envelope ... ><soapenv:Header/><soapenv:Body><p98:obtainSecurityInfoResponse xmlns:p98="http://itso.ibm.com"><obtainSecurityInfoReturn><string>ITSO1235</string><string>Mon Nov 13 15:19:21 GMT+00:00 2006</string><string>WTSC58</string><string>9.12.4.8</string><string>valence</string><string>z/OS</string><string>01.08.00</string></obtainSecurityInfoReturn></p98:obtainSecurityInfoResponse></soapenv:Body></soapenv:Envelope>

All this validates that identity assertion occurs between the Web service client and the Web service provider using WS-Security.


Chapter 7. Secure Sockets Layer (SSL)

This chapter provides an overview of SSL changes in WebSphere V6.1 for z/OS and how these changes are applied.


� “Centrally managed SSL” on page 210� “WebSphere V6.1 for z/OS SSSL to JSSE changes” on page 213� “SSL RACF certificate management” on page 214� “Hardware crypto and Java crypto providers” on page 222� “IBMJCECCA and IBMJCE characteristics” on page 227� “SSL and JCERACFKS keystore” on page 229� “Hardware crypto using a JCECCARACFKS keystore” on page 233� “SSL troubleshooting and traces” on page 239

7


7.1 Introduction

This section introduces new SSL features, changes, and provides z/OS-specific considerations when using SSL.

7.2 Centrally managed SSL

In previous versions of WebSphere, every endpoint using SSL required a repertoire alias to be configured. Consequently, changing the SSL repertoire alias for an endpoint was cumbersome since the user had to know what path to take in the admin console to get to a desired endpoint, and getting to the endpoint configuration usually involved traversing several screens.

WebSphere V6.1 provides a new approach to organizing SSL configurations by centralizing all SSL configurations on one panel. Additionally, SSL configurations can be scoped at the cell (network deployment only), node, server, and endpoint level so that an alias is not required for every endpoint. The panel is broken into two hierarchies, one tree for inbound endpoints, and one tree for outbound endpoints.


A new WebSphere base installation will have only one SSL configuration defined at the node level, as illustrated in Figure 7-1. Select SSL certificate and key management → Manage endpoint security configurations.

Figure 7-1 Centrally managed SSL configuration

In Figure 7-1, the server and endpoints under the inbound topology inherit their SSL configuration NodeDefaultSSLSettings from the node-level SSL configuration. Additional SSL configurations can be defined at a lower scope overriding the node-level configuration by simply clicking the server or endpoint and choosing a new SSL configuration.

SSL aliases are still supported in WebSphere V6.1, but using centrally managed SSL configuration is recommended for ease of management. Application servers that are migrated from earlier releases of WebSphere to WebSphere V6.1 still use SSL aliases, and the endpoints need to be manually configured to take advantage of the centrally managed SSL support.

Following any of the paths for the endpoints in Table 7-2 on page 214, the transport chain can be changed from using an SSL configuration alias specific to an endpoint to using the centrally configured SSL configuration.

Chapter 7. Secure Sockets Layer (SSL) 211

Figure 7-2 shows an example of how the admin console’s SSL inbound channel was changed from using an SSL configuration alias to being centrally managed.

Figure 7-2 Centrally managed SSL endpoint


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

There have been improvements to the way SSL is configured and managed in the admin console in WebSphere V6.1. In previous versions of WebSphere an SSL repertoire could be defined as one of two types, either as Java Secure Socket Extension (JSSE) or System SSL (SSSL). JSSE and SSL differed in the following ways:

� JSSE– Used Java APIs for SSL– Defined with path to an HFS Java keystore file– Defined with a path to a safkeyring URI

� SSL (system SSL)– Used z/OS set of C/C++ APIs for SSL– Defined with z/OS SAF keyring name only

Certain endpoints were designed to only work with SSSL or JSSE, and each endpoint needed to be configured with a repertoire alias. It was important to know the location in the admin console for updating the alias of a transport.

Table 7-1 shows the WebSphere V6.0 SSL type and admin console location for specifying a repertoire alias.

Table 7-1 WebSphere V6.0 endpoint details

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.

WebSphere V6.0 for z/OS base server

Endpoint Type Administration console location

HTTPS SSSL Application servers → server name →Web container → HTTP transport →Choose SSL transport

RMI-IIOP CSIV2 SSSL Global security → Authentication Protocol → CSIv2 inbound/outbound transport

Daemon SSL SSSL Application servers → server name → z/OS location service daemon

JMX™ Soap Connector

JSSE Application servers → server name → Administration Services → JMX connectors → SOAPConnector → Custom Properties → sslConfig


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

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

WebSphere V6.1 for z/OS base server

Endpoint Type Central/alias Administration console location

HTTPS JSSE Centrallyconfigured (preferred)

SSL certificate and key management → Manage endpoint security configurations

Alias Application servers → server name → Web container → z/OS additional settings → Web container transport chains → Choose SSL enabled transportSSL inbound channel (SSL_2)

RMI-IIOPCSIV2

JSSE Centrallyconfigured (preferred)

SSL certificate and key management → Manage endpoint security configurations

Alias Secure administration, applications, and infrastructure →RMI/IIOP security → CSIv2 inbound/outbound transport

Daemon SSL

SSSL Not Centrally configured

See Alias

Alias Application servers → server name →z/OS location service daemon

JMX SoapConnectors

JSSE Centrallyconfigured (preferred)

SSL certificate and key management →Manage endpoint security configurations

Alias Application servers → server name → Administration Services →JMX connectors → SOAPConnector → Custom Properties > sslConfig


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:

http://publib.boulder.ibm.com/infocenter/wasinfo/v6r1/index.jsp?topic=/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

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)

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.


� 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.IBMJCEFIPSsecurity.provider.1=com.ibm.crypto.provider.IBMJCEsecurity.provider.2=com.ibm.jsse.IBMJSSEProvidersecurity.provider.3=com.ibm.jsse2.IBMJSSEProvider2security.provider.4=com.ibm.security.jgss.IBMJGSSProvidersecurity.provider.5=com.ibm.security.cert.IBMCertPathsecurity.provider.6=com.ibm.security.sasl.IBMSASLsecurity.provider.7=com.ibm.security.cmskeystore.CMSProvidersecurity.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

# List of providers and their preference orders (see above):#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

# List of providers and their preference orders (see above):#security.provider.1=com.ibm.crypto.hdwrCCA.provider.IBMJCECCAsecurity.provider.2=com.ibm.crypto.provider.IBMJCE


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

The Use HW column indicates that hardware is used for SSL acceleration.

Providername

Keystoretype

Certificatelocation

Key location

UseHW

WebSpherepath

Tooling

IBMJCECCAIBMJCE

JKSJCEKSPKCS12

File File system

Yes path/file WASikeymankeytool

JCECCARACFKS RACF Hardware Yes safkeyring:///safkeyringhw:///

RACF

JCECCAKS File Hardware Yes path/file hwkeytool

IBMJCE JKSJCEKSPKCS12

File Filesystem

No path/file WASikeymankeytool

JCERACFKS RACF RACF No safkeyring:/// RACF


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.

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


� 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

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.

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.


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: >CN=HDwtsc58.itso.ibm.com.OU=IBM< 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:


>CN=HDwtsc58.itso.ibm.com.OU=IBM< Subject's Name: >CN=HDPersonal.O=IBM< Private Key Type: ICSF Private Key Size: 1024 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

# List of providers and their preference orders (see above):

security.provider.1=com.ibm.crypto.hdwrCCA.provider.IBMJCECCAsecurity.provider.2=com.ibm.crypto.provider.IBMJCEsecurity.provider.3=com.ibm.jsse.IBMJSSEProvider2security.provider.4=com.ibm.jsse2.IBMJSSEProvidersecurity.provider.5=com.ibm.security.jgss.IBMJGSSProvidersecurity.provider.6=com.ibm.security.cert.IBMCertPathsecurity.provider.7=com.ibm.security.sasl.IBMSASLsecurity.provider.8=com.ibm.security.cmskeystore.CMSProvidersecurity.provider.9=com.ibm.security.jgss.mech.spnego.IBMSPNEGO

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� Confirm 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 traceWhen 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 traceTo 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 0com.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(DocumentDigestImpljava:128)com.ibm.ws.management.repository.FileDocument.calcDigest(FileDocument.java:212)



Chapter 8. Web services transport security

Web services security can be addressed at both the transport level and the message level. In this chapter we focus on the transport level security features for Web services.

The following examples are provided here:

� “Authentication with HTTP” on page 246� “Integrity with SSL” on page 252� “Confidentiality with SSL” on page 268� “Confidentiality with SSL using hardware crypto” on page 272� “Confidentiality and basic authentication” on page 282� “Confidentiality and client certificate authentication” on page 282

8


8.1 Authentication with HTTP

Basic authentication can be enabled for a Web service in the application server at the transport level by specifying BASIC in the Web deployment descriptor. When basic authentication is enabled, the client needs to specify a user name and password that will be passed in the header when calling the Web services protected URL. The user name and password are sent over the network unencrypted using the HTTP protocol. The user name and password are also sent with each subsequent request. Since HTTP communication is not encrypted, the user name and password are visible and can be intercepted. To protect the user name and password from being sent over the network, basic authentication is usually performed over an encrypted transport through the use of Secure Sockets Layer (SSL).

8.1.1 HTTP basic authentication scenario description

On the client side, a user invokes a servlet from a static Web page running in the WebSphere distributed system. The servlet invokes a Web service enabled EJB that has its Web service client descriptor configured with a user name and password. The user name and password flow in the HTTP header to the Web service provider. The Web service provider extracts the user ID and password to authenticate the Web service requestor.

Figure 8-1 illustrates the HTTP basic authentication scenario.

Figure 8-1 Web service transport security HTTP basic authentication scenario

In this scenario, we demonstrate how the client SecureCaller EJB can provide a user name and password to authenticate to the SecureInfo EJB that is Web


service enabled. An authentication method of BASIC is specified in the SecurityInfoRouterWS deployment descriptor. The user name and password are specified in a Web service client binding, as opposed to specifying them programmatically in the code. The transport does not have SSL enabled.

8.1.2 Configuring the z/OS Web service provider with authentication

The process for configuring transport-level basic authentication for a Web service is similar to configuring transport-level basic authentication for a Web application. The Web service endpoint resides in a WAR file, and can be configured using the Web deployment descriptor editor.

1. In the J2EE perspective, traverse the tree under Dynamic Web Projects, and open the deployment descriptor for the SecurityInfoRouterWS.

2. Select the Security tab. Under Security Roles, add a role named SecureCustomer.

3. Under Security Constraints, add a security constraint named SecureConstraint.

– Set Resource Name to Secure Web Resource.– Select the check box for “GET, and POST” HTTP Methods.– Add the pattern /*.

4. Under Authorized Roles, add SecureCustomer.

5. Select the Pages tab. Under Authentication Method, select BASIC and provide the realm name SecurityInfo Realm.

In Example 8-1, the XML code shows how the security-constraint, login-config, and security role were setup in the web.xml.

Example 8-1 Security setup in web.xml

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


</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 providerDeploy 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/SecurityInfo

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}SecurityInfoHi 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 → SecurityCallerEAR → Manage Modules → SecurityCallerEJB.jar → Web 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

POST /SecurityInfoRouterWS/services/SecurityInfo HTTP/1.1Host: wtsc58.itso.ibm.com:19080Accept: application/soap+xml,multipart/related,text/*User-Agent: IBM WebServices/1.0Cache-Control: no-cachePragma: no-cacheSOAPAction: ""Authorization: Basic V0lOU0VSVjpXSU5TRVJWConnection: Keep-Alive


Content-Type: text/xml; charset=utf-8Content-Length: 402Date: Wed, 08 Nov 2006 16:33:48 GMT

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"><soapenv:Header/><soapenv:Body><p98:obtainSecurityInfo xmlns:p98="http://itso.ibm.com"><input>ITSO5285</input></p98:obtainSecurityInfo></soapenv:Body></soapenv:Envelope>

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 clientIn 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/OSIn 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 configurationIn 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 → SecurityCallerEAR → Manage Modules → SecurityCallerEJB.jar → Web 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 → SecurityCallerEAR → Manage Modules → SecurityCallerEJB.jar → Web services deployment descriptor Extension → Web services client bindings → SecurityInfoService:SecurityCallerEJB.


Configuring the Web service requestor endpoint URLIn this example, the endpoint URL was changed to:

https://wtsc58.itso.ibm.com:19445/SecurityInfoRouterWS/services/SecurityInfo

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. 2. Under Additional Properties, select quality of protection (Qop) settings.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

Host: wtsc58.itso.ibm.com:19445Accept: application/soap+xml,multipart/related,text/*User-Agent: IBM WebServices/1.0Cache-Control: no-cachePragma: no-cacheSOAPAction: ""Connection: Keep-AliveContent-Type: text/xml; charset=utf-8Content-Length: 402Date: Fri, 10 Nov 2006 15:25:10 GMT

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"><soapenv:Header/><soapenv:Body><p98:obtainSecurityInfo xmlns:p98="http://itso.ibm.com"><input>ITSO1916</input></p98:obtainSecurityInfo></soapenv:Body></soapenv:Envelope>(....[xU.n..........QHTTP/1.1 200 OKContent-Type: text/xml; charset=utf-8Content-Language: en-US


Content-Length: 650Date: Fri, 10 Nov 2006 15:25:13 GMTServer: WebSphere Application Server/6.1<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"><soapenv:Header/><soapenv:Body><p98:obtainSecurityInfoResponse xmlns:p98="http://itso.ibm.com"><obtainSecurityInfoReturn><string>ITSO1916</string><string>Fri Nov 10 15:25:13 GMT+00:00 2006</string><string>WTSC58</string><string>9.12.4.8</string><string>UNAUTHENTICATED</string><string>z/OS</string><string>01.08.00</string></obtainSecurityInfoReturn></p98:obtainSecurityInfoResponse></soapenv:Body></soapenv:Envelope>...K.....g.\..o

Enforcing integrity with the Web service descriptorAt 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

<user-data-constraint><transport-guarantee>INTEGRAL</transport-guarantee>

</user-data-constraint>

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:



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. 2. Under Additional Properties, select quality of protection (Qop) settings.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, applications, and infrastructure → SSL Confirugrations.

1. Choose WebServiceConfig. 2. Under Additional Properties, select quality of protection (Qop) settings.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.

Enforcing confidentiality with the Web service descriptorAt 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

<user-data-constraint><transport-guarantee>CONFIDENTIAL</transport-guarantee>

</user-data-constraint>

The application must be redeployed after making the change to the deployment descriptor.

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:


The browser output shows:




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 certificatesCreate 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: >CN=HDwtsc58.itso.ibm.com.OU=IBM< Subject's Name: >CN=HDwtsc58.itso.ibm.com.OU=IBM< Key Usage: CERTSIGN Private Key Type: ICSF Private Key Size: 1024 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: >CN=HDwtsc58.itso.ibm.com.OU=IBM< Subject's Name: >CN=HDPersonal.O=IBM< Private Key Type: ICSF Private Key Size: 1024 PKDS Label: IRR.DIGTCERT.ASCR1.SC58.BFBDE9BD1F5C88CC Ring Associations: Ring Owner: ASCR1 Ring: >WASKeyring.HD<

Extracting the signer certificate from z/OSExport 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 distributedIn 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.jarchmod 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

# List of providers and their preference orders (see above):

security.provider.1=com.ibm.crypto.hdwrCCA.provider.IBMJCECCAsecurity.provider.2=com.ibm.crypto.provider.IBMJCEsecurity.provider.3=com.ibm.jsse.IBMJSSEProvider2security.provider.4=com.ibm.jsse2.IBMJSSEProvidersecurity.provider.5=com.ibm.security.jgss.IBMJGSSProvidersecurity.provider.6=com.ibm.security.cert.IBMCertPathsecurity.provider.7=com.ibm.security.sasl.IBMSASLsecurity.provider.8=com.ibm.security.cmskeystore.CMSProvidersecurity.provider.9=com.ibm.security.jgss.mech.spnego.IBMSPNEGO

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 keystoreIn 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� Confirm 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 configurationCreate 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 portIf 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, applications, and infrastructure → SSL Confirugrations.

1. Choose the WebServiceSSLConfig.2. Under Additional Properties, select quality of protection (Qop) settings.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, applications, and infrastructure → SSL Confirugrations.

1. Choose the WebServiceConfig. 2. Under Additional Properties, select quality of protection (Qop) settings.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.


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 2472. “Configuring the Web service requestor to authenticate” on page 2493. “Configuring the z/OS Web service provider SSL configuration” on page 2554. “Configuring the Web service requestor SSL configuration” on page 2615. “Configuring the z/OS Web service provider for confidentiality” on page 2696. “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.

Note: It is also possible to invoke the Web service provider’s URL from a Web browser:


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.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 RACFTo 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 keystoreIn 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


Comparing the personal certificate on z/OS and WindowsAt 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 Private Key Size: 1024 Ring Associations: Ring Owner: WINSERV Ring: >WASKeyring.CL6581<

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:




In the Windows admin console follow the path to SSL certificate and key management → Key stores and certificates → NodeDefaultKeyStore → 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 open the deployment descriptor for the SecurityInfoRouterWS.

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>


</auth-constraint></security-constraint><login-config>

<auth-method>CLIENT-CERT</auth-method></login-config><security-role>

<role-name>SecureCustomer</role-name></security-role>


Deploy the SecurityInfo ear file in the admin console, accepting the default settings presented during deployment.

Enable client certificate authentication for SSL configFollow the path Security → Secure Administration, applications, and infrastructure → SSL Confirugrations.

1. Choose WebServiceSSLConfig. 2. Under Additional Properties, select quality of protection (Qop) settings.3. Change the client authentication to Required.

Figure 8-26 Setting client authentication for SSL configuration


8.6.6 Validating client certificate authentication

Successful output from the application should show the user principal of the user ID associated with the personal certificate in the Web page table Remote SecurityInfoBean Information. In this scenario WINSERV is seen as the user principal. See Figure 8-27.

Figure 8-27 Client certificate authentication validation

Attention: For the client certificate scenario to work successfully, the fix for PK31729 needed to be applied, which corrected a problem with authorization errors when creating native credentials.



Chapter 9. Security attribute propagation and CSIv2

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


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 example. See Figure 9-2.

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-onAs 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 administrative console, navigate to Secure administration, applications, 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 administrative console, navigate to Secure administration, applications, 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 propagationFor cross-cell attribute propagation to happen, identity propagation or single sign-on is a prerequisite. Hence, the process described in the preceding section has to be executed.

Horizontal attribute propagation implies the usage of JMX calls. If you are using JMX across cells then a great deal of trust is implied between the cells. In addition to the requirement for shared LTPA encryption keys, the cell level server identities end up with substantial authority across the cell boundaries. This is because, as with any administrative call, the JMX call requires authentication and authorization.

For the remote JMX administration call across the cell to succeed, the two cells must share a common security infrastructure, registries, SSL Keys, and so on. Also, the cell’s security server ID must have administrative access to the remote cell. All cells must completely trust each other. Each has administrative authority over the other. The same behavior holds with propagation within a cell, but in that case there is no issue because servers within a cell already trust each other and share a common administrative identity.

9.3 CSIv2 standard identity assertion

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.

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.


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 identityThe 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 relationshipIdentity 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 transportOn 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 authenticationOn 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 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 transportOn the CSIv2 downstream server side, using the administrative console, click Security → Secure administration, applications, and infrastructure. Under 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 authenticationOn the CSIv2 downstream server side, using the administrative console, click Security → Secure administration, applications, and infrastructure. Under 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.

On the CSIv2 downstream server side, using the administrative console, click Security → Secure administration, applications, and infrastructure. Under 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 environmentThis 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 assertionThe 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 actionIn 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/servers/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:

http://publib.boulder.ibm.com/infocenter/wasinfo/v6r0/index.jsp?topic=/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 administrative console.

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 example. See Figure 9-22.

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:


2. Navigate to Security → Secure administration, applications, and 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:


2. Navigate to Security → Secure administration, applications, and infrastructure. Under Authentication, click RMI/IIOP security → CSIv2 inbound authentication.


3. Check the option for Security attribute propagation (Figure 9-24). This option enables vertical or downstream propagation. It deserializes the full security context within the RMI-IIOP call.


Figure 9-24 Downstream server vertical attribute propagation configuration

With the security attribute propagation enabled, the security attributes of the originating server where the initial login occurred get propagated to the downstream server. These security attributes include any custom attributes or tokens that are set in the custom login modules in the login server.


9.4.5 Cross-cell considerations

Security attribute propagation relies on the usage of LTPA tokens. These tokens are encrypted using LTPA keys. By default, these keys are automatically generated and shared among all application servers in the same cell. This is the reason why all application servers in one cell are able to generate and encrypt or decrypt and read any LTPA token generated by another. Security attribute propagation happens sharing one set of LTPA keys in the cell. In a deployment manager configuration, the LTPA keys generated at the deployment manager level are automatically replicated to all servers’ members of the same cell.

In a multiple cells environment, LTPA keys and security configurations are likely to be different by default and need some adjustment to be able to communicate.

Refer to “Cross-cell identity propagation or single sign-on” on page 303 for how to configure LTPA keys across cells.

“Cross-cell horizontal attribute propagation” on page 305 does not apply to vertical security attribute propagation because no JMX call is involved in vertical attribute propagation.


Chapter 10. User registries

User registries or repositories are essential to security architectures. They contain critical users and groups information. WebSphere Application Server for z/OS v6.1 provides some flexible features to access different types of registries. The new federated repositories functionality extends even more its capabilities.

This chapter describes the following topics:

� “Introduction to user registries” on page 336� “Our scenario and our environment” on page 339� “Standalone LDAP registry” on page 340� “Federated repositories” on page 363� “z/OS local operating system registry” on page 382

10


10.1 Introduction to user registries

In WebSphere Application Server for z/OS, a user registry or repository authenticates a user and retrieves information about users and groups to perform security-related functions, including authentication and authorization. The information about users and groups resides within a registry or repository.

WebSphere Application Server for z/OS v6.1 provides implementations that support multiple types of registries and repositories:

� Local operating system� Standalone LDAP registry� Standalone custom registry � Federated repositories

With WebSphere Application Server for z/OS, a user registry or repository is used for:

� Authenticating a user using basic authentication, identity assertion, client certificates, tokens

� Retrieving information about users and groups to perform security-related administrative functions, such as mapping users and groups to security roles

Although the WebSphere Application Server supports different types of user registries, only one user registry can be active. This active registry is shared by all of the product server processes within a cell.

Local operating system registryWebSphere 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 registryLightweight 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 registryA 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 repositoriesThis 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 WebSphere Application Server for z/OS.

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 configurationThe 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://:3389maxConnections 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.comPort : 3389Base DN : ou=itsoracf,o=itsoUser DN : racfid=valence,profiletype=user,ou=itsoracf,o=itsoUser 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 SDBMWebSphere 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 Application Server for z/OS.

WebSphere and z/OS LDAP SDBM back-end validationAfter 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 authorizationWhen 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.

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

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.


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 configurationThe 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 GLDBTDBMsuffix "ou=itsotdbm,o=itso"servername DB2Bdbuserid GLDSRVdatabasename GLDDBdsnaoini 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://:3389maxConnections 60 adminDN "cn=LDAP Administrator" adminPW "secret" # TDBM-specific CONFIGURATION SETTINGSdatabase tdbm GLDBTDBMsuffix "ou=itsotdbm,o=itso"servername DB2Bdbuserid GLDSRVdatabasename GLDDBdsnaoini WTSC58.LDAP1.CNTL(DSNAOINI)attroverflowsize 255


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.ldifldapmodify -h wtsc58 -p 3389 -D "cn=LDAP Administrator" -w secret -f /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=itsochangetype:modify replace:userpassword userpassword: usertdbm


Use a command similar to the following to modify the user entry in the LDAP tree:

ldapmodify -h wtsc58 -p 3389 -D "cn=LDAP Administrator" -w secret -f 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:


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 TDBMWebSphere Application Server for z/OS supports accessing z/OS LDAP with a 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.

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-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 validationAfter 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 (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 configurationFirst 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://:3389maxConnections 60 adminDN "cn=LDAP Administrator" adminPW "secret" # TDBM-specific CONFIGURATION SETTINGSdatabase tdbm GLDBTDBMsuffix "ou=itsotdbm,o=itso"servername DB2Bdbuserid GLDSRVdatabasename GLDDBdsnaoini WTSC58.LDAP1.CNTL(DSNAOINI)attroverflowsize 255 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 Nativeibm-nativeId: VALENCEobjectclass: 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 authenticationFrom 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 validationWe 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

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.

Federated repositories Other user registry options

Supported registries File-basedLDAPDB (via wsadmin)

Local operating systemStandalone LDAPStandalone custom

Simultaneous multi-registry support

Yes No

Registry read/write support

Read/write Read only


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.

z/OS LDAP TDBM configurationConfigure 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 TDBMWebSphere Application Server for z/OS supports accessing z/OS LDAP with a 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.

1. Within the administrative console, click Security → Secure administration, applications and infrastructure. Under User account repository, select 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.

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.


– 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, applications and infrastructure. Under User account repository, select 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

3. Within the administrative console, click Security → Secure administration, applications and infrastructure. Under User account repository, select 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.

Then click Apply and save to the master configuration. WebSphere validates that it can find the administrative user identity.

Figure 10-22 WebSphere federated repositories base entries

4. Within the administrative console, click Security → Secure administration, 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 validationAfter 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 (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 (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.

z/OS LDAP TDBM configurationConfigure 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 TDBMNative 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) configurationHow 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=itsoou: itsoitdsobjectclass: organizationalUnitobjectclass: top

dn: cn=UserItds, ou=itsoitds,o=itsouid: UserItdsdescription: Test user for ITDSobjectclass: inetOrgPersonobjectclass: ePersonobjectclass: organizationalPersonobjectclass: personobjectclass: topsn: 2007cn: 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=itsochangetype: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.comPort : 389Base DN : ou=itsoitds,o=itsoUser DN : cn=LDAP AdministratorUser 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 ITDSWebSphere 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.

1. Within the administrative console, click Security → Secure administration, applications and infrastructure. Under User account repository, select 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.

Then click Apply and save to the master configuration. WebSphere validates that it can access the LDAP server.

Figure 10-30 WebSphere configuration for ITDS as a federated repository

2. Within the administrative console, click Security → Secure administration, applications and infrastructure. Under User account repository, select 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

3. Within the administrative console, click Security → Secure administration, applications and infrastructure. Under User account repository, select 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

4. Within the administrative console, click Security → Secure administration, 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 validationTo log into the administrative console, use the primary administrative user name defined earlier. It is possible to use the full distinguished name


(cn=UserTdbm,ou=itsotdbm,o=itso) or the user name only (usertdbm). Using our ldif file, the password is usertdbm also.

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)SETROPTS RACLIST(EJBROLE) REFRESH

In this example, the domain name is PRODCELL. The role name is bankTeller. The authorized user ID is JOHN.

If a Lightweight Access Directory Protocol (LDAP) registry or custom registry is configured and SAF authorization is specified, a mapping to a z/OS principal is required at each login for any protected methods to run. If the authentication mechanism is Lightweight Third Party Authentication, we recommend that you update all of the following configuration entries to include a mapping to a valid z/OS principal (such as WEB_INBOUND, RMI_INBOUND, and DEFAULT).

Table 10-2 Authorization providers characteristics

Authorization providers Characteristics

Default authorization (WebSphere bindings)

� Access to servlets or EJB methods is based upon the role (job title, function, and so on) of the user or caller.

� Roles are associated with servlets or EJBs at assembly time.� Roles are stored in the application's .ear file: application.xml.� Which users and groups have which roles is also stored in the

application's .ear file: ibm-application-bnd.xmi.� Roles are managed by the application developer and the application

deployer. � RACF only provides user and group information.

System Authorization Facility authorization


� Roles are associated with servlets or EJBs at assembly time.� 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.


SAF delegationSystem 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 mapperWebSphere 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

External authorization using a JACC provider


� Roles are associated with servlets or EJBs at assembly time.� 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.

Authorization providers Characteristics


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 ThreadSync-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 identityConnection manager RunAs identity applies to connections to back-end Enterprise Information Systems such as DB2 and IMS JDBC. It allows the changing of the OS thread identity to the J2EE identity at the connector level.

Thread security support for DB2 and IMS JDBC is enabled when:

� Connection manager RunAs thread identity is enabled.

� A local connection is used between the application server and the EIS.

� Res-auth=Container is specified for the resource reference defined in the deployment descriptor.

� The connection factory does not specify a JAAS authentication alias.


� The BBO.SYNC facility class is defined in RACF and the control region user ID has control or read access to it. Use the optional SURROGAT facility class for finer-grained access controls.

With such a configuration, the connection manager synchronizes the OS thread identity with the J2EE identity before obtaining the EIS connection. See Figure 10-36.

Figure 10-36 Administrative console connection manager RunAs identity option

This “Enable the conection manager RunAs thread identity” option is available using the administrative console in Secure administration, applications, and infrastructure → z/OS security options.


10.5.3 Thread identity support

Thread identity support is the ability to pass the identity of the Java principal within the subject (J2EE identity) through a JCA connector or a JDBC ressource adapter to an Enterprise Information System. Depending on the connector being used, thread identity support may or may not require you to configure connection manager RunAs identity. Some connectors can accomplish thread identity support without synchronizing the J2EE identity with the OS thread identity. Some connectors accomplish thread identity support by synchronizing the J2EE identity with the OS thread identity.

WebSphere Application Server for z/OS allows you to assign an identity as an owner of a connection when you first obtain the connection. This thread identity function only applies to J2EE Connector Architecture (JCA) resource adapters and Relational Resource Adapter (RRA) wrappered Java Database Connectivity (JDBC) providers that support the use of thread identity for connection ownership.

Thread identity support is enabled when:

� A local connection is used between the application server and the EIS (CICS, IMS, DB2, and so on).

� Res-auth=Container is specified for the resource reference defined in the deployment descriptor.

� The connection factory does not specify a JAAS Authentication Alias.

� You are using an SAF-based user registry.

Table 10-3 lists the JCA resource adapter and JDBC provider processes that support thread identity and thread security. It also provides the level of thread identity support.

Table 10-3 Connectors thread identity and OS thread security support

Connectors Thread identity support

OS thread security support

IMS Connector - local ConnectionFactory configuration Allowed Not supported

IMS Connector - remote ConnectionFactory configuration Not allowed Not supported

CTG CICSECIConnector - local ConnectionFactory configuration Allowed Not supported

CTG CICSECIConnector - remote ConnectionFactory configuration Not allowed Not supported

IMS JDBC Connector - local ConnectionFactory configuration (By default, IMS JDBC only supports this type of configuration.)

Required Supported


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.

RRA DB2 for z/OS local JDBC provider - data sources configured to the local DB2

Allowed Supported

RRA DB2 Universal JDBC Driver Provider using Type 2 connectivity Allowed Supported

RRA DB2 Universal JDBC Driver Provider using Type 4 connectivity Not allowed Not supported

WebSphere MQ JMS Provider: Connection Factory (TransportType = BINDINGS)

Allowed Supported

WebSphere MQ JMS Provider - Connection Factory (TransportType = CLIENT)

Not allowed Not supported

WebSphere JMS Provider (such as Integral JMS Provider): Connection Factory

Not allowed Not supported

Connectors Thread identity support

OS thread security support


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 Application Server for z/OS.

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


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 principalA 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 [email protected].

� The instance name: This is optional. It is used to further define the primary name, for example, fdevalence/[email protected]. 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/[email protected].


� 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 ticketThe 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 protocolThe 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 WindowsKerberos 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/0707_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


http://www.ibm.com/developerworks/websphere/techjournal/0707_rogers/0707_rogers.html

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 configuringA 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-8BE1-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 nameCreate 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

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

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.


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 wtsc58aRegistering ServicePrincipalNames for CN=wtsc58a,CN=Users,DC=kkdc,DC=test,DC=com HTTP/wtsc58a.kkdc.test.comUpdated object

C:\>setspn -l wtsc58aRegistered ServicePrincipalNames for CN=wtsc58a,CN=Users,DC=kkdc,DC=test,DC=com: HTTP/wtsc58a.kkdc.test.com

Creating the Kerberos keytab fileUse 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.

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


http://technet2.microsoft.com/WindowsServer/en/library/318642de-15a3-4478-beb0-8022696def511033.mspx?mfr=true

� crypto specifies the type of cryptographic system to use. With the wtsc58a Windows account we set up, DES-CBC-MD5 has to be selected.

We run the following command for our environment:

ktpass -princ HTTP/[email protected] -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.

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/[email protected] -out c:\wtsc58a.keytab -pass password -mapUser wtsc58a -crypto DES-CBC-MD5 -mapOp set -ptype KRB5_NT_PRINCIPALTargeting domain controller: sec05.kkdc.test.comUsing legacy password setting methodSuccessfully mapped HTTP/wtsc58a.kkdc.test.com to wtsc58a.Key created.Output keytab to c:\wtsc58a.keytab:Keytab version: 0x502keysize 67 HTTP/[email protected] ptype 1 (KRB5_NT_PRINCIPAL)vno 8 etype 0x3 (DES-CBC-MD5) keylength 8 (0x13bfe54345ea08d3)

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

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.


http://technet2.microsoft.com/WindowsServer/en/library/5090598d-a735-4c73-9e37-1a95a4651fa51033.mspx?mfr=true

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 fileThe 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 WebSphereThis 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.


In our environment we add the following properties with the following values:

com.ibm.ws.security.spnego.SPN1.hostName : wtsc58a.kkdc.test.comcom.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 TAIThe 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 →

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



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 → server_name → Java and Process management → Process Definition → 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

Figure 11-13 Java Virtual Machine properties display

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


Verifying security in WebSphereThe 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/[email protected] com.ibm.ws.security.spnego.SPN.filter=request-url%=snoop com.ibm.ws.security.spnego.SPN.filterClass=com.ibm.ws.security.spnego.HTTPHeaderFilter@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 ExplorerComplete 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 FirefoxComplete 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 → server_name → Java and Process management → Process Definition → 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:

http://publib.boulder.ibm.com/infocenter/wasinfo/v6r1/index.jsp?topic=/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 WebSphere Application Server for z/OS.

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. Trace: 2006/11/16 14:26:31.281 01 t=8C7718 c=UNK key=P8 (13007002) ThreadId: 00000029 FunctionName: handleRequest SourceId: com.ibm.ws.security.spnego.SpnegoHandler Category: INFO ExtendedMessage: CWSPN0023I: Username [email protected] Token size 1662.Trace: 2006/11/16 14:26:31.282 01 t=8C7718 c=UNK key=P8 (13007002) ThreadId: 00000029


FunctionName: trimUsername SourceId: com.ibm.ws.security.spnego.SpnegoHandler Category: FINER ExtendedMessage: Principal name was trimmed to: VALENCE Trace: 2006/11/16 14:26:31.283 01 t=8C7718 c=UNK key=P8 (13007002) ThreadId: 00000029 FunctionName: negotiateValidateandEstablishTrust SourceId: com.ibm.ws.security.spnego.TrustAssociationInterceptorImpl Category: FINER ExtendedMessage: Authenticated user: VALENCE Subject: Subject: Principal: [email protected]

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.


Chapter 12. Operating system security

In this chapter we introduce some new security features for WebSphere Application Server Version 6.1 for z/OS administrative security.

We cover the following topics:

� “Out-of-the-box administrative security” on page 430� “Automatically generated server IDs” on page 441� “RACF - mixed-case password support” on page 443� “Sync-to-OS thread update” on page 444

12


12.1 Out-of-the-box administrative security

When installing WebSphere Application Server Version 6.1 for z/OS you may notice some differences from previous versions. WebSphere Application Server Version 6.1 for z/OS contains improved security features. One of the most remarkable new options is out-of-the-box administrative security. Out-of-the-box administrative security gives you the option to enable administrative security at installation and configuration time to prevent unauthorized access to the administrative console.

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.

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))

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

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.

Figure 12-2 Security Customization panel

In the following sections we explain the features of each option.

------------ WebSphere Application Server for z/OS Customization --------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


Option 1: Use a z/OS security productIf 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.

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)

------------ WebSphere Application Server for z/OS Customization --------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


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

Figure 12-5 WebSphere Application Server security panel

------------ WebSphere Application Server for z/OS Customization --------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:


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 securityIf 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 repository

Local operating systemUser IDs, groups, and passwords are stored in RACF.

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

User IDs and passwords are stored in fileRegistry.xml

Authorization technology(external authenticated providersecurity)

System Authorization Facility (SAF) authorizationUse the authorization policy that is stored in RACF.

Default authorizationUse WebSphere Security authorization.

Administrative role definition

RACF EJBROLE profileMapping information is stored in RACF.

Definition of EJBROLE profiles is required. (Default roles are defined during server installation process.)

WebSphere Admin RoleMapping information is stored in UNIX System Services.� Information of user IDs and

roles is stored in admin-auth.xml.

� Primary admin user ID, which is used to log on to the administrative console, is stored in security.xml.

Key store type System Authorization Facility keyringStored in RACF DBKey store PATH: safkeyring:/// <keyring_name>Type: JCERACFKS

File-based key storeStored in UNIX System Services.Key store PATH: ${CONFIG_ROOT}/cells/<cell_name>/nodes/<node_name>/<key_file>Type: PKCS12


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

Application deployment (role mapping)

Security Authorization Facility (SAF)-based mapping � Need to define new

EJBROLE profiles in RACF.� The “Map security roles to

users or groups” step in the deployment of an application is ineffective.

File-based mappingNeed to map user and role in the “Map security roles to users or groups” step in the deployment of application.

z/OS security WebSphere Application Server security


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


Figure 12-8 Password excerpt of the SETROPTS LIST command output

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.1Additional 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

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.

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.


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


Chapter 13. WAS administrative security

On the z/OS platform the term administrative security refers to the security configuration that is in effect for the WebSphere Application Server cell.

The configuration of administrative security for a security domain encompasses authentication of HTTP clients, authentication of IIOP clients, administrative console security, and naming security.

In this chapter we focus on configuring administrative roles, resource instance access, and naming service security.

These subtopics are addressed:

� “Security configuration and administration” on page 448� “Role-based administrative security” on page 460� “Naming service security” on page 467

13


13.1 Security configuration and administration

In this section we introduce the helpful security administration tools provided in V6.1 and show an example of a security implementation using the security wizard.

13.1.1 Simplified security administration

WebSphere Application Server V6.1 has an improved administrative console interface, which is different from V6.0. A more user-friendly interface simplifies the configuration of security settings and administrative operations.

After installation and initial configuration of an application server environment you would normally first customize your security environment. The security wizard is helpful for basic security customization if your server is running with security disabled. The security configuration reporting tool is useful to display an overview of your current security settings.

Security wizardThe security wizard helps you to configure an existing user registry and to enable administrative, application, and resource security.

Security configuration reporting toolThe 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.

2. Click Security → Secure administration, applications, and infrastructure.


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.

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.

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.


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:

SETROPTS RACLIST(EJBROLE) REFRESH

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

Figure 13-6 Updated security.xml

<?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-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 securityIf 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.

1. Click Security → Secure administration, applications, and infrastructure.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.

<?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" externalName="uid=itsouser,o=defaultWIMFileBasedRealm" uniqueId="cc750038-75ad-4454-b9b6-c5bdced553ca" uniqueName="uid=itsouser,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>U0hBLTE6ZW9oYTM4dnYxc3l6OnEwK2FFN2RRMUtVTldiVlVNdFJtdE5HWlZtdz0K</wim:password> <wim:uid>itsouser</wim:uid> <wim:cn>itsouser</wim:cn> <wim:sn>itsouser</wim:sn> </wim:entities> </wim:Root></sdo:datagraph>


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 NONEWASX7357I: By request, this scripting client is not connected to any server process. Certain configuration and application operations will be available in local mode.WASX7029I: For help, enter: "$Help help"wsadmin>securityoffLOCAL 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:

http://publib.boulder.ibm.com/infocenter/wasinfo/v6r1/index.jsp?topic=/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.


http://publib.boulder.ibm.com/infocenter/wasinfo/v6r1/index.jsp?topic=/com.ibm.websphere.zseries.doc/info/zseries/ae/rxml_mvsmodify.html

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.


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

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 usersThe 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

repositories configuration. � Create, update, or delete groups in the federated

repositories configuration.

Deployer (New in V6.1)Only available for wsadmin usersConfiguration actions and runtime operations on applications.

adminsecuritymanager (New in V6.1)Only available for wsadmin usersWhen 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.

Role Description


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)SETROPTS RACLIST(EJBROLE) REFRESH

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

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.

Note: A resource instance can only belong to one authorization group.


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.

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.

Note: The standalone server itself cannot be part of any authorization group.


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: cl6582node name: nd6582server name: ws6582server_profile_root: /WebSphereBS2/V6R1/AppServer/profiles/default/bin

The wsadmin commands are in the jython scripting language.

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 pswdWASX7209I: Connected to process "ws6582" on node nd6582 using SOAP connector; The type of process is: UnManagedProcessWASX7031I: For help, enter: "print Help.help()"wsadmin>AdminTask.createAuthorizationGroup('[-authorizationGroupName APPG]')'cells/cl6582/authorizationgroups/APPG|authorizationgroup.xml#AuthorizationGroup_1164863617316'

Note: WebSphere administrative (wsadmin) scripting support for the JACL language is deprecated as of V6.1.


wsadmin>AdminTask.addResourceToAuthorizationGroup('[-authorizationGroupName 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)

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:

SETROPTS RACLIST(EJBROLE) REFRESH

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.


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: UnManagedProcessWASX7031I: For help, enter: "print Help.help()"wsadmin>print AdminApp.list()DefaultApplicationHelloApplicationivtAppquerywsadmin>appManager = AdminControl.queryNames('type=ApplicationManager,* ')wsadmin>AdminControl.invoke(appManager,'stopApplication','HelloApplication')''wsadmin>AdminControl.invoke(appManager,'stopApplication','DefaultApplication')''wsadmin>

Example 13-7 APPUSER1 execution output

/WebSphereBS2/V6R1/AppServer/profiles/default/bin # wsadmin.sh -lang jython -user APPUSER1 -password pswdWASX7209I: Connected to process "ws6582" on node nd6582 using SOAP connector; The type of process is: UnManagedProcessWASX7031I: For help, enter: "print Help.help()"wsadmin>print AdminApp.list()HelloApplication


wsadmin>appManager = AdminControl.queryNames('type=ApplicationManager,* ')wsadmin>AdminControl.invoke(appManager,'stopApplication','HelloApplication')''wsadmin>AdminControl.invoke(appManager,'stopApplication','DefaultApplication')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.


http://www-03.ibm.com/support/techdocs/atsmastr.nsf/WebIndex/TD103324

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

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.

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. The ALL_AUTHENTICATED special-subject is the default policy for this role.

CosNamingDelete Destroy objects in the name space, for example, using the JNDI destroySubcontext method and CosNamingCreate operations. The ALL_AUTHENTICATED special-subject is the default policy for this role.


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)SETROPTS RACLIST(EJBROLE) REFRESH

WSGUEST is the unauthenticated user ID and WSCFG1 is the WebSphere Application Server Configuration Group name, as defined in the server configuration process. CosNamingRead is defined with UACC(READ), which is the closest thing in RACF to the EVERYONE special-subject. Note that we permit the unauthenticated user ID specifically to the CosNamingRead role because it has been defined with the RESTRICTED attribute. The server special-subject WSCFG1 should be permitted to all of the four CosNaming roles, because it provides processes that run under the server identity access to all the CosNaming operations.

We recommend mapping groups or one of the special-subjects to naming roles. That is more flexible than mapping specific users and is easier to administer. When SAF authorization is the chosen authorization provider, you benefit from the fact that servers do not need to be restarted in order to activate changes in bindings to the naming roles.


Appendix A. Additional material

This book refers to additional material that can be downloaded from the Internet as described below.

Locating the Web materialThe 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.

A


ftp://www.redbooks.ibm.com/redbooks/SG247384



Using the Web materialThe additional Web material that accompanies this book includes the following files:

File name DescriptionSG7348.zip Zipped code samples

How to use the Web materialCreate 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 RedbooksFor 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 publicationsThese 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 resourcesThese 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


� What is new for securing Web services


� IBM HTTP Server - setting up a secure server


� WebSphere Application Server documentation


� IBM Education Assistant - CSIv2



http://www-1.ibm.com/support/docview.wss?uid=pub1sa22768709

http://www.elink.ibmlink.ibm.com/public/applications/publications/cgibin/pbi.cgi?CTY=US&FNC=SRX&PBL=GC34659001

http://publibz.boulder.ibm.com/epubs/pdf/csfb3z50.pdf

http://www.elink.ibmlink.ibm.com/publications/servlet/pbi.wss?CTY=US&FNC=SRX&PBL=SC34658801




http://www.w3.org/Signature/


















� IBM WebSphere Developer Technical Journal: Securing connections between WebSphere Application Server and WebSphere MQ


� 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


� Windows Server 2003 Service Pack 1 32-bit Support Tools


� Windows Server 2003 Resource Kit Tools


� SPNEGO TAI configuration requirements


� SPNEGO TAI custom configuration attributes


� SPNEGO trust association interceptor (TAI) troubleshooting tips


How to get IBM RedbooksYou 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




http://www-128.ibm.com/developerworks/java/jdk/security/index.html





http://publib.boulder.ibm.com/infocenter/wasinfo/v6r1/index.jsp?topic=/com.ibm.websphere.zseries.doc/info/zseries/ae/rsec_SPNEGO_tai_attribs.htm




Help from IBMIBM Support and downloads

ibm.com/support

IBM Global Services

ibm.com/services


http://www.ibm.com/support/

http://www.ibm.com/support/

http://www.ibm.com/services/

http://www.ibm.com/services/

Index

Numerics128-bit encryption algorithm 26840-bit encryption algorithm 268

Aadministration security

options 432do not enable security 437use a z/OS security product 433use a z/OS security product, user IDs creat-ed 433use WAS security 435

Administrative ConsoleAccessing ITDS configuration 378administrative security 449Certificate

manage certificate expiration 218change internal server user id 442Configuring the JVM for the SPNEGO TAI 416Develop your own TAI 396LDAP

TDBMFederate Repositories 368

z/OS LDAP SDBM 344z/OS LDAP TDBM 355

RunAs thread identity 388SAF authorization 383, 385Security Attribute Propagation

Vertical propagation 331security configuration reporting tool 448Security role-based

AdminSecurityManager 461Deployer 461iscadmins 461

security wizard 448SPNEGO configuration 414z/OS thread identity synchronization 387

administrative rolesadded in WAS V6.1 460Administrator 461AdminSecurityManager 460Configurator 460Deployer 460

© Copyright IBM Corp. 2007. All rights reserved.

iscadmins 460Monitor 460Operator 460

administrative security 72default authorization provider 455disabling

using admin console 457disabling, using wsadmin 457options 449security trace 458

administrative security, fine-grained 462options to implement 463

adminstrative securitywhat does it protect? 72

Application Securityenabling, in admin console 73

application security 72asymmetric cipher algorithm 30Auditing 4authDataAlias 48Authentication 3authentication keys 32Authorization 3

Default authorization 384External authorization using JACC provider 385SAF authorization 384

authorization group 462authorization providers 450

default authorization 450Java Contract for Containers (JACC)

external authorization 450System Authorization Facility (SAF) 450

authorization, SAF-based 25

Bbase64 254Basic Authentication 72, 98, 246

Identity assertion 193basic authentication 51Binary Der Data 254

CCA - Top Secret 228

477

callbackhandler 114caller part 114CBIND class 309Certificate

Comparing the personal certificate 286Certificate Authority (CA) 117certificates

comparing between z/OS and Windows 286extracting the z/OS signer certificate 254extracting the z/OS signer certificate, RACF command 254importing the server signer certificate into the cli-ent 254

CICS 336–337authorization and authentication support, in WAS 23

CICS Transaction Gateway (CTG)CICSECIConnector 389JCA custom principal mapping 48

cipher suite group, medium 268cipher suite group, strong 268Client Certificate Authentication 72, 98, 282Common Client Interface (CCI) 23Common Object Request Broker Architecture (CORBA) 467Common Secure Inter operability Version 2 (CSIv2) 17Common Secure Interoperability Specification v2 (CSIv2) 18Common Secure Interoperability Version 2 (CSIv2) 98

features in WAS for z/OS 306Common Secure Interoperability version 2 (CSIv2) 5, 44, 305

authentication mechanisms 307Basic Authentication 307client certificate authentication 307

identity assertion 305–307configuration

inbound authentication 317

Basic Authentication 318

client certificate authentica-tion 318

client identity types 320inbound transport 315outbound authentication 312

Basic authentication 313

client certificate authentica-tion 313

outbound transport 310example 321identity formats supported in WAS for z/OS 308

certificate 308Distinguished Name 308SAF identity 308

trust relationship 308ways of establishing trust 308

J2EE server authentication using CSIv2logical flow 45

layers 306message layer authentication 306security attribute propagation 306transport layer authentication 306

Confidentiality 3, 268CosNaming 467CosNaming security 467create 237cryptography 164CSIv2 5CSIv2 - Common Secure Interpretability

What is CSIv2? 41custom login module 16

Ddata encryption method algorithm 176Data Encryption Standard (DES) 164Data Replication Service (DRS) 299DB2 336–337, 340, 386, 388

Universal JDBC Driver Providertype 2 390type 4 390

z/OS local JDBC provider 390DefaultPrincipalMapping 48deployment descriptor 10digest code 88Digital Signature

Identity assertion 193Digital signature

how is it created? 88

EEIS - Enterprise Information Systems 336–337, 386, 388–389


EJBexecution identity 33Runas identity 33security identity 33security role 33

EJB containerprogrammatic security APIs 11

ejbActivate() method 23ejbCreate() method 23ejbLoad() method 23Enterprise Information Systems (EIS) 22errors

creating native credentials 291External Authorization Server

Authorization using external authorization serverconfiguration tasks 57

FFederated 25Federated Repositories 363

ITDS 378SPNEGO 399what are federated repositories? 363

fingerprint 88fixes

PK31729 291Form based authentication 72

GGeneral Inter-ORB Protocol (GIOP) 44Generic Security Services Username Password (GSSUP) token 315global security 71, 430group 430

HHardware Cryptography

IBMJCEcharacteristics 227

IBMJCECCAcharacteristics 227

hardware cryptography 192HFS owner user ID, adding 432HTTP Server

Authenticating in HTTP serverconfiguration tasks 37

HTTP server

authenticating in HTTP serverlogic al flow 36

HTTP(s) 13Hypertext Transfer Protocol (HTTP) 90Hyptertext Transfer protocol over SSL (HTTPS) 91

IIBM SDKs 475IBM Tivoli Access Manager 3, 48, 360, 395, 397

principal mapping module 48IBM Tivoli Access Manager for e-business (TAMeb) 17IBM Tivoli Directory Server v6 (ITDS) 340, 356, 367, 375, 475

Configuration 375How to install 375WebSphere z/OS configuration 378

IBMJCECCA 192, 222, 275ibm-webservices-bnd.xmi 112ibm-webservices-bnd.xml 110ibm-webservicesclient-bnd.xmi 111ibm-webservicesclient-ext.xmi 111ibm-webservices-ext.xmi 111ibm-webservices-ext.xml 110ICSF managed keys 192Identity Assertion

Configurationz/OS provider 199

Identity assertion 17IMS 336–337, 386, 388

authorization and authentication support, in WAS 24Connector 389JDBC Connector 389

INADDR_ANY parameter 14Integrity 3Intermediaries 80Internet 29Interoperable Inter-ORB Protocol (IIOP) 44IP/UDP layer 29

JJ2C

application contract 23connector components 23container contract 23contracts 23system contract 23

Index 479

J2EE 9Security 5

J2EE client 13J2EE client authentication using CSIv2 40

configuration tasks 43logical flow 41

J2EE Connector Architecture (JCA)custom mapping 47JCA custom principal mapping 46

J2EE deployment descriptor files 112J2EE security 10

declarative security 10programmatic security 10

J2EE security,architecture 11J2EE server

J2EE server authentication using CSIv2 43JAAS login module 59JACC - Java Contract for Containers

External authorization 385Java 2 security 5, 9Java Authentication and Authorization Service (JAAS) 19Java Authorization Contract for Containers (JACC) 25Java Contract for Containers (JACC)

authorization using external authorization server 56

Java Cryptography Extension (JCE) 222Java Cryptography Extension (JCE), IBM version 222Java Message Service (JMS) 91Java security 5java.security file 223, 275JAX-RPC 91–92JCA - J2EE Connector Architecture

JCA custom principal mappingconfiguration tasks 50

resource adapter 389JCE - Java Cryptography Extension

IBMJCECCA 227

What is JCE? 222JCECCRACFKS 276

KKDC - Key Distribution Center 392–393, 395, 398, 402, 412

z/OS 399

Kerberos 392, 397Authentication protocol 393Encryption types 411Keytab file 410Realm

WinKerbRealm 399–400zOSKerbRealm 399–400

Service Principal Name (SPN) 405key encryption method algorithm 177key information 114key locator 114key store path, WebSphere default 175keystore 226

LLDAP - Lightweight Directory Access Protocol 337–338, 378

336–337, 340Active Directory 395JOBLOG 361messages 361SAF authorization 384SLAPDCNF member 341, 351SPNEGO 399z/OS

SDBM 340–341schema 342WebSphere z/OS configuration 344

TDBM 337, 340, 350, 367configuration 351Federated Repositories 368Native Authentication configuration 360WebSphere z/OS configuration 355

WebSphere z/OS configuration for Native Authentication 362

Lightweight Directory Access Protocol (LDAP) 30Lightweight Third Party Authentication (LTPA) 16link layer, 29LSA - Local Security Authority 395, 402LTPA token 116, 302

keys 302LtpaToken 297LtpaToken2 297

MMessage Authentication Code (MAC) 222Microsoft Internet Explorer 398

SPNEGO configuration 419


Microsoft Windows Active Directory (AD) 392, 395–396, 398

Create a user account for WebSphere Applica-tion Server for z/OS 405

Microsoft Windows Server 2003 475SP 1 475SP1 401

Microsoft Windows XP Professional 2002 SP2 401Mozilla Firefox 398

SPNEGO configuration 421

Nnaming service security 467Native Authentication 359, 373

Why to use Native Authentication? 360nonce 115non-ICSF managed keys 192Non-repudiation 4NTLM credential 397

OOASIS 21Object Management Group (OMG) 5Open System Interconnection (OSI) 29Operating System (OS) security 4org.omg.CORBA.NO_PERMISSION exception 468Organization for the Advancement of Structured In-formation Standards (OASIS) 82OS thread identity 386

PPresumed Trust

Identity assertion 193

RRACDCERT 218RACF 103

Access Control Element (ACEE ) 7Attribute

AUDITOR 343CLASS 8classes, relevant to WAS on z/OS 8

APPL 8CBIND 8DIGTCERT 8DSNR 8

EJBROLE 8FACILITY 8GEJBROLE 8KERBLINK 8LOGSTRM 8SERVAUTH 8SERVER 8STARTED 8SURROGAT 9

CommandsADDUSER 432PERMIT 104, 434RACDCERT 284RDEFINE 104, 384–385, 434SETROPTS 104

Cosnaming EJB Roles 9GROUP 7How to define an EJBROLE in RACF 384keystore 215MIXEDCASE option 443mixed-case password support, enabling 443profile

segments 7profile, attributes 7RACO (ENVR Object) 7SPNEGO 399User Profiles 341

Redbooks Web Site 475Contact us xvi

RegistriesIntroduction 336Local Operating System 336, 382

Configurating WAS to use local z/OS for au-thorization 433SPNEGO 399When 337

Standalone Custom Registry 336, 338How to write a custom registry? 338SAF authorization 384

Standalone LDAP Registry 336–337, 340SDBM 340–341

configuration 341schema 342WebSphere z/OS configuration 344

TDBM 337, 340, 350configuration 351WebSphere z/OS configuration 355

Why should you use a LDAP registry? 337Remote Method Invocation over Internet Inter-ORB

Index 481

Protocol (RMI-IIOP) 91Repositories

Federated repositories 336, 338Resource Access Control Facility (RACF) 6

functionality 6profile 6

resource instances 462Reverse Proxy Security Server (RPSS)

authenticating in reverse proxy security server 37

configuration tasks 40forwarding the user id mechanisms 38logical flow 39

RMI-IIOP 13Using jax-rpc to support non-SOAP binding 92

RPSS - Reverse Proxy Security ServerTAI 395

RunAS 33

SSAF - System Authorization Facility 336

Authorization 383Delegation 385EJBROLE 385Profile mapper 385

Sample applicationsSecurityInfo 98

sas.client.props file 310SDK 1.5 5Secure Hash Algorithm (SHA-1) 164Secure Sockets Layer (SSL) 30, 91

aliases 211authentication keys 32Basic Authentication

configuring 282centrally managed 210certificate request 31certificates

deleting keystores and truststores 222deleting or adding to or from RACF keyring 217RACF commands 218

CERTB64 keyword 220CERTDER keyword 220connecting a personal certificate 230connecting to a ring 229creating a personal certificate 229creating a ring 229

deleting a CA signer certificate 222deleting a keyring 221deleting a personal certificate 222exporting a personal certificate 220exporting a signer certificate to an HFS file 220generating a signer certificate 229PKCS12B64 keyword 220PKCS12DER keyword 220removing a CA signer certificate from a keyring 221removing a personal certificate from a keyring 221viewing a list of certificates on a keyring for a user ID 218viewing certificate authority information 218viewing personal certificate information for a user ID 218

viewing in Admin console 217WebSphere

available export formats 221certificate expiration monitoring 218deleting 221expired certificates 218expired certificates, email notification 218importing 220

cipher suite 31client certificate authentication 282configuration the z/OS Web Service provider 255configuring the Web Service requestor 261configuring the Web Service requestor endpoint URL 264creating a new SSL Configuration in WAS 256creating a new SSL inbound channel in WAS 257enforcing confidentiality 271enforcing integrity 267errors

CWPKI0022E 242ICSF address space unavailable 242signer certificate is from a client’s truststore 242SSLC0008E 242starting Websphere using IBMJCECCA pro-vider 243

handshake 30


handshake errors 239handshake flow 95handshake, common errors 242hardware cryptographic support 272

configuring the Web Service provider for confidentiality 281configuring the Web Service requestor for confidentiality 281configuring the Web Service requestor SSL configuration 280connecting a CA to a keyring 272connecting a personal certificate to a keyring 273creating a new CA 272creating a new keyring 272creating a new personal certificate 273exporting the signer certificate 274HDWebServiceSSLConfig 280importing the signer certificate 274installing the unrestricted Java policy jars 275JCECCRACFKS 276JCECCRACFKS, creating a new keystore 276SSLException 281updating the JVM to use IBMJCECCA 275validating confidentiality 281viewing CA information 273viewing the personal certificate information 274

hardware cryptographyCommon Cryptographic Architecture (CCA) interfaces 222creatING a new keystore 237diagnosing SSL handshake issues 240IBMJCE4758 223IBMJCECCA 222IBMJCECCA, prereqs 223JCECCARACFKS keystore 233keys in hardware 234safkeyring URI 237unrestricted policy jars 236unrestricted policy jars, installing in Web-Sphere 236update the java.security file with the IB-MJCECCA provider 236

IBMJCE providerkeystore types

JCECCAKS 226

JCECCARACFKS 226JCEKS 225JCERACFKS 225JKS 225PKCS11 225PKCS12 225

Java Secure Socket Extension (JSSE) 213JCE provider 223keystore 226

storage 227keystore types 227–228

JCECCAKS 229JCECCARACFKS 228JCEKS 228JCERACFKS 228JKS 228PKCS11KS 229PKCS12KS 228

master secret 32NodeDefaultSSLSettings 211pre-master secret 32protocol version 31repertoire alias 210setting the cipher suite group, for Web Service provider 264symmetric encryption keys 32System SSL (SSSL) 213trace, enabling dynamically 242trace, JSSE 242traces 241traces, enabling 241transport chain 259truststore 227WebSphere

keystores, available 224WebSphere V6.0 endpoint details 213WebSphere V6.1 210WebSphere V6.1 endpoint details 214X.509 v.3 certificates 31

security attribute propagation 294attribute propagation 294benefits 295horizontal propagation 295, 298, 305

configuration 301cross-cell considerations 302Data Replication Service (DRS) 299DynaCache 299example 300JMX 299

Index 483

JMX calls 305LTPA key, sharing 303LTPA keys, sharing 304LTPA keys, sharing, automatically generated 304mechanisms, in WebSphere 299performance implications 299Single Sign On, cross-cell 303SSO token 298

identity propagation 294initial login 295JAAS Subject 294Java serialization 297Lightweight Third Party Authentication (LTPA) 296Principal 294propagation login 295Reverse Proxy Security Server (RPSS) 295Run-As 295Single Sign On (SSO) 294styles 295token framework 297vertical propagation 295Webseal 295WebSphere token framework

authentication token 297authorization token 297LtpaToken 297LtpaToken2 297propagation token 297Single Sign On 297Subject-based tokens 297thread-based token 297

security attribute propoagationvertical propagation 328

cross-cell considerations 334implementation 331Remote Method Invocation (RMI) over the Internet Inter-ORB Protocol (RMI over IIOP) 328

Security Attribute Service (SAS) 305Security Constraint 267security.xml file 218server ID 441Service Oriented Architecture (SOA) 51servlet

execution identity 33Runas identity 33security identity 33

security role 33Simple Object Access Protocol (SOAP) 90

confidentiality 89identity assertion 90integrity 87Web Services authentication 51WS-Security standard 82

Simple WebSphere Authentication Mechanism (SWAM) 16Single Sign On (SSO) 16

authenticating in HTTP server 35SOA - Service Oriented Architecture

Introduction to soa and z/OS security 76SOAP - Simple Object Access Protocol

RMI-IIOP with multiprotocol jax-rpc 92SPNEGO 391

Configuring Microsoft Internet Explorer 419Configuring Mozilla Firefox 421Configuring the JVM 416Configuring the Microsoft Windows server 404Configuring WebSphere Application Server for z/OS 414handshake 397RACF 399Troubleshooting 422What is SPNEGO? 396

SSO - Single Sign On 16SPNEGO 392WebSphere Application Server for z/OS using SPNEGO 397z/OS KDC and Microsoft Windows KDC 399

symmetric algorithm 30symmetric encryption keys 32Sync-to-OS Thread 386, 444

activation 387defining RACF profile 446What’s new in Version 6.1? 444

System Access Facility(SAF) 6System Authorization Facility (SAF) 5System Network Architecture (SNA) 29system.wssecurity.IDAssertionUsernameToken 128system.wssecurity.PKCS7 128system.wssecurity.PkiPath 128system.wssecurity.UsernameToken 128system.wssecurity.X509BST 128


TTCP layer 29Ticket

Kerberos 392–393Ticket Granting Server (TGS) 393Ticket Granting Ticket (TGT) 393

token generator 114Top Secret 5Trust association 17Trust Association Interceptor (TAI) 16, 38, 395Trust Relationship

TAI 395trust store path, WebSphere default 180truststore 227

Uunrestricted policy jars 275user 430user account repository 440User registry

federated repository 24Local Operating System (LocalOS) 24standalone custom registry 24–25standalone LDAP 24

VVirtual Member Manager (VMM) 365

WWAS - WebSphere Application Server

Accessing ITDS 378Build Number

cf20633.22 401Configuration

administration security optionDo not enable security 437Use a z/OS security product 433Use WebSphere Application Server se-curity 435

Create a user account in the AD 405JMS Provider 390OS thread identity 386SPNEGO 391, 396

Kerberos requirements 412trace 422z/OS KDC 399

Web authentication

for any URI 66for protected URIs only 65system properties

com.ibm.wsspi.security.web.webauthreq 67

Web authentication behavioradmin console, settings 65

Web containerprogrammatic security APIs 11

Web ServicesAuthentication

logic flow 52authentication 51Confidentiality

configure z/OS provider 183configure z/OS requestor 185

Identity Assertionconfigure the z/OS provider 199

Message layer security 21message layer security 78

authenticationconfiguring a token for Web Service pro-vider 123configuring a token for Web Service re-questor 119custom token 117LTPA token 116token generator, configuring 120token type 119

custom 119

Username 119

X509 certificate token 119Username token 116X.509 certificate token 116XML digital signature 117

componentscallbackhandler 114caller part 114key information 114key locator 114nonce 115timestamp 115token generator 114trust anchor 115

confidentiality 164asymmetric encryption algorithms 164configuring encryption, server 171

Index 485

configuring provider 178configuring requestor 172configuring, encryption algorithm 171encryption, algorithms 164extracting WebSphere for z/OS signer certificate 167one-way encryption algorithm 164support in WS-Security 165symmetric encryption algorithms 164

configuration components 114configuration files 111deployment descriptors 110deployment descriptors, editing tools 110deployment descriptors, format in Web-Sphere versions 110identity assertion 192

configuring 195configuring Web Service requestor 196trust modes 193trust relationship 203WS-Security support 193

integrity 131canonicalization method algorithm 143configuring the Web Service provider 146configuring the Web Service requestor 135configuring the z/OS provider for XML digital signature 154configuring the z/OS requestor for XML digital signature 159digest method algorithm 144signature method algorithm 143transform 145XML digital signature 131

integritysignature algorithm 133security token 116SOAP security header 109when to use? 80WS Binding 113WS Extension 113

security exposures 77Transport layer security 21transport layer security 78

Basic Authentication, configuring 247Basic Authentication, validating 250configuring the requestor to authenticate 249Enterprise Service Bus (ESB) 93

HTTP(S)authentication 94Basic Authentication 94Basic Authentication information 94benefits 93client certificate authentication 94integrity and confidentiality 94Universal Resource Identifier (URI) 91

JMSSSL 97

point-to-point security 93Remote Method Invocation over Internet In-ter-ORB Protocol (RMI-IIOP) 92RMI over IIOP 98

CSIv2 98SOAP over HTTP 91SOAP over JMS 92when to use? 80

Web Services Interpretability Organization (WS-I) 84Web Services Security (WS-Security) 108WebSeal 17Webseal 395WebSphere Application Server

What is new in v6.1 security? 2WebSphere Application Server (WAS)

connections 13encryption algorithms 268security settings 440

WebSphere Application Server configuration group, create 431WebSphere Application Server HFS Owner 431WebSphere Message Queueing

WMQ client authentication 53WebSphere MQ 19

communication protocols 97WebSphere MQ Extended Security Edition 97WebSphere token framework 297WebSphereCA 254WMQ - WebSphere Message Queueing

JMS Provider 390World Wide Web (WWW) 29WS Binding 113WS Extension 113WS-Authorization 22WS-Federation 22WS-Policy 22WS-Privacy 22WS-SecureConversation 22


WS-Securityauthentication mechanisms 86high level architecture 85identity assertion

basic authentication 90digital signature

90modes 90presumed trust 90

Kerberos Token Profile 84Minimalist Profile (MProf) 84Rights Expression Language (REL) Token Pro-file 83SAML Token Profile 83SOAP Message Security 1.0 83SOAP Message with Attachments (SwA) Profile 84specifications 82support in WAS V6.x 84Web Services Security Username Token Profile 1.0 83Web Services Security X.509 Certificate Token Profile 1.0 83WS-Authorization 83WS-Federation 83WS-I Basic Profile 84

support in WAS v6.0 and later 84WS-I Basic Security Profile (BSP) v1.0 84WS-Policy 82WS-Privacy 83WS-Secure Conversation 83WS-Trust 83XML digital signature 87XML encryption standard 165

Ws-SecurityXML encryption 89

WS-Security authentication mechanismbasic authentication 86custom 86ID assertion 86LTPA 86signature 86

WS-Trust 22

XX.509 certificate token 116X.509 v.3 certificates 31XML digital signature 117

Zz/OS KDC 399z/OS thread identity 389

RunAs 388synchronization 386

activation 387

Index 487


Security in WebSphere Application Server Version 6.1 and

Security in WebSphere Application

Server Version 6.1 and J2EE 1.4 on z/OS

Security in WebSphere

Application Server Version 6.1 and J2EE 1.4 on z/OS

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

®

SG24-7384-00 ISBN 0738488631

INTERNATIONAL TECHNICALSUPPORTORGANIZATION

BUILDING TECHNICALINFORMATION BASED ONPRACTICAL EXPERIENCE

IBM Redbooks are developed by the IBM International Technical Support Organization. Experts from IBM, Customers and Partners from around the world create timely technical information based on realistic scenarios. Specific recommendations are provided to help you implement IT solutions more effectively in your environment.

For more information:ibm.com/redbooks

Security in WebSphere Application Server Version 6.1and 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

This IBM® Redbooks® publication was written with the objective to provide a technical description of some of the most important security scenarios available with WebSphere® Application Server Version 6.1 for z/OS®. We chose scenarios that are not really documented elsewhere and that have had significant changes in Version 6.1.

In the first two chapters we provide an overview of security with WAS on z/OS for those readers who are unfamiliar with the security landscape on z/OS. From Chapter 3 onwards we go into more technical depth.

Back cover




Date post:	13-Oct-2020
Category:	Documents
Upload:	others
View:	6 times
Download:	0 times

Security in WebSphere Application Server Version 6.1 and J2EE … · Application Server Version 6.1...

Documents