Tivoli SecureWay Policy Director WebSEAL. Administration Guide. Version 3.8

Transcription

1 Tivoli SecureWay Policy Director WebSEAL Administration Guide Version 3.8

2

3 Tivoli SecureWay Policy Director WebSEAL Administration Guide Version 3.8

4 Tivoli SecureWay Policy Director WebSEAL Administration Guide Copyright Notice Copyright IBM Corporation All rights reserved. May only be used pursuant to a Tivoli Systems Software License Agreement, an IBM Software License Agreement, or Addendum for Tivoli Products to IBM Customer or License Agreement. No part of this publication may be reproduced, transmitted, transcribed, stored in a retrieval system, or translated into any computer language, in any form or by any means, electronic, mechanical, magnetic, optical, chemical, manual, or otherwise, without prior written permission of IBM Corporation. IBM Corporation grants you limited permission to make hardcopy or other reproductions of any machine-readable documentation for your own use, provided that each such reproduction shall carry the IBM Corporation copyright notice. No other rights under copyright are granted without prior written permission of IBM Corporation. The document is not intended for production and is furnished as is without warranty of any kind. All warranties on this document are hereby disclaimed, including the warranties of merchantability and fitness for a particular purpose. U.S. Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corporation. Trademarks IBM, the IBM logo, Tivoli, the Tivoli logo, AIX, Cross-Site, NetView, OS/2, Planet Tivoli, RS/6000, Tivoli Certified, Tivoli Enterprise, Tivoli Enterprise Console, Tivoli Ready, and TME are trademarks or registered trademarks of International Business Machines Corporation or Tivoli Systems Inc. in the United States, other countries, or both. Microsoft, Windows, Windows NT, 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. Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the United States, other countries, or both. Notices References in this publication to Tivoli Systems or IBM products, programs, or services do not imply that they will be available in all countries in which Tivoli Systems or IBM operates. Any reference to these products, programs, or services is not intended to imply that only Tivoli Systems or IBM products, programs, or services can be used. Subject to valid intellectual property or other legally protectable right of Tivoli Systems or IBM, any functionally equivalent product, program, or service can be used instead of the referenced product, program, or service. The evaluation and verification of operation in conjunction with other products, except those expressly designated by Tivoli Systems or IBM, are the responsibility of the user. Tivoli Systems or IBM may have patents or pending patent applications covering subject matter 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 the IBM Director of Licensing, IBM Corporation, North Castle Drive, Armonk, New York , U.S.A.

5 Contents Preface... xiii Who Should Read This Guide... xiii What This Guide Contains... xiv Typeface Conventions... xv Related Policy Director Documents.... xvi Accessing Online Documentation... xvi Ordering Documentation.... xviii Providing Feedback about Product Documentation... xviii Contacting Customer Support... xviii Chapter 1. WebSEAL Overview... 1 Protecting Your Web Space with WebSEAL Identifying Content Types and Levels of Protection... 3 Planning and Implementing the Security Policy... 4 Understanding WebSEAL Authentication... 5 The Goals of Authentication... 6 Understanding Credentials Acquisition The Extended Privilege Attribute Certificate (EPAC)... 8 Understanding WebSEAL Junctions... 9 WebSEAL Junctions and Web Site Scalability Chapter 2. WebSEAL Server Configuration General Server Information Introducing the webseald.conf Configuration File Root Directory of the WebSEAL Installation WebSEAL Server Root Directory Starting and Stopping WebSEAL Tivoli SecureWay Policy Director WebSEAL Administration Guide iii

6 Configuring Communication Parameters Configuring WebSEAL for HTTP Requests Configuring WebSEAL for HTTPS Requests Restricting Connections from Specific SSL Versions Configuring HTTP and HTTPS Worker Threads Timeout Parameters for HTTP/HTTPS Communication Additional WebSEAL Server Timeout Parameters Managing the Web Space Root Directory of the Web Document Tree Configuring Directory Indexing Windows: File Naming Conventions for CGI Programs Configuring Web Document Caching Configuring HTTP Error Messages Macro Support Managing Custom HTML Pages Custom Page Parameters and Values Custom HTML Page Descriptions Managing Client-side and Server-side Certificates Understanding GSKit Key Database File Types Configuring Key Database Parameters for WebSEAL Using the ikeyman Certificate Management Utility Configuring CRL Checking Configuring a Default Quality of Protection Level Configuring QOP for Individual Hosts and Networks Configuring Authorization Database Updates and Polling Configuring Update Notification Listening Configuring Authorization Database Polling Replicating Front-end WebSEAL Servers Configuring Standard HTTP Logging iv Version 3.8

7 Enabling and Disabling HTTP Logging Specifying the Timestamp Type Specifying Log File Rollover Thresholds Specifying the Frequency for Flushing Log File Buffers Configuring the Content Length Recorded in request.log HTTP Common Log Format (for request.log) Displaying the request.log File Displaying the agent.log File Displaying referer.log Chapter 3. WebSEAL Security Policy WebSEAL-specific ACL Policies /WebSEAL/<host> /WebSEAL/<host>/<file> WebSEAL ACL Permissions Default /WebSEAL ACL Policy Three Strikes Login Policy Command Syntax Password Strength Policy Password Strength Policy Set by the pdadmin Utility Command Syntax Valid and Invalid Password Examples Specific User and Global Settings Authentication Strength POP Policy (Step-up) Configuring Levels for Step-up Authentication Enabling Step-up Authentication Step-up Login Form Step-up Authentication Algorithm Step-up Authentication Notes and Limitations Tivoli SecureWay Policy Director WebSEAL Administration Guide v

8 Network-based Authentication POP Policy Configuring Authentication Levels Specifying IP Addresses and Ranges Disabling Step-up Authentication by IP Address Network-based Authentication Algorithm Network-based Authentication Notes and Limitations Quality of Protection POP Policy Handling Unauthenticated Users (HTTP / HTTPS) Processing a Request from an Anonymous Client Forcing User Login Applications of Unauthenticated HTTPS Controlling Unauthenticated Users with ACL/POP Policies Chapter 4. WebSEAL Authentication Understanding the Authentication Process Supported Session Data Types Supported Authentication Methods References to Detailed Configuration Information Managing Session State The GSKit and WebSEAL Session Caches Configuring the WebSEAL Credentials Cache Configuring the GSKit SSL Session ID Cache Maintaining State with Session Cookies Determining Valid Session ID Data Types Configuring Failover Cookies Authentication Configuration Overview Local Authentication Parameters External Custom CDAS Authentication Parameters Default Configuration for WebSEAL Authentication vi Version 3.8

9 Configuring Multiple Authentication Methods Prompting for Login Logout and Change Password Commands Configuring Basic Authentication Enabling and Disabling Basic Authentication Setting the Realm Name Configuring the Basic Authentication Mechanism Configuration Conditions Configuring Forms Authentication Enabling and Disabling Forms Authentication Configuring the Forms Authentication Mechanism Configuration Conditions Customizing HTML Response Forms Configuring Client-side Certificate Authentication Background: Mutual Authentication via Certificates The WebSEAL Test Certificate Enabling and Disabling Certificate Authentication Configuring the Certificate Authentication Mechanism Configuration Conditions Configuring HTTP Header Authentication Enabling and Disabling HTTP Header Authentication Specifying Header Types Configuring the HTTP Header Authentication Mechanism Configuration Conditions Configuring IP Address Authentication Enabling and Disabling IP Address Authentication Configuring the IP Address Authentication Mechanism Configuring Token Authentication Enabling and Disabling Token Authentication Tivoli SecureWay Policy Director WebSEAL Administration Guide vii

10 Configuring the Token Authentication Mechanism Supporting Multiplexing Proxy Agents Valid Session Data Types and Authentication Methods Authentication Process Flow for MPA and Multiple Clients Enabling and Disabling MPA Authentication Create a User Account for the MPA Add the MPA Account to the webseal-mpa-servers Group MPA Authentication Limitations Chapter 5. Cross Domain Sign-on Solutions Configuring CDSSO Authentication Integrating a Custom CDMF Shared Library Authentication Process Flow for CDSSO with CDMF Enabling and Disabling CDSSO Authentication Configuring the CDSSO Authentication Mechanism Encrypting the Authentication Token Data Configuring the Token Time Stamp Expressing CDSSO HTML Links Protecting the Authentication Token Configuring e-community Single Sign-on e-community Features and Requirements e-community Process Flow Understanding the e-community Cookie Understanding the Vouch For Request and Reply Understanding the Vouch For Token Encrypting the Vouch For Token Configuring an e-community Chapter 6. WebSEAL Junctions WebSEAL Junctions Overview viii Version 3.8

11 Junction Database Location and Format Applying Coarse-Grained Access Control: Summary Applying Fine-Grained Access Control: Summary Guidelines for Creating WebSEAL Junctions WebSEAL Only Supports HTTP 1.0 Across Junctions Additional References for WebSEAL Junctions Using pdadmin server task to Create Junctions Configuring a Basic WebSEAL Junction TCP Type Junctions SSL Type Junctions Mutually Authenticated SSL Junctions WebSEAL Validates Back-end Server Certificate Distinguished Name (DN) Matching WebSEAL Authenticates with Client Certificate WebSEAL Authenticates with BA Header Handling Client Identity Information Across Junctions Creating TCP and SSL Proxy Junctions WebSEAL-to-WebSEAL Junctions Over SSL Additional Junction Options Forcing a New Junction ( f) Supplying Client Identity in HTTP Headers ( c) Supplying Client IP Addresses in HTTP Headers ( r) Passing Session Cookies to Junctioned Portal Servers ( k) Supporting Case-Insensitive URLs ( i) Processing URLs From Scripts and Client-side Applications ( j) Handling Server-relative URLs with Junction Mapping Stateful Junction Support ( s, u) Specifying Back-End Server UUIDs for Stateful Junctions ( u) Junctioning to Windows File Systems ( w) Tivoli SecureWay Policy Director WebSEAL Administration Guide ix

12 Technical Notes for Using WebSEAL Junctions: Mounting Multiple Servers at the Same Junction Filtering Static HTML URLs from Junctioned Servers Exceptions to Enforcing Permissions Across Junctions Certificate Authentication Across Junctions Using query_contents with Third-Party Servers Installing query_contents Installing query_contents on Third-Party UNIX Servers Installing query_contents on Third-Party Win32 Servers Customizing query_contents Securing query_contents Chapter 7. Web Single Sign-on Solutions Configuring BA Headers for Single Sign-on Solutions Single Sign-On (SSO) Concepts Supplying Client Identity in BA Headers Supplying Client Identity and Generic Password Forwarding Original Client BA Header Information Removing Client BA Header Information Supplying User names and Passwords from GSO Using Global Sign-on (GSO) Mapping the Authentication Information Configuring a GSO-Enabled WebSEAL Junction Configuring the GSO Cache Single Sign-on to IBM WebSphere (LTPA) Configuring an LTPA Junction Configuring the LTPA Cache Technical Notes for LTPA Single Sign-on Chapter 8. Application Integration x Version 3.8

13 Supporting CGI Programming Windows: Supporting WIN32 Environment Variables Supporting Back-End Server-Side Applications Enabling Dynamic Business Entitlements Creating Business Entitlements from LDAP Data Building a Custom Personalization Service Configuring WebSEAL for a Personalization Service Personalization Service Example Providing Access Control to Dynamic URLs Dynamic URL Components Mapping ACL Objects to Dynamic URLs Updating WebSEAL for Dynamic URLs Resolving Dynamic URLs in the Object Space Configuring Limitations on POST Requests Summary and Technical Notes Dynamic URL Example: The Travel Kingdom The Application The Interface The Security Policy Secure Clients Access Control Conclusion Appendix A. webseald.conf Reference Appendix B. WebSEAL Junction Reference Using pdadmin server task to Create Junctions The Junction Commands Create a New Junction for an Initial Server Tivoli SecureWay Policy Director WebSEAL Administration Guide xi

14 Add an Additional Server to an Existing Junction Appendix C. Managing Certificates with ikeyman 249 Starting the ikeyman Utility Opening the Default WebSEAL Key Database Creating a New Key Database Creating a New Self-signed Digital Certificate Adding a New Root CA Certificate Deleting a Root CA Certificate Copying Certificates Between Databases Extract Certificate to a File; Add Certificate from a File Import Certificate Directly from a Database Export Certificate Directly to a Database Requesting a Server Certificate Receiving a Digital Certificate Deleting a Digital Certificate Assigning a New Default Certificate Changing a Database Password Index xii Version 3.8

15 Preface Welcome to the Tivoli SecureWay Policy Director WebSEAL Administration Guide. Tivoli SecureWay Policy Director WebSEAL is the Policy Director resource security manager for Web-based resources. WebSEAL is a high performance, multi-threaded Web server that applies fine-grained security policy to the protected Web object space. WebSEAL can provide single sign-on solutions and incorporate back-end Web application server resources into its security policy. This administration guide provides a comprehensive set of procedures and reference information for managing the resources of your secure Web domain. This guide also provides you with valuable background and concept information for the wide range of WebSEAL functionality. Who Should Read This Guide The target audience for this guide includes: Security administrators System installation and deployment administrators Network system administrators IT architects Application developers Tivoli SecureWay Policy Director WebSEAL Administration Guide xiii

16 What This Guide Contains Chapter 1: WebSEAL Overview This chapter introduces you to important WebSEAL concepts and functionality such as: organizing and protecting your object space, authentication, credentials acquisition, and WebSEAL junctions. Chapter 2: WebSEAL Server Configuration This chapter is a technical reference for general WebSEAL configuration tasks, including: managing the Web space, timeout parameters, managing certificates, handling unauthenticated users, and WebSEAL-specific ACL and POP policies. Chapter 3: WebSEAL Security Policy This chapter provides detailed technical procedures for customizing security policy on WebSEAL, including: ACL and POP policies, quality of protection, step-up authentication policy, network-based authentication policy, three-strikes login policy, and password strength policy. Chapter 4: WebSEAL Authentication This chapter provides detailed technical procedures for setting up WebSEAL to manage a variety of authentication methods, including: user name and password, client-side certificates, SecurID token passcode, and special HTTP header data. Chapter 5: Cross Domain Sign-on Solutions This chapter discusses cross domain sign-on solutions for the external side of a WebSEAL proxy configuration between the client and the WebSEAL server. Chapter 6: WebSEAL Junctions This chapter is a complete technical reference for setting up and using WebSEAL junctions. Chapter 7: Web Single Sign-on Solutions This chapter discusses single sign-on solutions for the internal side of a WebSEAL proxy configuration between the WebSEAL server and the back-end junctioned application server. xiv Version 3.8

17 Chapter 8: Application Integration This chapter explores a variety of WebSEAL capabilities for integrating third-party application functionality. Appendix A: webseald.conf Reference Appendix B: WebSEAL Junction Reference Appendix C: Managing Certificates with ikeyman Typeface Conventions This guide uses several typeface conventions for special terms and actions. These conventions have the following meaning: Bold Italics Monospace Command names and options, keywords, and other information that you must use literally appear in bold. Variables, command arguments, and values you must provide appear in italics. Titles of publications and special words or phrases that are emphasized also appear in italics. Code examples, command lines, screen output, file and directory names, and system messages appear in monospace font. Tivoli SecureWay Policy Director WebSEAL Administration Guide xv

18 Related Policy Director Documents The following table summarizes some of the available Policy Director documentation, located on the Tivoli SecureWay Policy Director support site: Tivoli SecureWay Policy Director Technical Documents Installation Guides Tivoli SecureWay Policy Director Base Installation Guide Tivoli SecureWay Policy Director WebSEAL Installation Guide Administration Guides Tivoli SecureWay Policy Director Base Administration Guide Tivoli SecureWay Policy Director WebSEAL Administration Guide (this document) Tivoli SecureWay Policy Director Plug-in for Edge Server Administration Guide Tivoli SecureWay Policy Director Web Portal Manager Administration Guide Developer References Tivoli SecureWay Policy Director Authorization ADK Developer Reference Tivoli SecureWay Policy Director Authorization API Java Wrappers Developer Reference Tivoli SecureWay Policy Director Administration API Developer Reference Tivoli SecureWay Policy Director WebSEAL Developer Reference Supplemental Documentation Tivoli SecureWay Policy Director Release Notes Tivoli SecureWay Policy Director Performance Tuning Guide Tivoli SecureWay Policy Director Capacity Planning Guide Accessing Online Documentation The Tivoli Customer Support Web site ( provides links to the following documentation information: xvi Version 3.8

19 Technical information, including release notes, installation and configuration guides, administration guides, and developer references. Frequently Asked Questions (FAQs) Software download information You can find the Customer Support Handbook (a guide to support services) at: You can access the index of online Tivoli publications at Click on Master Index to find product-specific support pages. You can locate Policy Director technical documentation, by product version, at: The documentation for some products is available in PDF and HTML formats. Translated documents are also available for some products. To access most of the documentation, you need an ID and a password. To obtain an ID for use on the support Web site, go to Resellers should refer to for more information about obtaining Tivoli technical documentation and support. Business Partners should refer to Ordering Documentation on page xviii for more information about obtaining Tivoli technical documentation. Tivoli SecureWay Policy Director WebSEAL Administration Guide xvii

20 Ordering Documentation Order Tivoli documentation online at or by calling one of the following telephone numbers: U.S. customers: (800) Canadian customers: (800) Providing Feedback about Product Documentation We are very interested in hearing about your experience with Tivoli products and documentation, and we welcome your suggestions for improvements. If you have comments or suggestions about our products and documentation, contact us in one of the following ways: Send to Fill out our customer feedback survey at Contacting Customer Support The Tivoli Customer Support Handbook at: provides information about all aspects of Tivoli Customer Support, including the following: Registration and eligibility How to contact support, depending on the severity of your problem Telephone numbers and addresses, depending on the country you are in What information you should gather before contacting support xviii Version 3.8

21 1 WebSEAL Overview 1. WebSEAL Overview Tivoli SecureWay Policy Director WebSEAL is a high performance, multi-threaded Web server that applies fine-grained security policy to the protected Web object space. WebSEAL can provide single sign-on solutions and incorporate back-end Web application server resources into its security policy. This overview chapter introduces you to the main capabilities of the WebSEAL server. Topic Index: Protecting Your Web Space with WebSEAL on page 1 Understanding WebSEAL Authentication on page 5 Understanding Credentials Acquisition on page 7 Understanding WebSEAL Junctions on page 9 Protecting Your Web Space with WebSEAL Tivoli SecureWay Policy Director WebSEAL is the Policy Director resource security manager for Web-based resources. WebSEAL is a high performance, multi-threaded Web server that applies fine-grained security policy to the protected Web object space. WebSEAL can provide single sign-on solutions and incorporate back-end Web application server resources into its security policy. Tivoli SecureWay Policy Director WebSEAL Administration Guide 1

22 WebSEAL provides the following features: Supports multiple authentication methods Both built-in and plug-in architectures allow flexibility in supporting a variety of authentication mechanisms. Accepts HTTP and HTTPS requests Integrates and protects back-end server resources through WebSEAL junction technology Manages fine-grained access control for the local and back-end server Web space Supported resources include URLs, URL-based regular expressions, CGI programs, HTML files, Java servlets, and Java class files. Performs as a reverse Web proxy WebSEAL appears as a Web server to clients and appears as a Web browser to the junctioned back-end servers it is protecting. Provides single sign-on capabilities Authentication Secured Web Object Space / Client WebSEAL WebSEAL junction Web Application Server supports multiple authentication methods integrates Authorization Service manages fine-grain control of web resources handles variety of resource types incorporates and secures back-end server resources unified protected Web resource space provides single sign-on solutions Figure 1. Protecting the Web Space with WebSEAL 2 Version 3.8

23 Identifying Content Types and Levels of Protection As the security administrator of your Web space, you must correctly identify the types of content available to a variety of user types. Some content must be highly protected and available only to specific users; other content is for general public view. Each security scenario demands different protection requirements and the associated WebSEAL configuration. It is your responsibility to: Know your Web content Identify the types of users requiring access to this content Understand the strengths and weaknesses of the available WebSEAL configuration options for securing this content 1. WebSEAL Overview Protection of Web content falls into three broad categories: 1. Public content access requires no protection Unauthenticated clients access via HTTP Unauthenticated credential used for access control to resources Basic WebSEAL configuration requirements 2. Public content access requires privacy (encryption) Unauthenticated clients access via HTTPS Encryption required to protect sensitive data required by application server (such as credit card numbers and user account information) Unauthenticated credential used for access control to resources WebSEAL configuration needs to stipulate privacy 3. Private content access requires authentication Authenticated clients access via HTTP or HTTPS Administrator determines the need for encryption Tivoli SecureWay Policy Director WebSEAL Administration Guide 3

24 Authenticated credential used for access control to resources; clients must have account defined in user registry WebSEAL configuration is complex and all options must be considered carefully to determine impact of security policy Planning and Implementing the Security Policy A corporate security policy identifies: 1. The Web resources requiring protection 2. The level of protection Policy Director uses a virtual representation of these Web resources, called the protected object space. The protected object space contains objects that represent actual physical resources in your network. You implement security policy by applying the appropriate security mechanisms to the objects requiring protection. Security mechanisms include: Access control list (ACL) policies ACL policies identify user types who can be considered for access and specify the operations permitted on the object. Protected object policies (POP) A POP specifies additional conditions governing the access to the protected object, such as privacy, integrity, auditing, and time-of-day access. Extended attributes Extended attributes are additional values placed on an object, ACL, or POP that can be read and interpreted by third-party applications (such as an external authorization service). The core component of Policy Director is the Authorization Service which permits or denies access to protected objects (resources) based on the user s credentials and the access controls placed on the objects. 4 Version 3.8

25 To successfully implement the security policy, you must logically organize the different content types (as described in Planning and Implementing the Security Policy on page 4) and apply the appropriate ACL and POP policies. Access control management can be very complex and is made much easier by careful categorization of the content types. Understanding WebSEAL Authentication Authentication is the method of identifying an individual process or entity attempting to login to a secure domain. When both server and client require authentication, the exchange is known as mutual authentication. 1. WebSEAL Overview Who are you? Client WebSEAL Who are you? Figure 2. Mutual Authentication WebSEAL can enforce a high degree of security in a secure domain by requiring each client to provide proof of its identity. When access to every resource in a secure domain is controlled by WebSEAL, WebSEAL s demands for authentication and authorization can provide very comprehensive network security. In security architecture, authentication is distinct from authorization. Authorization determines whether an authenticated user has the right to perform an operation on a specific resource. Authentication ensures that the individual is who it claims to be, but says nothing about the ability to perform operations on a resource. The following conditions apply to WebSEAL authentication: Tivoli SecureWay Policy Director WebSEAL Administration Guide 5

26 WebSEAL supports a standard set of authentication methods. You can customize WebSEAL to support other authentication methods. The WebSEAL process is independent of the authentication method. WebSEAL only requires a client identity. From this identity, WebSEAL obtains an authenticated (or unauthenticated) credential that can be used by the Authorization Service to permit or deny access to resources. This flexible approach to authentication allows security policy to be based on business requirements and not physical network topology. The Goals of Authentication Although WebSEAL is independent of the authentication process, WebSEAL requires the results of authentication the client identity.the authentication process results in the following actions: 1. The authentication method results in a client identity Client authentication is only successful if the user has an account defined in the Policy Director user registry. Otherwise the user is designated as unauthenticated. 2. WebSEAL uses the identity to acquire credentials for that client WebSEAL matches the authenticated client identity with a registered Policy Director user. WebSEAL then obtains the credentials appropriate to this user. This is known as credentials acquisition. Credentials include the user name and any groups where the user has membership. If a user is anonymous, WebSEAL builds an unauthenticated credential. These credentials are available to the Authorization Service which permits or denies access to requested objects in the WebSEAL protected object space. 6 Version 3.8

27 Credentials can be used by any Policy Director service that requires information about the client. Credentials allow Policy Director to securely perform a multitude of services such as authorization, auditing, and delegation. See WebSEAL Authentication on page 79 for further information about support for specific authentication methods. Understanding Credentials Acquisition One of the primary goals of the authentication process is to acquire credential information describing the client user. The user credential is one of the key requirements for participating in the secure domain. 1. WebSEAL Overview Policy Director distinguishes the authentication of the user from the acquisition of credentials. A user s identity is always constant. However, credentials which define the groups or roles in which a user participates are variable. Context-specific credentials can change over time. For example, when a person is promoted, credentials must reflect the new responsibility level. The authentication process results in method-specific user identity information. This information is checked against user account information that resides in the Policy Director user registry (LDAP by default). WebSEAL maps the user name and group information to a common domain-wide representation and format known as the Extended Privilege Attribute Certificate (EPAC). Tivoli SecureWay Policy Director WebSEAL Administration Guide 7

28 Method-Specific Identity Information Policy Director Credentials Username/password Token passcode Custom HTTP header X.509 certificate EPAC Figure 3. Mapping Identity Information to Credentials Method-specific identity information, such as passwords, tokens, and certificates, represent physical identity properties of the user. This information can be used to establish a secure session with the server. The resulting credential, that represents a user s privileges in the secure domain, describes the user in a specific context and is only valid for the lifetime of that session. Policy Director credentials contain the user identity and groups where this user has membership. The Extended Privilege Attribute Certificate (EPAC) Credentials are used by any Policy Director service that requires information about the client. For example, the Authorization Service uses credentials to determine whether a user is authorized to perform specific operations on a protected resource in the secure domain. EPACs contain the Unique Universal Identifiers (UUIDs) that Policy Director needs to work with access control lists (ACLs). Policy Director uses credentials for other services such as: Auditing Service Delegation capabilities in WebSEAL junctions 8 Version 3.8

29 The following EPAC fields are appropriate to Policy Director: Attribute Secure Domain ID Principal UUID Group UUIDs Description Principal s home secure domain identifier UUID of the principal UUID(s) of groups to which the principal belongs 1. WebSEAL Overview Understanding WebSEAL Junctions Policy Director provides authentication, authorization, and management services for a network. In a Web-based network, these services are best provided by one or more front-end WebSEAL servers that integrate and protect Web resources and applications located on back-end Web servers. The connection between a WebSEAL server and a back-end Web application server is known as a WebSEAL junction, or junction. A WebSEAL junction is a TCP/IP connection between a front-end WebSEAL server and a back-end server. The back-end server can be another WebSEAL server or, more commonly, a third-party Web application server. The back-end server Web space is connected to the WebSEAL server at a specially designated junction (mount) point in the WebSEAL namespace. Tivoli SecureWay Policy Director WebSEAL Administration Guide 9

30 Secure Domain Client WebSEAL / TCP or SSL Web Application Server /mnt Junction Figure 4. Junctions Connect WebSEAL with Back-End Servers A junction allows WebSEAL to provide protective services on behalf of the back-end server. WebSEAL can perform authentication and authorization checks on all requests before passing those requests on to the back-end server. If the back-end server requires fine-grained access control on its objects, you must perform additional configuration steps to describe the third-party Web space to the Policy Director security service (see Using query_contents with Third-Party Servers on page 178). Junctions provide a scalable, secure environment that allows load balancing, high availability, and state management capabilities all performed transparent to clients. As an administrator, you can benefit from this centralized management of the namespace. WebSEAL junctions provide the added value of logically combining the Web space of a back-end server with the Web space of the WebSEAL server. Junctions between cooperating servers result in a single, unified, distributed Web space that is seamless and transparent to users. The client never needs to know the physical location of a Web resource. WebSEAL translates logical URL addresses into the 10 Version 3.8

31 physical addresses that a back-end server expects. Web objects can be moved from server to server without affecting the way the client accesses those objects. A unified Web space simplifies the management of all resources for the system administrator. Additional administrative benefits include scalability, load balancing, and high availability. 1. WebSEAL Overview / WebSEAL Web space junction-point / Combined Web space: WebSEAL plus junctioned server Figure 5. WebSEAL Junction Results in a Unified Web Space Most commercial Web servers do not have the ability to define a logical Web object space. Instead, their access control is connected to the physical file and directory structure. WebSEAL junctions can transparently define an object space that reflects organizational Tivoli SecureWay Policy Director WebSEAL Administration Guide 11

32 structure rather than the physical machine and directory structure commonly encountered on standard Web servers. WebSEAL junctions also allow you to create single sign-on solutions. A single sign-on configuration allows a user to access a resource, regardless of the resource s location, using only one initial login. Any further login requirements from back-end servers are handled transparent to the user. WebSEAL junctions are an important tool for making your Web site scalable. Junctions allow you to respond to increasing demands on a Web site by attaching additional servers. WebSEAL Junctions and Web Site Scalability WebSEAL junctions are used to create a scalable Web site. As the demands on the Web site grow, more servers can easily be added to expand the capabilities of the site. Additional servers can be added for the following reasons: To extend the site with additional content To duplicate existing content for load balancing, fail-over capability, and high availability Replicated Front-End WebSEAL Servers Junction support for back-end servers starts with at least one front-end WebSEAL server. Replicated front-end WebSEAL servers provide the site with load balancing during periods of heavy demand. The load balancing mechanism is handled by a mechanism such as IBM Network Dispatcher or Cisco Local Director. Front-end replication also provides the site with fail-over capability if a server fails for some reason, the remaining replica servers will continue to provide access to the site. Successful load balancing and fail-over capability results in high availability for users of the site. 12 Version 3.8

33 SSL Client Internet Load-Balancing mechanism SSL Client 1. WebSEAL Overview WebSEAL Server Primary WebSEAL Server Replica Figure 6. Replicated Front-End WebSEAL Servers When you replicate front-end WebSEAL servers, each server must contain an exact copy of the Web space and the junction database. Account information for authentication resides in a user registry that is independent of the front-end servers. Supporting Back-End Servers Web site content can be served by the WebSEAL server itself, back-end servers, or a combination of both. WebSEAL junction support for back-end servers allows you to scale the Web site through additional content and resources. Each unique back-end server must be junctioned to a separate junction (mount) point. As the demand for additional content grows, more servers can be added through junctions. This scenario provides a solution for networks that have a large existing investment in third-party Web servers. Tivoli SecureWay Policy Director WebSEAL Administration Guide 13

34 SSL Client Internet SSL Client Load-Balancing mechanism WebSEAL Server Primary WebSEAL Server Replica Third-Party Server /engineering Third-Party Server /sales Figure 7. Junctioning Back-End Servers The following diagram illustrates how junctions provide a unified, logical object space. This Web space is transparent to the user and allows for centralized management. 14 Version 3.8

35 Engineering Junction Web Object Space / Sales Junction 1. WebSEAL Overview Figure 8. Unified Web Space Replicated back-end servers are junctioned to the same junction point, as discussed in the next section. Replicated Back-End Servers To extend scalability features to a back-end server configuration, you can replicate the back-end servers. As is the case with replicated front-end servers, replicated back-end servers must contain Web spaces that are mirror images of each other. WebSEAL load balances across the replicated servers using a least-busy scheduling algorithm. This algorithm directs each new request to the server with the fewest connections already in progress. WebSEAL will also correctly fail-over when a server is down and start re-using that server once it has been restarted. If the back-end application requires state to be maintained over several pages, stateful junctions can be used to ensure that each session returns to the same back-end server. Tivoli SecureWay Policy Director WebSEAL Administration Guide 15

36 SSL Client Internet SSL Client Load-Balancing mechanism WebSEAL Server Primary WebSEAL Server Replica Replicated Front-End Servers Replicated Engineering Servers Replicated Sales Servers Figure 9. Replicated Back-End Servers 16 Version 3.8

37 2 WebSEAL Server Configuration This chapter contains information that describes general administration and configuration tasks you can perform to customize the WebSEAL server for your network. Topic Index: General Server Information on page 18 Configuring Communication Parameters on page 21 Managing the Web Space on page 25 Configuring HTTP Error Messages on page 32 Managing Custom HTML Pages on page 36 Managing Client-side and Server-side Certificates on page 38 Configuring a Default Quality of Protection Level on page 44 Configuring Authorization Database Updates and Polling on page 46 Replicating Front-end WebSEAL Servers on page 48 Configuring Standard HTTP Logging on page WebSEAL Server Configuration Tivoli SecureWay Policy Director WebSEAL Administration Guide 17

38 General Server Information The following sections describe general information about the WebSEAL server: Introducing the webseald.conf Configuration File on page 18 Root Directory of the WebSEAL Installation on page 19 WebSEAL Server Root Directory on page 20 Starting and Stopping WebSEAL on page 20 Introducing the webseald.conf Configuration File You can customize the operation of WebSEAL by configuring the parameters located in the webseald.conf configuration file. The file is located in the following directory: UNIX: /opt/pdweb/etc/ Windows: C:\Program Files\Tivoli\PDWeb\etc\ The following table summarizes the sections and stanzas: Sections WEBSEAL GENERAL LDAP SSL JUNCTION Stanzas [server] [ldap] [ssl] [junction] [filter-url] [filter-schemes] [script-filtering] [gso-cache] [ltpa-cache] 18 Version 3.8

39 Sections AUTHENTICATION SESSION CONTENT LOGGING AUTHORIZATION API POLICY DIRECTOR Stanzas [ba] [forms] [token] [certificate] [http-headers] [auth-headers] [ipaddr] [authentication-levels] [mpa] [cdsso] [cdsso-peers] [failover] [e-community-sso] [inter-domain-keys] [authentication-mechanisms] [ssl-qop] [ssl-qop-mgmt-hosts] [ssl-qop-mgmt-networks] [ssl-qop-mgmt-default] [session] [content] [acnt-mgt] [cgi] [cgi-types] [cgi-environment-variable] [content-index-icons] [icons] [content-cache] [content-mime-types] [content-encodings] [logging] [aznapi-configuration] [aznapi-entitlement-services] [policy-director] 2. WebSEAL Server Configuration See webseald.conf Reference on page 225. Note: Anytime you make a change to the webseald.conf file, you must manually restart WebSEAL so that the new changes are recognized. See Starting and Stopping WebSEAL on page 20. Root Directory of the WebSEAL Installation WebSEAL program files are installed in the following root directory: UNIX: /opt/pdweb/ Windows: C:\Program Files\Tivoli\PDWeb\ Tivoli SecureWay Policy Director WebSEAL Administration Guide 19

40 You can configure this path on a Policy Director for Windows installation. You cannot configure this path on UNIX installations of Policy Director. This guide uses the <install-path> variable to represent this root directory. On UNIX installations, the following separate directory contains expandable files, such as audit and log files: /var/pdweb/ WebSEAL Server Root Directory The server-root parameter in the webseald.conf configuration file defines the location of the WebSEAL server operation at start-up. [server] server-root = /opt/pdweb/www All relative path names expressed in the webseald.conf configuration file are relative to this root directory. Note: Under normal conditions, you should not change this pathname. Starting and Stopping WebSEAL You can start and stop the WebSEAL server process using the pdweb_start command on UNIX and using the Services Control Panel on Windows. UNIX: pdweb_start {start stop restart status} For example, to stop the WebSEAL server and then restart the server, use: # pdweb_start restart The pdweb_start command is located in the following directory: /opt/pdweb/bin/ Windows: 20 Version 3.8

41 Identify the WebSEAL server process in the Services Control Panel and use the appropriate control buttons. Configuring Communication Parameters The following sections describe general information about the WebSEAL server: Configuring WebSEAL for HTTP Requests on page 21 Configuring WebSEAL for HTTPS Requests on page 22 Restricting Connections from Specific SSL Versions on page 22 Configuring HTTP and HTTPS Worker Threads on page 22 Timeout Parameters for HTTP/HTTPS Communication on page 23 Additional WebSEAL Server Timeout Parameters on page 24 Configuring WebSEAL for HTTP Requests WebSEAL typically handles many HTTP requests from unauthenticated users. For example, it is common to allow anonymous users read-only access to selected documents on the public section of your Web site. 2. WebSEAL Server Configuration Parameters for handling HTTP requests over TCP are located in the [server] stanza of the webseald.conf configuration file. Enabling/Disabling HTTP Access Enable or disable HTTP access during WebSEAL configuration: http = {yes no} Setting the HTTP Access Port Value The default port for HTTP access is 80: http-port = 80 To change to port 8080, for example, set: http-port = 8080 Tivoli SecureWay Policy Director WebSEAL Administration Guide 21

42 Configuring WebSEAL for HTTPS Requests Parameters for handling HTTP requests over SSL (HTTPS) are located in the [server] stanza of the webseald.conf configuration file. Enabling/Disabling HTTPS Access Enable or disable HTTPS access during WebSEAL configuration: https = {yes no} Setting the HTTPS Access Port Value The default port for HTTPS access is 443: https-port = 443 To change to port 4343, for example, set: https-port = 4343 Restricting Connections from Specific SSL Versions You can independently enable and disable connectivity for SSL version 2, SSL version 3, and TLS version 1. The parameters that control connections for specific SSL and TLS versions are located in the [ssl] stanza of the webseald.conf configuration file. By default, all SSL and TLS versions are enabled. [ssl] disable-ssl-v2 = no disable-ssl-v3 = no disable-tls-v1 = no Configuring HTTP and HTTPS Worker Threads The number of configured worker threads specifies the number of concurrent incoming requests that can be serviced by a server. Other connections that arrive when all worker threads are busy will be buffered until a worker thread is available. You can set the number of threads available to service incoming connections to WebSEAL. Configuring the number of worker threads should be done carefully due to possible performance impacts. 22 Version 3.8

43 This configuration parameter does not impose an upper boundary on the number of simultaneous connections. This parameter simply specifies the number of threads made available to service a potentially unlimited work queue. Choosing the optimal number of worker threads depends on understanding the quantity and type of traffic on your network. By increasing the number of threads, you are, in general, decreasing the average time it takes to finish the requests. However, increasing the number of threads impacts other factors which could have an adverse effect on server performance. WebSEAL maintains a single, generic worker list and worker threads pool for handling requests from clients using TCP, SSL, or GSSAPI tunneling. This enhanced mechanism enables WebSEAL to consume fewer system resources while handling significantly greater load. You can configure the worker thread pool size by setting the worker-threads parameter in the [server] stanza portion of the webseald.conf configuration file. [server] worker-threads = WebSEAL Server Configuration Note: It is highly recommended that this parameter only be changed to troubleshoot a performance problem. Timeout Parameters for HTTP/HTTPS Communication WebSEAL uses the IBM Global Security Kit (GSKit) implementation of SSL. When WebSEAL receives a request from an HTTPS client, GSKit SSL establishes the initial handshake and maintains session state. WebSEAL supports the following timeout parameters for HTTP and HTTPS communication. These parameters are located in the [server] stanza of the webseald.conf configuration file. client-connect-timeout Tivoli SecureWay Policy Director WebSEAL Administration Guide 23

44 Once the initial handshake has occurred, this parameter dictates how long WebSEAL holds the connection open for the initial HTTP or HTTPS request. The default is 120 seconds. [server] client-connect-timeout = 120 persistent-con-timeout This parameter is specific to HTTP/1.1 (not HTTP/1.0) connections. After the first HTTP/1.1 request and server response, this parameter controls maximum number of seconds WebSEAL holds an HTTP/1.1 persistent connection open before it is shutdown. The default value is 5 seconds. [server] persistent-con-timeout = 5 Connect SSL Handshake GSKit controlled Client HTTP Request Response HTTP Request client-connect-timeout WebSEAL persistent-con-timeout (HTTP/1.1 only) Figure 10. Timeout Parameters for HTTP and HTTPS Communication Additional WebSEAL Server Timeout Parameters The following additional timeout parameters are set in the webseald.conf configuration file: 24 Version 3.8

45 Parameter Description Default Value (seconds) [junction] http-timeout [junction] https-timeout [cgi] cgi-timeout [junction] ping-time The timeout value for sending to and reading from a back-end server over a TCP junction. The timeout value for sending to and reading from a back-end server over an SSL junction. The timeout value for sending to and reading from a local CGI process. WebSEAL performs a periodic background ping of each junctioned server to determine whether it is running. WebSEAL will not try more often than once every 300 seconds (or whatever value is set) WebSEAL Server Configuration Managing the Web Space The following sections describe tasks required to manage the Web space: Root Directory of the Web Document Tree on page 25 Configuring Directory Indexing on page 27 Windows: File Naming Conventions for CGI Programs on page 28 Configuring Web Document Caching on page 29 Root Directory of the Web Document Tree The Web document tree location is the absolute path to the root of the document tree for documents made available by WebSEAL. This path name is represented by the doc-root parameter in the [content] Tivoli SecureWay Policy Director WebSEAL Administration Guide 25

46 stanza of the webseald.conf configuration file. The default location is initially established during the installation of WebSEAL: UNIX: doc-root = /opt/pdweb/www/docs Windows: doc-root = C:\Program Files\Tivoli\PDWeb\www\docs This value is only used once the first time WebSEAL is started after installation. The value is then stored in the junction database. Future modification of this value in webseald.conf has no impact. After installation, you must use the pdadmin utility to change the document root directory location value. The following example (server name is webseala) illustrates this procedure: 1. Login to pdadmin: # pdadmin pdadmin> login Enter User ID: sec_master Enter Password: pdadmin> 2. Use the server task list command to display all current junction points: pdadmin> server task webseala list / 3. Use the server task show command to display details of the junction: pdadmin> server task webseala show / Junction point: / Type: Local Junction hard limit: 0 -using global value Junction soft limit: 0 -using global value Active worker threads: 0 Root Directory: /opt/pdweb/www/docs 4. Create a new local junction to replace the current junction point (the -f option is required to force a new junction that overwrites an existing junction): 26 Version 3.8

47 pdadmin> server task webseala create -t local -f -d /tmp/docs / Created junction at / 5. List the new junction point: pdadmin> server task webseala list / 6. Display the details of this junction: pdadmin> server task webseala show / Junction point: / Type: Local Junction hard limit: 0 -using global value Junction soft limit: 0 -using global value Active worker threads: 0 Root Directory: /tmp/docs Configuring Directory Indexing You can specify the name of the default file returned by WebSEAL when the URL expression of a request ends with a directory name. If this default file exists, WebSEAL returns the file to the client. If the file does not exist, WebSEAL dynamically generates a directory index and returns the list to the client. 2. WebSEAL Server Configuration The parameter for configuring the directory index file is located in the [content] stanza of the webseald.conf configuration file. The default value for the index file is: [content] directory-index = index.html You can change this filename if your site uses a different convention. For example: [content] directory-index = homepage.html WebSEAL dynamically generates a directory index if the directory in the request does not contain the index file defined by the directory-index parameter. The generated index contains a list of the directory contents, with links to each entry in the directory. The index is only generated if the client requesting access to the directory has the list (l) permission on the ACL for that directory. Tivoli SecureWay Policy Director WebSEAL Administration Guide 27

48 You can configure the specific graphical icons used by WebSEAL for each file type listed in a generated index. The [content-index-icons] stanza of the webseald.conf configuration file contains a list of the document MIME types and the associated.gif files that are displayed: [content-index-icons] image/*= /icons/image2.gif video/* = /icons/movie.gif audio/* = /icons/sound2.gif text/html = /icons/generic.gif text/* = /icons/text.gif application/x-tar = /icons/tar.gif application/* = /icons/binary.gif You can configure this list to specify other icons for each MIME type. Icons can also be located remotely. For example: application/* = You can also configure these additional icon values: Icon used to represent sub-directories: [icons] diricon = /icons/folder2.gif Icon used to represent the parent directory: [icons] backicon = /icons/back.gif Icon used to represent unknown file types: [icons] unknownicon = /icons/unknown.gif Windows: File Naming Conventions for CGI Programs Parameters contained in the [cgi-types] stanza of the webseald.conf configuration file allow you to specify the Windows file extension types that are recognized and executed as CGI programs. The UNIX operating system has no file name extension requirements. File extension types must be defined, however, for Windows operating systems. The [cgi-types] stanza lists all valid extension types and maps each extension (when necessary) to an appropriate CGI program. 28 Version 3.8

49 [cgi-types] <extension> = <cgi-program> By default only those files with extensions matching those listed in the stanza will be executed as CGI programs. If a CGI program has an extension that is not contained in this list, the program will not be executed. Files with the.exe extensions are run as programs by Windows default and require no mapping. Note: Anytime you want to install a.exe file on Windows for download, however, you must rename the extension or install the file as part of an archive (such as.zip). You must supply the appropriate interpreter programs for extensions that represent interpreted script files. Examples of these types of extensions include: shell scripts (.sh and.ksh), Perl scripts (.pl), and Tcl scripts (.tcl) files. The following example illustrates a typical [cgi-types] stanza configuration: [cgi-types] bat = cmd cmd = cmd pl = perl sh = sh tcl = tclsh76 2. WebSEAL Server Configuration Note: There are serious security issues involved in the use of.bat and.cmd files. Use these file types with caution. Configuring Web Document Caching Clients can often experience extended network access time and file downloading time due to poor Web document retrieval performance. Poor performance can occur because the WebSEAL server is waiting for documents retrieved from junctioned back-end servers or even slow local storage. The Web document caching feature allows you to store commonly accessed Web document types in the WebSEAL server s memory. Tivoli SecureWay Policy Director WebSEAL Administration Guide 29

50 Clients will experience much faster response to follow-up requests for documents that have been cached in the WebSEAL server. Cached documents can include static text documents and graphic images. Dynamically generated documents, such as database query results, cannot be cached. Web document caching gives you the flexibility of serving documents locally from WebSEAL rather than from a back-end server across a junction. Caching is performed on the basis of MIME type.when you configure WebSEAL for Web document caching, you identify the following three parameters: Document MIME type Type of storage medium Size of storage medium You define Web document caching in the [content-cache] stanza of the webseald.conf configuration file. The following syntax applies: <mime-type> = <cache-type>:<cache-size> Parameter mime-type cache-type cache-size Description Represents any valid MIME type conveyed in an HTTP Content-Type: response header. This value may contain a wildcard (*). A value of */* represents a default object cache that will hold any object that does not correspond to an explicitly configured cache. Specifies the type of storage medium to use for the cache. This release of Policy Director supports only memory caches. Specifies the maximum size (in kilobytes) to which the given cache can grow before objects are removed according to a Least Recently Used algorithm. 30 Version 3.8

51 Examples: text/html = memory:2000 image/* = memory:5000 */* = memory:1000 The Web document caching mechanism observes these conditions: Caching only occurs when a cache is defined. No caches are defined at installation. If you do not specify a default cache, documents which do not match any explicit cache are not cached. Authorization is still performed on all requests for cached information. Flush All Caches You can use the pdadmin utility to flush all configured caches. The utility does not allow you to flush individual caches. You must login to the secure domain as the Policy Director administrator sec_master before you can use pdadmin. 2. WebSEAL Server Configuration To flush all Web document caches, enter the following command: UNIX: # pdadmin server task <server-name> cache flush all Windows: MSDOS> pdadmin server task <server-name> cache flush all Cache Statistics You can use the pdadmin utility to provide basic statistics on the current use of the cache. The statistics information indicates the number of items held in the cache and how many request have been made for each item. You must login to the secure domain as the Policy Director administrator sec_master before you can use pdadmin. Tivoli SecureWay Policy Director WebSEAL Administration Guide 31

52 To obtain statistics information on the current use of the cache, enter the following command: UNIX: # pdadmin server task <server-name> cache stat Windows: MSDOS> pdadmin server task <server-name> cache stat Configuring HTTP Error Messages Sometimes the WebSEAL server attempts to service a request and fails. There can be many causes of this failure. For example: A file does not exist Permission settings forbid access CGI programs cannot be executed because of incorrect UNIX file permissions or something similar When a failure to service a request occurs, the server returns an error message to the browser, such as 403 Forbidden, in an HTML error page. There are several error messages available; each message is stored in a separate HTML file. These files are stored in the following directory: UNIX: <install-path>/www/lib/errors/<locale-dir> Windows: <install-path>\www\lib\errors/<locale-dir> The errors directory contains a number of locale subdirectories containing localized versions of the error message files. For example, the directory path for US/English messages is: UNIX: <install-path>/www/lib/errors/en_us Windows: <install-path>\www\lib\errors/en_us 32 Version 3.8

53 The messages in this directory are in HTML format so that they appear correctly in a browser. You can edit these HTML pages to customize their contents. The names of the files are the hexadecimal values of the internal error codes that are returned when the operations fail. These file names should not be changed. The following table contains a list of the file names and contents for some of the more common error messages: Filename Title Description HTTP Error Code c8.html 1354a2fa.html 1898d259.html 1898d25a.html 1898d25b.html 1898d25c.html Authentication Failed Non-Empty Directory Could Not Sign User On User Has No Single Sign-on Information No Single Sign-on Target for User Multiple Sign-on Targets for User Credentials could not be retrieved for the client certificate used. Possible reasons include: the user supplied an incorrect certificate the certificate has been revoked the user s credentials are missing from the authentication database The requested operation requires the removal of a non-empty directory. This is an illegal operation. The resource requested requires the WebSEAL server to sign user on to another Web server. However, a problem occurred while WebSEAL was attempting to retrieve the information. WebSEAL could not locate the GSO user for the requested resource. WebSEAL could not locate the GSO target for the requested resource. Multiple GSO targets are defined for the requested resource. This is a mis-configuration. 2. WebSEAL Server Configuration Tivoli SecureWay Policy Director WebSEAL Administration Guide 33

54 Filename Title Description HTTP Error Code 1898d25d.html Login Required The resource requested is protected by a junctioned back-end Web server, requiring WebSEAL to sign user on to that Web server. In order to do this, user must first log into WebSEAL. 1898d25e.html 1898d25f.html Could Not Sign User On Unexpected Authentication Challenge The resource requested requires WebSEAL to sign user on to another Web server. However, the sign-on information for the user account is incorrect. WebSEAL received an unexpected authentication challenge from a junctioned back-end Web server. 1898d421.html Moved Temporarily The requested resource has been temporarily moved. This usually occurs if there has been a mishandled redirect. 1898d424.html Bad Request WebSEAL received an invalid HTTP request. 1898d425.html Login Required The resource you have requested is secured by WebSEAL, and in order to access it, you must first login. 1898d427.html Forbidden User does not have permissions to access requested resource. 1898d428.html Not Found Requested resource cannot be located. 1898d432.html Service Unavailable A service required by WebSEAL to complete request is currently not available Version 3.8

55 Filename Title Description HTTP Error Code 1898d437.html Server Suspended The WebSEAL server has been temporarily suspended by the System Administrator. No requests will be handled until the server is returned to service by the Administrator. 1898d439.html Session Information Lost The browser/server interaction was a stateful session with a junctioned back-end server that is no longer responding. WebSEAL requires a service located on this server to complete your request. 1898d442.html Service Unavailable The service required by WebSEAL is located on a junctioned back-end server where SSL mutual authentication has failed. 1898d7aa.html CGI Program Failed A CGI program failed to execute properly. default.html Server Error WebSEAL could not complete your 500 request due to an unexpected error. deletesuccess.html Success Client-initiated DELETE request 200 completed successfully. putsuccess.html Success Client-initiated PUT operation 200 completed successfully. relocated.html Temporarily Moved The requested resource has 302 temporarily moved. websealerror.html 400 WebSEAL Server Error WebSEAL server internal error WebSEAL Server Configuration Macro Support The following macros are available for use in customizing the HTML error pages listed in the previous section. Macros dynamically substitute appropriate information that is available. Tivoli SecureWay Policy Director WebSEAL Administration Guide 35

56 Macro %ERROR_CODE% %ERROR_TEXT% %METHOD% %URL% %HOSTNAME% %HTTP_BASE% %HTTPS_BASE% %REFERER% %BACK_URL% %BACK_NAME% Description The numeric value of the error code. The text associated with an error code in the message catalog. The HTTP method requested by the client. The URL requested by the client. Fully qualified hostname. Base HTTP URL of the server Base HTTPS URL of the server, The value of the referer header from the request, or Unknown, if none. The value of the referer header from the request, or / if none. The value BACK if a referer header is present in the request, or HOME if none. Managing Custom HTML Pages Policy Director includes sample HTML forms that can be customized to contain site-specific messages or perform site-specific actions. Most forms are appropriate for Forms, token, and BA authentication over HTTP or HTTPS. The file locations for these forms are defined by the mgt-pages-root parameter in the [acnt-mgt] stanza of the webseald.conf configuration file. mgt-pages-root = lib/html/<lang-dir> The actual directory used is based on localization. The default United States English directory is: lib/html/c The Japanese locale locates its files in: lib/html/jp 36 Version 3.8

57 Custom Page Parameters and Values The following special HTML page parameters and values are located in the [acnt-mgt] stanza of the webseald.conf configuration file. Some pages are only used by the Forms login method of providing identity information. Parameter Page Usage login = login.html Forms login logout = logout.html Forms login account-locked = acct_locked.html Any method passwd-expired = passwd_exp.html Any method passwd-change = passwd.html Any method passwd-change-success = passwd_rep.html Any method passwd-change-failure = passwd.html Any method help = help.html Any method token-login = tokenlogin.html Token login next-token = nexttoken.html Token login stepup-login = stepuplogin.html Step-up authentication 2. WebSEAL Server Configuration Custom HTML Page Descriptions Form login.html logout.html acct_locked.html passwd_exp.html passwd.html passwd_rep.html help.html tokenlogin.html nexttoken.html Description Standard request form for username and password Page displayed after successful logout. Page displayed if user authentication failed due to a locked account. Page displayed if user authentication failed due to an expired password. Change password form. Also displayed if password change request failed. Page displayed if password change request was successful. Page containing links to valid administration pages. Token login form. Next token form. Tivoli SecureWay Policy Director WebSEAL Administration Guide 37

58 Form stepuplogin.html Description Step-up authentication login form. There are also two macros available for use in these pages. These macro strings can be placed in the template files. The macro dynamically substitutes appropriate values. Macro %USERNAME% %ERROR% Description The name of the logged in user. The hard-coded error message returned from Policy Director. Managing Client-side and Server-side Certificates This section describes the administration and configuration tasks required to set up WebSEAL to handle client-side and server-side digital certificates used for authentication over SSL. WebSEAL requires certificates for the following situations: WebSEAL identifies itself to SSL clients with its server-side certificate WebSEAL identifies itself to a junctioned back-end server (configured for mutual authentication) with a client-side certificate WebSEAL refers to its database of Certificate Authority (CA) root certificates to validate clients accessing with client-side certificates WebSEAL refers to its database of Certificate Authority (CA) root certificates to validate junctioned back-end servers configured for mutual authentication WebSEAL uses the IBM Global Security Kit (GSKit) implementation of SSL to configure and administer digital certificates. GSKit provides the ikeyman utility to set up and 38 Version 3.8

59 manage the certificate key database that contains one or more WebSEAL server/client certificates and the CA root certificates. WebSEAL includes the following components at installation to support SSL authentication via digital certificates: A default key database (pdsrv.kdb) A default key database stash file (pdsrv.sth) and password ( pdsrv ) Several common CA root certificates A self-signed test certificate that WebSEAL can use to identify itself to SSL clients It is recommended that you apply for a commonly recognized certificate from a known Certificate Authority to replace this test certificate. Configuration for WebSEAL certificate handling includes: Configuring Key Database Parameters for WebSEAL on page WebSEAL Server Configuration Using the ikeyman Certificate Management Utility on page 43 Configuring CRL Checking on page 44 Understanding GSKit Key Database File Types The IBM Key Management tool (ikeyman) uses several file types that are summarized in the following table. A CMS key database consists of a file with the extension.kdb and possibly two or more other files. The.kdb file is created when you create a new key database. A key record in a.kdb file can be either a certificate or a certificate with its encrypted private key information. The.rdb and.crl files are created when you create a new certificate request. The.rdb file is required throughout the CA certificate request process. Tivoli SecureWay Policy Director WebSEAL Administration Guide 39

60 .kdb.sth.rdb.crl.arm File Type Description The key database file. Stores personal certificates, personal certificate requests, and signer certificates. For example, the default WebSEAL key database file is pdsrv.kdb. The stash file. Stores an encrypted version of the key database password. The stem name of this file is the same as the associated.kdb file. The request database file. Automatically created when you create a.kdb key database file. The stem name of this file is the same as the associated.kdb file. This file contains certificate requests that are outstanding and have not yet been received back from the CA. When a certificate is returned from the CA, the.rdb file is searched for the matching certificate request (based on the public key). If a match is found, the certificate is received and the corresponding certificate request is deleted from the.rdb file. If a match is not found, the attempt to receive the certificate is rejected. Included in the certificate request is the common name, organization, street address, and other information that was specified at the time of the request, as well as the public and private key associated with the request. The certificate revocation list file. This file normally contains the list of certificates that have been revoked for one reason or another. However, ikeyman does not provide any support for certificate revocation lists, so it is empty. An ASCII encoded binary file. A.arm file contains a base-64 encoded ASCII representation of a certificate, including its public key, but not its private key. The original binary certificate data is transformed into an ASCII representation. When a user receives a certificate in a.arm file, ikeyman decodes the ASCII representation and places the binary representation into the appropriate.kdb file. Similarly, when a user extracts a certificate from a.kdb file, ikeyman converts the data from binary to ASCII and places it in a.arm file. The ASCII data in the.arm file is what you send to the CA during the certificate request process. Note: Any file type is acceptable to use (other than.arm), as long as the file itself is a Base64 encoded file. 40 Version 3.8

61 File Type Description.der The Distinguished Encoding Rules file. A.der file contains a binary representation of a certificate, including its public key, but not its private key. It is very similar to a.arm file, except that the representation is binary, not ASCII..p12 The PKCS 12 file, where PKCS stands for Public-Key Cryptography Standards. A.p12 file contains a binary representation of a certificate, including both its public and private keys. A.p12 file may also include more than one certificate; for example, a certificate, the certificate of the CA that issued the certificate, the issuer of the CA s certificate, as well as his issuer, and so on. Because a.p12 file contains a private key, it is password protected. Configuring Key Database Parameters for WebSEAL WebSEAL Certificate Keyfile: At installation, WebSEAL provides a default certificate key database. The webseal-cert-keyfile parameter, located in the [ssl] stanza of the webseald.conf configuration file, identifies the name and location of this file: [ssl] webseal-cert-keyfile = /var/pdweb/www/certs/pdsrv.kdb 2. WebSEAL Server Configuration You can use the ikeyman utility to create a new key database. However, you must enter the name and location of this new key file in the webseal-cert-keyfile parameter so that WebSEAL can find and use the certificates contained in that database. Certificate Keyfile Password: At installation, WebSEAL also provides a default stash file that contains the password for the pdsrv.kdb key file. The webseal-cert-keyfile-stash parameter informs WebSEAL of the location of the stash file: webseal-cert-keyfile-stash = /var/pdweb/www/certs/pdsrv.sth Tivoli SecureWay Policy Director WebSEAL Administration Guide 41

62 The default password encrypted in this stash file is pdsrv. You can also express a password as plain text in the webseal-cert-keyfilepwd parameter. For example: webseal-cert-keyfile-pwd = pdsrv At installation, WebSEAL uses the stash file to obtain the key file password. The webseal-cert-keyfile-pwd is commented out. By using the stash file you can avoid displaying the password as text in the webseald.conf configuration file. Note: Uncomment the specific password parameter you want to use. If both password and stash file are specified, the password value is used. WebSEAL Test Certificate: At installation, WebSEAL provides a non-secure self-signed test certificate. The test certificate, acting as a server-side certificate, allows WebSEAL to identify itself to SSL clients. To better control how this test certificate is used, the certificate is not installed as a default certificate. Instead, the webseal-cert-keyfile-label parameter designates the certificate as the active server-side certificate and overrides any other certificate designated as default in the keyfile database. webseal-cert-keyfile-label = WebSEAL Although this test certificate allows WebSEAL to respond to an SSL-enabled browser request, it cannot be verified by the browser (which does not contain an appropriate root CA certificate). Because the private key for this default certificate is contained in every WebSEAL distribution, this certificate offers no true secure communication. You must use the ikeyman utility to generate a certificate request that can be sent to a Certificate Authority (CA). Use ikeyman to install and label the returned server certificate. 42 Version 3.8

63 If you use different certificates for other scenarios (such as K junctions), you can use the ikeyman utility to create, install, and label these certificates. The keyfile label must not contain spaces. WebSEAL (which by default runs as user ivmgr) must have read (r) permission on these key database files. See also Managing Certificates with ikeyman on page 249. Internal Policy Director Server SSL Communication: The [ssl] stanza of the webseald.conf configuration file contains four additional parameters used to configure the keyfile used by WebSEAL for internal SSL communication with other Policy Director servers. You should only modify these parameters through the pdconfig configuration script. [ssl] ssl-keyfile = ssl-keyfile-pwd = ssl-keyfile-stash = ssl-keyfile-label = Using the ikeyman Certificate Management Utility The ikeyman utility is a tool provided with GSKit that you can use to manage digital certificates used by WebSEAL. Use ikeyman to: create a one or more key databases change key database passwords create new WebSEAL certificates set a new default WebSEAL certificate create a self-signed certificate for testing request and receive CA root certificates add certificates to and delete certificates from the database copy certificates from one database to another 2. WebSEAL Server Configuration For detailed instructions on using ikeyman to perform these tasks, see Managing Certificates with ikeyman on page 249. Tivoli SecureWay Policy Director WebSEAL Administration Guide 43

64 Configuring CRL Checking The Certificate Revocation List (CRL) is a method of preventing the validation of unwanted certificates. The CRL contains the identities of certificates that are deemed untrustworthy. The GSKit implementation of SSL used by WebSEAL supports CRL checking. GSKit allows WebSEAL to perform CRL checking on client-side certificates and certificates from SSL junctions. WebSEAL must know the location of this list in order to perform CRL checking. Parameters for the location of the LDAP server that can be referenced for CRL checking during certificate authentication are found in the [ssl] stanza of the webseald.conf configuration file: [ssl] #ssl-ldap-server = <server-name> #ssl-ldap-server-port = <port-id> #ssl-ldap-user = <webseal-admin-name> #ssl-ldap-user-password = <admin-password> By default, CRL checking is disabled (parameters are commented out). To enable CRL checking during certificate authentication, uncomment each parameter and enter the appropriate values. A null value for the ssl-ldap-user indicates that the SSL authentication mechanism should bind to the LDAP server as an anonymous user. Configuring a Default Quality of Protection Level You can control the default level of encryption required for access to WebSEAL over SSL (HTTPS) by configuring the quality of protection (QOP). Default quality of protection management is controlled using parameters in the SSL QUALITY OF PROTECTION MANAGEMENT section of the webseald.conf configuration file: Enable and disable QOP management with the ssl-qop-mgmt parameter Specify allowed encryption levels in the [ssl-qop-mgmt-default] stanza 44 Version 3.8

65 1. Enable quality of protection management: [ssl-qop] ssl-qop-mgmt = yes 2. Specify the default encryption level for HTTPS access: [ssl-qop-mgmt-default] # default = ALL NONE <cipher-level> # ALL (enables all ciphers) # NONE (disables all ciphers and uses an MD5 MAC check sum) # DES-40 # DES-56 # DES-168 # RC2-40 # RC2-128 # RC4-40 # RC4-128 default = ALL Note that you can also specify a selected group of ciphers: [ssl-qop-mgmt-default] default = RC4-128 default = RC2-128 default = DES-168 Configuring QOP for Individual Hosts and Networks The ssl-qop-mgmt = yes parameter also enables any settings that appear in the [ssl-qop-mgmt-hosts] and [ssl-qop-mgmt-networks] stanzas. These stanzas allow quality of protection management by specific host/network/netmask IP address. 2. WebSEAL Server Configuration The [ssl-qop-mgmt-default] stanza lists the ciphers used for all IP addresses not matched in the [ssl-qop-mgmt-hosts] and [ssl-qop-mgmt-networks] stanzas. Example configuration syntax for hosts: [ssl-qop-mgmt-hosts] # <host-ip> = ALL NONE <cipher-level> # ALL (enables all ciphers) # NONE (disables all ciphers and uses an MD5 MAC check sum) # DES-40 # DES-56 # DES-168 # RC2-40 # RC2-128 Tivoli SecureWay Policy Director WebSEAL Administration Guide 45

66 # RC4-40 # RC4-128 xxx.xxx.xxx.xxx = ALL yyy.yyy.yyy.yyy = RC2-128 Example configuration syntax for network/netmask: [ssl-qop-mgmt-networks] # <network/netmask> = ALL NONE <cipher-level> # ALL (enables all ciphers) # NONE (disables all ciphers and uses an MD5 MAC check sum) # DES-40 # DES-56 # DES-168 # RC2-40 # RC2-128 # RC4-40 # RC4-128 xxx.xxx.xxx.xxx/ = RC4-128 yyy.yyy.yyy.yyy/ = DES-56 The [ssl-qop-mgmt-hosts] and [ssl-qop-mgmt-networks] stanzas are provided for backward compatibility only. It is not recommended that you use them for Policy Director 3.8 configuration. Configuring Authorization Database Updates and Polling The Management Server manages the master authorization policy database and maintains location information about other Policy Director servers in the secure domain. A Policy Director administrator can make security policy changes to the secure domain at any time. The Management Server makes the necessary adjustments to the master authorization database whenever security policy changes are implemented. When the Management Server makes a change to the master authorization database, it can send out notification of this change to all replica databases in the secure domain that support individual policy enforcers (such as WebSEAL). The policy enforcers must then request an actual database update from the master authorization database. 46 Version 3.8

67 WebSEAL, as a resource manager and policy enforcer, has three options to obtain information about authorization database changes: Listen for update notifications from the Management Server (configurable and enabled by default). Check (poll) the master authorization database at regular intervals (configurable and disabled by default). Enable both listening and polling. The [aznapi-configuration] stanza of the webseald.conf configuration file contains parameters for configuring update notification listening and database polling. The path to WebSEAL s local replica authorization policy database is defined by the db-file parameter: [aznapi-configuration] db-file = /var/pdweb/db/webseald.db Configuring Update Notification Listening The listen-flags parameter enables and disables update notification listening by WebSEAL. By default, listening is enabled. To disable listening, enter disable. [aznapi-configuration] listen-flags = enable 2. WebSEAL Server Configuration The tcp-port parameter configures the TCP port for the listener: [aznapi-configuration] tcp-port = The udp-port parameter configures the TCP port for the listener: [aznapi-configuration] udp-port = 0 Configuring Authorization Database Polling You can configure WebSEAL to regularly poll the master authorization database for update information. The cache-refresh-interval parameter can be set to default, disable, or a specific time interval in seconds. The default setting is equal to 600 seconds. By default, polling is disabled. Tivoli SecureWay Policy Director WebSEAL Administration Guide 47

68 [aznapi-configuration] cache-refresh-interval = disable Replicating Front-end WebSEAL Servers Note: The following information replaces the former pdadmin server modify baseurl command, used in previous versions of Policy Director. In a heavy load environment, it is advantageous to replicate front-end WebSEAL servers to provide better load-balancing and fail-over capability. When you replicate front-end WebSEAL servers, each server must contain an exact copy of the Web space, the junction database, and the dynurl database. This version of Policy Director supports a manual configuration procedure to replicate front-end WebSEAL servers. The pdadmin command is no longer used for this task. In the following example, WS1 is the host name of the primary WebSEAL server. WS2 is the host name for the replica WebSEAL server. 1. Install and configure WebSEAL on both WS1 and WS2 servers. 2. Stop WebSEAL on WS2. 3. On WS2, change the value of the server-name parameter in the webseald.conf configuration file from WS2 to WS1 : [server] server-name = WS1 4. Restart WebSEAL on WS2. The WS2 server now uses the object /WebSEAL/WS1 as the base for authorization evaluations. The WS2 server can also respond to object list and object show commands for objects residing below /WebSEAL/WS1. 48 Version 3.8

69 The pdadmin utility still lists the /WebSEAL/WS2 object as part of the object space. This object is now meaningless and can be removed: pdadmin> object delete /WebSEAL/WS2 Conditions: Unified object space management: Although a single object hierarchy is visible to the administrator, all replicated WebSEAL servers are affected by administration commands applied to that object hierarchy and all servers are able to respond to these commands. Unified authorization evaluation: If server WS2 is configured as a replica of server WS1, server WS2 uses /WebSEAL/WS1 as the base for authorization evaluations. Unified configuration: For front-end WebSEAL replication to function correctly, the Web space, junction database, and dynurl database configuration must be identical on each server. 2. WebSEAL Server Configuration Configuring Standard HTTP Logging WebSEAL maintains three conventional HTTP log files that record activity rather than messages: request.log agent.log referer.log By default, these log files are maintained under the following directory: UNIX: /var/pdweb/www/log/ Windows: C:\Program Files\Tivoli\PDWeb\www\log\ Parameters for configuring standard HTTP logging are located in the [logging] stanza of the webseald.conf configuration file. Tivoli SecureWay Policy Director WebSEAL Administration Guide 49

70 The following table illustrates the relationship between the HTTP log files and the configuration file parameters: Log Files Location Parameter Enable/Disable Parameter( = yes or no) request.log requests-file requests referer.log referers-file referers agent.log agents-file agents For example, the entry for the default location of the request.log file appears as follows: UNIX: requests-file = /var/pdweb/www/log/request.log Windows: requests-file = \Program Files\Tivoli\PDWeb\www\log\request.log Enabling and Disabling HTTP Logging By default, all HTTP logging is enabled: [logging] requests = yes referers = yes agents = yes Each log can be enabled or disabled independently from the others. If any parameter is set to no, logging is disabled for that file. Specifying the Timestamp Type You can choose to have the timestamps in each log recorded in Greenwich Mean Time (GMT) instead of the local timezone. By default, the local timezone is used: [logging] gmt-time = no To use GMT timestamps, set: gmt-time = yes 50 Version 3.8

71 Specifying Log File Rollover Thresholds The max-size parameter specifies the maximum size to which each of the HTTP log files may grow and has the following default value (in bytes): [logging] max-size = When a log file reaches the specified value known as its rollover threshold the existing file is backed up to a file of the same name with an appended current date and timestamp. A new log file is then started. The various possible max-size values are interpreted as follows: If the max-size value is less than zero (< 0), then a new log file is created with each invocation of the logging process and every 24 hours from that instance. If the max-size value is equal to zero (= 0), then no rollovers are performed and the log file grows indefinitely. If a log file already exists, new data is appended to it. If the max-size value is greater than zero (> 0), then a rollover is performed when a log file reaches the configured threshold value. If a log file already exists at startup, new data is appended to it. Specifying the Frequency for Flushing Log File Buffers Log files are written to buffered data streams. If you are monitoring the log files in real time, you may want to alter the frequency with which the server forces a flush of the log file buffers. 2. WebSEAL Server Configuration By default, log files are flushed every 20 seconds: [logging] flush-time = 20 If you specify a negative value, a flush will be forced after every record is written. Tivoli SecureWay Policy Director WebSEAL Administration Guide 51

72 Configuring the Content Length Recorded in request.log WebSEAL automatically filters static HTML URLs from back-end junctioned application servers. The [filter-url] stanza in the webseald.conf configuration file defines the URL attributes that WebSEAL filters in responses from the back-end server. See Filtering Static HTML URLs from Junctioned Servers on page 176. When content requested from a back-end junctioned server contains embedded URLs, WebSEAL filters the URL strings by prepending the junction point to the path. When it is returned to the browser, the client can successfully use the URL. The final content length of the pages returned to the browser can therefore be somewhat larger than the original content returned from the junctioned server to WebSEAL. This version of Policy Director WebSEAL allows you to configure the content length recorded by the request.log file (if enabled). The log-filtered-pages parameter in the [logging] stanza of the webseald.conf configuration file can be set to record a zero byte size or the unfiltered byte size. To record the unfiltered byte size, set the parameter to yes (default): [logging] log-filtered-pages = yes To record a zero byte size, set the parameter to no : [logging] log-filtered-pages = no HTTP Common Log Format (for request.log) Every response (success or failure) sent back by the Policy Director server is recorded with a one-line entry in the request.log file using following HTTP Common Log Format: host -authuser [date] request status bytes 52 Version 3.8

73 where: host authuser date request status bytes Specifies the IP address of the requesting machine. This field takes the value of the From: header of the received HTTP request. The value unauth is used for an unauthenticated user. Specifies the date and time of the request. Specifies the first line of the request as it came from the client. Specifies the HTTP status code sent back to the requesting machine. Specifies the number of bytes sent back to the requesting machine. This value either the unfiltered content size or a zero size is configured with the log-filtered-pages parameter. Displaying the request.log File The request.log records standard logging of HTTP requests, such as information on URLs that have been requested and information on the client (for example, IP address) that made the request. 2. WebSEAL Server Configuration The following example shows a sample version of a request.log file: [26/Aug/2001:17:23: ] "GET /xsmith/private_html/ HTTP/1.0" [26/Aug/2001:17:23: ] GET /icons HTTP/1.0" [26/Aug/2001:17:23: ] "GET /icons/ HTTP/1.0" [26/Aug/2001:17:24: ] "GET /xsmith/private_html/ HTTP/1.0" [26/Aug/2001:17:24: ] "GET /xsmith/ HTTP/1.0" Displaying the agent.log File The agent.log file records the contents of the User_Agent: header in the HTTP request. This log reveals information about the client browser, such as architecture or version number, for each request. Tivoli SecureWay Policy Director WebSEAL Administration Guide 53

74 The following example shows a sample version of a agent.log file: Mozilla/4.01 [en] (WinNT; U) Mozilla/4.01 [en] (WinNT; U) Mozilla/4.01 [en] (WinNT; U) Mozilla/4.01 [en] (WinNT; U) Displaying referer.log The referer.log records the Referer: header of the HTTP request. For each request, the log records the document that contained the link to the requested document. The log uses the following format: referer -> object This information is useful for tracking external links to documents in your Web space. The log reveals that the source indicated by referer contains a link to a page object. This log allows you to track stale links and to find out who is creating links to your documents. The following example shows a sample version of a referer.log file: -> /pics/tivoli_logo.gif ->/pics/tivoli_logo.gif -> /pddl/index.html -> /pddl/index.html ->/pics/tivoli_logo.gif -> /pddl/index.html 54 Version 3.8

75 3 WebSEAL Security Policy This chapter contains information that describes how you can configure and customize WebSEAL security policy. Topic Index: WebSEAL-specific ACL Policies Three Strikes Login Policy on page 57 Password Strength Policy on page 59 Authentication Strength POP Policy (Step-up) on page 64 Network-based Authentication POP Policy on page 71 Quality of Protection POP Policy on page 74 Handling Unauthenticated Users (HTTP / HTTPS) on page 75 WebSEAL-specific ACL Policies The following security considerations apply for the /WebSEAL container in the protected object space: The WebSEAL object begins the chain of ACL inheritance for the WebSEAL region of the object space If you do not apply any other explicit ACLs, this object defines (through inheritance) the security policy for the entire Web space The traverse permission is required for access to this object and any object below this point 3. WebSEAL Security Policy Tivoli SecureWay Policy Director WebSEAL Administration Guide 55

76 Refer to the Tivoli SecureWay Policy Director Base Administration Guide for complete information about Policy Director ACL policies. /WebSEAL/<host> This subtree contains the Web space of a particular WebSEAL server. The following security considerations apply for this object: The traverse permission is required for access to any object below this point If you do not apply any other explicit ACLs, this object defines (through inheritance) the security policy for the entire object space on this machine /WebSEAL/<host>/<file> This is the resource object checked for HTTP access. The permissions checked depend on the operation being requested. WebSEAL ACL Permissions The following table describes the ACL permissions applicable for the WebSEAL region of the object space: Operation Description r read View the Web object x execute Run the CGI program. d delete Remove the Web object from the Web space. m modify PUT an HTTP object. (Place - publish - an HTTP object in the WebSEAL object space.) l list Required by Management Server to generate an automated directory listing of the Web space. This permission also governs whether a client can see the directory contents listing when the default index.html page is not present. g delegation Assigns trust to a WebSEAL server to act on behalf of a client and pass requests to a junctioned WebSEAL server. 56 Version 3.8

77 Default /WebSEAL ACL Policy Core entries for the WebSEAL ACL, default-webseal, include: Group iv-admin Group webseal-servers User sec_master Any-other Unauthenticated Tcmdbsvarxl Tgmdbsrxl Tcmdbsvarxl Trx T At installation, this default ACL is attached to the /WebSEAL container object in the object space. The group, webseal-servers, contains an entry for each WebSEAL server in the secure domain. The default permissions allow the servers to respond to browser requests. The traverse permission allows expansion of the Web space as represented in the Web Portal Manager. The list permission allows the Web Portal Manager to display the contents of the Web space. Three Strikes Login Policy The three strikes login policy, available for LDAP-based Policy Director installations, enables you to specify a maximum number of failed login attempts (n) and a penalty lockout time (x), such that after n failed login attempts a user is locked out for x seconds (or the account is disabled). The three strikes login policy is used to prevent computer password attacks. The policy creates a condition where a user must wait a period of time before making more login attempts that fail. For example, a policy could dictate 3 failed attempts followed by a 180 second penalty. This type of login policy can prevent random computer-generated login attempts occurring many times a second. 3. WebSEAL Security Policy The three strikes login policy requires the joint contribution of two pdadmin policy command settings: Maximum number of failed login attempts policy set max-login-failures Penalty for exceeding failed login attempt setting Tivoli SecureWay Policy Director WebSEAL Administration Guide 57

78 policy set disable-time-interval The penalty setting can include an account lockout time interval or a complete disabling of the account. If a login policy is set (as an example) for three failed attempts followed by specific lockout time penalty, a fourth attempt (correct or incorrect) will result in an error page that states the account is temporarily unavailable because of password policy. The time interval is specified in seconds the minimum recommended time interval is 60 seconds. If the disable-time-interval policy is set to disable, the user is locked out of the account and the LDAP account valid attribute for this user is set to no. An administrator re-enables the account through the Web Portal Manager. Note: Setting the disable-time-interval to disable results in additional administration over-head. You may observe delays in replicating account valid information to the WebSEAL server. This situation depends on your LDAP environment. In addition, certain LDAP implementations might experience performance degradation as a result of the account valid update operation. For these reasons it is recommended that you use a timeout interval. Command Syntax The following pdadmin commands are appropriate only for use with an LDAP registry. Command Description policy set max-login-failures {<number> unset} [-user <username>] policy get max-login-failures [-user <username>] 58 Version 3.8

79 Command Description Manages the policy controlling the maximum number of failed login attempts allowed before a penalty is imposed. This command depends on a penalty set in the policy set disable-time-interval command. As the administrator, you can apply this policy to a specific user or apply the policy globally to all users listed in the LDAP registry. The default setting is 10 attempts. policy set disable-time-interval {<number> unset disable} [-user <username>] policy get disable-time-interval [-user <username>] Manages the penalty policy controlling the time period an account should be disabled if the maximum number of failed login attempts is reached. As the administrator, you can apply this penalty policy to a specific user or apply the policy globally to all users listed in the LDAP registry. The default setting is 180 seconds. Password Strength Policy Password strength policy, available for LDAP-based Policy Director installations, refers to the stipulations placed on the construction of a password by password policy rules. Policy Director provides two means of controlling password strength policy: Five pdadmin password policy commands 3. WebSEAL Security Policy A plugable authentication module (PAM) that allows you to customize a password policy Refer to the Tivoli SecureWay Policy Director WebSEAL Developer Reference. Tivoli SecureWay Policy Director WebSEAL Administration Guide 59

80 Password Strength Policy Set by the pdadmin Utility The five password strength attributes implemented through the pdadmin utility include: Minimum password length Minimum alphabetic characters Minimum non-alphabetic characters Maximum repeated characters Spaces allowed These policies are enforced when you create a user with pdadmin or the Web Portal Manager, and when a password is changed with pdadmin, the Web Portal Manager, or the pkmspasswd utility. Command Syntax The following pdadmin commands are only appropriate for use with an LDAP registry. The unset option disables this policy attribute that is, the policy is not enforced. Command Description policy set min-password-length {<number> unset} [-user <username>] policy get min-password-length [-user <username>] Manages the policy controlling the minimum length of a password. As the administrator, you can apply this policy to a specific user or apply the policy globally to all users listed in the default registry. The default setting is 8. policy set min-password-alphas {<number> unset} [-user <username>] policy get min-password-alphas [-user <username>] 60 Version 3.8

81 Command Description Manages the policy controlling the minimum number of alphabetic characters allowed in a password. As the administrator, you can apply this policy to a specific user or apply the policy globally to all users listed in the default registry. The default setting is 4. policy set min-password-non-alphas {<number> unset} [-user <username>] policy get min-password-non-alphas [-user <username>] Manages the policy controlling minimum number of non-alphabetic (numeric) characters allowed in a password. As the administrator, you can apply this policy to a specific user or apply the policy globally to all users listed in the default registry. The default setting is 1. policy set max-password-repeated-chars {<number> unset} [-user <username>] policy get max-password-repeated-chars [-user <username>] Manages the policy controlling the maximum number of repeated characters allowed in a password. As the administrator, you can apply this policy to a specific user or apply the policy globally to all users listed in the default registry. The default setting is 2. policy set password-spaces {yes no unset} [-user <username>] policy get password-spaces [-user <username>] 3. WebSEAL Security Policy Tivoli SecureWay Policy Director WebSEAL Administration Guide 61

82 Command Description Manages the policy controlling whether a password can contain spaces. As the administrator, you can apply this policy to a specific user or apply the policy globally to all users listed in the default registry. The default setting is unset. Default Policy Parameter Values The following table lists the policy parameters and the default values: Parameter Default Value min-password-length 8 min-password-alphas 4 min-password-non-alphas 1 max-password-repeated-chars 2 password-spaces not set To create the password policy behavior found in earlier releases of Policy Director, apply the unset option to each of the five password parameters listed above. Valid and Invalid Password Examples The following table illustrates several password examples and the policy results based on the default values of the five pdadmin parameters: Example password pass passs1234 Result Not valid: must contain at least one non-alphabetic character. Not valid: must contain at least 8 characters. Not valid: contains more than two repeated characters. 62 Version 3.8

83 Example Result Not valid: must contain at least four alphabetic characters. password3 Valid. Specific User and Global Settings The pdadmin policy commands can be set for a specific user (with the - user option) or globally (by not using the - user option). Any user-specific setting overrides a global setting for the policy. You can also disable (unset) a policy parameter, which means the parameter contains no value. Any policy with the unset option is not checked or enforced. For example: pdadmin> policy set min-password-length 8 pdadmin> policy set min-password-length 4 -user matt pdadmin> policy get min-password-length Minimum password length: 8 pdadmin> policy get min-password-length -user matt Minimum password length: 4 (User matt has a minimum password length policy of 4 characters; all other users have a minimum password length policy of 8.) pdadmin> policy set min-password-length unset -user matt (User matt is now governed by the global minimum password length policy of 8 characters.) pdadmin> policy set min-password-length unset 3. WebSEAL Security Policy (All users, including user matt now have no minimum password length policy.) Tivoli SecureWay Policy Director WebSEAL Administration Guide 63

84 Authentication Strength POP Policy (Step-up) The authentication strength POP policy makes it possible to control access to objects based on the authentication method that they use. You can use this functionality sometimes known as step-up authentication to ensure that users accessing more sensitive resources use a stronger authentication mechanism. You might want this condition because of the greater threat of improper access. For example, you can provide greater security to a junctioned region of the Web space by applying a step-up POP policy that requires a stronger level of authentication than the client used when initially entering the WebSEAL domain. Authentication strength policy is set in the IP Endpoint Authentication Method attribute of a POP policy. Configuring Levels for Step-up Authentication The first step in configuring authentication-specific access is to configure the supported authentication methods and determine the order in which these authentication methods should be considered stronger. Any client accessing a WebSEAL server has an authentication level, such as unauthenticated or password, which indicates the method by which the client last authenticated with WebSEAL. In some situations it may be necessary to enforce minimum safe levels of authentication required to access certain Web space objects. For example, in one environment, authentication by token passcode may be considered more secure than authentication by username and password. Another environment could have different standards. Rather than forcing clients to restart their sessions with WebSEAL when they do not meet the required level of authentication, the step-up authentication mechanism gives clients a second chance to re-authenticate using the required method (level). 64 Version 3.8

85 Step-up authentication means that a user is not immediately shown a denied message when they try to access a resource that requires a higher authentication level that the one they logged in with. Instead, they are presented with a new authentication prompt that requests information to support the higher authentication level. If they are able to supply this level of authentication then their original request will be permitted. WebSEAL recognizes three authentication methods (levels) for use in the step-up authentication mechanism: unauthenticated password token-card You configure authentication levels in the [authentication-levels] stanza of the webseald.conf configuration file. Initially, only two levels are configured: [authentication-levels] level = unauthenticated level = password Based on the order of the methods in the list, each method is assigned a level index, ranging from 0 to 2. The unauthenticated method must always be the first in the list and therefore is assigned a level index of 0. Subsequent methods can be placed in any order. See Step-up Authentication Notes and Limitations on page 69. By default, password appears at the next level making it level index WebSEAL Security Policy There must be at least two entries to enable step-up authentication, Note: See WebSEAL Authentication on page 79 for detailed information about setting up the required authentication mechanisms. Tivoli SecureWay Policy Director WebSEAL Administration Guide 65

86 Enabling Step-up Authentication Step-up authentication is implemented via a POP policy placed on the objects requiring authentication-sensitive authorization. You use the IP Endpoint Authentication Method attribute of a POP policy. The pdadmin pop modify set ipauth command specifies both the allowed networks and the required authentication level in the IP Endpoint Authentication Method attribute. The configured authentication levels can be linked to IP address ranges. This method is intended to provide management flexibility. If filtering users by IP address is not important, you can set a single entry for anyothernw (any other network).this setting will affect all accessing users, regardless of IP address, and require them to authenticate at the specified level. This is the most common method for implementing step-up authentication. Syntax: pdadmin> pop modify <pop-name> set ipauth anyothernw <level-index> The anyothernw entry is used as a network range that will match any network not otherwise specified in the POP. This method used to create a default entry which could either deny all unmatched IP addresses or allow anyone access who can meet the authentication level requirement. By default, anyothernw appears in a POP with an authentication level index of 0. The entry appears as Any Other Network in the pop show command: pdadmin> pop show test Protected object policy: test Description: Test POP Warning: no Audit level: none Quality of protection: none Time of day access: sun, mon, tue, wed, thu, fri, sat: anytime:local IP Endpoint Authentication Method Policy Any Other Network 0 66 Version 3.8

87 Example 1. Configure authentication levels in webseald.conf: [authentication-levels] level = unauthenticated level = token-card 2. Configure IP Endpoint Authentication Method POP attribute: pdadmin> pop modify test set ipauth anyothernw 1 pdadmin> pop show test Protected object policy: test Description: Test POP Warning: no Audit level: none Quality of protection: none Time of day access: mon, wed, fri:anytime:local IP Endpoint Authentication Method Policy Any Other Network 1 This policy requires a step-up to the token-card authentication method (level 1) for all users initially accessing as unauthenticated (level 0). All unauthenticated users attempting to access objects protected by this POP policy are issued a prompt for username and token passcode. See also Network-based Authentication POP Policy on page 71. Step-up Login Form WebSEAL presents a special form when the step-up POP policy on the requested resource forces the client to re-authenticate. The location of this HTML form is specified by the stepup-login parameter in the [acnt-mgt] stanza of the webseald.conf configuration file. [acnt-mgt] stepup-login = stepuplogin.html 3. WebSEAL Security Policy You can configure this HTML form to meet your requirements, in the same manner as you might configure the login.html or tokenlogin.html forms. This file contains macros, in the form of %TEXT% sequences, which are replaced with the appropriate values. This substitution Tivoli SecureWay Policy Director WebSEAL Administration Guide 67

88 occurs within WebSEAL s template file processing functions and allows the form to be used for both password and token authentication methods with correct formatting. It also allows other information, such as error message and method name (stepping up to), to be supplied in the form for the user. Figure 11. Login Form for Username and Password Step-up 68 Version 3.8

89 Figure 12. Login Form for SecurID Token Passcode Step-up Step-up Authentication Algorithm WebSEAL uses the following algorithm to process the conditions in apop: 1. Check the IP endpoint authentication method policy on the POP. 2. Check ACL permissions. 3. Check time-of-day policy on the POP. 4. Check the audit level policy on the POP. Step-up Authentication Notes and Limitations 1. Step-up authentication is supported over both HTTP and HTTPS. 2. You cannot step-up from the HTTP protocol to HTTPS. 3. Unauthenticated must always be the first method in the level list, and may not occur anywhere else in the list. 4. Methods can only be specified once in the level list. 5. Certificate authentication is not a supported method for step-up authentication. 3. WebSEAL Security Policy Tivoli SecureWay Policy Director WebSEAL Administration Guide 69

90 Note: Step-up authentication actually handles client-side certificates as a special case. If a client accesses WebSEAL with a client-side certificate, and WebSEAL is configured to accept certificates, the client is treated as unauthenticated with a level index of 0. From Method: unauthenticated password token-card Can step-up to: password token-card token-card password 6. Authentication levels are represented by authentication methods, which means that it is impossible to specify a precise authentication mechanism for authentication at that level. Authentication methods may be supported by multiple authentication mechanisms, including local authenticators and custom external authenticators. WebSEAL follows specific rules for determining which authenticator to select when muliple instances of the same authentication method type have been configured. 7. If there are three configured levels, the valid index values are: 0,1,2. If any other index value is configured, WebSEAL presents an error page whenever any object with that POP attached is requested. 8. Incorrect configuration of step-up authentication levels in the webseald.conf configuration file results in the disabling of step-up functionality within WebSEAL. This situation can lead to unexpected authentication behavior, such as the password login page being issued for objects protected by a POP that requires the token passcode authentication method. After configuring step-up authentication levels, check the webseald.log file for reports of any configuration errors. 70 Version 3.8

91 Network-based Authentication POP Policy The network-based authentication POP policy makes it possible to control access to objects based on the IP address of the user. You can use this functionality to prevent specific IP addresses (or IP address ranges) from accessing any resources in your secure domain. You can also apply step-up authentication configuration to this policy and require a specific authentication method for each specified IP address range. Network-based authentication policy is set in the IP Endpoint Authentication Method attribute of a POP policy. You must specify two requirements in this attribute: Authentication levels Allowed networks Configuring Authentication Levels WebSEAL recognizes three authentication methods for use in the step-up authentication mechanism: unauthenticated password token-card Based on the order of the methods in the list, each method is assigned a level index, ranging from 0 to 2. You configure authentication levels in the [authentication-levels] stanza of the webseald.conf configuration file. Initially, only two levels are configured: [authentication-levels] level = unauthenticated level = password 3. WebSEAL Security Policy You can use these default settings when you configure network-based authentication. In this case, unauthenticated is level 0 and password is level 1. Tivoli SecureWay Policy Director WebSEAL Administration Guide 71

92 See also Configuring Levels for Step-up Authentication on page 64. Specifying IP Addresses and Ranges Now you must specify the IP addresses and IP address ranges permitted by this POP policy. The pdadmin pop modify set ipauth add command specifies both the network (or network range) and the required authentication level in the IP Endpoint Authentication Method attribute. Syntax: pdadmin> pop modify <pop-name> set ipauth add <network> <netmask> <level-index> The configured authentication levels are linked to IP address ranges. This method is intended to provide flexibility. If filtering users by IP address is not important, you can set a single entry for anyothernw (any other network).this setting affects all accessing users, regardless of IP address, and require them to authenticate at the specified level. Syntax: pdadmin> pop modify <pop-name> set ipauth anyothernw <level-index> Conversely, if you wish to ignore the authentication level and only want to allow or deny access based on IP address, you can use level 0 for ranges that you want to allow in and forbidden for ranges you want to deny. The anyothernw entry is used as a network range that matches any network not otherwise specified in the POP. This method used to create a default entry which could either deny all unmatched IP addresses or allow anyone access who meet the authentication level requirement. By default, anyothernw appears in a POP with an authentication level index of 0. The entry appears as Any Other Network in the pop show command: 72 Version 3.8

93 pdadmin> pop show test Protected object policy: test Description: Test POP Warning: no Audit level: none Quality of protection: none Time of day access: sun, mon, tue, wed, thu, fri, sat: anytime:local IP Endpoint Authentication Method Policy Any Other Network 0 Refer to Configuring Levels for Step-up Authentication on page 64 for a more detailed discussion on setting authentication levels. Examples Require users from IP address range and netmask to use level 1 authentication ( password by default): pdadmin> pop modify test set ipauth add Require a specific user to use level 0 authentication: pdadmin> pop modify test set ipauth add Prevent all users (other than those specified as in the examples above) from accessing the object: pdadmin> pop modify test set ipauth anyothernw forbidden Disabling Step-up Authentication by IP Address Syntax: pdadmin> pop modify <pop-name> set ipauth remove <network> <netmask> For example: pdadmin> pop modify test set ipauth remove Network-based Authentication Algorithm WebSEAL uses the following algorithm to process the conditions in apop: 1. Check the IP endpoint authentication method policy on the POP. 2. Check ACL permissions. 3. Check time-of-day policy on the POP. 3. WebSEAL Security Policy Tivoli SecureWay Policy Director WebSEAL Administration Guide 73

94 4. Check the audit level policy on the POP. Network-based Authentication Notes and Limitations The IP address used by WebSEAL for enforcing the network-based authentication policy should be the IP address of the originator of the TCP connection. If your network topology uses HTTP proxies, the address that appears to WebSEAL might be the IP address of the proxy server. In this case, WebSEAL is not able to definitively identify the true client IP address. You must be careful when setting a network-based authentication policy that network clients can directly connect to the WebSEAL server. Quality of Protection POP Policy The quality of protection POP attribute allows you to specify what level of data protection is required when performing an operation on an object. Currently, this attribute is only appropriate in a WebSEAL environment. The quality of protection POP attribute is the replacement for the P and I ACL permission bits that activated privacy and integrity requirements in previous versions of Policy Director. This older implementation of quality of protection was inefficient and impacted system performance. The quality of protection POP attribute permits a single transaction where the yes response to the ACL decision also includes the required quality of protection level. If the resource manager (such as WebSEAL) cannot guarantee the required level of protection, the request is denied. pdadmin> pop modify <pop-name> set qop {none integrity privacy} QOP level Privacy Description Data encryption is required (SSL). 74 Version 3.8

95 QOP level Integrity Description Use some mechanism to ensure that the data has not changed. For example: pdadmin> pop modify test set qop privacy Handling Unauthenticated Users (HTTP / HTTPS) WebSEAL accepts requests from both authenticated and unauthenticated users over HTTP and HTTPS. WebSEAL then relies on the Authorization Service to enforce security policy by permitting or denying access to protected resources. The following conditions apply to unauthenticated users who access over SSL: The exchange of information between the unauthenticated user and WebSEAL is encrypted just as it is with an authenticated user. An SSL connection between an unauthenticated user and WebSEAL only requires server-side authentication. Processing a Request from an Anonymous Client 1. An anonymous client makes a request to WebSEAL (over HTTP or HTTPS). 2. WebSEAL creates an unauthenticated credential for this client. 3. The request proceeds, with this credential, to the protected Web object. 4. The Authorization Service checks the permissions on the unauthenticated entry of the ACL for this object, and permits or denies the requested operation. 5. Successful access to this object depends on the unauthenticated ACL entry containing at least the read (r) and traverse (T) permissions. 3. WebSEAL Security Policy Tivoli SecureWay Policy Director WebSEAL Administration Guide 75

96 6. If the request fails the authorization decision, the client receives a login form (BA or Forms-based). Forcing User Login You can force an unauthenticated user to log in by correctly setting the appropriate permissions on the unauthenticated entry in the ACL policy that protects the requested object. The read (r) and traverse (T) permissions allow unauthenticated access to an object. To force an unauthenticated user to log in, remove the read (r) permission from the unauthenticated entry in the ACL policy that protects the object. The user receives a login prompt (BA or Forms-based). Applications of Unauthenticated HTTPS There are many practical business reasons for supporting unauthenticated access to WebSEAL over HTTPS: Some applications do not require a personal login, but require sensitive information, such as addresses and credit card numbers. Examples include online purchases of airline tickets and other merchandise. Some applications require that you register for an account with the business before you can proceed with further transactions. Again, sensitive information must be passed over the network. Controlling Unauthenticated Users with ACL/POP Policies Note: The any-authenticated entry type is equivalent to the any-other entry type. 1. To permit unauthenticated user access to public objects, protect the public content with an ACL that contains at least the read (r) and traverse (T) permissions for the unauthenticated and any-authenticated entries: unauthenticated Tr any-authenticated Tr 76 Version 3.8

97 Note: The unauthenticated entry is a mask (a bitwise and operation) against the any-authenticated entry when permissions are determined. A permission for unauthenticated is granted only if the permission also appears in the any-authenticated entry. Since unauthenticated depends on any-authenticated, it makes little sense for an ACL to contain unauthenticated without any-authenticated. If an ACL does contain unauthenticated without any-authenticated, the default response is to grant no permissions to unauthenticated. 2. To require encryption (SSL), protect the content with a Protected Object Policy (POP) that specifies privacy as a condition. See Quality of Protection POP Policy on page WebSEAL Security Policy Tivoli SecureWay Policy Director WebSEAL Administration Guide 77

98 78 Version 3.8

99 4 4. WebSEAL Authentication WebSEAL Authentication This chapter discusses how WebSEAL maintains session state and handles the authentication process. Successful authentication results in a Policy Director identity that represents the user. WebSEAL uses this identity to acquire credentials for that user. Credentials are used by the Authorization Service to permit or deny access to protected resources. Topic Index: Understanding the Authentication Process on page 80 Managing Session State on page 83 Authentication Configuration Overview on page 94 Configuring Basic Authentication on page 99 Configuring Forms Authentication on page 101 Configuring Client-side Certificate Authentication on page 103 Configuring HTTP Header Authentication on page 107 Configuring IP Address Authentication on page 109 Configuring Token Authentication on page 110 Supporting Multiplexing Proxy Agents on page 111 Tivoli SecureWay Policy Director WebSEAL Administration Guide 79

100 Understanding the Authentication Process Authentication is the method of identifying an individual process or entity that is attempting to login to a secure domain. WebSEAL supports several authentication methods by default and can be customized to use other methods. The result of successful authentication to WebSEAL is a Policy Director user registry identity. WebSEAL uses this identity to obtain a credential for that user. The Authorization Service uses this credential to permit or deny access to protected objects after evaluating the ACL permissions and POP conditions governing the policy for each object. Note: ACL = access control list policy POP = protected object policy During authentication, WebSEAL examines a client request for the following information: Session data Session data is information that identifies a specific connection between the client and the WebSEAL server. Session data is stored with the client and accompanies subsequent requests by that client. It is used to re-identify the client session to the WebSEAL server and avoid the overhead of establishing a new session for each request. Authentication data Authentication data is information from the client that identifies the client to the WebSEAL server. Authentication data types include client-side certificates, passwords, and token codes. When WebSEAL receives a client request, WebSEAL always looks for session data first, followed by authentication data. The initial client request never contains session data. 80 Version 3.8

101 Supported Session Data Types WebSEAL supports the following session data types: 1. SSL ID (defined by the SSL protocol) 2. Server-specific session cookie 3. BA header data 4. HTTP header data 5. IP address 4. WebSEAL Authentication When WebSEAL examines a client request, it searches for session data in the order specified in this list. Supported Authentication Methods Although WebSEAL functions independently of the authentication process, WebSEAL uses credentials to monitor all users participating in the secure domain. To obtain the necessary identity information for credentials acquisition, WebSEAL relies on the information gained from the authentication process. The following authentication methods are supported by WebSEAL for credentials acquisition: Authentication Method Supported Connection Type 1. Failover cookie HTTP and HTTPS 2. CDSSO ID token HTTP and HTTPS 3. Client-side certificate HTTPS 4. Token passcode HTTP and HTTPS 5. Forms authentication (username and password) HTTP and HTTPS 6. Basic Authentication (username and password) HTTP and HTTPS 7. HTTP headers HTTP and HTTPS 8. IP address HTTP and HTTPS When WebSEAL examines a client request, it searches for authentication data in the order specified in this table. Tivoli SecureWay Policy Director WebSEAL Administration Guide 81

102 Authentication methods can be independently enabled and disabled for both HTTP and HTTPS transports. If no authentication methods are enabled for a particular transport, the authentication process is inactive for clients using that transport. References to Detailed Configuration Information Managing Session State on page 83 Authentication Configuration Overview on page 94 Configuring Basic Authentication on page 99 Configuring Forms Authentication on page 101 Configuring Client-side Certificate Authentication on page 103 Configuring HTTP Header Authentication on page 107 Configuring IP Address Authentication on page 109 Configuring Token Authentication on page 110 Supporting Multiplexing Proxy Agents on page 111 CDAS authentication Refer to the Tivoli SecureWay Policy Director WebSEAL Developer Reference 82 Version 3.8

103 Managing Session State A secure connection, or session, between a client and a server requires that the server have the ability to remember over numerous requests who it is talking to. The server must have some form of session state information that identifies the client associated with each request. 4. WebSEAL Authentication Without an established session state between client and server, the communication between the client and the server must be renegotiated for each subsequent request. Session state information improves performance by eliminating repeated closing and re-opening of client/server connections. The client can log in once and make numerous requests without performing a separate login for each request. WebSEAL handles both HTTP and HTTPS communication. HTTP is a stateless protocol and does not provide any means of distinguishing one request from another. The SSL transport protocol, on the other hand, is specifically designed to provide a session ID to maintain session state information. HTTP communication can be encapsulated over SSL to become HTTPS. However, WebSEAL must often handle HTTP communication from unauthenticated clients. And there are times when the SSL session ID is not an appropriate solution. Therefore, WebSEAL is designed to use any of the following information types to maintain session state with a client: 1. SSL ID 2. Server-specific session cookie 3. BA header data 4. HTTP header data 5. IP address Tivoli SecureWay Policy Director WebSEAL Administration Guide 83

104 The GSKit and WebSEAL Session Caches A session cache allows a server to store the session ID information from multiple clients. Two session caches are available to accommodate both HTTPS and HTTP session state information. WebSEAL credentials cache The WebSEAL credentials cache stores any type of session ID information (see the list above) plus the credential information obtained for each client. Credential information is cached to eliminate repetitive queries to the user registry database during authorization checks. GSKit SSL session ID cache The GSKit session cache handles HTTPS (SSL) communication when SSL session ID information is used to maintain session state. The GSKit cache also maintains session state information for the SSL connection between WebSEAL and the LDAP user registry. There are several configuration parameters available for each cache that allow you to tune the performance of the cache. These parameters are summarized in the following figure: WebSEAL Client GSK SSL Session Cache Maintains: - SSL session ID WebSEAL Credentials Cache Maintains: - Session ID info - Credential info GSK Cache Configuration Parameters - ssl-v2-timeout - ssl-v3-timeout - ssl-cache-max-sessions WebSEAL Cache Configuration Parameters - timeout - inactive-timeout - max-entries Figure 13. Session Cache Configuration Parameters 84 Version 3.8

105 Configuring the WebSEAL Credentials Cache The following configuration tasks are available for the WebSEAL session/credentials cache: Setting the Maximum Concurrent Entries Value Setting the Cache Entry Timeout Value Setting the Cache Entry Inactivity Timeout Value 4. WebSEAL Authentication Setting the Maximum Concurrent Entries Value The max-entires parameter, located in the [session] stanza of the webseald.conf configuration file, sets the maximum number of concurrent entries in the WebSEAL session/credentials cache. This value corresponds to the number of concurrent login sessions. When the cache size reaches this value, entries are removed from the cache according to a least recently used algorithm to allow new incoming logins. The default number of concurrent login sessions is 4096: [session] max-entries = 4096 Setting the Cache Entry Timeout Value The timeout parameter, located in the [session] stanza of the webseald.conf configuration file, sets the maximum lifetime timeout for an entry in the WebSEAL session/credentials cache. WebSEAL caches credential information internally. The session cache timeout parameter dictates the length of time authorization credential information remains in memory on WebSEAL. The parameter is not an inactivity timeout. The value maps to a credential lifetime rather than a credential timeout. Its purpose is to enhance security by forcing the user to re-authenticate when the specified timeout limit is reached. The default login session timeout (in seconds) is 3600: Tivoli SecureWay Policy Director WebSEAL Administration Guide 85

106 [session] timeout = 3600 Setting the Cache Entry Inactivity Timeout Value The inactive-timeout parameter, located in the [session] stanza of the webseald.conf configuration file, sets the timeout value for login session inactivity. The default login session inactivity timeout (in seconds) is 600: [session] inactive-timeout = 600 To disable this timeout feature, set the parameter value to 0. Configuring the GSKit SSL Session ID Cache The following configuration tasks are available for the GSKit SSL session ID cache: Setting the Cache Entry Timeout Value Setting the Maximum Concurrent Entries Value Setting the Cache Entry Timeout Value The parameters for setting the maximum lifetime timeout for an entry in the GSKit SSL session ID cache are located in the [ssl] stanza of the webseald.conf configuration file. There are two parameters: one for SSL V2 connections (ssl-v2-timeout) and one for SSL V3 connections (ssl-v3-timeout). The default SSL V2 session timeout (in seconds) is 100 (with a possible range of 1-100): [ssl] ssl-v2-timeout = 100 The default SSL V3 session timeout (in seconds) is 7200 (with a possible range of ): [ssl] ssl-v3-timeout = Version 3.8

107 Setting the Maximum Concurrent Entries Value The ssl-max-entries parameter, located in the [ssl] stanza of the webseald.conf configuration file, sets the maximum number of concurrent entries in the GSKit SSL session ID cache. This value corresponds to the number of concurrent login sessions. When the cache size reaches this value, entries are removed from the cache according to a least recently used algorithm to allow new incoming logins. 4. WebSEAL Authentication The default number of concurrent login sessions is 4096: [ssl] ssl-max-entries = 4096 Maintaining State with Session Cookies One method of maintaining session state between a client and a server is to use a cookie to hold this session information. The server packages the state information for a particular client in a cookie and sends it to the client s browser. For each new request, the browser re-identifies itself by sending the cookie (with the session information) back to the server. Session cookies offer a possible solution for situations when the client uses a browser that renegotiates its SSL session after very short periods of time. For example, some versions of the Microsoft Internet Explorer browser renegotiate SSL sessions every two or three minutes. A session cookie only provides re-authentication of a client to the single, unique server that the client had previously authenticated to within a short time period (around ten minutes). The mechanism is based on a server cookie that cannot be passed to any machine other than the one which generated the cookie. In addition, the session cookie contains only a random number identifier that is used to index into the server s session cache. There is no other information exposed in the session cookie. The session cookie cannot compromise security policy. Tivoli SecureWay Policy Director WebSEAL Administration Guide 87

108 Understanding Session Cookies WebSEAL uses a secure server-specific session cookie. The following conditions apply to this cookie mechanism: Cookie contains session information only; it does not contain identity information Cookie resides only in the browser memory (it is not written to the browser cookie jar on the disk) Cookie has a limited lifetime (configurable) Cookie has path and domain parameters that prohibit its use by other servers Enabling and Disabling Session ID Cookies The ssl-id-sessions parameter, located in the [session] stanza of the webseald.conf configuration file, enables and disables session cookies. This parameter controls whether the SSL session ID is used to maintain the login session for clients accessing over HTTPS. If the parameter is set to no, session cookies are used for most authentication methods. [session] ssl-id-sessions = no A no configuration setting for this parameter results in the following conditions for clients accessing over HTTPS: 1. The SSL session ID is never used as session ID data. 2. Cookies will be used to maintain sessions with clients authenticating with Failover cookies, CDSSO ID tokens, Forms username and password, Token passcode, and client-side certificates. 3. Cookies are used for Basic Authentication clients only when use-same-session = yes (see next section). Otherwise, the BA header is used for session ID data. 4. The HTTP header is used as session ID data for clients authenticating with HTTP headers 5. The IP address is used as session ID data for clients authenticating with IP addresses. 88 Version 3.8

109 When you use cookies to maintain session state, the cookie is sent to the browser only once, following a successful login. However, some browsers enforce a limit on the number of in-memory cookies they can store concurrently. In some environments, applications can place a large number of in-memory cookies per domain on client systems. In this case, any configured WebSEAL session cookie or failover cookie can be easily replaced by another cookie. 4. WebSEAL Authentication When you configure WebSEAL to use session cookies (and perhaps failover cookies), you can set the resend-webseal-cookies parameter, located in the [session] stanza of the webseald.conf configuration file, to have WebSEAL send the session cookie and the failover cookie to the browser with every response. This action helps to ensure that the session cookie and the failover cookie remain in the browser memory. The resend-webseal-cookies parameter has a default setting of no : [session] resend-webseal-cookies = no Change the default setting to yes to send WebSEAL session cookies and failover cookies with every response. Enabling and Disabling Same Sessions You can configure WebSEAL to use the same session ID data when a client logs in over one type of transport (HTTP, for example), disconnects, and re-logs in over another type of transport (HTTPS, for example). The use-same-session parameter, located in the [session] stanza of the webseald.conf configuration file, enables and disables the recognition of the same session ID data. By default, this parameter is set to no : [session] use-same-session = no A yes configuration setting for this parameter results in the following conditions: Tivoli SecureWay Policy Director WebSEAL Administration Guide 89

110 1. Session cookies are used to identify the following client types for subsequent logins over another transport: a. Failover cookies b. Client-side certificates c. CDSSO ID token d. Token passcode e. Forms username and password f. Basic Authentication 2. The HTTP header is used for clients accessing with HTTP headers. 3. The IP address is used for clients accessing with IP addresses. 4. The ssl-id-sessions configuration is ignored; the resulting behavior is the same as if ssl-id-sessions were set to no. This logic is important because HTTP clients do not have an SSL session ID available as session data. 5. Because the cookies are available to both HTTP and HTTPS clients, they are not flagged as secure cookies. Determining Valid Session ID Data Types The session data type for a client accessing with a particular authentication method is determined by specific combinations of the following configuration parameters: Enabling or disabling session cookies (ssl-id-sessions) Enabling or disabling the ability to use the same session data when a client switches between HTTP and HTTPS (use-same-session) The following tables summarizes the valid session ID data for any given configuration that combines the ssl-id-sessions and use-same-session parameters: 90 Version 3.8

111 Authentication Method ssl-id-sessions = yes HTTPS Clients ssl-id-sessions = no use-same-session = no use-same-session = yes ssl-id-sessions ignored Failover cookie SSL ID Cookie Cookie Certificate SSL ID Cookie Cookie CDSSO SSL ID Cookie Cookie Token SSL ID Cookie Cookie Forms SSL ID Cookie Cookie BA SSL ID BA header Cookie HTTP header SSL ID HTTP header HTTP header IP address SSL ID IP address IP address 4. WebSEAL Authentication HTTP Clients Authentication use-same-session = no use-same-session = yes Method Failover cookie Cookie Cookie CDSSO Cookie Cookie Token Cookie Cookie Forms Cookie Cookie BA BA header Cookie HTTP header HTTP header HTTP header IP address IP address IP address Configuring Failover Cookies The following failover cookie feature (for HTTP and HTTPS) is appropriate for a client connecting to a replicated front-end WebSEAL server cluster through a load-balancing mechanism. The purpose of a failover cookie is to prevent forced re-authentication when the server that has the original session with the client suddenly becomes unavailable. A front-end WebSEAL cluster can be implemented to provide high availability of resources for large numbers of clients. The Tivoli SecureWay Policy Director WebSEAL Administration Guide 91

112 load-balancing mechanism intercepts the incoming requests and distributes the requests across the available front-end servers. Refer to the following diagram during this discussion. Replicated Front-end WebSEAL Servers WS1 Client WS2 Back-end Resources Load-balancing mechanism WS3 Figure 14. Failover Cookie Scenario The client is not aware of the replicated front-end server configuration. The load-balancing mechanism is the single point of contact for the requested URL. The load-balancing mechanism connects a client with an available server (such as WS1). A session state is established with WS1 and all subsequent requests from that client are sent to WS1. The problem that can be solved by failover cookies involves a situation when WS1 becomes unavailable for some reason (for example, system failure or taken off line by an administrator). If WS1 becomes unavailable, the load-balancing mechanism redirects the request to one of the other replicated servers (WS2 or WS3). The original session-to-credential mapping is now lost. The client is new to this substitute server and is normally forced to authenticate again. You can configure the replicated WebSEAL servers to encrypt a client s credential data in a server-specific cookie. The cookie is placed on the browser when the client first connnects. If the initial 92 Version 3.8

113 WebSEAL server becomes temporarily unavailable, the cookie (with the encrypted credential information) is presented to the substitute server. The replicated WebSEAL servers share a common key that can decrypt the credential information. The client can now establish a new session with a replica WebSEAL sever without being forced to re-authenticate. The reference point for the cookie is the DNS of the load-balancing mechanism. This single point of reference is important because the cookie is a server-specifc cookie, and not a domain-specific cookie. The cookie is only accepted by a server with the same DNS name as the server that created the cookie. The client always makes requests through the load-balancing mechanism. Therefore, the cookie is always accepted and then passed to the next available server during a failover operation. 4. WebSEAL Authentication Enabling Failover Cookies The failover-auth parameter, located in the [failover] stanza of the webseald.conf configuration file, enables or disables server-specific failover cookies: To enable failover cookies, enter http, https, or both. To disable failover cookies, enter none (default). For example: [failover] failover-auth = https You must set this parameter on each of the front-end WebSEAL servers. Encrypting and Decrypting the Credential Data To secure the cookie data, use the cdsso_key_gen utility provided by WebSEAL. This utility generates a symmetric key that encrypts and decrypts the credential data in the cookie. Specify the location (absolute pathname) of the key file when you run the utility: UNIX: # cdsso_key_gen <pathname> Tivoli SecureWay Policy Director WebSEAL Administration Guide 93

114 Windows: MSDOS> cdsso_key_gen <pathname> Run the utility on one of the replicated servers and manually copy the key file to each of the remaining replicated servers. Enter this key file location in the [failover] stanza of the webseald.conf configuration file of each server. If you do not specify a key file, the failover cookie functionality is disabled for that server: [failover] failover-cookies-keyfile = <absolute-pathname> You can give the key file any appropriate name, such as ws.key. Configuring the Cookie Lifetime The value for the cookie lifetime (in minutes) is set in the following parameter: failover-cookie-lifetime = 60 Authentication Configuration Overview You can enable and disable authentication for both HTTP and HTTPS clients on a per-method basis. The mechanisms for all authentication methods supported by WebSEAL are configured in the [authentication-mechanisms] stanza of the webseald.conf configuration file. Supported authentication method parameters include: Local (built-in) authenticators Parameters for local authenticators specify the appropriate built-in shared library (UNIX) or DLL (Windows) files. Custom external authenticators WebSEAL provides template server code that you can use to build and specify a custom external Cross Domain Authentication Service (CDAS) server. An external CDAS authenticator specifies the appropriate custom shared library. 94 Version 3.8

115 Local Authentication Parameters The following parameters specify local built-in authenticators: Parameter Description Forms and Basic Authentication passwd-ldap Client access with LDAP username and password. Token Authentication token-cdas Client access with LDAP username and SecurID token passcode. Client-side Certificate Authentication cert-ssl Client access with client-side certificate over SSL. HTTP Header and / or IP Address Authentication http-request Client access via special HTTP header and / or IP address. CDSSO ID Token Authentication cdsso Cross Domain Single Sign-on authentication. 4. WebSEAL Authentication You use the [authentication-mechanisms] stanza to configure the authentication method and the implementation in the following format: <authentication-method-parameter> = <shared-library> See References to Detailed Configuration Information on page 82. External Custom CDAS Authentication Parameters The following parameters are available to specify custom shared libraries for external CDAS servers: Parameter passwd-cdas token-cdas cert-cdas Description Client access with username and password for a third-party registry. Client access with username and token passcode. Client access with client-side certificate over SSL. Tivoli SecureWay Policy Director WebSEAL Administration Guide 95

116 Refer to the Tivoli SecureWay Policy Director WebSEAL Developer Reference for details on building and configuring a custom shared library that implements a CDAS server. Default Configuration for WebSEAL Authentication By default, WebSEAL is set to authenticate clients over SSL using Basic Authentication (BA) usernames and passwords (LDAP registry). WebSEAL is normally enabled for both TCP and SSL access. Therefore, a typical configuration of the [authenticationmechanisms] stanza includes support for username and password (LDAP registry) and support for client-side certificates over SSL. The following example represents the typical configuration of the [authentication-mechanisms] stanza for Solaris: [authentication-mechanisms] passwd-ldap = libldapauthn.so cert-ssl = libsslauthn.so To configure other authentication methods, add the appropriate parameter with its shared library (or CDAS module). For detailed configuration information on each authentication method, see References to Detailed Configuration Information on page 82. Configuring Multiple Authentication Methods You modify the [authentication-mechanism] stanza of the webseald.conf configuration file to specify the shared library to be used for any supported authentication method. The following conditions apply when you configure multiple authentication methods: 1. All authentication methods can function independently from each other. It is possible to configure a shared library for each supported method. 2. The cert-cdas method overrides the cert-ssl method when both are configured. You must enabled one of these to support client-side certificates. 96 Version 3.8

117 3. Only one password type authenticator is actually used when more than one is configured. WebSEAL uses the following order of priority to resolve multiple configured password authenticators: a. passwd-cdas b. passwd-ldap 4. It is possible to configure the same custom library for two different authentication methods. For example, you could write a custom shared library to process both username/password and HTTP header authentication. For this example, you would configure both the passwd-cdas and http-request parameters with the same shared library. It is the responsibility of the developer to maintain session state and avoid conflicts between the two methods. Prompting for Login WebSEAL prompts a client for a login under the following conditions: 1. An unauthenticated client that fails an authorization check 2. A Forms or Basic Authentication client that fails an authorization check 4. WebSEAL Authentication The following client types are presented a 403 failure error: 1. When an authorization check fails: a. Client-side certificate b. Failover cookie c. CDSSO d. IP address e. HTTP header 2. When a client authenticates with a method that is disabled by WebSEAL Logout and Change Password Commands Policy Director provides the following commands for supporting clients who authenticate over HTTP or HTTPS. Tivoli SecureWay Policy Director WebSEAL Administration Guide 97

118 pkmslogout Clients can use the pkmslogout command to log out from the current session when they use an authentication method that does not supply authentication data with each request. For example, pkmslogout does not work for clients using Basic Authentication or IP address authentication. In this case, you must close the browser to log out. The pkmslogout command is appropriate for authentication via client-side certificate, token passcode, Forms authentication, and certain implementations of HTTP header authentication. Run the command as follows: The browser displays a logout form defined in the webseald.conf configuration file: [acnt-mgt] logout = logout.html You can modify the logout.html file to suit your requirements. The pkmslogout utility also supports multiple logout response pages when the network architecture requires different exit screens for users logging out of distinctly different back-end systems. The following expression identifies a specific response file: where custom_logout_file is the filename of the logout response. This file must reside in the same lib/html/c directory that contains the default logout.html file and other sample HTML response forms. pkmspasswd You can use this command to change your login password when using Basic Authentication (BA) or Forms authentication. This command is appropriate over HTTP or HTTPS. For example: 98 Version 3.8

119 To assure maximum security when BA is used with WebSEAL, this command has the following behavior for a BA client: 1. The password is changed. 2. The client user is logged out from the current session. 3. When the client makes an additional request, the browser presents the client with a BA prompt. 4. The client must re-log in to continue making requests. 4. WebSEAL Authentication This scenario only applies to a client using Basic Authentication. Configuring Basic Authentication Basic Authentication (BA) is a standard method for providing a username and password to the authentication mechanism. BA is defined by the HTTP protocol and can be implemented over HTTP and over HTTPS. By default, WebSEAL is configured for authentication over HTTPS via Basic Authentication (BA) username and password. Enabling and Disabling Basic Authentication The ba-auth parameter, located in the [ba] stanza of the webseald.conf configuration file, enables and disables the Basic Authentication method. To enable the Basic Authentication method, enter http, https, or both. To disable the Basic Authentication method, enter none. For example: [ba] ba-auth = https Setting the Realm Name The realm name is the text that is displayed in the dialog box that appears when the browser prompts the user for login data. Tivoli SecureWay Policy Director WebSEAL Administration Guide 99

120 The configuration parameter that sets the realm name is located in the [ba] stanza of the webseald.conf configuration file. For example: [ba] basic-auth-realm = Policy Director Figure 15. BA Login Prompt Configuring the Basic Authentication Mechanism The passwd-ldap parameter specifies the shared library used to handle username and password authentication. On UNIX, the file that provides the built-in mapping function is a shared library called libldapauthn. On Windows, the file that provides the built-in mapping function is a DLL called ldapauthn. Authn Shared Library Mechanism Solaris AIX Windows HP-UX passwd-ldap libldapauthn.so libldapauthn.a ldapauthn.dll libldapauthn.sl 100 Version 3.8

121 You can configure the username and password authentication mechanism by entering the passwd-ldap parameter with the platform-specific name of the shared library file in the [authentication-mechanism] stanza of the webseald.conf configuration file. For example: Solaris: [authentication-mechanisms] passwd-ldap = libldapauthn.so 4. WebSEAL Authentication Windows: [authentication-mechanisms] passwd-ldap = ldapauthn.dll Configuration Conditions If Forms authentication is enabled for a specific transport, the Basic Authentication settings for that transport will be ignored. Configuring Forms Authentication Policy Director provides Forms authentication as an alternative to the standard Basic Authentication mechanism. This method produces a custom HTML login form from Policy Director instead of the standard login prompt resulting from a Basic Authentication challenge. When you use Forms-based login, the browser does not cache the username and password information as it does in Basic Authentication. Enabling and Disabling Forms Authentication The forms-auth parameter, located in the [forms] stanza of the webseald.conf configuration file, enables and disables the Forms authentication method. To enable the Forms Authentication method, enter http, https, or both. To disable the Forms Authentication method, enter none. For example: Tivoli SecureWay Policy Director WebSEAL Administration Guide 101

122 [forms] forms-auth = https Configuring the Forms Authentication Mechanism The passwd-ldap parameter specifies the shared library used to handle username and password authentication. On UNIX, the file that provides the built-in mapping function is a shared library called libldapauthn. On Windows, the file that provides the built-in mapping function is a DLL called ldapauthn. Authn Shared Library Mechanism Solaris AIX Windows HP-UX passwd-ldap libldapauthn.so libldapauthn.a ldapauthn.dll libldapauthn.sl You can configure the username and password authentication mechanism by entering the passwd-ldap parameter with the platform-specific name of the shared library file in the [authentication-mechanism] stanza of the webseald.conf configuration file. For example: Solaris: [authentication-mechanisms] passwd-ldap = libldapauthn.so Windows: [authentication-mechanisms] passwd-ldap = ldapauthn.dll Configuration Conditions If Forms authentication is enabled for a specific transport, the Basic Authentication settings for that transport will be ignored. Customizing HTML Response Forms Forms authentication requires you to use a custom login form. By default, the sample login.html form is located in the following directory: <install-directory>/lib/html 102 Version 3.8

123 You can customize the content and design of this form. For example: 4. WebSEAL Authentication Figure 16. Sample WebSEAL Login Form For detailed information on the available HTML forms you can customize, see Managing Custom HTML Pages on page 36. Configuring Client-side Certificate Authentication WebSEAL supports secure communication with clients using client-side digital certificates over SSL. In this authentication method, certificate information (such as the Distinguished Name or DN) is mapped to a Policy Director identity. Background: Mutual Authentication via Certificates Authentication via digital certificates takes place in two phases: WebSEAL identifies itself to SSL clients with its server-side certificate WebSEAL uses its database of Certificate Authority (CA) root certificates to validate clients accessing with client-side certificates 1. An SSL client requests a connection with a WebSEAL server. 2. In response, WebSEAL sends its public key via a signed server-side certificate. This certificate has been previously signed by a trusted third-party certificate authority (CA). Tivoli SecureWay Policy Director WebSEAL Administration Guide 103

124 3. The client checks whether the certificate s issuer is one that it can trust and accept. The client s browser usually contains a list of root certificates from trusted CAs. If the signature on WebSEAL s certificate matches one of these root certificates, then the server can be trusted. Request Server's Digital ID Response Client Browser's CA Root Certificates belsign certisign entrust verisign... verisign "I can trust who you are." WebSEAL Server Figure 17. Client Validates the WebSEAL Certificate 4. If there is no match for the signature, the browser informs its user that this certificate was issued by an unknown certificate authority. It is then the user s responsibility to accept or reject the certificate. 5. If the signature matches an entry in the browser s root certificate database, session keys are securely negotiated between the client and the WebSEAL server. The end result of this process is a secure channel over which the client can authenticate (for example, via username and password). After successful authentication, the client and server can continue to communicate securely over this channel. 6. Now the client sends its public key certificate to the WebSEAL server. 7. WebSEAL attempts to match the signature on the client certificate to a known CA. Like a client browser, the WebSEAL server maintains a list of root certificates from trusted CAs in its key database. 104 Version 3.8

125 8. If there is no match for the signature, WebSEAL will generate an SSL error code and send it to the client. 9. If there is a match for the signature, then the client can be trusted. Authentication of the client takes place, resulting in a Policy Director identity. 10. Session keys are securely negotiated between the client and the WebSEAL server. The end result of this process is a secure and trusted communication channel between the mutually authenticated client and server. The WebSEAL Test Certificate At installation, WebSEAL contains a self-signed test server certificate. Although this test certificate allows WebSEAL to respond to an SSL-enabled browser request, it cannot be verified by the browser (which does not contain an appropriate root CA certificate). Because the private key for this default certificate is contained in every WebSEAL distribution, this certificate offers no true secure communication. 4. WebSEAL Authentication To ensure secure communication over SSL, it is very important to register for and obtain a unique site server certificate from a trusted Certificate Authority (CA). You can use the GSKit ikeyman utility to generate a certificate request that is sent to the CA. You also use ikeyman to install and label the new site certificate. Use the webseal-cert-keyfile-label parameter in the [ssl] stanza of the webseald.conf configuration file to designate the certificate as the active WebSEAL server-side certificate (this setting overrides any certificate designated as default in the keyfile database). If you require different certificates for other scenarios (such as for mutually authenticated junctions), you can use the ikeyman utility to create, install, and label these additional certificates. See Configuring Key Database Parameters for WebSEAL on page 41. See Managing Certificates with ikeyman on page 249. Tivoli SecureWay Policy Director WebSEAL Administration Guide 105

126 Enabling and Disabling Certificate Authentication You can specify how WebSEAL is to handle authentication via client-side certificates over SSL by setting the accept-client-certs parameter, located in the [certificate] stanza of the webseald.conf configuration file. By default, WebSEAL does not accept client-side certificates: [certificate] accept-client-certs = never Additional values for this parameter include optional and required. The following table lists describes the values allowed for the accept-client-certs parameter: Value never optional required Description Do not accept X.509 certificates from clients. Ask clients for an X.509 certificate and use certificate-based authentication, if certificate is supplied. Ask clients for an X.509 certificate and use certificate-based authentication. If client does not present a certificate, do not allow a connection. Configuring the Certificate Authentication Mechanism The cert-ssl parameter specifies the shared library for mapping certificate authentication information. On UNIX, the file that provides the built-in mapping function is a shared library called libsslauthn. On Windows, the file that provides the built-in mapping function is a DLL called sslauthn. Authn Shared Library Mechanism Solaris AIX Windows HP-UX cert-ssl libsslauthn.so libsslauthn.a sslauthn.dll libsslauthn.sl 106 Version 3.8

127 You can configure the certificate authentication mechanism by entering the cert-ssl parameter with the platform-specific name of the shared library file in the [authentication-mechanism] stanza of the webseald.conf configuration file. Solaris: [authentication-mechanisms] cert-ssl= libsslauthn.so 4. WebSEAL Authentication Windows: [authentication-mechanisms] cert-ssl = sslauthn.dll The default mapping provided by the shared library file directly maps a certificate DN to an LDAP DN. Configuration Conditions If client-side certificate handling is set to required, all other authentication settings are ignored for HTTPS clients. Configuring HTTP Header Authentication Policy Director supports authentication via custom HTTP header information supplied by the client or a proxy agent. This mechanism requires a mapping function (a shared library) that maps the trusted (pre-authenticated) header data to a Policy Director identity. WebSEAL can take this identity and create a credential for the user. WebSEAL assumes custom HTTP header data has been previously authenticated. For this reason, it is recommended that you implement this method exclusively with no other authentication methods enabled. It is possible to impersonate custom HTTP header data. By default, this shared library is built to map data from Entrust Proxy headers. Tivoli SecureWay Policy Director WebSEAL Administration Guide 107

128 Enabling and Disabling HTTP Header Authentication The http-headers-auth parameter, located in the [http-headers] stanza of the webseald.conf configuration file, enables and disables the HTTP header authentication method. To enable the HTTP header authentication method, enter http, https, or both. To disable the HTTP header authentication method, enter none. For example: [http-headers] http-headers-auth = https Specifying Header Types You must specify all supported HTTP header types in the [auth-headers] stanza of the webseald.conf configuration file. [auth-headers] header = <header-type> By default, this built-in shared library is hard-coded to support Entrust Proxy header data. [auth-headers] header = entrust-client You must customize this file to authenticate other types of special header data and, optionally, map this data to a Policy Director identity. Refer to the Tivoli SecureWay Policy Director WebSEAL Developer Reference for API resources. Configuring the HTTP Header Authentication Mechanism The http-request parameter specifies the shared library for mapping HTTP authentication header information. On UNIX, the file that provides the built-in mapping function is a shared library called libhttpauthn. On Windows, the file that provides the built-in mapping function is a DLL called httpauthn. 108 Version 3.8

129 Authn Shared Library Mechanism Solaris AIX Windows HP-UX http-request libhttpauthn.so libhttpauthn.a httpauthn.dll libhttpauthn.sl By default, this built-in shared library is hard-coded to map Entrust Proxy header data to a valid Policy Director identity. You must customize this file to authenticate other types of special header data and, optionally, map this data to a Policy Director identity. Refer to the Tivoli SecureWay Policy Director WebSEAL Developer Reference for API resources. 4. WebSEAL Authentication You can configure the HTTP header authentication mechanism by entering the http-request parameter with the platform-specific name of the shared library file in the [authentication-mechanism] stanza of the webseald.conf configuration file. For example: Solaris: [authentication-mechanisms] http-request = libhttpauthn.so Windows: [authentication-mechanisms] http-request = httpauthn.dll Configuration Conditions 1. Session ID cookies are not used to maintain state if ssl-id-sessions = no. The unique header value is used to maintain state. 2. If the client encounters an authorization failure, the client receives a Forbidden page (HTTP 403). Configuring IP Address Authentication Policy Director supports authentication via an IP address supplied by the client. Tivoli SecureWay Policy Director WebSEAL Administration Guide 109

130 Enabling and Disabling IP Address Authentication The ipaddr-auth parameter, located in the [ipaddr] stanza of the webseald.conf configuration file, enables and disables the IP address authentication method. To enable the IP address authentication method, enter http, https, or both. To disable the IP address authentication method, enter none. For example: [ipaddr] ipaddr-auth = https Configuring the IP Address Authentication Mechanism Authentication via an IP address requires a custom shared library. Use http-request parameter for this shared library. Configuring Token Authentication Policy Director supports authentication via a token passcode supplied by the client. Enabling and Disabling Token Authentication The token-auth parameter, located in the [token] stanza of the webseald.conf configuration file, enables and disables the token authentication method. To enable the token authentication method, enter http, https, or both. To disable the token authentication method, enter none. For example: [token] token-auth = https Configuring the Token Authentication Mechanism The token-cdas parameter specifies the shared library for mapping token passcode authentication information. 110 Version 3.8

131 On UNIX, the file that provides the built-in mapping function is a shared library called libtokenauthn. On Windows, the file that provides the built-in mapping function is a DLL called tokenauthn. Authn Shared Library Mechanism Solaris AIX Windows HP-UX token-cdas libtokenauthn.so libtokenauthn.a tokenauthn.dll libtokenauthn.sl 4. WebSEAL Authentication By default, this built-in shared library is hard-coded to map SecurID token passcode data. You can customize this file to authenticate other types of special token data and, optionally, map this data to a Policy Director identity. Refer to the Tivoli SecureWay Policy Director WebSEAL Developer Reference for API resources. You can configure the token authentication mechanism by entering the token-cdas parameter with the platform-specific name of the shared library file in the [authentication-mechanism] stanza of the webseald.conf configuration file. For example: Solaris: [authentication-mechanisms] token-cdas = libtokenauthn.so Windows: [authentication-mechanisms] token-cdas = tokenauthn.dll Supporting Multiplexing Proxy Agents Policy Director provides solutions for securing networks that use a Multiplexing Proxy Agent (MPA). Tivoli SecureWay Policy Director WebSEAL Administration Guide 111

132 Standard Proxy Agents (SPA) are gateways that support per-client sessions between clients and the origin server over SSL or HTTP. WebSEAL can apply normal SSL or HTTP authentication to these per-client sessions. Multiplexing Proxy Agents (MPA) are gateways that accommodate multiple client access. These gateways are sometimes known as WAP gateways when clients access via Wireless Access Protocol (WAP). Gateways establish a single authenticated channel to the origin server and tunnel all client requests and responses through this channel. To WebSEAL, the information across this channel initially appears as multiple requests from one client. WebSEAL must distinguish between the authentication of the MPA server and the additional authentication of each individual client. Client A Client B MPA Gateway A B C WebSEAL Server Client C multiple sessions over single SSL channel MPA authenticates to WebSEAL MPA has membership in webseal-mpa-servers group clients authenticate to WebSEAL Figure 18. Communication over an MPA Gateway Since WebSEAL maintains an authenticated session for the MPA, it must simultaneously maintain separate sessions for each client. Therefore, the session data and authentication method used for the MPA must be distinct (different) from the session data and authentication method used by the client. 112 Version 3.8

133 Valid Session Data Types and Authentication Methods The session data type used by the MPA to WebSEAL must be distinct (different) from the session data type used by the client to WebSEAL. The table below lists the valid session types for the MPA and the client: Valid Session Types MPA-to-WebSEAL Client-to-WebSEAL SSL Session ID HTTP Header HTTP Header BA Header BA Header IP Address Cookie Cookie 4. WebSEAL Authentication The client cannot use an SSL session ID as the session data type. As an example, if the MPA uses a BA header for the session data type, the client s choices for session data type include only HTTP header and cookie. If the MPA uses an HTTP header for session data, the client can use a different HTTP header type. The server-specific cookie contains session information only; it does not contain identity information. If MPA support is enabled, the function of ssl-id-sessions changes. Normally, if ssl-id-sessions=yes, only the SSL session ID is used to maintain sessions for HTTPS clients. To allow the MPA to maintain a session with an SSL session ID and have clients maintain sessions using another method, this restriction is removed. See also Determining Valid Session ID Data Types on page 90. The authentication method used by the MPA to WebSEAL must be distinct (different) from the authentication method used by the client to WebSEAL. The table below lists the valid authentication methods for the MPA and the client: Tivoli SecureWay Policy Director WebSEAL Administration Guide 113

134 Valid Authentication Types MPA-to-WebSEAL Basic Authentication Forms Token HTTP Header Certificate IP Address Client-to-WebSEAL Basic Authentication Forms Token HTTP Header As an example, if the MPA uses Basic Authentication, the client s choices for authentication methods includes Forms, token, and HTTP header. Certificates and IP address authentication methods are not valid for use by the client. Normally, if either Forms (or token) authentication is enabled for a particular transport, Basic Authentication is automatically disabled for that transport (see Configuring the Basic Authentication Mechanism on page 100. If MPA support is enabled, this restriction is removed. This allows the MPA to log in, for example, with Forms (or token) and clients to log in with Basic Authentication over the same transport. Authentication Process Flow for MPA and Multiple Clients 1. The WebSEAL administrator performs the following preliminary configuration: Enable support for Multiplexing Proxy Agents Create a Policy Director account for the specific MPA gateway Add this MPA account to the webseal-mpa-servers group 2. Clients connect to the MPA gateway. 3. The gateway translates the request to an HTTP request. 4. The gateway authenticates the client. 114 Version 3.8

135 5. The gateway establishes a connection with WebSEAL with the client request. 6. The MPA authenticates to WebSEAL (using a method distinct from the client) and an identity is derived for the MPA (which already has a WebSEAL account). 7. WebSEAL verifies the MPA s membership in the webseal-mpa-servers group. 4. WebSEAL Authentication 8. A credential is built for the MPA and flagged as a special MPA type in the cache. Although this MPA credential accompanies each future client request, it is not used for authorization checks on these requests. 9. Now WebSEAL needs to further identify the owner of the request. The MPA is able to distinguish the multiple clients for proper routing of login prompts. 10. The client logs in and authenticates using a method distinct from the authentication type used for the MPA. 11. WebSEAL builds a credential from the client authentication data. 12. Session data type used by each client must be distinct from the session data type used by the MPA. 13. The Authorization Service permits or denies access to protected objects based on the user credential and the object s ACL permissions. Enabling and Disabling MPA Authentication The mpa parameter, located in the [mpa] stanza of the webseald.conf configuration file, enables and disables MPA authentication: To enable the MPA authentication method, enter yes. To disable the MPA authentication method, enter no. For example: Tivoli SecureWay Policy Director WebSEAL Administration Guide 115

136 [mpa] mpa = yes Create a User Account for the MPA Refer to the Tivoli SecureWay Policy Director Base Administration Guide and the Tivoli SecureWay Policy Director Web Portal Manager Administration Guide for information on creating user accounts. Add the MPA Account to the webseal-mpa-servers Group Refer to the Tivoli SecureWay Policy Director Base Administration Guide and the Tivoli SecureWay Policy Director Web Portal Manager Administration Guide for information on managing groups. MPA Authentication Limitations This release of Policy Director only supports one MPA per WebSEAL server. 116 Version 3.8

137 5 Cross Domain Sign-on Solutions When WebSEAL is implemented as a proxy server to provide protection to a secure domain, there is often a requirement to provide solutions for single sign-on to resources. This chapter discusses two cross domain single sign-on solutions. Topic Index: Configuring CDSSO Authentication on page 117 Configuring e-community Single Sign-on on page Cross Domain Sign-on Solutions Configuring CDSSO Authentication The Policy Director Cross Domain Single Sign-on (CDSSO) provides a mechanism for transferring user credentials across multiple secure domains. CDSSO allows Web users to perform a single sign-on and move seamlessly between two separate secure domains. The CDSSO authentication mechanism does not rely on a Master Authentication Server (see e-community SSO). CDSSO supports the goals of scalable network architecture by allowing the integration of multiple secure domains. For example, a large corporate extranet can be set up with two or more unique domains each with its own users and object space. CDSSO allows movement of users between the domains with a single sign-on. When a user makes a request to a resource located in another domain, the CDSSO mechanism transfers an encrypted user identity Tivoli SecureWay Policy Director WebSEAL Administration Guide 117

138 token from the first domain to the second domain. The second domain now has the user s identity (as authenticated in the first domain) and the user is not forced to perform another login. Integrating a Custom CDMF Shared Library In many CDSSO scenarios, the default one-to-one mapping between users in different domains may not suit all deployment requirements. The Cross Domain Mapping FrameWork (CDMF) is a programming interface that allows you to build a custom shared library that can handle extended user attributes and provide mapping services for the user identity. The CDMF programming interface allows flexibility in customizing the mapping of user identities and the handling of user attributes. Authentication Process Flow for CDSSO with CDMF The following process flow description is illustrated in Figure Any user who wants to participate in multiple domains must have a valid user account in the primary domain and an identity that can be mapped into a valid account in each of the participating remote domains. A user cannot invoke the CDSSO functionality without initially authenticating to an initial secure domain (A) that contains the user s account. 2. The user makes a request to access a resource in domain B via a custom link on a Web page. The link contains a special CDSSO expression: /pkmscdsso?<destination-url> For example: /pkmscdsso? 3. The request is first processed by the WebSEAL server in domain A. WebSEAL builds an authentication token that contains the user s Policy Director identity (short name), the current domain ( A ), additional user information, and a time stamp. 118 Version 3.8

139 The additional user information is obtained by a call out to the customized CDMF shared library (cdmf_get_usr_attributes). This library has the ability to supply user attributes that can be used by domain B during the user mapping process. WebSEAL triple-des encrypts this token data with the symmetric key generated by the cdsso_key_gen utility. This key file is shared and stored in the [cdsso-peers] stanza of the webseald.conf configuration file on both domain A and domain B WebSEAL servers. The token contains a configurable time stamp (authtoken-lifetime) that defines the lifetime of the token. The time stamp, when properly configured, can prevent replay attacks. 4. The domain A WebSEAL server re-directs the request plus the encrypted token back to the browser and then to the domain B WebSEAL server (HTTP redirection). 5. The domain B WebSEAL server uses its version of the same key file to decrypt and validate the token as coming from the referring domain. 5. Cross Domain Sign-on Solutions 6. The domain B WebSEAL server now calls out to a CDSSO authentication mechanism library. This CDSSO library in turn calls out to the customized CDMF library which performs the actual user mapping (cdmf_map_usr). The CDMF library passes the user s identity, and optionally additional user attribute information, back to the CDSSO library. The CDSSO library uses this information to build a credential. 7. The domain B authorization service permits or denies access to protected objects based on the user s credential and the specific ACL permissions associated with the requested objects. Tivoli SecureWay Policy Director WebSEAL Administration Guide 119

140 Domain A Client single sign-on / CDMF Shared Library SSL WebSEAL A Domain B /pkmscdsso / CDMF Shared Library WebSEAL B CDSSO Library Client clicks on link to Domain B. WebSEAL A CDSSO uses CDMF library to get additional user information. Then builds and sends encrypted ID token with request. WebSEAL B decrypts and validates token WebSEAL B CDSSO calls CDMF shared library to map the user identity. Credential is built and client participates in Domain B Figure 19. Cross Domain Single Sign-on Process with CDMF Enabling and Disabling CDSSO Authentication The cdsso-auth parameter, located in the [cdsso] stanza of the webseald.conf configuration file, enables and disables the CDSSO authentication method. To enable the CDSSO authentication method, enter http, https, or both. To disable the CDSSO authentication method, enter none. For example: [cdsso] cdsso-auth = https Configuring the CDSSO Authentication Mechanism The cdsso configuration parameter specifies the hard-coded shared library for mapping authentication information. On UNIX, the file that provides the built-in mapping function is a shared library called libcdssoauthn. 120 Version 3.8

141 On Windows, the file that provides the built-in mapping function is a DLL called cdssoauthn. Authn Shared Library Mechanism Solaris AIX Windows HP-UX cdsso libcdssoauthn.so libcdssoauthn.a cdssoauthn.dll libcdssoauthn.sl You can configure the CDSSO authentication mechanism by entering the cdsso parameter with the platform-specific name of the shared library file in the [authentication-mechanism] stanza of the webseald.conf configuration file. For example: Solaris: [authentication-mechanisms] cdsso = libcdssoauthn.so Windows: [authentication-mechanisms] cdsso = cdssoauthn.dll Encrypting the Authentication Token Data WebSEAL must encrypt the authentication data placed in the token using a key generated by the cdsso_key_gen utility. You must synchronize this key by sharing the key file with each WebSEAL server in each participating domain. Each participating WebSEAL server in each domain needs to use the same key. 5. Cross Domain Sign-on Solutions Note: The creation and distribution of key files is not a part of the Policy Director CDSSO process. The cdsso_key_gen utility requires that you specify the location (absolute pathname) of the key file when you run the utility: UNIX: # cdsso_key_gen <absolute-pathname> Windows: MSDOS> cdsso_key_gen <absolute-pathname> Tivoli SecureWay Policy Director WebSEAL Administration Guide 121

142 Enter this key file location in the [cdsso-peers] stanza of the webseald.conf configuration file of the participating WebSEAL server in each domain. The format includes the WebSEAL machine name and the key file location: [cdsso-peers] <webseal-machine-name> = <keyfile-location> Domain A Configuration Example: [cdsso-peers] = <pathname>/a-b.key Domain B Configuration Example: [cdsso-peers] = <pathname>/a-b.key In the above example, the A-B.key file would be generated on one machine (WebSEAL A, for example) and manually (and securely) copied to the other machine (WebSEAL B, for example). Configuring the Token Time Stamp The token contains a configurable time stamp that defines the lifetime of the identity token. Once the time stamp has expired, the token is considered invalid and is not used. The time stamp is used to help prevent replay attacks by setting a value short enough to prevent the token from being stolen and replayed within its lifetime. The authtoken-lifetime parameter, located in the [cdsso] stanza of the webseald.conf configuration file, sets the token lifetime value. The value is expressed in seconds. The default value is 180: [cdsso] authtoken-lifetime = 180 You must take into account any clock skew between the participating domains. Expressing CDSSO HTML Links HTML links to resources on a secondary secure domain must contain a special CDSSO expression: /pkmscdsso?<destination-url> 122 Version 3.8

143 For example: /pkmscdsso? Protecting the Authentication Token While the authentication token does not contain authentication information (such as username and password), it does contain a user identity that is trusted within the receiving domain. The token itself must therefore be protected against theft and replay. The token is protected against theft off the wire through the use of SSL to secure communications between the WebSEAL servers and the users. The token could conceivably be stolen from the user s browser history. The time stamp on the token should be short enough to make it unlikely that the token could be stolen and replayed during the lifetime of the token. However, a token that has expired with respect to its time stamp is still vulnerable to cryptographic attacks. If the key used to encrypt the token is discovered or otherwise compromised, a malicious user could build their own tokens. 5. Cross Domain Sign-on Solutions These tokens could then be inserted into a pseudo-cdsso flow. They would be indistinguishable from real authentication tokens to the WebSEAL servers participating in the CDSSO domain. For this reason, the keys used to protect the tokens must also be carefully managed, and changed on a regular basis. Configuring e-community Single Sign-on E-community single sign-on is another implementation of cross-domain authentication in a Policy Director environment. The goal of cross-domain authentication is to allow users to access resources across multiple servers in multiple domains without re-authentication. An e-community is a group of distinct domains (Policy Director or DNS) that participate in a business relationship. These participating domains can be configured as part of one business (and perhaps using different DNS names for geographic reasons), or as disparate Tivoli SecureWay Policy Director WebSEAL Administration Guide 123

144 businesses with a shared relationship (for example, company headquarters, a life insurance company, and a financial management company). In either scenario, there is always one domain that is designated the home or owner domain. In the case of participating businesses, the home domain owns the business agreements that govern the e-community. In both scenarios, authentication information about the users who participate in the e-community (including the user names and passwords used for authentication) is maintained in the home domain. This arrangement allows a single point of reference for administration issues, such as help desk calls within the e-community that all refer to the home domain. Alternatively, you can use the Policy Director Web Portal Manager to delegate the management of this information such that participating domains have responsibility for the administration of their own users. The diagram below illustrates a sample e-community with two participating domains: domain A (da.com) and domain B (db.com). In this example, domain A represents the home or owner domain. Domain B is a participating, or remote, domain. 124 Version 3.8

145 Domain A Domain B WebSEAL MAS Client WebSEAL 3 mas.da.com ws3.db.com WebSEAL 1 ws1.da.com WebSEAL 2 ws2.da.com WebSEAL 4 ws4.db.com 5. Cross Domain Sign-on Solutions Figure 20. The e-community Model The home domain owns the users that is, it controls the user s authentication information. Regardless of where a user makes a request for resources, the home domain is always where the user must authenticate. Authentication occurs against a master authentication server (MAS) a server (or set of replica servers) that is located in the home domain and configured to authenticate all users. The diagram represents the MAS as mas.da.com. The duty of the MAS should be restricted to providing authentication services. The MAS should not contain resources that are available to users. Once a user has successfully authenticated to the MAS, the MAS generates a vouch for token. This token is passed back to the server where the user is making the request. The server treats this vouch for token as proof that the user has successfully authenticated to the MAS and can participate in the e-community. Tivoli SecureWay Policy Director WebSEAL Administration Guide 125

146 The transfer of information between e-community domains is described in detail in the section e-community Process Flow on page 127. e-community Features and Requirements The model supports access via direct URLs (bookmarks) to resources. This feature contrasts with the CDSSO model that relies on a specially configured pkmscdsso link (see Configuring CDSSO Authentication on page 117). The e-community implementation requires a consistent configuration across all WebSEAL servers in all domains participating in the e-community. All users who are participating in the e-community authenticate against a single master authentication server (MAS) located in the home domain. The e-community implementation allows for local authentication in remote domains if the user does not have a valid account with the MAS (for example, users who belong to domain B but do not participate in the domain A-domain B e-community). A user who fails authentication with the MAS when requesting a resource in a non-mas (but participating) domain is given the option to authenticate to the local server where the request is being made. The MAS (and eventually other selected servers in the remote domains) vouch for the user s authenticated identity. Domain-specific cookies are used to identify the server that can provide vouch for services. This allows servers in a remote domain to request vouch for information locally. The encrypted contents of e-community cookies do not contain user identity or security information. Special tokens are used to pass encrypted vouched for user identity. The vouch for token does not contain actual user authentication information. Integrity is provided by shared secret key (triple-des). The token contains a time-out (lifetime) value to limit the duration of the token validity. 126 Version 3.8

147 The e-community implementation is supported on both HTTP and HTTPS. Individual e-community domains manage their own user identities and associated privileges. You can use the Cross Domain Mapping Function (CDMF) API to map a user from a remote domain to a valid user in the local domain. If the e-community domains share global user identities, this mapping function is not required. Configuration for e-community is set in the webseald.conf file of each participating WebSEAL server. e-community Process Flow An e-community consists of a master authentication WebSEAL server (MAS) and additional WebSEAL servers located in the home domain and remote domains. The MAS can exist as a single instance of a WebSEAL server, or a set of WebSEAL replicas located behind a load balancer (where the load balancer is identified as the MAS). All participating local and remote WebSEAL servers need to be configured to use the home domain MAS for initial client authentication. This is a hard requirement for servers in the home domain, and a soft requirement for servers in remote domains. For example, some servers in remote domains can be configured to handle their own authentication. These servers, and the resources they protect, can operate independently of the e-community, even if they are located in a participating e-community domain. 5. Cross Domain Sign-on Solutions The e-community implementation is based on a vouch for system. Normally, when a user requests a resource from a WebSEAL server where the user has not established a valid session, WebSEAL prompts the user for authentication information. In an e-community configuration, the WebSEAL server identifies a vouch for server and requests verification from this vouch for server that the user has authenticated. The vouch for server has valid credential information for that user. For the user s first request, the vouch for server is always the MAS. The MAS continues to serve as the vouch for server for Tivoli SecureWay Policy Director WebSEAL Administration Guide 127

148 resources located in the home domain. As the user continues with resource requests across the e-community, an individual server in each remote domain can build its own credential for the user (based on user identity information from the MAS) and assume the role of vouch for server for resources in its domain. The verification requested of the vouch for server takes the form of a vouch for token. The vouch for server creates the token and returns it to the requesting WebSEAL server. The user identity information in the token is encrypted. The token contains a lifetime limit. Upon receipt of the vouch for token, the requesting server builds credentials and a local session for that user. The user can now access the requested resource based on normal authorization controls. The user benefits from not having to re-authenticate a goal of the e-community model. Refer to the following diagram as you follow the e-community process flow in the remainder of this section. The process flow describes two possible FIRST access scenarios (1 and 2). These are followed by two possible NEXT access scenarios (3 and 4) which follow immediately after 2 or 3. Scenario 5 occurs any time after the initial access. 128 Version 3.8

149 Domain A Domain B WebSEAL MAS mas.da.com WebSEAL 1 Client WebSEAL 3 ws3.db.com ws1.da.com WebSEAL 2 ws2.da.com Figure 21. e-community Process Flow WebSEAL 4 ws4.db.com Vouch For Servers The MAS is always used to authenticate a user accessing any part of the e-community for the first time. The MAS should perform only as an authentication server, and not as a resource provider. The MAS should not be configured to act as a master authentication server and, simultaneously, protect resources. This recommendation addresses performance concerns and is not a security requirement. 5. Cross Domain Sign-on Solutions The MAS is always the vouch for server for the home domain (domain A in this example). A domain-specific e-community cookie is used to identify the vouch for server for all other servers within a given domain. The vouch for server is the first server in a domain that requests a vouch for token from the MAS. The vouch for server provides vouch for information for the user within the domain. Subsequent requests for vouch for services in a given remote domain can be made locally by this server, rather than Tivoli SecureWay Policy Director WebSEAL Administration Guide 129

150 accessing the out-of-domain MAS.In the home domain, the e-community cookie identifies the MAS as the vouch for server. (1) FIRST e-community Access: WebSEAL 1 (Domain A) User requests a resource protected by WebSEAL 1 (within the same domain as MAS). The browser contains no e-community cookie for this domain. WebSEAL 1 has no cached credentials for the user. WebSEAL 1 configuration has e-community authentication enabled and specifies the location of the MAS. WebSEAL 1 re-directs the browser to a special vouch for URL on the MAS. The MAS receives the vouch for request and, failing to find credentials for that user, prompts the user to login. Upon successful login, the MAS builds a credential for the user, stores it in the cache, and re-directs the browser back to the originally requested URL on WebSEAL 1 with an encrypted vouch for token. In addition, a domain A-specific e-community cookie is placed on the browser to identify the vouch for server for this domain (in this case, the MAS). If the login attempt is unsuccessful, the MAS returns a vouch for token that indicates a failure status. This token is constructed to be indistinguishable from a success status vouch for token. The requesting server reacts to a failure status token as if the user had failed local authentication. WebSEAL 1 decrypts the token and builds its own credential for the user. Note: Identity mapping should not be required within the same domain. If identity mapping is required, WebSEAL 1 must use the Cross Domain Mapping Framework (CDMF). The authorization service permits or denies the request. (2) FIRST e-community Access: WebSEAL 3 (Domain B) 130 Version 3.8

151 User requests a resource protected by WebSEAL 3 (remote domain B). The browser contains no e-community cookie for this domain. WebSEAL 3 has no cached credentials for the user. WebSEAL 3 configuration has e-community authentication enabled and specifies the location of the MAS. WebSEAL 3 re-directs the browser to a special vouch for URL on the MAS. The MAS receives the vouch for request and, failing to find credentials for that user, prompts the user to login. Upon successful login, the MAS builds a credential for the user, stores it in the cache, and re-directs the browser back to the originally requested URL on WebSEAL 3 with an encrypted vouch for token. In addition, a domain A-specific e-community cookie is placed on the browser to identify the vouch for server for this domain (in this case, the MAS). If the login attempt is unsuccessful, the MAS returns a vouch for token that indicates a failure status. This token is constructed to be indistinguishable from a success status vouch for token. The requesting server reacts to a failure status token as if the user had failed local authentication. 5. Cross Domain Sign-on Solutions WebSEAL 3 decrypts the token and builds its own credential for the user. WebSEAL 3 creates and sets a second e-community cookie (valid for domain B) on the browser, identifying WebSEAL 3 as the vouch for server for domain B. The authorization service permits or denies the request. (3) NEXT e-community Access: WebSEAL 2 (Domain A) User requests a resource protected by WebSEAL 2 (within the same domain as MAS). The browser contains a domain A e-community cookie identifying the MAS as the vouch for server. WebSEAL 2 receives this cookie. WebSEAL 2 has no cached credentials for the user. WebSEAL 2 configuration has e-community authentication enabled and specifies the location of the MAS. The presence of Tivoli SecureWay Policy Director WebSEAL Administration Guide 131

152 the domain A e-community cookie overrides the WebSEAL 2 configuration for the MAS location. The cookie provides WebSEAL 2 with the identity of the vouch for server. (If scenario 2 occurred first, there would also be a domain B cookie maintained on the browser that would not be sent to a domain A server.) WebSEAL 2 re-directs the browser to a special vouch for URL on the domain A vouch for server identified in the cookie (in this case the MAS, because WebSEAL 2 is in domain A). The MAS receives the vouch for request and finds credentials for that user in the cache (this occurred in scenario 1 and 2). The MAS re-directs the browser back to the originally requested URL on WebSEAL 2 with an encrypted vouch for token. WebSEAL 2 decrypts the token and builds its own credential for the user. The authorization service permits or denies the request. (4) NEXT e-community Access: WebSEAL 4 (Domain B) User requests a resource protected by WebSEAL 4 (remote domain B). If scenario 2 occurred first, the browser contains a domain B e-community cookie identifying WebSEAL 3 as the vouch for server. WebSEAL 4 has no cached credentials for the user. WebSEAL 4 configuration has e-community authentication enabled and specifies the location of the MAS. The presence of a domain B e-community cookie overrides the WebSEAL 4 configuration for the MAS location. The cookie provides WebSEAL 4 with the identity of the vouch for server. (If scenario 1 occurred first, there would only be a domain A cookie maintained on the browser that would not be sent to a domain B server. The configured MAS location would be used instead. WebSEAL 4 would then become the vouch for server for domain B.) 132 Version 3.8

153 If scenario 2 occurred first, WebSEAL 4 re-directs the browser to a special vouch for URL on the domain B vouch for server identified in the domain B cookie (in this case WebSEAL 3). WebSEAL 3 receives the vouch for request and finds credentials for that user in the cache (this occurred in scenario 2). WebSEAL 3 re-directs the browser back to the originally requested URL on WebSEAL 4 with an encrypted vouch for token. WebSEAL 4 decrypts the token and builds its own credential for the user. The authorization service permits or denies the request. (5) ANOTHER e-community Access: WebSEAL 2 (Domain A) User connects to WebSEAL 2 (domain A) with a request. If scenario 3 occurred, WebSEAL 2 has cached credentials for the user. The authorization service permits or denies the request. 5. Cross Domain Sign-on Solutions Logout from the e-community If the user logs out by closing the browser, all SSL sessions and all e-community cookies are cleared. If the user logs out via the /pkmslogout page, the SSL session and e-community cookie for that domain are cleared. Understanding the e-community Cookie The e-community cookie is a domain-specific cookie set by one WebSEAL server, stored in the memory of the user s browser, and transmitted to other WebSEAL servers (in the same domain) in subsequent requests. The domain-specific cookie contains the name of the vouch for server, the e-community identity, a location (URL) of the vouch for server and functionality, and a lifetime value. The cookie contains no user information. Tivoli SecureWay Policy Director WebSEAL Administration Guide 133

154 The e-community cookie allows servers in participating domains to request vouch for information locally. The e-community cookie for the domain where the MAS resides plays a less significant role. The cookie has a lifetime (timeout) value that is set in the webseald.conf configuration file. This lifetime value specifies how long a remote server is able to provide vouch for information for the user. When the cookie lifetime has expired, the user must be redirected to the MAS for authentication. The cookie is cleared from memory when the browser is closed. If the user logs out of a specific domain, the e-community cookie is overwritten as empty. This action effectively removes it from the browser. Understanding the Vouch For Request and Reply The e-community vouch for operation requires dedicated functionality accessed through two specially constructed URLs: the vouch for request and the vouch for reply. These URLs are constructed during the e-community vouch for HTTP re-directs based on the configuration information in webseald.conf. The vouch for Request The vouch for request is triggered when a user requests a resource from a target server (configured for e-community) that contains no credential information for that user. The server sends an HTTP re-direct to the vouch for server (either the MAS or a server identified in an e-community cookie). The vouch for request contains the following information: The receiving server checks the ecommunity-name to validate the e-community identity. The receiving server uses the target-url in the vouch for reply to re-direct the browser back to the originally requested page. The pkmsvouchfor vouch for URL is configurable. 134 Version 3.8

155 For example: The vouch for Reply The vouch for reply is the response from the vouch for server to the target server. The vouch for reply contains the following information: The PD-VFHOST parameter identifies the server that performed the vouch for operation. The receiving (target) server uses this information to select the correct key required to decrypt the vouch for token (PD-VF). The PD-VF parameter represents the encrypted vouch for token. For example: Understanding the Vouch For Token In order to achieve cross domain single sign-on, some user identity information must be transmitted between servers. This sensitive information is handled using a re-direct that includes the identity information encrypted as part of the URL. This encrypted data is called a vouch for token. The token contains the vouch for success or failure status, the user s identity (if successful), the fully qualified name of the server that created the token, the e-community identity, and a creation time value. The holder of a valid vouch for token can use this token to establish a session (and set of credentials) at a server without explicitly authenticating to that server. The token is encrypted using a shared triple-des secret key so that its authenticity can be verified. Encrypted token information is not stored on the browser. 5. Cross Domain Sign-on Solutions Tivoli SecureWay Policy Director WebSEAL Administration Guide 135

156 The token is only passed once. The receiving server uses this information to build user credentials in its own cache. The server uses these credentials for future requests by that user during the same session. The token has a lifetime (timeout) value that is set in the webseald.conf configuration file.this value can be very short (seconds) to reduce the risk of a re-play attack. Encrypting the Vouch For Token WebSEAL must encrypt the authentication data placed in the token using a key generated by the cdsso_key_gen utility. You must synchronize this key by sharing the key file with each WebSEAL server in each participating domain. Each participating WebSEAL server in each domain needs to use the same key. Note: The creation and distribution of key files is not a part of the Policy Director e-community process. You must manually and securely copy keys to each participating server. The cdsso_key_gen utility requires that you specify the location (absolute pathname) of the key file when you run the utility: UNIX: # cdsso_key_gen <absolute-pathname> Windows: MSDOS> cdsso_key_gen <absolute-pathname> The location of the key used to secure tokens sent between servers within the same domain (home and remote) is entered as the value of the intra-domain-key parameter in the [e-community-sso] stanza of the webseald.conf configuration file. [e-community-sso] intra-domain-key = <absolute-pathname> The location of the key files used to secure tokens sent between the MAS and servers in remote domains is entered in the [inter-domain-keys] stanza. Other servers in the same domain as the MAS do not require inter-domain-keys. The MAS is the only server that needs to communicate with servers in remote domains. 136 Version 3.8

157 [inter-domain-keys] <domain-name> = <absolute-pathname> <domain-name> = <absolute-pathname Configuring an e-community This section reviews all the configuration parameters required for an e-community implementation. These parameters are located in the webseald.conf file. You must carefully configure this file for each participating server in the e-community. e-community-sso-auth This parameter enables or disables e-community authentication. Values include http, https, both, or none. For example: [e-community-sso] e-community-sso-auth = both The values http, https, and both specify the type of communication used by e-community participants. The value none disables e-community for that server. The default setting is none. master-http-port 5. Cross Domain Sign-on Solutions If e-community-sso-auth enables HTTP e-community authentication and the master authentication server listens for HTTP requests on a port other than the standard HTTP port (port 80), the master-http-port parameter identifies the non-standard port. This parameter is ignored if this server is the master authentication server. By default, this parameter is disabled. [e-community-sso] master-http-port = <port-number> master-https-port If e-community-sso-auth enables HTTPS e-community authentication and the master authentication server listens for HTTPS requests on a port other than the standard HTTP port (port 443), the master-http-port parameter identifies the non-standard port. This parameter is ignored if this server is the master authentication server. By default, this parameter is disabled. Tivoli SecureWay Policy Director WebSEAL Administration Guide 137

158 [e-community-sso] master-https-port = <port-number> e-community-name This parameter identifies the unifying name of the e-community for all participating servers in all participating domains. For example: [e-community-sso] e-community-name = companyabc The e-community-name value must be the same for all WebSEAL servers in all domains that are participating in the e-community. intra-domain-key This parameter identifies the location of the key file used to encrypt and decrypt tokens that are exchange within this server s domain. For example: [e-community-sso] intra-domain-key = /abc/xyz/key.file You must generate this key file in one location and then manually (and securely) copy the file to the specified location in all other WebSEAL servers within the domain. is-master-authn-server This parameter identifies whether this server is the MAS or not. Values include yes or no. For example: [e-community-sso] is-master-authn-server = yes Multiple WebSEALs can be configured to act as master authentication servers and then placed behind a load balancer. In this scenario, the load balancer is recognized as the MAS by all other WebSEAL servers in the e-community. master-authn-server 138 Version 3.8

159 If the is-master-authn-server parameter is set to no, this parameter must be uncommented and specified. The parameter identifies the fully qualified domain name of the MAS. For example: [e-community-sso] master-authn-server = mas.da.com vf-token-lifetime This parameter sets the lifetime timeout value (in seconds) of the vouch for token. This value is checked against the creation time stamped on the cookie. The default value is 180 seconds. You must take into account clock skew between participating servers. For example: [e-community-sso] vf-token-lifetime = 180 vf-url This parameter specifies the vouch for URL The value must begin with a forward-slash (/). The default value is /pkmsvouchfor. For example: [e-community-sso] vf-url = /pkmsvouchfor 5. Cross Domain Sign-on Solutions You can also express an extended URL: vf-url = /ecomma/pkmsvouchfor ec-cookie-lifetime This parameter specifies the maximum lifetime (in minutes) of the e-community domain cookie. The default value is 300 minutes. For example: [e-community-sso] ec-cookie-lifetime = 300 Inter Domain Keys The location of the key files required for encrypting and decrypting tokens between the MAS and participating servers in remote domains is specified in the [inter-domain-keys] stanza. You must Tivoli SecureWay Policy Director WebSEAL Administration Guide 139

160 specify fully qualified domain names for the servers and absolute path names for the key file locations. The following example provides the MAS (domain A) with key files for communicating with two remote domains: [inter-domain-keys] db.com = /abc/xyz/key.fileb dc.com = /abc/xyz/key.filec In this example, key.fileb identifies the key file used between domain A and domain B. key.filec identifies the key file used between domain A and domain C. Each remote server would need to have a copy of the appropriate key file used by the MAS. To exchange tokens with the MAS (domain A), all servers in domain B require copies of key.fileb. [inter-domain-keys] da.com = /efg/hij/key.fileb To exchange tokens with the MAS (domain A), all servers in domain C require copies of key.filec. [inter-domain-keys] da.com = /efg/hij/key.filec Configuring the CDSSO Authentication Mechanism The e-community configuration requires that you enable the cdsso authentication mechanism. This mechanism is required when the requesting server builds user credentials from the identity information contained in the vouch for token. The cdsso configuration parameter specifies the hard-coded shared library for mapping authentication information. On UNIX, the file that provides the built-in mapping function is a shared library called libcdssoauthn. On Windows, the file that provides the built-in mapping function is a DLL called cdssoauthn. 140 Version 3.8

161 Authn Shared Library Mechanism Solaris AIX Windows HP-UX cdsso libcdssoauthn.so libcdssoauthn.a cdssoauthn.dll libcdssoauthn.sl You can configure the CDSSO authentication mechanism by entering the cdsso parameter with the platform-specific name of the shared library file in the [authentication-mechanism] stanza of the webseald.conf configuration file. For example: Solaris: [authentication-mechanisms] cdsso = libcdssoauthn.so Windows: [authentication-mechanisms] cdsso = cdssoauthn.dll 5. Cross Domain Sign-on Solutions Tivoli SecureWay Policy Director WebSEAL Administration Guide 141

162 142 Version 3.8

163 6 WebSEAL Junctions The connection between a WebSEAL server and a back-end Web application server is known as a WebSEAL junction, or junction. A WebSEAL junction is a TCP/IP connection between a front-end WebSEAL server and a back-end Web application server. Junctions allow WebSEAL to protect Web resources located on back-end servers. You can create WebSEAL junctions with the pdadmin command-line utility or with the Web Portal Manager. This chapter discusses the details of the many options for configuring WebSEAL junctions. Topic Index: WebSEAL Junctions Overview on page 144 Using pdadmin server task to Create Junctions on page 146 Configuring a Basic WebSEAL Junction on page 147 Mutually Authenticated SSL Junctions on page 150 Creating TCP and SSL Proxy Junctions on page 155 WebSEAL-to-WebSEAL Junctions Over SSL on page 156 Additional Junction Options on page 157 Technical Notes for Using WebSEAL Junctions: on page 175 Using query_contents with Third-Party Servers on page WebSEAL Junctions Tivoli SecureWay Policy Director WebSEAL Administration Guide 143

164 WebSEAL Junctions Overview You can create the following WebSEAL junction types: WebSEAL to back-end server over TCP connection WebSEAL to back-end server over SSL connection WebSEAL to back-end server over TCP connection via HTTP proxy server WebSEAL to back-end server over SSL connection via HTTPS proxy server WebSEAL to WebSEAL over SSL connection You must address the following two concerns when creating any junction: 1. Decide where to junction (mount) the Web application server(s) in the WebSEAL object space. 2. Choose the type of junction. Junction Database Location and Format WebSEAL junction information is now store in XML-formatted database files. The location of the junction database directory is defined in the [junction] stanza of the webseald.conf configuration file. The directory is relative to the WebSEAL server root (server-root parameter in the [server] stanza): [junction] junction-db = jct Each junction is defined in a separate file with a.xml extension. Use pdadmin utility to create and manage junctions and options. The XML format allows you to manually create, edit, duplicate, and backup junction files. Applying Coarse-Grained Access Control: Summary 1. Use the pdadmin utility or the Web Portal Manager to create a junction between WebSEAL and the back-end server. 144 Version 3.8

165 2. Place an appropriate ACL policy on the junction point to provide coarse-grained control to the back-end server. Applying Fine-Grained Access Control: Summary 1. Use the pdadmin utility or the Web Portal Manager to create a junction between WebSEAL and the back-end server. WebSEAL cannot automatically see and understand a third-party file system. You must inform WebSEAL of the third-party object space using a special application, called query_contents, that inventories the third-party Web space and reports the structure and contents to WebSEAL. 2. Copy the query_contents program to the third-party server. 3. Apply ACL policy to appropriate objects in the unified object space. Guidelines for Creating WebSEAL Junctions The following guidelines summarize the rules for junctions: You can add a junction anywhere in the primary WebSEAL object space You can junction multiple replica servers at the same mount point Multiple replica servers mounted at the same junction point must be of the same type TCP or SSL ACL policies are inherited across junctions to third-party servers The junction point should not match any directory in the Web space of the local WebSEAL server. For example, if WebSEAL has resources of the form /path/..., do not create a junction point with the name /path. 6. WebSEAL Junctions The junction point should not match any directory in the Web space of the back-end server if HTML pages from that server contain programs (such as Javascript or applets) with server-relative URLs to that directory. For example, if pages from the back-end server contain programs with a URL of form /path/..., do not create a junction point of name /path. Tivoli SecureWay Policy Director WebSEAL Administration Guide 145

166 WebSEAL Only Supports HTTP 1.0 Across Junctions WebSEAL only supports HTTP 1.0 across junctions. This limitation can affect performance tuning and development of applications deployed on back-end junctioned servers. Connection Supported Protocol RFC Number Front-end (client-to-webseal) Back-end (WebSEAL-tojunctioned server) HTTP/1.0 and HTTP/1.1 HTTP/1.0 only RFC2068 RFC1945 Note: The HTTP/1.0 Keep-Alive is not supported for the front-end connection. The HTTP persistent connection is supported for HTTP/1.1. Additional References for WebSEAL Junctions See Understanding WebSEAL Junctions on page 9 for a conceptual overview of WebSEAL junctions. See WebSEAL Junction Reference on page 241 for complete information on junction command options. Using pdadmin server task to Create Junctions Before using pdadmin, you must login to a secure domain as the sec_master administration user. For example: UNIX: # pdadmin pdadmin> login Enter User ID: sec_master Enter Password: pdadmin> Windows: 146 Version 3.8

167 MSDOS> pdadmin pdadmin> login Enter User ID: sec_master Enter Password: pdadmin> To create WebSEAL junctions, you use the pdadmin server task command: pdadmin> server task <server-name> <task> The server-name argument is the full expression of the actual machine name and the Policy Director component used by this command (such as WebSEAL). <policy-director-component>-<machine-name> For example, if the machine name is cruz and the Policy Director component is WebSEAL, the server-name is: webseald-cruz Use the server list command to verify server-name expressions: pdadmin> server list webseald-cruz Configuring a Basic WebSEAL Junction WebSEAL supports both standard TCP (HTTP) and secure SSL (HTTPS) junctions between WebSEAL and back-end Web application servers. The junction between WebSEAL and the back-end server is independent of the type of connection (and its level of security) between the client and the WebSEAL server. 6. WebSEAL Junctions The mandatory command options required to create a basic WebSEAL junction using pdadmin include: Host name of the back-end application server ( h option) Junction type: tcp, ssl, tcpproxy, sslproxy, local ( t option) Junction point (mount point) Tivoli SecureWay Policy Director WebSEAL Administration Guide 147

168 pdadmin> server task <server-name> create t <type> h <host-name> <jct-point> For example: pdadmin> server task webseald-cruz create -t tcp -h doc.tivoli.com /pubs TCP Type Junctions A WebSEAL junction over a TCP connection provides the basic properties of a junction but does not provide secure communication across the junction. Secure Domain Client WebSEAL / Junction /mnt HTTP TCP Web Application Server Figure 22. Non-secure TCP (HTTP) Junction To create a secure TCP junction and add an initial server, use the create command with the t tcp option: pdadmin> server task <server-name> create t tcp h <host-name> [ p <port>] <jct-point> The default port value for a TCP junction (if not specified) is 80. SSL Type Junctions SSL junctions function exactly like TCP junctions, with the added value that all communication between WebSEAL and the back-end server is encrypted. 148 Version 3.8

169 Secure Domain Client WebSEAL / Junction /mnt HTTPS SSL TCP Web Application Server Figure 23. Secure SSL (HTTPS) Junction SSL junctions allow secure end-to-end browser-to-application transactions; You can use SSL to secure communications from the client to WebSEAL and from WebSEAL to the back-end server. The back-end server must be HTTPS-enabled when you use an SSL junction. To create a secure SSL junction and add an initial server, use the create command with the t ssl option: pdadmin> server task <server-name> create t ssl h <host-name> [ p <port>] <jct-point> The default port value for an SSL junction (if not specified) is 443. Verifying the Back-end Server Certificate When a client makes a request for a resource on the back-end server, WebSEAL, in its role as a security server, performs the request on behalf of the client. The SSL protocol specifies that when a request is made to the back-end server, that server must provide proof of its identity via a server-side certificate. 6. WebSEAL Junctions When WebSEAL receives this certificate from the back-end server, it must verify its authenticity by matching the certificate against a list of root CA certificates stored in its certificate database. Policy Director uses the IBM Global Security Kit (GSKit) implementation of SSL. You must use the GSKit ikeyman utility to Tivoli SecureWay Policy Director WebSEAL Administration Guide 149

170 add the root certificate of the CA who signed the back-end server certificate to the WebSEAL certificate keyfile (pdsvr.kdb). For complete information on managing the certificate key database, refer to Managing Certificates with ikeyman on page 249. Examples of SSL Junctions Junction host sales.tivoli.com at junction point /sales over SSL: pdadmin> server task <server-name> create t ssl h sales.tivoli.com /sales Note: In the above example, the t ssl option dictates a default port of 443. Junction host travel_svr on port 4443 at junction point /travel over SSL: pdadmin> server task <server-name> create t ssl p 4443 h travel_svr /travel Mutually Authenticated SSL Junctions WebSEAL supports mutual authentication between a WebSEAL server and a back-end server over an SSL junction ( t ssl or t sslproxy). The following outline summarizes the supported functionality for mutual authentication over SSL (command options are listed where appropriate): 1. WebSEAL authenticates the back-end server (normal SSL process) WebSEAL validates server certificate from the back-end server See WebSEAL Validates Back-end Server Certificate on page 151. WebSEAL verifies the Distinguished Name (DN) contained in the certificate ( D) (optional, but highly recommended) See Distinguished Name (DN) Matching on page Back-end server authenticates WebSEAL (two methods) 150 Version 3.8

171 Back-end server validates client certificate from WebSEAL ( K) See WebSEAL Authenticates with Client Certificate on page 152. Back-end server validates WebSEAL identity information in Basic Authentication (BA) header ( B, U, W) See WebSEAL Authenticates with BA Header on page 153. The command options that control mutual authentication over SSL provide the following features: You can specify client certificate or BA authentication method. You can apply authentication method on a per-junction basis. Special considerations for combining the b options (for handling BA information) with mutual authentication over SSL are described in Handling Client Identity Information Across Junctions on page 153 WebSEAL Validates Back-end Server Certificate WebSEAL verifies a back-end server certificate according to the standard SSL protocol. The back-end server sends its server certificate to WebSEAL. WebSEAL validates the server certificate against a pre-defined list of root Certificate Authority (CA) certificates. The Certificate Authority (CA) certificates that form the trust chain for the application server certificate (from the signing CA up to and including the root certificate) must be included in the key database in use by WebSEAL. You use the ikeyman utility to create and manage the database of root CA certificates. See Managing Certificates with ikeyman on page 249. Distinguished Name (DN) Matching You can enhance server-side certificate verification through Distinguished Name (DN) matching. To enable server DN matching, you must specify the back-end server DN when you create the SSL junction to that server. Although DN matching is an optional 6. WebSEAL Junctions Tivoli SecureWay Policy Director WebSEAL Administration Guide 151

172 configuration, it is highly recommended that you implement this feature with mutual authentication over SSL junctions. During server-side certificate verification, the DN contained in the certificate is compared with the DN defined by the junction. The connection to the back-end server fails if the two DNs do not match. To enable the server DN matching, specify the back-end server DN when you create the SSL junction using the D <DN> option. To preserve any blank spaces in the string, surround the DN string with double quotation marks. For example: D /C=US/O=Tivoli/OU=SecureWay/CN=Policy Director The D option is only appropriate when used with the K or B option. WebSEAL Authenticates with Client Certificate Use the K option to enable WebSEAL authentication to the junctioned back-end server via client certificate. K <key-label> The conditions for this scenario include: The back-end server is set up to require verification of WebSEAL s identity with a client certificate. WebSEAL is configured (webseald.conf) to use a specific client certificate to authenticate to the back-end server (ssl-keyfile-label). It is also highly recommended that you configure the junction for DN matching ( D). The K option uses an argument that specifies the key-label of the required certificate as stored in the GSKit key database. Use the ikeyman utility to add new certificates to the key database. Use the ssl-keyfile-label parameter in the webseald.conf configuration file to configure the key-label. You must surround the key-label argument with quotation marks. For example: 152 Version 3.8

173 K cert1_tiv See Configuring Key Database Parameters for WebSEAL on page 41. WebSEAL Authenticates with BA Header Use the B U <username> W <password> option to enable WebSEAL authentication via Basic Authentication. B U <username> W <password> The conditions for this scenario include: The back-end server is set up to require verification of WebSEAL s identity with a BA header. Do not configure the junction with any b option. (Internally, however, the B option uses b filter.) WebSEAL is configured to pass its identity information in a BA header to authenticate to the back-end server. It is highly recommended that you also configure the junction for DN matching ( D). You must surround the user name and password arguments with double quotation marks. For example: U WS1 W abcde Handling Client Identity Information Across Junctions A junction can be set up to specify client identity information in BA headers. The b option allows four possible arguments: filter, supply, ignore, gso. You can find detailed information about these arguments in Configuring BA Headers for Single Sign-on Solutions on page WebSEAL Junctions The b option has an impact on the junction settings for mutual authentication and you must consider the correct combination of options. Tivoli SecureWay Policy Director WebSEAL Administration Guide 153

174 Using b supply WebSEAL authentication via BA header is not allowed with this option. This option uses the BA header for the original client user name and a dummy password. WebSEAL authentication via client certificate is allowed with this option. Using b ignore WebSEAL authentication via BA header is not allowed with this option. This option uses the BA header for the original client user name and password. WebSEAL authentication via client certificate is allowed with this option. Using b gso WebSEAL authentication via BA header is not allowed with this option. This option uses the BA header for user name and password information supplied by the GSO server. WebSEAL authentication via client certificate is allowed with this option. Using b filter Internally, the b filter option is used when WebSEAL authentication is set to use BA header information. The WebSEAL BA header is used for all subsequent HTTP transactions. To the back-end server, WebSEAL appears logged on at all times. WebSEAL authentication via client certificate is allowed with this option. If the back-end server requires actual client identity (from the browser), the CGI variables HTTP_IV_USER, HTTP_IV_GROUP, and HTTP_IV_CREDS can be used. For scripts and servlets, use the corresponding Policy Director-specific HTTP headers: iv-user, iv-groups, iv-creds. 154 Version 3.8

175 Creating TCP and SSL Proxy Junctions You can create WebSEAL junctions that allow communication to traverse network topologies that use HTTP or HTTPS proxy servers. You can configure the junction to handle requests as standard TCP communication or protected SSL communication. The create command requires one of the following arguments to the type option to establish either a TCP-based or SSL-based junction through a proxy server: t tcpproxy t sslproxy Both create and add commands require the following options and arguments to identity the proxy server and the target Web server: H <host-name> The DNS host name or IP address of the proxy server. P <port> The TCP port of the proxy server. h <host-name> The DNS host name or IP address of the target Web server. p <port> The TCP port of target Web server. Default is 80 for TCP junctions; 443 for SSL junctions. Example TCP proxy junction (entered as one line): pdadmin> server task <server-name> create t tcpproxy H clipper P 8081 h p 80 /ibm Example SSL proxy junction (entered as one line): pdadmin> server task <server-name> create t sslproxy H clipper P 8081 h p 443 /ibm 6. WebSEAL Junctions Tivoli SecureWay Policy Director WebSEAL Administration Guide 155

176 Secure Domain Client WebSEAL Clipper Proxy Server Internet Web Server junction at /ibm -H and -P -h and -p Figure 24. Example Proxy Junction WebSEAL-to-WebSEAL Junctions Over SSL Policy Director supports SSL junctions between a front-end WebSEAL server and a back-end WebSEAL server. Use the C option with the create command to junction the two WebSEAL servers over SSL and provide mutual authentication. Example: pdadmin> server task <server-name> create t ssl C h servera /jcta Mutual authentication occurs in the following two stages: The SSL protocol allows the back-end WebSEAL server to authenticate to the front-end WebSEAL server through its server certificate. The C option enables the front-end WebSEAL server to pass its identity information to the back-end WebSEAL server in a Basic Authentication (BA) header. Additionally, the C option enables the functionality of the c option that allows you to place Policy Director-specific client identity and group membership information into the HTTP header of the request destined for the back-end WebSEAL server. The header parameters include iv-user, iv-groups, and iv-creds. See Supplying Client Identity in HTTP Headers ( c) on page Version 3.8

177 The following conditions apply to WebSEAL-to-WebSEAL junctions: The junction is only appropriate with the t ssl or t sslproxy junction type. Both WebSEAL servers must share a common LDAP or DCE registry. This allows the back-end WebSEAL server to authenticate the front-end WebSEAL server identity information. Additional Junction Options You can provide the following additional WebSEAL junction functionality with additional options: Forcing a New Junction ( f) on page 157 Supplying Client Identity in HTTP Headers ( c) on page 158 Supplying Client IP Addresses in HTTP Headers ( r) on page 160 Passing Session Cookies to Junctioned Portal Servers ( k) on page 161 Supporting Case-Insensitive URLs ( i) on page 162 Processing URLs From Scripts and Client-side Applications ( j) on page 163 Handling Server-relative URLs with Junction Mapping on page 168 Stateful Junction Support ( s, u) on page 169 Specifying Back-End Server UUIDs for Stateful Junctions ( u) on page 170 Junctioning to Windows File Systems ( w) on page 174 Forcing a New Junction ( f) You must use the f option when you want to force a new junction that overwrites an existing junction. 6. WebSEAL Junctions The following example (server name is webseala) illustrates this procedure: Tivoli SecureWay Policy Director WebSEAL Administration Guide 157

178 1. Login to pdadmin: # pdadmin pdadmin> login Enter User ID: sec_master Enter Password: pdadmin> 2. Use the server task list command to display all current junction points: pdadmin> server task webseala list / 3. Use the server task show command to display details of the junction: pdadmin> server task webseala show / Junction point: / Type: Local Junction hard limit: 0 -using global value Junction soft limit: 0 -using global value Active worker threads: 0 Root Directory: /opt/pdweb/www/docs 4. Create a new local junction to replace the current junction point (the -f option is required to force a new junction that overwrites an existing junction): pdadmin> server task webseala create -t local -f -d /tmp/docs / Created junction at / 5. List the new junction point: pdadmin> server task webseala list / 6. Display the details of this junction: pdadmin> server task webseala show / Junction point: / Type: Local Junction hard limit: 0 -using global value Junction soft limit: 0 -using global value Active worker threads: 0 Root Directory: /tmp/docs Supplying Client Identity in HTTP Headers ( c) The c option allows you to insert Policy Director-specific client identity and group membership information into the HTTP headers of requests destined for junctioned third-party servers. The Policy 158 Version 3.8

179 Director HTTP header information enables applications on junctioned third-party servers to perform user-specific actions based on the client s Policy Director identity. HTTP header information must be transformed by the back-end server to environment variable format for use by a service on the back-end server. Header information is transformed into a CGI environment variable format by replacing all dashes (-) with underbars (_) and prepending HTTP to the beginning of the string. The value of the HTTP header becomes the value of the new environment variable. PD-specific HTTP Header Fields CGI Environment Variable Equivalents Description iv-user = HTTP_IV_USER = The short or long name of the client. Defaults to Unauthenticated if client is unauthenticated (unknown). iv-groups = HTTP_IV_GROUPS = A list of groups to which the client belongs. Consists of comma separated quoted entries. iv-creds = HTTP_IV_CREDS = Encoded opaque data structure representing a Policy Director credential. Supplies credentials to remote servers so mid-tier applications can use the Authorization API to call the Authorization Service. Refer to the Tivoli SecureWay Policy Director Authorization ADK Developer Reference. The Policy Director-specific HTTP header entries are available to CGI programs as the environment variables HTTP_IV_USER, HTTP_IV_GROUPS and HTTP_IV_CREDS. For other application framework products, see the product s documentation for instructions on extracting headers from HTTP requests. 6. WebSEAL Junctions c Syntax The c option specifies what Policy Director-specific HTTP header data is sent to the back-end application server. c <header-types> Tivoli SecureWay Policy Director WebSEAL Administration Guide 159

180 The header-types arguments include: all, iv_user, iv_user_l, iv_groups, and iv_creds. Argument iv_user iv_user_l iv_groups iv_creds Description Provides the user name (short form) as the iv-user field in the HTTP header of the request. Provides the full DN of the user (long form) as the iv-user field in the HTTP header of the request. Provides the user s list of groups as the iv-groups field in the HTTP header of the request. Provides the user s credential information as the iv-creds field in the HTTP header of the request. Note: Use either iv_user or iv_user_l, but not both. The c all option inserts all three types of identity information into the HTTP header (the short name format (iv_user ) is used in this case). Note: Separate multiple arguments with commas only. Do not enter any spaces. Examples: c all c iv_creds c iv_user,iv_groups c iv_user_l,iv_groups,iv_creds Supplying Client IP Addresses in HTTP Headers ( r) The r option allows you to insert client IP address information into the HTTP headers of requests destined for junctioned application servers. The Policy Director HTTP header information enables applications on junctioned third-party servers to perform actions based on this IP address information. 160 Version 3.8

181 HTTP header information must be transformed by the back-end server to environment variable format for use by a service on the back-end server. Header information is transformed into a CGI environment variable format by replacing all dashes (-) with underbars (_) and prepending HTTP to the beginning of the string. The value of the HTTP header becomes the value of the new environment variable. Note: The value of the IP address does not always represent the address of the originating client machine. The IP address value could represent the address of a proxy server or a network address translator (NAT). PD-specific HTTP Header Field iv-remote-address CGI Environment Variable Equivalent HTTP_IV_REMOTE_ ADDRESS Description The IP address of the client. This value could represent the IP address of a proxy server or a network address translator (NAT). The r option specifies that the IP address of the incoming request be sent to the back-end application server. The option is express without any arguments. Passing Session Cookies to Junctioned Portal Servers ( k) A Web portal is a server that offers a broad array of personalized resources and services. The k option allows you to send the Policy Director session cookie (originally established between the client and WebSEAL) to a back-end portal server. This option currently exists to directly support the integration of WebSEAL with the Plumtree Corporate Portal solution. 6. WebSEAL Junctions When a client requests a personal resource list from the portal server, the portal server builds this list by accessing resources located on other supporting application servers, also protected by Tivoli SecureWay Policy Director WebSEAL Administration Guide 161

182 WebSEAL. The session cookie allows the portal server to perform seamless single sign-on to these application servers, on behalf of the client. You include the k option, without arguments, when you create the junction between WebSEAL and the back-end portal server. Conditions to consider for a portal server configuration: For access via user name and password, Forms authentication is required. Do not use Basic Authentication (BA). The ssl-id-sessions parameter in the [session] stanza of the webseald.conf configuration files must be set to no. For HTTPS communication, this setting forces the use of a session cookie, instead of the SSL session ID, to maintain session state. If the portal server is front-ended by a WebSEAL cluster, enable the failover type cookie.the failover cookie contains encrypted credential information that allows authentication to succeed with any replicated WebSEAL server that processes the request. Supporting Case-Insensitive URLs ( i) By default, Policy Director treats URLs as case-sensitive when applying access controls. The i option is used to specify that WebSEAL treat URLs as case-insensitive when handling a request to a junctioned back-end server. When you set this option on the junction, WebSEAL does not distinguish between uppercase and lowercase characters when parsing URLs. By default, Web servers are expected to be case-sensitive. Although most HTTP servers support the HTTP specification that defines URLs as case-sensitive, some HTTP servers treat URLs as case-insensitive. For example, on case-insensitive servers, the following two URLS: Version 3.8

183 are viewed as the same URL. This behavior requires an administrator to place the same access controls (ACLs) on both URLs. By junctioning a third-party server with the i option, WebSEAL treats the URLs directed to that server as case-insensitive. Processing URLs From Scripts and Client-side Applications ( j) This section describes how WebSEAL handles script-generated absolute and server-relative links to resources on the back-end server. Background to the Problem on page 163 Handling Server-relative URLs with Junction Cookies on page 165 Handling Absolute URLs with Script Filtering on page 166 Handling Server-relative URLs with Junction Mapping on page 168 Background to the Problem When a client accesses a junctioned Web server, the returning information can be the result of plain HTML, a client-side application (applet), or a script. Web scripting languages include Javascripts, VBscripts, ASP, JSP, and ActiveX. Any page generated by HTML, a script, or an applet is likely to contain links (URLs) to other resources on that back-end server or elsewhere. URL expressions can appear in the following formats: absolute relative server-relative 6. WebSEAL Junctions A link back to the back-end server will only succeed if the URL is relative or contains information that identifies the junction. Tivoli SecureWay Policy Director WebSEAL Administration Guide 163

184 WebSEAL must examine the URLs contained in this wide variety of generated information and supply junction identity information when appropriate. URLs expressed in relative format never require any manipulation by WebSEAL. Links to the back-end server expressed in absolute or server-relative formats do not succeed because the original URL does not contain information about the junction. These links incorrectly appear as requests from objects located on the local WebSEAL server. Example relative URL expressions (link will always succeed): abc.html../abc.html./abc.html sales/abc.html Example absolute URL expression (link requires junction information): Example server-relative URL expressions (link requires junction information): /abc.html /accounts/abc.html WebSEAL handles dynamically generated absolute and server-relative URLs in the following ways: Static HTML sources Because HTML is plain text and easily parsed, WebSEAL automatically prepends the correct junction information to the URL, when appropriate. See Filtering Static HTML URLs from Junctioned Servers on page 176. Scripts and client-side application sources The complexity of scripts makes it inefficient for WebSEAL to filter embedded absolute and server-relative URL expressions as they pass from the back-end server to the client. WebSEAL must be configured to provide junction information, when appropriate. 164 Version 3.8

185 Note: All programmers of Web scripts are encouraged to use relative links (not absolute or server-relative) for dynamically generated URLs. Handling Server-relative URLs with Junction Cookies In the following scenario, a script located on the back-end server dynamically generates a server-relative URL expression. WebSEAL cannot manipulate this embedded code as it passes to the client. The client sees a URL that is incorrectly expressed because it does not include the junction information. /jcta Client Client incorrectly receives: /webseal/abc.html WebSEAL Application Server (serves Javascript) Dynamically generated server-relative URL: /abc.html Figure 25. Script-generated URL with No Filtering If the client requests the resource specified by this link, WebSEAL will incorrectly assume the link is pointing to a local page. After failing to find the page, it returns a Not Found error to the client. The j option provides a cookie-based solution for handling server-relative URLs that are dynamically generated by a Web script on the junctioned server and run on the client machine. General syntax: pdadmin> server task <server-name> create... j WebSEAL Junctions For each request, a junction-identifier cookie is sent to the client. The cookie contains the following variable and value: IV_JCT_<backend-server-name> = </junction-name> When the client makes a request using this URL, WebSEAL processes the URL in its original format. When it fails to locate the Tivoli SecureWay Policy Director WebSEAL Administration Guide 165

186 resource, WebSEAL immediately retries the request using the junction information supplied by the cookie. With the correct junction information in the URL expression, the resource is successfully located. The following diagram illustrates this solution for filtering server-relative URLs 1 Client Request WebSEAL /jcta with -j option Request Application Server (serves Javascript) 2 Script runs and displays link:/abc.html /jcta WebSEAL sends cookie to identify junction Script containing server-relative URL: /abc.html 3 Client makes request using link: /abc.html /jcta Cookie sent with requrest WebSEAL reformats link to: /jcta/abc.html abc.html successfully located Figure 26. Filtering Server-relative URLs WebSEAL provides an alternative, non-cookie-based solution for handling server-relative URLs. See Handling Server-relative URLs with Junction Mapping on page 168. Handling Absolute URLs with Script Filtering WebSEAL requires additional configuration to handle dynamically generated absolute URLs across a junction. The webseald.conf configuration file contains a parameter that enables or disables filtering of absolute URLs: [script-filtering] script-filter = no Script-filtering is disabled by default. To enable script filtering, set: script-filter = yes 166 Version 3.8

187 Note: You must also use the j option to create the junction to the back-end server. A junction-identifier cookie is sent to the client - although it is not required by the script-filtering mechanism. The script-filter mechanism expects absolute URLs with a standard schema, server, resource format: The script-filter mechanism replaces the schema and server portions of the link with the correct junction information. /junction-name/resource This solution requires additional processing overhead and can negatively impact performance. Limit your use of the script-filter parameter only to junctions that require support for absolute URL filtering. The following diagram illustrates this URL filtering solution: Client Client receives: /jcta/abc.html Client makes request using link: /jcta/abc.html Request WebSEAL script-filtering=yes WebSEAL reformats link to: /jcta/abc.html /jcta with -j option Request Application Server (serves Javascript) Script containing absolute URL: abc.html successfully located 6. WebSEAL Junctions Figure 27. Filtering Absolute URLs Tivoli SecureWay Policy Director WebSEAL Administration Guide 167

188 Handling Server-relative URLs with Junction Mapping Policy Director provides an alternative to the cookie-based solution for filtering server-relative URLs. You can create and activate a junction mapping table that maps specific target resources to junction names. WebSEAL checks the location information in the server-relative URL with the data contained in the junction mapping table. If the path information in the URL matches an entry in the table, WebSEAL directs the request to the junction associated with that location. The table is an ASCII text file called jmt.conf. The location of this file is specified in the [junction] stanza of the webseald.conf configuration file: jmt-map = lib/jmt.conf The format for data entry in the table consists of the junction name, a space, and the resource location pattern. You can also use wildcard characters to express the resource location pattern. In the following example of the junction mapping configuration file, two back-end servers are junctioned to WebSEAL at /jcta and /jctb: #jmt.conf #<junction-name> <resource-location-pattern> /jcta /documents/release-notes.html /jcta /travel/index.html /jctb /accounts/* /jctb /images/weather/*.jpg The original jmt.conf mapping table is an empty file. After you add data to the file, you must use the jmt load command to load the data so that WebSEAL has knowledge of the new information. pdadmin> server task <server-name> jmt load JMT table successfully loaded. The following conditions apply to the junction mapping table solution: This solution does not require the j option or junction cookie 168 Version 3.8

189 The mapping table requires setup and activation by a security administrator This solution does not handle links created with absolute URLs Resource location pattern matching must be unique across the local Web space and across junctioned Web application servers If there is a duplicate pattern entry in the file, the mapping table does not load. However, WebSEAL continues to run. If there is an error loading the mapping table, the mapping table is not available. However, WebSEAL continues to run. If the mapping table is empty or there is an error in the table entries, the mapping table does not load. However, WebSEAL continues to run. Any errors that occur while loading the mapping table result in serviceability entries in the WebSEAL server log file (webseald.log). Stateful Junction Support ( s, u) Most Web-enabled applications maintain a state for a sequence of HTTP requests from a client. This state is used, for example, to: Track a user s progress through the fields in a data entry form generated by a CGI program Maintain a user s context when performing a series of database inquiries Maintain a list of items in an online shopping cart application where a user randomly browses and selects items to purchase Servers that run Web-enabled applications can be replicated in order to improve performance through load sharing. When the WebSEAL server provides a junction to these replicated back-end servers, it must ensure that all the requests contained within a client session are forwarded to the correct server, and not distributed among the replicated back-end servers according to the load balancing rules. 6. WebSEAL Junctions By default, Policy Director balances back-end server load by distributing requests across all available replicated servers. Policy Tivoli SecureWay Policy Director WebSEAL Administration Guide 169

190 Director uses a least-busy algorithm. This algorithm directs each new request to the server with the fewest connections already in progress. The create command s flag overrides this load balancing rule and creates a stateful junction that ensures a client s requests are forwarded to the same server throughout an entire session. When the initial client request occurs, WebSEAL places a cookie on the client system that contains the UUID of the designated back-end server. When the client makes future requests to the same resource, the cookie s UUID information ensures that the requests are consistently routed to the same back-end server. The s option is appropriate for a single front-end WebSEAL server with multiple back-end servers junctioned at the same junction point. Note that once the initial junction is created as stateful, the add command is used without the s option to junction the remaining replicated back-end servers to the same junction point. If the scenario involves multiple front-end WebSEAL servers, all junctioned to the same back-end servers, you must use the u option to correctly specify each back-end server UUID to each front-end WebSEAL server. See Specifying Back-End Server UUIDs for Stateful Junctions ( u). Specifying Back-End Server UUIDs for Stateful Junctions ( u) When a new junction is created to a back-end Web application server, WebSEAL normally generates a Unique Universal Identifier (UUID) to identify that back-end server. This UUID is used internally and also to maintain stateful junctions (create s). When the initial client request occurs, WebSEAL places a cookie on the client system that contains the UUID of the designated back-end server. When the client makes future requests to the same resource, the cookie s UUID information ensures that the requests are consistently routed to the same back-end server. 170 Version 3.8

191 Client Cookie with UUID2 WebSEAL Stateful Junctions Application Server 2 (UUID2) Application Server 1 (UUID1) Figure 28. Stateful Junctions Use Back-End Server UUIDs The handling of stateful junctions becomes more complex when there multiple front-end WebSEAL servers junctioned to multiple back-end servers. Normally, each junction between a front-end WebSEAL server to a back-end server generates a unique UUID for the back-end server. This means a single back-end server will have a different UUID on each front-end WebSEAL server. Multiple front-end servers require a load balancing mechanism to distribute the load between the two servers. For example, an initial state could be established to a back-end server through WebSEAL server 1 using a specific UUID. However, if a future request from the same client is routed through WebSEAL server 2 by the load balancing mechanism, the state will no longer exist, unless WebSEAL server 2 uses the same UUID to identity the same back-end server. Normally, this will not be the case. The u option allows you to supply the same UUID for a specific back-end server to each front-end WebSEAL server. 6. WebSEAL Junctions As an example, consider two replicated front-end WebSEAL servers, each with a stateful junction to two back-end servers. When you create the stateful junction between WebSEAL server 1 and back-end server 2, a unique UUID (UUID A) is generated to identity back-end server 2. However, when a stateful junction is created between Tivoli SecureWay Policy Director WebSEAL Administration Guide 171

192 WebSEAL server 2 and back-end server 2, a new and different UUID (UUID B) is generated to identify back-end server 2. WebSEAL-1 UUID A Application Server 1 WebSEAL-2 Stateful Junctions UUID B Application Server 2 Figure 29. Dissimilar UUIDs A state established between a client and back-end server 2, via WebSEAL server 1 will fail if a subsequent request from the client is routed through WebSEAL server 2. Apply the following process for specifying a UUID during the creation of a junction: 1. Create a junction from WebSEAL server 1 to each back-end server. Use create s and add. 2. List the UUID generated for each back-end server during Step 1. Use show. 3. Create a junction from WebSEAL server 2 to each back-end server and specify the UUIDs identified in Step 2. Use create s u and add u. 172 Version 3.8

193 In the following figure, back-end server 1 is known by both WebSEAL-1 and WebSEAL-2 as UUID 1. Back-end server 2 is known by both WebSEAL-1 and WebSEAL-2 as UUID 2. Client Load Balancing Mechanism WebSEAL-1 Stateful Junctions Application Server 1 (UUID 1) Cookie with UUID 2 WebSEAL-2 Application Server 2 (UUID 2) Figure 30. Specifying Back-End Server UUIDs for Stateful Junctions Example: In the following example, WebSEAL-1 is called WS1 WebSEAL-2 is called WS2 Back-end server 1 is called APP1 Back-end server 2 is called APP2 pdadmin> server task webseald-ws1 create t tcp h APP1 s /mnt pdadmin> server task webseald-ws1 add h APP2 /mnt pdadmin> server task webseald-ws1 show /mnt (This reveals UUID1 and UUID2) pdadmin> server task webseald-ws2 create t tcp h APP1 u <UUID1> s /mnt pdadmin> server task webseald-ws2 add h APP2 u <UUID2> /mnt 6. WebSEAL Junctions When a client establishes a stateful connection with back-end server 2, it receives a cookie containing UUID2. The above example now ensures that the client will always connect to back-end server 2, regardless of whether future requests are routed through WebSEAL-1 or WebSEAL-2. Tivoli SecureWay Policy Director WebSEAL Administration Guide 173

194 Junctioning to Windows File Systems ( w) WebSEAL performs security checks on client requests to junctioned back-end servers based on the file paths specified in the URL. A compromise in this security check can occur because Win32 file systems provide for two different methods for accessing long filenames. The first method acknowledges the entire filename (abcdefghijkl.txt). The second method uses the old 8.3 filename format for backward compatibility (abcdefx1.txt). When you create junctions in a Windows environments, it is important to restrict access control to one object representation only and not allow the possibility of back doors that bypass the security mechanism. The w option disallows the 8.3 filename format. A user cannot avoid an explicit ACL on a long filename by using the short (8.3) form of the filename. The server will return a 403 Forbidden error on any short form filename entered. In Windows, a file with filename foo. is treated the same as filename foo. The w option removes trailing dots from filenames in a URL before sending the request to the back-end server. ACL checks are based on the filename without the trailing dot. Note: The problem with Win32 case-insensitivity (abcde.txt = AbCdE.txt) is addressed by the i option. See Supporting Case-Insensitive URLs ( i) on page 162. Example: On Windows NT 4.0, the file \Program Files\Company Inc.\Release.Notes can also be accessed via the following paths: 1. \program files\company inc.\release.notes 2. \program files\company inc\release.notes 3. \prograx1\companx2\releasx3.not 174 Version 3.8

195 Example 1 above illustrates the case-insensitivity effect which is addressed by the i option (not w). Example 2 illustrates how Windows NT ignores a trailing extension dot. Example 3 illustrates how Windows NT creates an alias (for DOS compatibility) that contains no spaces in the file names and conforms to the 8.3 format. The w option addresses the potential security holes illustrated by Examples 2 and 3. The w option dictates that trailing dots be ignored and access to shortened filenames containing a tilde character (x) be disallowed in request URLs for this junctioned server. Technical Notes for Using WebSEAL Junctions: Mounting Multiple Servers at the Same Junction on page 175 Filtering Static HTML URLs from Junctioned Servers on page 176 Exceptions to Enforcing Permissions Across Junctions on page 177 Certificate Authentication Across Junctions on page 177 Mounting Multiple Servers at the Same Junction You can mount multiple replicated servers at the same junction point. There can be any number of servers mounted at the same point. All servers mounted at one junction point must be replicas (mirrored Web spaces), and must use the same protocol HTTP or HTTPS. Do not mount dissimilar servers on the same junction point. 6. WebSEAL Junctions From the primary Policy Director server Web space, access pages belonging to the junctioned server(s). You should be able to access these pages (subject to permissions, of course) and the pages should Tivoli SecureWay Policy Director WebSEAL Administration Guide 175

196 appear consistent. If a page cannot be found occasionally, or if it changes occasionally, it means that page was not replicated properly. Check that the document exists and is identical in the document tree of both replicated servers. Filtering Static HTML URLs from Junctioned Servers Only static documents of mime type text/html that are received from junctioned servers are filtered. There are 2 sets of URLs that can be modified by WebSEAL: absolute and server-relative. Server- relative URLs indicate a URL position in relation to the document root of the junctioned server, for example: /dir/file.html These URLs are modified to reflect the junction point of the junctioned server, for example: /jct/dir/file.html Absolute URLs indicate a URL position in relation to a HOST name or IP address, and a network port, for example: or These URLs are modified according to the following set of rules: 1. If the URL is HTTP and the host/port matches a TCP junctioned server, the URL is modified to reflect the junction point, for example: /jct/ If the URL is HTTPS and the host/port matches an SSL junctioned server, the URL is modified to reflect the junction point, for example: /jct/ Only URLs for TAG/Attribute pairs that are defined in the iv.conf file are filtered. 176 Version 3.8

197 4. META tags are always filtered for refresh requests, for example: <META HTTP-EQUIV= Refresh CONTENT= 5;URL= > 5. If a BASE tag contains an HREF attribute, the tag is removed from the response to the client. Parameters for filtering URLs through junctioned servers are located in the [filter-url] stanza of the webseald.conf configuration file. The [filter-url] stanza contains a list of HTML tags that the WebSEAL server filters or modifies to adjust absolute URLs obtained through a junctioned server. All commonly used HTML tags are configured by default. The administrator may need to add additional HTML tags that contain URLs. See also Processing URLs From Scripts and Client-side Applications ( j) on page 163. Exceptions to Enforcing Permissions Across Junctions Certain Policy Director permissions are not enforceable across a junction. You cannot control, for example, the execution of a CGI script with the x permission, or a directory listing with the l permission. WebSEAL has no means of accurately determining whether or not a requested object on a back-end server is, for example, a CGI program file, a dynamic directory listing, or a regular HTTP object. Access to objects across junctions, including CGI programs and directory listings, is only controlled through the r permission. Certificate Authentication Across Junctions At installation, WebSEAL is configured with a non-default test certificate. The test certificate is designated as the active server-side certificate by the webseal-cert-keyfile-label parameter in the [ssl] stanza of the webseald.conf configuration file. 6. WebSEAL Junctions Tivoli SecureWay Policy Director WebSEAL Administration Guide 177

198 If a junctioned back-end application server requires WebSEAL to identify itself with a client-side certificate, you must first create, install, and label this certificate using the ikeyman utility. Then, configure the junction using the K <key-label> option. See Mutually Authenticated SSL Junctions on page 150 If the junction is not configured with K, GSKit handles a request for mutual authentication by automatically sending the default certificate contained in the keyfile database. If this is not the required response, you must ensure that there are no certificates marked as default (an asterisk mark) in the keyfile database (pdsrv.kdb). In summary: Identify all required certificates by label name. Do not mark any certificate in the keyfile database as default. Control the WebSEAL server-side certificate response with the webseal-cert-keyfile-label parameter. Control the WebSEAL client-side certificate response through the K junction option. Using query_contents with Third-Party Servers If you want to protect the resources of the third-party application Web space using the Policy Director security service, you must provide WebSEAL with information about the contents of the third-party Web space. A CGI program called query_contents provides this information. The query_contents program searches the third-party Web space contents and provides this inventory information to the Web Portal Manager on WebSEAL. The program comes with the WebSEAL installation, but must be manually installed on the third-party server. There are different program file types available, depending on whether the third-party server is based on UNIX or Windows. 178 Version 3.8

199 The Object Space manager of the Web Portal Manager automatically runs query_contents any time the portion of the Protected Object Space representing the junction is expanded in the Object Space management panel. Now that the Web Portal Manager knows about the contents of the third-party application space, you can display this information and apply policy templates to appropriate objects. Installing query_contents Installing query_contents is typically very easy. Installation involves copying one or two files from the Policy Director server to the third-party server and editing a configuration file. The following Policy Director directory contains a template of the program: UNIX: <install-path>/www/lib/query_contents Windows: <install-path>\www\lib\query_contents The contents of the directory includes: File query_contents.exe query_contents.sh query_contents.c query_contents.html query_contents.cfg Description Main executable program for Win32 systems. Should be installed in the cgi-bin directory of the third-party Web server. Main executable program for UNIX systems. Should be installed in the cgi-bin directory of the third-party Web server. Source code. The source is provided in case you need to modify the behavior of query_contents. In most cases, this will not be necessary. Help file in HTML format. A sample configuration file which identifies the document root for the Web server. 6. WebSEAL Junctions Tivoli SecureWay Policy Director WebSEAL Administration Guide 179

200 Installing query_contents on Third-Party UNIX Servers Locate the shell script named query_contents.sh in the following directory: <install-path>/www/lib/query_contents 1. Copy query_contents.sh into a functioning /cgi-bin directory on the third-party Web server. 2. Remove the.sh extension. 3. Set the UNIX execute bit for the administration account of the Web server. Installing query_contents on Third-Party Win32 Servers Locate the executable program named query_contents.exe and the configuration file named query_contents.cfg in the following directory: Windows: <install-path>\www\lib\query_contents 1. Ensure that the third-party Web server has a CGI directory correctly configured. 2. For testing purposes, ensure that a valid document exists in the document root of the third-party Web server. 3. Copy query_contents.exe into the CGI directory of the third-party Web server. 4. Copy query_contents.cfg into the Windows directory. Default values for this directory are shown in the table below: Operating System Windows 95 Windows NT 3.5x Windows NT 4.x Windows Directory c:\windows c:\winnt35 c:\winnt 5. Edit the query_contents.cfg file to correctly specify the document root directory for the third-party Web server. 180 Version 3.8

201 The file currently contains sample entries for the Microsoft Internet Information Server and Netscape FastTrack servers. The lines in this file that start with a semi-colon (;) are comments, and ignored by the query_contents program. Testing the Configuration 1. From an MS-DOS prompt on the Win32 machine, execute the query_contents program from the CGI directory as follows: MSDOS> query_contents dirlist=/ You should see something similar to the following output: 100 index.html cgi-bin// pics// The number 100 is a return status that indicates success. It is most important to see at least the number 100 as the first (and perhaps only) value. If you see an error code instead, then the configuration file is not in the correct place, or does not contain a valid document root entry. Check the configuration of the query_contents.cfg file and make sure that the document root exists. 2. From a browser, enter the following URL This should return the same result as the preceding step. If it does not return this result, the CGI configuration of your Web server is not correct. See the server s documentation to correct the problem. Customizing query_contents The job of query_contents is to return the contents of directories included in a URL request. 6. WebSEAL Junctions For example, to get the contents of the root directory of a server s Web space, the browser runs query_contents on a URL such as: Tivoli SecureWay Policy Director WebSEAL Administration Guide 181

202 The query_contents script performs the following actions: 1. Reads $SERVER_SOFTWARE, a standard CGI environment variable, to determine the server type. Based on the Web server type, the variable $DOCROOTDIR is set to a typical document root location. 2. Reads the environment variable $QUERY_STRING from the requested URL to obtain the requested operation and get the object path. The operation value is stored in the variable $OPERATION, and the object path in $OBJPATH. In the above example, the $OPERATION is dirlist and $OBJPATH is /. 3. Performs a directory listing (ls) on the object path and places the results on standard output, for use by the Policy Director server. Entries that indicate subdirectories have a double slash (//) appended to them. Typical output looks like: 100 index.html cgi-bin// pics// The number 100 is a return status that indicates success. Customizing the Doc Root Directory UNIX: To customize query_contents.sh for your UNIX server, you may need to modify the document root directory setting. If query_contents returns an error status (a number other than 100) and lists no files, examine the script and modify the $DOCROOTDIR variable, if needed, to match your server s configuration. If the document root directory is specified correctly and the script still fails, the cgi-bin location specification may be incorrect. Examine the $FULLOBJPATH variable and modify the value assigned to it to reflect the correct cgi-bin location. 182 Version 3.8

203 Windows: To customize query_contents.exe for your Windows server, modify the query_contents.cfg file. Additional Functionality The source code for the query_contents program (query_contents.c) is distributed royalty-free with Policy Director. Additional functionality can be added to this program to support special features of some third-party Web servers. These features include: 1. Directory mapping where a sub-directory not below the document root is mapped into the Web space. 2. Generation of a Web space that is not file system based. This might be the case for a database-hosted Web server. Securing query_contents The query_contents CGI program is used by Policy Director to display junctioned Web server object spaces in the Web Portal Manager. It is very important to secure this file to prevent unauthorized users from running it. You must set a security policy that allows only the Management Server (pdmgrd) identity to have access to the query_contents program. The following example ACL (query_contents_acl) meets this criteria: group ivmgrd-servers Tl user sec_master dbxtrlcam Use the pdadmin utility to attach this ACL to the query_contents.sh (UNIX) or query_contents.exe (Windows) object on the junctioned servers. For example (UNIX): pdadmin> acl attach /WebSEAL/<host>/<junction-name>/query_contents.sh query_contents_acl 6. WebSEAL Junctions Tivoli SecureWay Policy Director WebSEAL Administration Guide 183

204 184 Version 3.8

205 7 Web Single Sign-on Solutions 7. Web Single Sign-on Solutions When WebSEAL is implemented as a proxy server to provide protection to a secure domain, there is often a requirement to provide solutions for single sign-on to Web resources. This chapter discusses single sign-on solutions for the Web space of a WebSEAL proxy configuration. Examples include specially configured junctions, Global Sign-on, and LTPA. Topic Index: Configuring BA Headers for Single Sign-on Solutions on page 185 Using Global Sign-on (GSO) on page 193 Single Sign-on to IBM WebSphere (LTPA) on page 197 Configuring BA Headers for Single Sign-on Solutions This section discusses the possible solutions for creating single sign-on configurations across WebSEAL junctions using the b options. Single Sign-On (SSO) Concepts on page 186 Supplying Client Identity in BA Headers on page 186 Supplying Client Identity and Generic Password on page 187 Forwarding Original Client BA Header Information on page 189 Tivoli SecureWay Policy Director WebSEAL Administration Guide 185

206 Removing Client BA Header Information on page 191 Supplying User names and Passwords from GSO on page 192 Single Sign-On (SSO) Concepts When a protected resource is located on a back-end Web application server, a client requesting that resource can be required to perform multiple logins one for the WebSEAL server and one for the back-end server. Each login likely requires different login identities. Client Login #1 Login #2 WebSEAL Web Application Server Junction Figure 31. Multiple Logins The problem of administering and maintaining multiple login identities can often be solved with a single sign-on (SSO) mechanism. A single sign-on solution allows the user to access a resource, regardless of the resource s location, using only one initial login. Any further login requirements from back-end servers are handled transparent to the user. Supplying Client Identity in BA Headers You can configure WebSEAL junctions to supply the back-end server with original or modified client identity information. The set of b options allow you to supply specific client identity information in HTTP Basic Authentication (BA) headers. As the administrator, you must analyze your network architecture and security requirements, and determine answers to the following questions: 1. Is authentication information required by the back-end server? 186 Version 3.8

207 (WebSEAL uses the HTTP Basic Authentication header to convey authentication information.) 2. If authentication information is required by the back-end server, where does this information come from? (What information does WebSEAL place in the HTTP header?) 3. Does the connection between WebSEAL and the back-end server need to be secure? (TCP or SSL junction?) 7. Web Single Sign-on Solutions After the initial authentication between the client and WebSEAL, WebSEAL can build a new Basic Authentication header. The request uses this new header as it continues across the junction to the back-end server. You use the b options to dictate what specific authentication information is supplied in this new header. Client Initial authentication results in Policy Director credentials request WebSEAL New BA header with WebSEAL-supplied authentication information Web request Application junction Server Figure 32. Supplying Authentication Information to Back-End Servers Supplying Client Identity and Generic Password b supply The b supply option instructs WebSEAL to supply the authenticated Policy Director user name (client s original identity) with a static, generic ( dummy ) password. The original client password is not used in this scenario. Tivoli SecureWay Policy Director WebSEAL Administration Guide 187

208 A generic password eliminates password administration and supports the application on a per-user basis. The dummy password is set in basicauth-dummy-passwd parameter of the webseald.conf configuration file: [junction] basicauth-dummy-passwd = <password> This scenario assumes the back-end server requires authentication from a Policy Director identity. By mapping a client user to a known Policy Director user, WebSEAL manages authentication for the back-end server and provides a simple domain-wide single sign-on solution. The following conditions exist for this solution: WebSEAL is configured to supply the back-end server with the user name contained in the original client request plus a generic ( dummy ) password. The dummy password is configured in the webseald.conf configuration file. The back-end server registry must recognize the Policy Director identity supplied in the HTTP BA header. Because sensitive authentication information (user name and password) is passed across the junction, the security of the junction is important. An SSL junction is highly recommended. 188 Version 3.8

209 Client any authentication mechanism Registry WebSEAL SSL junction Registry Web Application Server 7. Web Single Sign-on Solutions WebSEAL supplies Policy Director identity and "dummy" password Figure 33. BA Header Contains Identity and dummy Password Limitations The same Policy Director dummy password is used for all requests; all users have the same password in the back-end server registry. The use of the common dummy password offers no basis for the application server to prove the legitimacy of the client logging in with that user name. If clients always go through WebSEAL to access the back-end server, this solution does not present any security problems. However, it is important to physically secure the back-end server from other possible means of access. Since this scenario has no password-level security, the back-end server must implicitly trust WebSEAL to verify the legitimacy of the client. The back-end server registry must also recognize the Policy Director identity in order to accept it. Forwarding Original Client BA Header Information b ignore Tivoli SecureWay Policy Director WebSEAL Administration Guide 189

210 The b ignore option instructs WebSEAL to pass the original client Basic Authentication (BA) header straight to the back-end server without interference. WebSEAL can be configured to authenticate this BA client information or ignore the BA header supplied by the client and forward the header, without modification, to the back-end server. Note: This is not a true single sign-on mechanism, but rather a direct login to the third-party server, transparent to WebSEAL. The following conditions exist for this solution: The back-end server requires client identity information via BA The back-end server will send a Basic Authentication challenge back to the client. The client responds with user name and password information which the WebSEAL server passes through without modification. The back-end server maintains its own client-supplied passwords WebSEAL is configured to supply the back-end server with the user name and password contained in the original client request. Because sensitive authentication information (user name and password) is passed across the junction, the security of the junction is important. An SSL junction is highly recommended. 190 Version 3.8

211 Client Basic Authentication Registry WebSEAL junction Registry Web Application Server 7. Web Single Sign-on Solutions WebSEAL supplies original client authentication (BA) information Figure 34. WebSEAL Forwards Original Client Identity Information Removing Client BA Header Information b filter The b filter option instructs WebSEAL to remove all Basic Authentication header information from any client requests before forwarding the requests to the back-end server. In this scenario, WebSEAL becomes the single security provider. The following conditions exist for this solution: Basic Authentication is configured between the client and WebSEAL The back-end server does not require Basic Authentication The back-end server can only be accessed through WebSEAL WebSEAL handles authentication on behalf of the back-end server Tivoli SecureWay Policy Director WebSEAL Administration Guide 191

212 Client Basic Authentication WebSEAL TCP or SSL junction no authentication required Web Application Server WebSEAL removes original client identity information from BA header Figure 35. Removing Client BA Header Information If you need to supply the back-end server with some client information, you can combine this option with the c option to insert Policy Director client identity information into HTTP header fields. See Supplying Client Identity in HTTP Headers ( c) on page 158. Supplying User names and Passwords from GSO b gso The b gso option instructs WebSEAL to supply the back-end server with authentication information (user name and password) obtained from a server set up to handle global sign-on (GSO). The following conditions exist for this solution: The back-end server applications require different user names and passwords that are not contained in the WebSEAL registry. Security is important for both WebSEAL and the back-end server. Because sensitive authentication information (user name and password) is passed across the junction, the security of the junction is important. An SSL junction is highly recommended. This mechanism is fully described in Using Global Sign-on (GSO) on page Version 3.8

213 Using Global Sign-on (GSO) Policy Director supports a flexible single sign-on solution that features the ability to provide alternative user names and passwords to the back-end Web application server. This single sign-on solution is supported and implemented in two ways, according to the type of user registry used: Secure domain with DCE registry use Tivoli Global Sign-On (GSO) product Secure domain with LDAP registry the LDAP directory provides Global Sign-on support 7. Web Single Sign-on Solutions Global Sign-On grants users access to the computing resources they are authorized to use through a single login. Designed for large enterprises consisting of multiple systems and applications within heterogeneous, distributed computing environments, GSO eliminates the need for end users to manage multiple user names and passwords. The integration is achieved by creating GSO aware junctions between WebSEAL and back-end Web servers. GSO resources and GSO resource groups must first be created using the Web Portal Manager. When WebSEAL receives a request for a resource located on the junctioned server, WebSEAL asks the GSO server for the appropriate authentication information. The GSO server contains a database of mappings for each registered user that provides alternative user names and passwords for specific resources and applications. The following figure illustrates how the GSO mechanism is used to retrieve user names and passwords for back-end application resources. 1. The client authenticates to WebSEAL with a request for access to an application resource on an back-end server. A Policy Director identity is obtained. Tivoli SecureWay Policy Director WebSEAL Administration Guide 193

214 Note: The single sign-on process is independent of the initial authentication method. 2. WebSEAL passes the Policy Director identity to the GSO or LDAP server. 3. The server returns a user name and password appropriate for the user and the requested application resource. 4. WebSEAL inserts the user name and password information in the HTTP Basic Authentication header of the request that is sent across the junction to the back-end server. Secure Domain Host: sales_svr Client 1 WebSEAL / 4 HTTP Resources: - accounts-app - travel-app /admin /sales Junctions (-b gso) Host: adm_svr 2 Policy Director Identity Username / Password 3 HTTPS Resources: - expenses-app - payroll-app LDAP or GSO Server SSL junction provides encrypted communication Figure 36. Global Sign-on Mechanism Mapping the Authentication Information The following example illustrates how GSO provides authentication information to WebSEAL. If user Michael wants to run the travel-app application resource (refer to Figure 36), WebSEAL asks the GSO / LDAP server for Michael s authentication information. 194 Version 3.8

215 The GSO / LDAP server maintains a complete database of authentication information in the form of mappings of resources to specific authentication information. The authentication information is a user name / password combination known as a resource credential. Resource credentials can only be created for registered users. The server contains a database for Michael that maps the resource: travel-app to a specific resource credential. 7. Web Single Sign-on Solutions The following table illustrates the structure of the GSO resource credential database: Michael resource: travel-app username=mike password=123 resource: payroll-app username=powell password=456 Paul resource: travel-app username=bundy password=abc resource: payroll-app username=jensen password=xyz In this example, GSO returns user name mike and password 123 to WebSEAL. WebSEAL uses this information when it constructs the Basic Authentication header in the request sent across the junction to the back-end server. Configuring a GSO-Enabled WebSEAL Junction Support for GSO is configured at the junction between WebSEAL and a back-end server. To create a junction that enables GSO, use the create command with the b gso option. The following example illustrates the syntax for the create command: create t tcp h <host-name> b gso T <resource> <jct-point> Options for setting up GSO junctions are listed below: Options Description b gso Specifies that GSO should provide authentication information for all requests crossing this junction. Tivoli SecureWay Policy Director WebSEAL Administration Guide 195

216 Options T <resource/ resource-group> Description Specifies the GSO resource or resource group. The resource name used as the argument to this option must exactly match the resource name as listed in the GSO database. Required for gso junctions. A junction used in a WebSEAL/GSO solution can be made secure through SSL by additionally applying the t ssl option when creating the junction. It is recommended that you always use SSL junctions with GSO to ensure encryption of credentials and all data. Examples of GSO-Enabled WebSEAL Junctions Junction the application resource: travel-app on host: sales_svr to junction point /sales: create t tcp b gso T travel-app h sales_svr /sales Junction the application resource: payroll-app on host: adm_svr to junction point /admin and make the junction secure with SSL: create t ssl b gso T payroll-app h adm_svr /admin Note: In the above example, the t ssl option dictates a default port of 443. Configuring the GSO Cache The Global Sign-on (GSO) cache functionality allows you to improve the performance of GSO junctions in a high load environment. By default, the GSO cache is disabled. Without the enhancement of the cache, a call to the LDAP server is required for each retrieval of GSO target information (GSO user name and GSO password). Parameters for configuring the GSO cache are located in the [gso-cache] stanza of the webseald.conf configuration file. You must first enable the cache. The remaining parameters configure the cache size and the timeout values for cache entries. Larger lifetime 196 Version 3.8

217 and inactivity timeout values improve performance, but increase the risk of information being exposed in the WebSEAL memory. Do not enable the GSO cache if GSO junctions are not used in your network solution. Parameter gso-cache-enabled gso-cache-size gso-cache-entry-lifetime gso-cache-entry-idle-timeout Description Enable and disable the GSO cache functionality. Values include yes and no. Default is no. Sets the maximum number of entries allowed in the cache hash table. Set this value to approximate the peak number of concurrent user sessions that access an application across a GSO junction. A high value uses more memory but results in faster information access. Each cache entry consumes approximately 50 bytes. Maximum time (in seconds) any cache entry can remain in the cache, regardless of activity. After a cache entry expires, the next request by that same user requires a new call to the LDAP server. Maximum time (in seconds) an inactive cache entry can remain in the cache. 7. Web Single Sign-on Solutions Single Sign-on to IBM WebSphere (LTPA) Policy Director WebSEAL can provide authentication and authorization services and protection to an IBM WebSphere environment. When WebSEAL is positioned as a protective front-end to WebSphere, accessing clients are faced with two potential login points. Therefore, WebSEAL supports a single sign-on solution to one or more IBM WebSphere servers across WebSEAL junctions. Tivoli SecureWay Policy Director WebSEAL Administration Guide 197

218 WebSphere provides the cookie-based lightweight third party authentication mechanism (LTPA). You can configure WebSEAL junctions to support LTPA and provide a single sign-on solution for clients. When a user makes a request for a WebSphere resource, the user must first authenticate to WebSEAL, Upon successful authentication, WebSEAL generates an LTPA cookie on behalf of the user. The LTPA cookie, which serves as an authentication token for WebSphere, contains user identity and password information. This information is encrypted using a password-protected secret key shared between WebSEAL and the WebSphere server. WebSEAL inserts the cookie in the HTTP header of the request that is sent across the junction to WebSphere. The back-end WebSphere server receives the request, decrypts the cookie, and authenticates the user based on the identity information supplied in the cookie. To improve performance, WebSEAL can store the LTPA cookie in a cache and use the cached LTPA cookie for subsequent requests during the same user session. You can configure lifetime timeout and idle (inactivity) timeout values for the cached cookie. Configuring an LTPA Junction Single sign-on to WebSphere via an LTPA cookie requires the following configuration items: 1. Enable the LTPA mechanism. 2. Provide the location of the key file used to encrypt the identity information. 3. Provide the password to this key file. These three configuration requirements are specified in three additional options to the junction create command. The A option enables the junction to support LPTA cookies. The F < keyfile > option and argument specifies the full path name location (on the WebSEAL server) of the key file used to encrypt the identity information contained in the cookie. The 198 Version 3.8

219 shared key is originally created on the WebSphere server and copied securely to the WebSEAL server. Refer to the appropriate WebSphere documentation for specific details regarding this task. The Z < keyfile-password > specifies the password required to open the key file. The password appears as encrypted text in the junction XML file. 7. Web Single Sign-on Solutions Use these options in addition to other required junction options when you create the junction between WebSEAL and the back-end WebSphere server. For example: create... -A -F /abc/xyz/key.file -Z abcdefg... Configuring the LTPA Cache The creation, encryption, and decryption of LTPA cookies introduces processing overhead. The LTPA cache functionality allows you to improve the performance of LTPA junctions in a high load environment. By default, the LTPA cache is enabled. Without the enhancement of the cache, a new LTPA cookie is created and encrypted for each subsequent user request. Parameters for configuring the LTPA cache are located in the [ltpa-cache] stanza of the webseald.conf configuration file. Parameters specify the cache size and the timeout values for cache entries. Larger lifetime and inactivity timeout values improve performance, but increase the risk of information being exposed in the WebSEAL memory. Parameter ltpa-cache-enabled Description Enable and disable the LTPA cache functionality. Values include yes and no. Default value is yes. Tivoli SecureWay Policy Director WebSEAL Administration Guide 199

220 Parameter ltpa-cache-size ltpa-cache-entry-lifetime ltpa-cache-entry-idle-timeout Description Sets the maximum number of entries allowed in the cache hash table. Set this value to approximate the peak number of concurrent user sessions that access an application across a LTPA junction. A high value uses more memory but results in faster information access. Each cache entry consumes approximately 50 bytes. Default value is 4096 entries. Maximum time (in seconds) any cache entry can remain in the cache, regardless of activity. After a cache entry expires, the next request by that same user requires the creation of a new LTPA cookie. Default value is 3600 seconds Maximum time (in seconds) an inactive cache entry can remain in the cache. Default value is 600 seconds. Technical Notes for LTPA Single Sign-on The key file contains information about a specific WebSphere server. An LTPA junction is specific to one WebSphere server. If you add more than one server to the same junction point, all servers will share the same key file. For single sign-on to succeed, WebSEAL and the WebSphere serve must in some way share the same registry information. The WebSphere server is responsible for setting up LTPA and the creation of the shared secret key. The WebSEAL participation involves the junction and cache configurations. 200 Version 3.8

221 8 Application Integration WebSEAL supports third-party application integration through environment variables and dynamic URL capability. WebSEAL extends the range of environment variables and HTTP headers to enable third-party applications to perform operations based on a client s identity. In addition, WebSEAL can provide access control on dynamic URLs, such as those that contain query text. Topic Index: Supporting CGI Programming on page 201 Supporting Back-End Server-Side Applications on page 204 Enabling Dynamic Business Entitlements on page 205 Building a Custom Personalization Service on page 209 Providing Access Control to Dynamic URLs on page 211 Dynamic URL Example: The Travel Kingdom on page Application Integration Supporting CGI Programming To support CGI programming, WebSEAL adds three additional environment variables to the standard set of CGI variables. These environment variables can be used by CGI applications running on either the local WebSEAL server or a junctioned back-end server. The variables provide Policy Director-specific user, group, and credential information to the CGI application. Tivoli SecureWay Policy Director WebSEAL Administration Guide 201

222 On a local WebSEAL server, these environment variables are automatically available to CGI programs. Environment variables used by a CGI application running on a junctioned third-party server are produced from the HTTP header information passed to the server from WebSEAL. You must use the c option to create a junction that supports Policy Director-specific header information in HTTP requests destined for a back-end server. See also Supplying Client Identity in HTTP Headers ( c) on page 158. Additional Policy Director-specific environment variables: CGI Environment Variables HTTP_IV_USER HTTP_IV_GROUPS HTTP_IV_CREDS Description The Policy Director user account name of the requester. The Policy Director groups to which the requester belongs. Specified as a comma-separated list of groups each group is surrounded by double-quote marks. Encoded opaque data structure representing a Policy Director credential. Supplies credentials to remote servers so mid-tier applications can use the Authorization API to call the Authorization Service. Refer to the Policy Director ADK Developer Reference. The REMOTE_USER variable on a local WebSEAL server: On a local server environment controlled by WebSEAL, the value of the HTTP_IV_USER variable listed above is provided as the value for the standard REMOTE_USER variable. Note that the REMOTE_USER variable may also be present in the environment of a CGI application running on a junctioned back-end server. However, in this situation, its value is not controlled by WebSEAL. 202 Version 3.8

223 CGI Environment Variable REMOTE_USER Description Contains the same value as the HTTP_IV_USER field. Windows: Supporting WIN32 Environment Variables This section applies to local junctions only. Windows does not automatically make all of its system environment variables available to processes such as CGI applications. Typically, the system environment variables you require are present. However, if any Windows system environment variables that you require are not present in the CGI environment, you can explicitly make them available to CGI programs through the webseald.conf configuration file. (Note that the Policy Director environment variables mentioned in the previous section are automatically available on all platforms). Add any of the required Windows system environment variables to the [cgi-environment-variables] stanza of the webseald.conf configuration file. Use the following format: ENV = <variable-name> 8. Application Integration For example: [cgi-environment-variables] #ENV = SystemDrive ENV = SystemRoot ENV = PATH ENV = LANG ENV = LC_ALL ENV = LC_CTYPE ENV = LC_MESSAGES ENV = LOCPATH ENV = NLSPATH Any uncommented lines are inherited by a CGI environment. Tivoli SecureWay Policy Director WebSEAL Administration Guide 203

224 Supporting Back-End Server-Side Applications WebSEAL also provides support for executable code that runs as an embedded component of a back-end Web server. Examples of such server-side executable code include: Java servlets Cartridges for Oracle Web Listener Server-side plug-ins When you create a junction to a back-end server using the c option, WebSEAL inserts Policy Director-specific client identity and group membership information into the HTTP headers of requests destined for that server. The Policy Director-specific HTTP header information enables applications on junctioned third-party servers to perform user-specific actions based on the client s Policy Director identity. WebSEAL provides the following Policy Director-specific HTTP headers: PD-specific HTTP Header Fields iv-user = iv-groups = iv-creds = Description The short or long name of the client. Defaults to Unauthenticated if client is unauthenticated (unknown). A list of groups to which the client belongs. Specified as a comma separated list of quoted groups. Encoded opaque data structure representing a Policy Director credential. Supplies credentials to remote servers so mid-tier applications can use the Authorization API to call the Authorization Service. Refer to the Tivoli SecureWay Policy Director Authorization ADK Developer Reference. These HTTP headers are available to CGI applications as the environment variables HTTP_IV_USER, HTTP_IV_GROUPS and 204 Version 3.8

225 HTTP_IV_CREDS. For other non-cgi application frameworks, see their associated product documentation for instructions on extracting headers from HTTP requests. See also Supplying Client Identity in HTTP Headers ( c) on page 158. Enabling Dynamic Business Entitlements Business enterprises and their partners often have the need to share common entitlements such as partner data (in a business-to-business relationship) or customer data (in a business-to-customer relationship). Generic entitlements are attributes describing information required by service-providing applications. Examples of such attributes include customer account information and customer billing data. Security entitlements are attributes that provide fine-grained conditions used in the authorizing of requests for resources. Examples of such conditions include user business roles, access control restrictions, and business rules that define a trading partner agreement. 8. Application Integration Through an extension of the Cross Domain Authentication Service (CDAS), Policy Director provides a flexible mechanism that allows you to include entitlement information, in the form of extended tag/value attributes, into user credentials at the point of authentication. Applications can extract this data from the credential directly using the Authorization API. For further information on implementing this CDAS extension, refer to the Tivoli Policy Director WebSEAL Developer Reference. Creating Business Entitlements from LDAP Data WebSEAL provides a specific built-in entitlement mechanism that allows you to insert user-defined supplemental LDAP information into a user credential as extended attributes. These attributes can then be placed in the HTTP header of a request sent to a back-end application server across a junction. Tivoli SecureWay Policy Director WebSEAL Administration Guide 205

226 User-defined supplemental data from any field of a user s LDAP registry account is added as extended attributs to the user s Policy Director credential. WebSEAL is configured to extract this data from the credential and place it in an HTTP header of the request that goes to a back-end server across a WebSEAL junction. The back-end application can extract the data from the header without requiring special code or the Authorization API. WebSEAL configuration for inserting supplemental LDAP information into an HTTP header involves two steps: 1. Retrieve supplemental data from the LDAP registry and inserting this data in the user credential at login. 2. Based on specific conditions placed on the junction, extract the appropriate data from the credential and insert it in an HTTP header of the request that is sent across the junction. Inserting Supplemental LDAP Data into a Credential There are two methods of placing supplemental LDAP user data in a credential: 1. Create entries in the [ldap-ext-cred-tags] stanza of the pd.conf configuration file that map specific LDAP data to fields in the credential. This method is described in this section. 2. Write a custom CDAS module that maps any user-defined data to fields in the credential. Refer to the Tivoli Policy Director WebSEAL Developer Reference for information on implementing this CDAS extension. You use the [ldap-ext-cred-tags] stanza of the pd.conf configuration file to map specific data from the LDAP inetorgperson object class to a user-defined attribute field in the user credential. The parameters in this stanza have the following format: <custom-credential-field> = <inetorgperson-field> 206 Version 3.8

227 In the credential itself, the name of each custom-credential-field parameter defined in the pd.conf configuration file is prefixed with the phrase tagvalue_. This prefix prevents any conflicts with other existing information in the credential. For example: LDAP user data from inetorgperson object class: The custom credential field name: Parameter entries in [ldap-ext-cred-tags] stanza: ldap-employee-number = employeenumber Entry and value placed in the user credential: tagvalue_ldap-employee-number:09876 employeenumber:09876 ldap-employee-number This functionality requires that the user authenticate via LDAP user name and password. The passwd-ldap authentication mechanism must be enabled. The libldapauthn (ldapauthn) shared library is coded to look in the [ldap-ext-cred-tags] stanza of the pd.conf configuration file for supplemental user-defined credential information. The LDAP data can come from a standard or custom field in the inetorgperson object class. You can place multiple entries in the [ldap-ext-cred-tags] stanza. All attributes specified in stanza entries are placed in the credential upon a user login. The LDAP attribute names are not case-sensitive. The credential field name is case-sensitive. 8. Application Integration Inserting Credential Data into the HTTP Header The user-defined credential information created in the previous section can be placed in an HTTP header of the request that is sent across the junction to the back-end server. This phase involves two tasks: Tivoli SecureWay Policy Director WebSEAL Administration Guide 207

228 1. Configure the junction to allow specific supplemental credential data. This task is achieved by setting the appropriate extended attributes on the junction object in the WebSEAL protected object space. 2. Extract the appropriate supplemental information from the credential and insert the data into an HTTP header of the request. You control the extraction of credential data required on a specific junction through the use of extended attributes on the junction object. The name of the extended attribute is HTTP-Tag-Value. This extended attribute uses the following format: <custom-credential-field>=<http-header-field> The custom-credential-field parameter appears exactly as it does in the [ldap-ext-cred-tags] stanza of the pd.conf configuration file. The tagvalue_ prefix is not included. The parameter is case-sensitive. The http-header-field parameter specifies the name of the HTTP header used to store the data. For example: HTTP-Tag-Value extended attribute on the junction object: ldap-employee-number=employee-id Entry and value found in the user credential: tagvalue_ldap-employee-number:09876 Entry and value placed in the HTTP header: employee-id:09876 When WebSEAL passes a user request to a back-end application server, it looks for any HTTP-Tag-Value extended attributes configured on the junction object. You configure a junction with extended attributes by using the pdadmin object modify set attribute command: pdadmin> object modify <obj-name> set attribute <attr-name> <attr-value> For example: 208 Version 3.8

229 pdadmin> object modify /WebSEAL/WS1/junctionA set attribute HTTP-Tag-Value ldap-employee-number=employee-id Multiple user attribute data can be passed to the junctioned server by using multiple pdadmin object modify set attribute commands to specify multiple HTTP-Tag-Value extended attributes (one atrribute is specified per command). Building a Custom Personalization Service A Web portal, or launch page, is an integrated Web site service that dynamically produces a customized list of Web resources available to a specific user. Resources can include corporate content, support services, and learning tools. The portal output represents a personalized list of resources based on the access permissions for the particular user. The launch page displays only those resources that have the correct access permissions for that user. You can use WebSEAL configuration options and the Authorization API Entitlements Service to build a custom portal solution in a Policy Director environment. 8. Application Integration The process flow for building a custom WebSEAL portal service includes the following items: 1. A specific region of the protected object space is created to locate the set of portal resource objects. 2. Appropriate explicit ACLs are attached to each of these resource objects. 3. The WebSEAL configuration file is edited to include the URL to the portal service, the path of the object space containing the portal resources, and the permission bit required by the user for access to these resources. 4. For each user request to the portal URL, WebSEAL uses the Authorization Entitlement Service to search this object space and produce a list of resources that meet the authorization conditions for that user. Tivoli SecureWay Policy Director WebSEAL Administration Guide 209

230 5. WebSEAL places this information in a PD_PORTAL HTTP header that is sent to the back-end (junctioned) portal server. 6. The custom portal service (such as a CGI or servlet) located on the back-end server reads the PD_PORTAL header contents and, for example, maps the contents to descriptions and URL links that are displayed to the user on a Web page. This information represents the personalized list of resources available to the user based on access control permissions. Configuring WebSEAL for a Personalization Service 1. Create a new WebSEAL junction to the personalization service. For example: pdadmin> server task <server-name> create -t tcp -h portalhost.abc.com /portal-jct 2. Edit the webseald.conf configuration file to add a new [portal-map] stanza: [portal-map] 3. The entry in this stanza identifies the server-relative URL of the portal service program and the region of the object space that is searched for available protected portal resources, followed by the permission required for access. This is the list that is placed in the PD_PORTAL header. [portal-map] <URL> = <object-space-region>:<permission> Note: Only resource objects with explicitly set ACLs containing the matching permission for that user are selected during the search. 4. After adding the stanza and the appropriate mapping entries, WebSEAL (webseald) must be re-started. Personalization Service Example Create a junction to the portal server: pdadmin> server task webseald-ws1 -t ssl -h PORTAL1 /portal Define the region of the WebSEAL protected object space that contains resources available to the personalization service: 210 Version 3.8

231 pdadmin> objectspace create /Resources Portal Object Hierarchy 10 pdadmin> object create /Resources/Content 10 ispolicyattachable yes pdadmin> object create /Resources/Support 10 ispolicyattachable yes pdadmin> object create /Resources/Content/CGI 11 ispolicyattachable yes pdadmin> object create /Resources/Support/Servlet 11 ispolicyattachable yes Note: The ispolicyattachable argument must be set to yes for each resource. The search mechanism only selects qualified resource objects with explicitly set ACLs. WebSEAL configuration (webseald.conf): [portal-map] /portal/servlet/portalservlet = /Resources:r Portal URL used by the user: Providing Access Control to Dynamic URLs The current Web environment gives users immediate access to rapidly changing information. Many Web applications dynamically generate Uniform Resource Locators (URLs) in response to each user request. These dynamic URLs may exist only for a short time. Despite their temporary nature, dynamic URLs still need strong protection from unwanted use or access. Dynamic URL Components Some sophisticated Web application tools use standard Web browsers to communicate with application servers through the CGI interface of a Web server. 8. Application Integration All these tools use dynamic URLs and hidden form elements to communicate the requested operation (with its parameter value) to the application server. A dynamic URL augments the standard URL address with information about the specific operation and its parameter values. The query string portion of the URL provides operations, parameters, and values to the Web application interface. Tivoli SecureWay Policy Director WebSEAL Administration Guide 211

232 Base URL Query String Protocol Web Server Directory Path to CGI Program CGI Program File Operation, Parameters, and Values for Web Application Interface Figure 37. Passing Data to a CGI Gateway via a URL Mapping ACL Objects to Dynamic URLs WebSEAL uses the protected object space model and policy templates (ACLs) to secure dynamically generated URLs, such as those generated by database requests. Each request to WebSEAL is resolved to a specific object as the first step in the authorization process. An ACL applied to the object dictates the required protection on any dynamic URL mapped to that object. Because dynamic URLs exist only temporarily, it is not possible to have entries for them in a pre-configured authorization policy database. Policy Director solves this problem by providing a mechanism where many dynamic URLs can be mapped to a single static protected object. Mappings from objects to patterns are kept in a plain text file: /opt/policydirector/www/lib/dynurl.conf The location of this file (relative to the server-root) is defined by the dynurl-map parameter in the [server] stanza of the webseald.conf configuration file: [server] dynurl-map = lib/dynurl.conf 212 Version 3.8

233 You must create this file; the file does not exist by default. The existence of this file (with entries) enables the dynamic URL capability. Edit this file to modify these mappings. Entries in the file are of the format: <object> <template> Policy Director uses a subset of UNIX shell pattern matching (including wild cards) to define the set of parameters that constitute one object in the object space. Any dynamic URL that matches those parameters is mapped to that object. Policy Director supports the following UNIX shell pattern-matching characters: Character Description \ The character that follows the backslash is part of a special sequence. For example, \t is the TAB character. Can also act as an escape character.? Wildcard that matches a single character. For example, the string abcde is matched by the expression ab?de * Wildcard that matches zero or more characters. [] Defines a set of characters, from which any can match. For example, the string abcde is matched with the regular expression ab[cty]de. ^ Indicates a negation. For example, the expression [^ab] matches anything but the a or b characters. 8. Application Integration The following example illustrates the form of a dynamic URL that performs credit balance lookup: The object that represents this dynamic URL would appear as follows: Tivoli SecureWay Policy Director WebSEAL Administration Guide 213

234 Careful examination of the dynamic URL in this example shows that it describes a specific account number. The object for account balances at home-bank shows that the ACL permissions apply to any account, because the last portion of the entry (acc=*) uses the asterisk wild card which matches all characters. The following figure illustrates a complete scenario of a specific dynamic URL mapped to a specific protected object: Protected Object Namespace Match query string with the Web namespace entry "redshirt" "*product=shirt*color=red*" sales/ Dynamic URL entries: web/ db.cgi redshirt ACL associated with object: " group admin -abc---t-m----lrx group ABC_company -abc---t-m----lrx any_authenticated unauthenticated Figure 38. Authorization on a Dynamic URL Updating WebSEAL for Dynamic URLs Use the dynurl update command to update the WebSEAL protected object space with entries made in the dynurl.conf configuration file. 1. Create, edit, or delete a dynamic URL entry in the dynurl.conf configuration file. 2. After making your changes, use the dynurl update command to update the server: 214 Version 3.8

235 pdadmin> server task webseald-<server-name> dynurl update The server-name argument represents the unqualified host name of the WebSEAL machine. Resolving Dynamic URLs in the Object Space The resolving of a dynamic URL to an object is dependent upon the ordering of the entries in the dynurl.conf configuration file. When attempting to map a dynamic URL to an object entry, the list of mappings in the dynurl.conf file is scanned from top to bottom until the first matching pattern is found. When the first match is found, the corresponding object entry is used for the subsequent authorization check. If no matches are found, WebSEAL uses the URL itself, minus the portion of the path. Keep the mappings which correspond to the most restrictive ACLs higher up in the list. For example, if the book.sales procedure of a sales order application is to be restricted to just a book club group, but the rest of the sales order application can be accessed by all users, then the mappings should be in the order shown in the following table: 8. Application Integration Object Space Entry /ows/sales/bksale /ows/sales/general URL Template /ows/db-apps/owa/book.sales* /ows/db-apps/owa/* Note that if the mapping entries were in the reverse order, all stored procedures in the /ows/db-apps/owa directory would map to the /ows/sales/general object. This could lead to possible breaches of security, due to this incorrect object space resolution. When you map a URL regular expression to an object space entry, the URL format should take on the format as produced from the GET method regardless of whether the POST or GET method is being used. Tivoli SecureWay Policy Director WebSEAL Administration Guide 215

236 In the GET method of data transmission, the dynamic data (such as the data supplied by a user in a form) is appended to the URL. In the POST method of data transmission, the dynamic data is included in the body of the request. ACL Evaluation Once the dynamic URL has been resolved to an object space entry, the standard ACL inheritance model is used to determine if the request should be processed or forbidden (due to insufficient privilege). Configuring Limitations on POST Requests The content of a POST request is contained in the body of the request. In addition, a POST request contains the browser-determined length of this content and lists the value in bytes. post-max-read The post-max-read parameter in the [server] stanza of the webseald.conf configuration file limits the impact of large POST requests on WebSEAL by specifying the maximum number of bytes to read in as content from the body of POST requests. The content read in by WebSEAL is subject to authorization checks, as described earlier in this section. The post-max-read parameter value is considered when the POST request is used for dynamic URL processing or Forms authentication. The default value is 4096 bytes: [server] post-max-read = 4096 Note that this parameter does not limit the maximum POST content size (which is unlimited). The parameter protects WebSEAL from processing an POST request of unreasonable size. dynurl-allow-large-posts Although the post-max-read parameter limits the amount of POST content read and processed by WebSEAL, it does not prevent the 216 Version 3.8

237 request, in its entirety, from being passed through to the application server. In this scenario, unvalidated content is passed through to the application server. If the application server does not have its own authorization capabilities, the situation might result in a security risk. The dynurl-allow-large-posts parameter allows you to control the way WebSEAL handles POST requests that have a content length larger than that specified by max-post-read. If the parameter value is set to no (default), WebSEAL rejects, in total, any POST request with a content length larger than that specified by max-post-read. [server] dynurl-allow-large-posts = no If the parameter value is set to yes, WebSEAL accepts the entire POST request, but only validates the amount of content equal to the max-post-read value. [server] dynurl-allow-large-posts = yes Example 1: A large POST request is received (greater than the post-max-read value). dynurl-allow-large-posts = no Dynamic URLs are enabled. Result: Forbidden error message. 8. Application Integration Example 2: A large POST request is received (greater than the post-max-read value). dynurl-allow-large-posts = yes Dynamic URLs are enabled. Result: WebSEAL maps the amount of content up to the post-max-read value to the object space entry and performs an authorization check based on that object. The remaining content is not mapped to the object space entry and no authorization check associated with this object is performed. Tivoli SecureWay Policy Director WebSEAL Administration Guide 217

238 The following template contains the type of pattern matching arrangement that invites misuse by a large POST request: /rtpi153/webapp/examples/hitcount\?*action=reset* Summary and Technical Notes Summary: To configure WebSEAL to securely handle dynamic URLs, create the following file: /opt/policydirector/www/lib/dynurl.conf The file must contain one or more lines of the format: <object> <template> If the file does not exist, or is empty, dynamic URL capability is not enabled. After the file has been processed, the object name appears as a child resource in the WebSEAL object space. The template can contain a subset of the standard pattern matching characters. The template can also be an exact string with no pattern matching characters. The following sample dynurl.conf file defines three objects representing some of the sample Web applications that are part of the IBM WebSphere product: Object Entry /app_showconfig /app_snoop /app_snoop /app_hitcount/ejb /app_hitcount URL Template /rtpi153/webapp/examples/showconfig* /rtpi153/servlet/snoop /rtpi025/servlet/snoop /rtpi153/webapp/examples/hitcount\?source=ejb /rtpi153/webapp/examples/hitcount* Technical Notes: Multiple URL templates can be mapped to the same object (for example, app_snoop maps to URLs on two different servers). 218 Version 3.8

239 Objects can be nested (for example, app_hitcount and app_hitcount/ejb). An incoming URL request is compared against templates in order, from top to bottom. When a match is found, processing stops. Therefore, place the more restrictive templates at the top of the file. To activate the definitions in the dynurl.conf file, issue the dynurl update command (use pdadmin server task). The update occurs immediately and the objects appear in the Web Portal Manager when you refresh the protected object space view. Avoid upper-case characters in the object name. Use lower-case characters only. Do not use an object name that already exists in the protected object space. Before deleting an object in the dynurl.conf file, remove any ACLs attached to the object. Dynamic URL Example: The Travel Kingdom The following example illustrates how a corporate intranet can secure URLs generated by an Oracle Web Listener. 8. Application Integration The dynamic URL Web server used in this example is the Oracle Web Listener. This technology can be applied equally to other dynamic URL Web servers. The Application Travel Kingdom is an organization which offers clients a travel booking service over the Internet. The business intends to operate two Oracle database applications on their Web server accessible from within the corporate firewall and across the Internet. 1. Travel Booking System Authorized customers can make bookings remotely and query their own current bookings. Travel Kingdom staff can also make bookings for telephone customers, process changes, and perform Tivoli SecureWay Policy Director WebSEAL Administration Guide 219

240 many other transactions. Because external customers pay for services with credit cards, the transmission of that information must be strongly secured. 2. Administration Manager Like most other companies, Travel Kingdom maintains an administration database containing salary, position, and experience information. This data is also accompanied by a photograph of each member of staff. The Interface An Oracle Web Server is configured to provide access to the following stored procedures in the database: /db-apps/owa/tr.browse /db-apps/owa/tr.book /db-apps/owa/tr.change Gives all users the ability to inquire about travel destinations, prices, etc. Used to place a booking (travel agent staff or authenticated customers). Used to review or change current bookings. /db-apps/owa/admin.browse /db-apps/owa/admin.resume /db-apps/owa/admin.update Used by any staff member to view unrestricted staff information, such as extension number, address, and photograph. Gives a staff member the ability to view or change their resume information in the Administration database. Used by Administration staff to update information on staff. Web Space Structure A WebSEAL server is used to provide a secure interface to the unified Web space of Travel Kingdom. A junction (/ows) is made to the Oracle Web Server running both the travel booking application and the administration application. 220 Version 3.8

241 The Security Policy To provide suitable security to Web resources, while retaining an easy-to-use system, the business has established the following security goals: 1. Travel agent staff have complete control over all bookings. 2. Authenticated customers can make and change their own bookings, but cannot interfere with the travel data of other authenticated customers. 3. Administration staff have complete access to all of the administration information. 4. Travel Kingdom staff other than the Administration department can change their own resume information and view partial information of other members of staff. Dynamic URL to Object Space Mappings To achieve the security goals described above, the mappings from dynamic URLs to ACL object entries need to be configured as shown in the following table. 8. Application Integration Remember that the ordering of these mappings is an important part of achieving the security goals discussed earlier. Object Space Entry /ows/tr/browse /ows/tr/auth /ows/tr/auth /ows/admin/forall /ows/admin/forall /ows/admin/auth URL Pattern /ows/db-apps/owa/tr.browse\?dest=*&date=??/??/???? /ows/db-apps/owa/tr.book\?dest=*&depart=??/??/????& return=??/??/???? /ows/db-apps/owa/tr.change /ows/db-apps/owa/admin.resume /ows/db-apps/owa/admin.browse\?empid=[th]??? /ows/db-apps/owa/admin.update\?empid=???? Secure Clients Client authenticate to WebSEAL over a secure, encrypted channel. Tivoli SecureWay Policy Director WebSEAL Administration Guide 221

242 Customers who wish to use the Web interface must additionally register with the Travel Kingdom Webmaster to receive an account. Account and Group Structure Four groups are created on the system: Staff Members of the Travel Kingdom organization. TKStaff Travel Kingdom travel agents. AdminStaff Customer Members of the Travel Kingdom Administration Department. Note that Administration staff members are also in the Staff group. Customers of Travel Kingdom who wish to make their travel bookings across the Internet. Each user is given an account in the secure domain so that they can be individually identified by the WebSEAL server. The user s identity is also passed to the Oracle Web Servers to provide a single sign-on solution to all of the Web resources. Access Control The following table lists the access controls resulting from application of the preceding information: /ows/tr/browse unauthenticated Tr any_authenticated Tr /ows/tr/auth unauthenticated - any_authenticated - group TKStaff Tr group Customer PTr /ows/admin/forall unauthenticated - any_authenticated - group Staff Tr /ows/admin/auth unauthenticated - any_authenticated - group AdminStaff Tr Customers and TKStaff have the same privileges on the booking and travel plan maintenance objects, except that the customers must encrypt information (privacy permission) to give them further security when submitting sensitive data (such as credit card information) across the untrusted Internet. 222 Version 3.8

243 Conclusion This simple example illustrates the concepts of deploying a system capable of: Securing sensitive information Authenticating users Authorizing access to sensitive information In addition, the identities of the authenticated users of the system are known to both the WebSEAL and Oracle Web Servers, and are used to provide an auditable, single sign-on solution. 8. Application Integration Tivoli SecureWay Policy Director WebSEAL Administration Guide 223

244 224 Version 3.8

245 A webseald.conf Reference webseald.conf configuration file Categories and stanzas: WEBSEAL GENERAL [server] LDAP [ldap] SSL [ssl] JUNCTION [junction] [filter-url] [filter-schemes] [script-filtering] [gso-cache] [ltpa-cache] AUTHENTICATION [ba] [forms] [token] [certificate] A. webseald.conf Reference Tivoli SecureWay Policy Director WebSEAL Administration Guide 225

246 [http-headers] [auth-headers] [ipaddr] [authentication-levels] [mpa] [cdsso] [cdsso-peers] [failover] [e-community-sso] [inter-domain-keys] [authentication-mechanisms] [ssl-qop] [ssl-qop-mgmt-hosts] [ssl-qop-mgmt-networks] [ssl-qop-mgmt-default] SESSION [session] CONTENT [content] [acnt-mgt] [cgi] [cgi-types] [cgi-environment-variables] [content-index-icons] [icons] [content-cache] [content-mime-types] [content-encodings] LOGGING [logging] AUTHORIZATION API 226 Version 3.8

247 [aznapi-configuration] [aznapi-entitlement-services] POLICY DIRECTOR [policy-director] [manager] WEBSEAL GENERAL Parameter Description [server] stanza SYSTEM unix-user UNIX user account for WebSEAL server. unix-group UNIX group account for WebSEAL server. unix-pid-file Location of PID file. server-root Root directory for the WebSEAL server. server-name WebSEAL server instance name. THREADS AND CONNECTIONS worker-threads Number of WebSEAL worker threads. client-connect-timeout Initial client connection timeout. persistent-con-timeout HTTP/1.1 persistent connection timeout. HTTPS CLIENT https Allow HTTPS access. https-port Port to use for secure HTTPS requests. HTTP CLIENT http Allow unsecure HTTP (TCP) access. http-port Port to use for unsecure HTTP requests. POST REQUESTS post-max-read Maximum number of bytes to read in as content from the body of POST requests. DYNURL dynurl-map Location of URL-to-protected object mapping file. A. webseald.conf Reference Tivoli SecureWay Policy Director WebSEAL Administration Guide 227

248 WEBSEAL GENERAL Parameter Description dynurl-allow-large-posts Limit WebSEAL s ability to read POST requests larger than that specified by post-max-read. URI HANDLING utf8-url-spport-enabled Parameter [ldap] stanza ldap-server-config cache-enabled prefer-readwrite-server auth-using-compare default-policy-overridesupport user-and-group-in-samesuffix ssl-enabled ssl-keyfile ssl-keyfile-dn ssl-keyfile-pwd bind-dn bind-pwd LDAP Description Location of the ldap.conf configuration file (set during configuration). Enable and disable the local LDAP cache. Allow selection of writeable LDAP server, when available. Allows faster authentication checks using an compare password operation rather than an LDAP bind. Check default policy or user-specific policy. Search performance. Indicates that groups are defined in the same LDAP suffix as the user. Enable and disable SSL for WebSEAL-to-LDAP communication. Location of the SSL key file. The certificate label in the SSL key file, if any. SSL key file password. The Distnguished Name of the WebSEAL daemon (set during configuration). The password for the WebSEAL daemon (set during configuration). 228 Version 3.8

249 enabled host port Parameter LDAP Description Parameter [ssl] stanza webseal-cert-keyfile webseal-cert-keyfile-pwd webseal-cert-keyfile-stash webseal-cert-keyfile-label ssl-keyfile ssl-keyfile-pwd ssl-keyfile-stash ssl-keyfile-label disable-ssl-v2 disable-ssl-v3 disable-tls-v1 ssl-v2-timeout ssl-v3-timeout SSL Description Location of the keyfile that contains the server certificate sent to browsers by WebSEAL when negotiating SSL sessions. WebSEAL certificate private key password. Location of WebSEAL private key password stashfile. Name of WebSEAL certificate to use other than the default. Location of the WebSEAL certificate keyfile used for internal communication. WebSEAL certificate private key password (for internal communication). Location of WebSEAL private key password stashfile (for internal communication). Name of certificate to use other than the default (for internal communication). Selectively disable SSL V2 support. Selectively disable SSL V3 support. Selectively disable TLS V1 support. GSKit cache session ID timeout for SSL V2 connections. GSKit cache session ID timeout for SSL V3 connections. A. webseald.conf Reference Tivoli SecureWay Policy Director WebSEAL Administration Guide 229

250 Parameter ssl-max-entries ssl-ldap-server ssl-ldap-server-port ssl-ldap-user ssl-ldap-user-password ssl-auto-refresh ssl-listening-port ssl-pwd-life ssl-authn-type SSL Description Maximum number of concurrent entries in GSKit SSL session ID cache. LDAP server used for CRL checking. Port number this LDAP server is listening on for CRL checking. Administration user for LDAP server. Password of administration user for LDAP server. Parameter [junction] stanza junction-db jmt-map http-timeout https-timeout ping-time basicauth-dummy-passwd worker-thread-hard-limit JUNCTION Description Location of the junction database. Location of the junction-to-request mapping table (JMT). Timeout for sending to and reading from a TCP-based junction. Timeout for sending to and reading from an SSL-based junction. Interval for WebSEAL-to-junctioned servers ping routine. Global password when supplying basic authentication data over -b supply junctions. Percent of total worker threads processing requests for a particular junction. 230 Version 3.8

251 Parameter worker-thread-soft-limit io-buffer-size DOCUMENT FILTERING [filter-url] stanza <tag> = <attribute> [filter-schemes] stanza scheme = <scheme-name> [script-filtering] stanza script-filter GSO CACHE [gso-cache] stanza gso-cache-enabled gso-cache-size gso-cache-entry-lifetime gso-cache-entry-idle-timeout LTPA CACHE [ltpa-cache] stanza ltpa-cache-enabled ltpa-cache-size ltpa-cache-entry-lifetime ltpa-cache-entry-idle-timeout JUNCTION Description Percent of total worker threads processing requests for a particular junction. Buffer size for reading from and writing to a junction. URL attributes that WebSEAL filters in responses from junctioned servers. List of URL schemes that WebSEAL filters in responses from junctioned servers. Enable and disable filtering of absolute URLs from scripts on junctioned servers. Enable and disable the GSO cache. Number of entries in the GSO cache. Maximum lifetime for a GSO cache entry. Maximum lifetime for an inactive GSO cache entry. Enable and disable the LTPA cache. Number of entries in the LTPA cache. Maximum lifetime for a LTPA cache entry. Maximum lifetime for an inactive LTAPA cache entry. A. webseald.conf Reference Tivoli SecureWay Policy Director WebSEAL Administration Guide 231

252 AUTHENTICATION Parameter Description BASIC AUTHENTICATION [ba] stanza ba-auth Enable and disable the Basic Authentication mechanism. basic-auth-realm Realm name displayed in the browser BA login prompt. FORMS [forms] stanza forms-auth Enable and disable authentication using Forms. TOKEN [token] stanza token-auth Enable and disable authentication using token passcodes. CERTIFICATE [certificate] stanza accept-client-certs Configure WebSEAL client-side certificates handling. HTTP HEADERS [http-headers] stanza http-headers-auth Enable and disable authentication using HTTP headers. [auth-headers] stanza header Specific HTTP headers used for authentication. IP ADDRESS [ipaddr] stanza ipaddr-auth Enable and disable authentication using IP address information. STEP UP [authentication-levels] stanza 232 Version 3.8

253 AUTHENTICATION Parameter Description level = unauthenticated level Step-up authentication configuration. = password MULTIPLEXING PROXY AGENTS [mpa] stanza mpa Enable and disable support for authentication via multiplexing proxy agents. CDSSO [cdsso] stanza cdsso-auth Enable and disable authentication using CDSSO tokens. authtoken-lifetime Maximum lifetime value for CDSSO authentication token. [cdsso-peers] stanza <machine-name> = <keyfile-location> FAILOVER [failover] stanza failover-auth failover-cookies-keyfile failover-cookie-lifetime enable-failover-cookie-fordomain e-community SSO [e-community-sso] stanza e-community-sso-auth e-community-name Domain peers that are participating in CDSSO. Enable and disable accepting failover cookies. Location (absolute pathname) of the cookie encryption key generated by cdsso_key_gen. Time limit for when failover cookie content is valid. Change failover cookie type from server-specific cookie to domain-specific cookie. Enable and disable e-community SSO. The e-community name that appears in vouch for tokens and requests. A. webseald.conf Reference Tivoli SecureWay Policy Director WebSEAL Administration Guide 233

254 Parameter intra-domain-key is-master-authn-server master-authn-server master-http-port master-https-port vf-token-lifetime vf-url ec-cookie-lifetime [inter-domain-keys] stanza <domain-name> = <keyfile> AUTHENTICATION Description Location of keyfile used to secure communication between WebSEAL instances in a DNS domain. Designates local machine as the master WebSEAL authentication server. Name of master WebSEAL authentication server (if not the local machine). Non-standard HTTP port for master authentication server to listen on. Non-standard HTTPSport for master authentication server to listen on. The vouch for token lifetime value. The vouch for URL. The e-community cookie lifetime value. The keyfiles for other domains participating in the e-community. AUTHENTICATION MECHANISMS AND LIBRARIES [authentication-mechanisms] stanza passwd-cdas passwd-ldap passwd-uraf token-cdas cert-ssl cert-cdas http-request cdsso passwd-strength cred-ext-attrs List of supported authentication mechanisms and associated shared libraries. SSL QUALITY OF PROTECTION MANAGEMENT [ssl-qop] stanza ssl-qop-mgmt Enable and disable quality of protection management. [ssl-qop-mgmt-hosts] stanza <ip-address> QOP encryption level for individual hosts. [ssl-qop-mgmt-networks] stanza 234 Version 3.8

255 Parameter <ip-address/mask> AUTHENTICATION Description QOP encryption level for individual networks. [ssl-qop-mgmt-default] stanza default Default QOP encryption level for all other unmatched IP addresses. Parameter [session] stanza max-entries timeout inactive-timeout SSL CLIENT SESSIONS ssl-id-sessions SHARING SESSIONS use-same-session SESSION Description Maximum number of concurrent entries in WebSEAL credentials/session cache. Maximum lifetime for an entry in the WebSEAL credentials/session cache. Lifetime of inactive entries in the WebSEAL credentials cache. Use the SSL ID to maintain HTTPS login sessions. Use the same session ID for clients who switch between HTTP and HTTPS. SENDING SESSION COOKIES resend-webseal-cookies Send any configured session and failover cookies with every response to the client. CONTENT Parameter Description [content] stanza LOCAL DIRECTORIES AND FILES doc-root Root directory of the Web document tree. directory-index Name of directory index file. A. webseald.conf Reference Tivoli SecureWay Policy Director WebSEAL Administration Guide 235

256 Parameter delete-trash-dir CONTENT Description Temporary trash directory for files deleted by the administrator. LOCAL USER DIRECTORIES user-dir Directory is user s home tree containing public HTML documents. ERROR PAGES error-dir Director containing WebSEAL error description files. ACCOUNT MANAGEMENT PAGES [acnt-mgt] stanza mgt-pages-root Root of account management pages. login Name of standard login form. logout Name of page displayed after successful logout. account-locked Name of page displayed if authentication failed due to a locked account. passwd-expired Name of page displayed if authentication fails due to an expired password. passwd-change Name of change password form. passwd-change-success Name of page displayed if password change request is successful. passwd-change-failure Name of page displayed if password change request is unsuccessful. help Name of page containing links to valid administration pages. token-login Name of token login form. next-token Name of next token form. stepup-login Name of step-up authentication login form. LOCAL CGI [cgi] stanza cgi-timeout Timeout value for writing to and reading from child CGI processes. 236 Version 3.8

257 Parameter [cgi-types] stanza bat = cmd cmd = cmd pl = perl sh = sh tcl = tclsh76 CONTENT Description Designates - for Win32 servers - what program to execute for a particular CGI file extension. [cgi-environment-variables] stanza ENV Environment variables to be inherited by CGI programs. ICONS [content-index-icons] stanza image/* video/* audio/* text/html text/* application/x-tar application/* [icons] stanza diricon backicon unknownicon DOCUMENT CACHING [content-cache] stanza text/html image/* */* MIME TYPES [content-mime-types] stanza <extension> = <type> deftype CONENT ENCODINGS [content-encodings] stanza Specifies the graphic icons to use when a directory index is generated by WebSEAL (this occurs when there is no index.html). Icon to use for sub-directories. Icon to use for the parent directory. Icon to use for unknown file types. Define cache type and size for specific document MIME types that WebSEAL stores in memory. Defines MIME type for specific document extensions. Default MIME type to use when the document type is not listed in the mapping table. A. webseald.conf Reference Tivoli SecureWay Policy Director WebSEAL Administration Guide 237

258 gz Z Parameter CONTENT Description Maps document extension to an encoding type for browsers that support content encoding. Parameter [logging] stanza server-log max-size flush-time requests requests-file referers referers-file agents agents-file gmt-time LOGGING Description Location of server error log file. Log file rollover threshold for HTTP logs. Frequency for flushing HTTP log file buffers. Enable and disable the HTTP request log. Location of the HTTP request log. Enable and disable the HTTP referer log. Location of the HTTP referer log. Enable and disable the HTTP agent log. Location of the HTTP agent log. Log requests with GMT time instead of local time zone. AUTHORIZATION API Parameter Description [aznapi-configuration] stanza db-file Location of the local client s policy database cache file. cache-refresh-interval Defines the interval between checks for updates (poll) to the master authorization server. listen-flags Enale and disable flags for the reception of policy cache update notifications. tcp-port The TCP port for the listener. 238 Version 3.8

259 AUTHORIZATION API Parameter Description udp-port The UDP port for the listener. AUTHORIZATION API LOGGING logclientid=webseald logsize Log file rollover threshold for management audit log. logflush Frequency for flushing management audit log file buffers. logaudit Eanbale and disabling auditing. auditlog Location of audit log. auditcfg = azn Capture authorization events. auditcfg = authn Capture authentication events. auditcfg = wand Capture WebSEAL events. AZNAPI SERVICE DEFINITIONS <service-id> mode azn-server-name pd-user-name [aznapi-entitlement-services] stanza AZN_ENT_EXT_ATTR Parameter [policy-director] stanza config-file [manager] stanza master-host master-port master-dn POLICY DIRECTOR Description Location of the pd.conf configuration file. A. webseald.conf Reference Tivoli SecureWay Policy Director WebSEAL Administration Guide 239

260 240 Version 3.8

261 B WebSEAL Junction Reference The pdadmin utility provides an interactive command-line prompt from which you can perform WebSEAL junction tasks. Topic Index: Using pdadmin server task to Create Junctions on page 241 The Junction Commands on page 243 Create a New Junction for an Initial Server on page 244 Add an Additional Server to an Existing Junction on page 247 Using pdadmin server task to Create Junctions Before using pdadmin, you must login to a secure domain as the sec_master administration user. For example: UNIX: # pdadmin pdadmin> login Enter User ID: sec_master Enter Password: pdadmin> Windows: Tivoli SecureWay Policy Director WebSEAL Administration Guide 241 B. WebSEAL Junction Reference

262 MSDOS> pdadmin pdadmin> login Enter User ID: sec_master Enter Password: pdadmin> Alternatively, you can achieve the same results with a single command line that uses the following options: # pdadmin -a sec_master -p <password> pdadmin> To create WebSEAL junctions, you use the pdadmin server task command: pdadmin> server task <server-name> <task> The server-name argument is the full expression of the actual machine name and the Policy Director component used by this command (such as WebSEAL). <policy-director-component>-<machine-name> For example, if the machine name is cruz and the Policy Director component is WebSEAL, the server-name is: webseald-cruz Use the server list command to verify server-name expressions: pdadmin> server list webseald-cruz The mandatory command options required to create a basic WebSEAL junction include: Host name of the back-end application server ( h option) Junction type tcp, ssl, tcpproxy, sslproxy, local ( t option) Junction point (mount point) pdadmin> server task <server-name> create t <type> h <host-name> <jct-point> 242 Version 3.8

263 The Junction Commands The following junction commands are available with pdadmin server task: Command create add remove Description Create a new junction for an initial server. Add additional server(s) to an existing junction point. Remove a server from a junction point. Syntax: remove i <server-id> <junction-point> delete list show jmt load jmt clear help Use the show command to determine the ID of a particular server. Remove the junction point. Syntax: delete <junction-point> List all junction points on this server. Syntax: list Display the details of a junction. Syntax: show <junction-point> The jmt load command provides WebSEAL with junction mapping table data (jmt.conf) to handle processing of dynamically generated server-relative URLs. The jmt clear command removes junction mapping table data from WebSEAL. List junction commands. help <command> exit Syntax: help Display detailed help on a specific junction commands. Exits the pdadmin utility. Syntax: exit Tivoli SecureWay Policy Director WebSEAL Administration Guide 243 B. WebSEAL Junction Reference

264 These commands, and associated options, are discussed in the following sections. Create a New Junction for an Initial Server Operation: Creates a new junction point and junctions an initial server. Syntax: create t <type> h <host-name> [<options>] <junction-point> Junction Type t <type> **Required** Type of junction. One of: tcp, ssl, tcpproxy, sslproxy, local. Default port for t tcp is 80. Default port for t ssl is 443. Host Name h <host-name> **Required** The DNS host name or IP address of the target back-end server. Options Mutual Authentication Over SSL K <key-label> WebSEAL uses client certificate to authenticate to back-end server. B WebSEAL uses BA header information to authenticate to back-end server. Requires U, W, and b filter options. U < username > WebSEAL username. Use with B to send BA header information to back-end server. W < password > WebSEAL password. Use with B to send BA header information to back-end server. D < DN > Specify Distinguished Name of back-end server certificate. This value, matched with actual certificate DN enhances authentication. 244 Version 3.8

265 Proxy junction options (requires t tcpproxy or t sslproxy) H <host-name> The DNS host name or IP address of the proxy server. P <port> The TCP port of the proxy server. Supplying BA header information b <BA-value> Defines how the WebSEAL server passes HTTP BA authentication information to the back-end server. One of: filter (default), ignore, supply, gso General TCP and SSL junction options c <id-types> Insert Policy Director client identity in HTTP headers across the junction. The id-types argument can include any combination of the following Policy Director HTTP header types: iv-user, iv-user-l, iv-groups, iv-creds, all. i WebSEAL server treats URLs as case insensitive. j Supply junction identification in a cookie to handle script generated server-relative URLs. k Send session cookie to back-end portal server. p <port> TCP port of the back-end third-party server. Default is 80 for TCP junctions; 443 for SSL junctions. q <url> Relative URL for query_contents script. Policy Director looks for query_contents in /cgi_bin/. If this directory is different or the query_contents file renamed, use this option to indicate to WebSEAL the new URL to the file. r Insert incoming IP address in HTTP header across the junction. Tivoli SecureWay Policy Director WebSEAL Administration Guide 245 B. WebSEAL Junction Reference

266 s Specifies that the junction should support stateful applications. By default, junctions are not stateful. T <resource/ resource-group> Name of GSO resource or resource group. Required for and used only with b gso option. u <UUID> Specifies the UUID of a back-end server connected to WebSEAL via a stateful junction ( s). v <virt-host-name> Virtual host name represented on the back-end server. This option supports a virtual host setup on the back-end server. You use v when the back-end junction server expects a host name header because you are junctioning to one virtual instance of that server. The default HTTP header request from the browser does not know that the back-end server has multiple names and multiple virtual servers. You must configure WebSEAL to supply that extra header information in requests destined for a back-end server set up as a virtual host. w Win32 filesystem support. LTPA junctions A Enable and disable LTPA junctions. F < keyfile > Location of key file used to encrypt LTPA cookie data. Z Password for the key file < keyfilepassword > WebSEAL-to-WebSEAL SSL junctions C Mutual authentication between a front-end WebSEAL server and a back-end WebSEAL server over SSL. Requires t ssl or t sslproxy type. Local junction options (use with t local) d <dir> Local directory to junction. **Required.** 246 Version 3.8

267 f Force the replacement of an existing junction. Junction Point Location in the WebSEAL namespace to create the junction. Add an Additional Server to an Existing Junction Operation: Adds an additional server to an existing junction point. Syntax: add h <host-name> [<options>] <junction-point> Host Name h <host-name> **Required** The DNS host name or IP address of the target back-end server. Options Mutual Authentication Over SSL D < DN > Specify Distinguished Name of back-end server certificate. This value, matched with actual certificate DN enhances authentication. Proxy junction options (required with t tcpproxy and t sslproxy) H <host-name> DNS host name or IP address of the proxy server. P <port> The TCP port of the proxy server. General TCP and SSL junction options i WebSEAL server treats URLs as case insensitive. j Supply junction identification in a cookie to handle script generated server-relative URLs. Tivoli SecureWay Policy Director WebSEAL Administration Guide 247 B. WebSEAL Junction Reference

268 p <port> TCP port of back-end third-party server. Default is 80 for TCP junctions; 443 for SSL junctions. q <url> Relative URL for query_contents script. Policy Director looks for query_contents in /cgi_bin/. If this directory is different or the query_contents file renamed, use this option to indicate to WebSEAL the new URL to the file. u <UUID> Specifies the UUID of a back-end server connected to WebSEAL via a stateful junction ( s). v <virt-host-name> Virtual host name represented on the back-end server. This option supports a virtual host setup on the back-end server. You use v when the back-end junction server expects a host name header because you are junctioning to one virtual instance of that server. The default HTTP header request from the browser does not know that the back-end server has multiple names and multiple virtual servers. You must configure WebSEAL to supply that extra header information in requests destined for a back-end server set up as a virtual host. w Win32 filesystem support. Junction Point Add server to this existing junction point. 248 Version 3.8

269 C Managing Certificates with ikeyman The ikeyman utility is a tool you can use to manage your digital certificates. With ikeyman, you can create a new key database, a new test digital certificate, add CA roots to your database, copy certificates from one database to another, request and receive a digital certificate from a CA, set default keys, and change passwords. The ikeyman utility is a part of the Global Security Kit (GSKit) package provided with Policy Director. Topic Index: Starting the ikeyman Utility on page 250 Opening the Default WebSEAL Key Database on page 251 Creating a New Key Database on page 253 Creating a New Self-signed Digital Certificate on page 256 Adding a New Root CA Certificate on page 258 Deleting a Root CA Certificate on page 259 Copying Certificates Between Databases on page 259 Requesting a Server Certificate on page 263 Receiving a Digital Certificate on page 265 Deleting a Digital Certificate on page 265 Tivoli SecureWay Policy Director WebSEAL Administration Guide 249 C. Managing Certificates with ikeyman

270 Assigning a New Default Certificate on page 266 Changing a Database Password on page 267 Starting the ikeyman Utility Start the ikeyman utility from the operating system command line prompt: Windows: MSDOS> /Program Files/IBM/gsk4/bin/gsk4ikm.exe UNIX: # /usr/bin/gsk4ikm The IBM Key Management window appears. Figure 39. IBM Key Management Window 250 Version 3.8

271 Opening the Default WebSEAL Key Database A key database contains the server and client-side certificates and root CA certificates required by WebSEAL to process certificate-based authentication. At installation, WebSEAL provides a default certificate key database (pdsrv.kdb). The key file contains a default WebSEAL certificate (key label = Policy Director) and a selection of common root CA certificates. To open the default WebSEAL key database, follow these steps: 1. From the IBM Key Management window, select Open from the Key Database File menu. 2. From the Open browse window, navigate to the following directory: UNIX: /opt/policydirector/lib/certs Windows: C:\Program Files\Tivoli\Policy Director\lib\certs 3. Select: pdsrv.kdb 4. Click Open. The Password Prompt dialog box appears. 5. Type the default WebSEAL password: pdsrv 6. Click OK. The database information populates the management window. Note that the default WebSEAL certificate appears in the Personal Certificates window. The key label for the certificate is Policy Director. The asterisk that appears to the left of this label marks the certificate as default. See Figure 40 on page 252. Tivoli SecureWay Policy Director WebSEAL Administration Guide 251 C. Managing Certificates with ikeyman

272 Change the certificate choice pull-down menu from Personal Certificates to Signer Certificates. The list of common root Certificate Authority (CA) certificates appears. See Figure 41 on page 253. Figure 40. Default WebSEAL pdsrv.kdb Key File: WebSEAL Certificate 252 Version 3.8

273 Figure 41. Default WebSEAL pdsrv.kdb Key File: Signer Certificates Creating a New Key Database A key database contains the server and client-side certificates and root CA certificates required by WebSEAL to process certificate-based authentication. At installation, WebSEAL provides a default certificate key database (pdsrv.kdb). The key file contains a default WebSEAL certificate (key label = Policy Director) and a selection of common root CA certificates. You can continue to use this default key database, or create a new database. If you create a new database and expect WebSEAL to use this as the default database, you must inform WebSEAL by configuring the ssl-keyfile parameter in the secmgrd.conf file. See Configuring Key Database Parameters for WebSEAL on page 41. To create a new key database file, follow these steps: Tivoli SecureWay Policy Director WebSEAL Administration Guide 253 C. Managing Certificates with ikeyman

274 1. From the IBM Key Management window, select New from the Key Database File menu. The New dialog box appears. Figure 42. New Dialog Box 2. Select CMS key database file in the Key database type field. 3. Enter a File Name such as key.kdb. 4. Accept the default value for the Location field, or enter a new value for the field, or use the Browse button to select a new value. 5. Click OK. The Password Prompt window appears. 6. Enter a password in the Password field, and type it again in the Confirm Password field. 7. (Optional) Select the Set expiration time checkbox and enter an appropriate value. 8. (Optional) Select the Stash the password to a file checkbox. A stash file contains the following extension:.sth You must inform WebSEAL of this new stash file by configuring the ssl-keyfile-stash parameter in the secmgrd.conf configuration file. See Configuring Key Database Parameters for WebSEAL on page Click OK. 254 Version 3.8

275 A confirmation window appears and verifies that you have created a new key database. 10. Click OK. You have successfully created a new key database. The IBM Key Management window reappears. The IBM Key Management window now reflects your new key file name and displays your signer certificates. The following signer digital certificates are provided with ikeyman: RSA Secure Server CA Thawte Personal Premium CA Thawte Personal Fre CA Thawte Personal Basic CA Thawte Premium Server CA Thawte Server CA VeriSign Class 1 Public Primary CA VeriSign Class 2 Public Primary CA VeriSign Class 3 Public Primary CA VeriSign Test CA Root Certificate These signer digital certificates are the root certificates from established Certificate Authorities (CA). WebSEAL uses these root certificates to validate client-side certificates. If you need to use a signer certificate that does not appear on this list, you must request it from the CA and add it to your key database. See Adding a New Root CA Certificate on page 258. Tivoli SecureWay Policy Director WebSEAL Administration Guide 255 C. Managing Certificates with ikeyman

276 Note: The VeriSign Test CA Root Certificate is a low-assurance CA that is included for testing purposes. You should remove this root before placing a key database class into a production application. The new database also needs to include a CA signed server certificate so WebSEAL can authenticate itself to clients or other servers. This certificate is stored in the Personal Certificates section of the management window. See Requesting a Server Certificate on page 263. See Receiving a Digital Certificate on page 265. Creating a New Self-signed Digital Certificate When you are developing a production application, you might not want to perform certificate authentication with a true digital certificate until you are finished testing the product. With ikeyman, you can create a self-signed digital certificate to use for testing. A self-signed digital certificate is a temporary digital certificate you issue to yourself, with yourself as the CA. Note: Do not release a production application with a self-signed digital certificate; no browser or client will be able to recognize or securely communicate with your server. At installation, WebSEAL provides a self-signed certificate called Policy Director. You can use this certificate for testing, or you can create a new self-signed certificate. To create a new self-signed digital certificate, follow these steps: 1. Use ikeyman to open the pdsrv.kdb key file, or another custom key file. The IBM Key Management window title bar shows the name of the key database file you selected, indicating that the file is open and ready. 2. Select Personal Certificates from the pull-down list. 256 Version 3.8

277 3. Click the New Self-Signed button. The Create New Self-Signed Certificate dialog box appears. 4. Enter a Key Label, such as test-cert. 5. Enter a Common Name and Organization (both required), and select a Country. For the remaining fields, either accept the default values, or type or select new values. See Figure Click OK. The IBM Key Management window Personal Certificates field shows the name of the self-signed digital certificate you created. Figure 43. Create New Self Signed Certificate Tivoli SecureWay Policy Director WebSEAL Administration Guide 257 C. Managing Certificates with ikeyman

278 Adding a New Root CA Certificate Before you can add a new root certificate for a specific CA, you must first make a request for this certificate from the CA. Each CA has unique procedures for this task. Contact the appropriate CA for this information. After you have requested and received a root certificate from a CA, you can add it to your key database. Most digital root certificates use the form *.arm (for example, cert.arm). To add a root CA certificate to a database, follow these steps: 1. In the IBM Key Management window, select Signer Certificates from the pull-down list. 2. Click Add. The Add CA s Certificate from a File window appears. Figure 44. Add CA s Certificate Dialog Box 1. Select Base64-encoded ASCII data from the Data type pull-down menu. 2. Enter the Certificate file name and Location for the root CA certificate, or click Browse to select the name and location. 3. Click OK. The Enter a Label dialog box appears. 4. Enter a key label for the root CA certificate, such as VeriSign Root CA Certificate, and click OK. The Signer Certificates field now contains the label of the root CA certificate you just added. 258 Version 3.8

279 Deleting a Root CA Certificate If you no longer want to support one of the signers in your signer certificate list, you need to delete the appropriate root CA certificate. Note: Before you delete a root CA certificate, create a backup copy of the certificate so you can later re-create that same CA root certificate. To delete a root CA certificate from a database, follow these steps: 1. In the IBM Key Management window, select Signer Certificates from the pull-down list. 2. Select (highlight) the root CA certificate you want to delete. 3. Click Delete. The Confirm window appears. 4. Click Yes. The label of the root CA certificate you just deleted no longer appears in the Signer Certificates field. Copying Certificates Between Databases When setting up a private trust network or using self-signed certificates for testing purposes, you might find it necessary to copy a certificate from one database and add it to another database. There are three methods to move certificates between databases: Extract Certificate to a File; Add Certificate from a File Import Certificate Directly from a Database Export Certificate Directly to a Database Extract Certificate to a File; Add Certificate from a File To extract a certificate from the (source) key database to a file, and then add the certificate to the (target) key database, follow these steps: 1. Open the source key database. Tivoli SecureWay Policy Director WebSEAL Administration Guide 259 C. Managing Certificates with ikeyman

280 2. From the IBM Key Management window pull-down menu, select the type of certificate you want to export: Personal or Signer. 3. Select the certificate that you want to add to another database. 4. If you select Personal, click the Extract Certificate button. If you select Signer, click the Extract button. The Extract a Certificate to a File window appears. 5. Select Base64-encoded ASCII data from the Data type pull-down menu. The data type needs to match the data type of the certificate stored in the certificate file. The ikeyman tool supports Base64-encoded ASCII files and binary DER-encoded certificates. 6. Enter the certificate file name and location where you want to store the certificate, or click Browse to select the name and location. Figure 45. Extract Certificate to a File 7. Click OK. The certificate is written to the specified file. To add a certificate from the file to the target database, follow these steps: 1. Open the target key database. 2. Select the type of certificate you would like to add: Personal or Signer. 3. Click Add for a Signer type certificate. Click Receive for a Personal type certificate. 260 Version 3.8

281 4. Enter the Certificate file name and Location that you used when you extracted the certificate. You can also use the Browse button. Figure 46. Receive Certificate from a File 5. Click OK. 6. A Confirm window ask you to select whether this certificate will be the default certificate. Click Yes or No. The certificate is now added to the target database and appears in the list of certificates. Import Certificate Directly from a Database To import a certificate from a (source) key database to the (target) key database follow these steps: 1. Open the target key database. 2. From the IBM Key Management window pull-down menu, select the type of certificate you want to export: Personal or Signer. 3. Click the Export/Import button. The Export/Import Key window displays. 4. Select Import from the Choose Action Type. 5. From the Key file type pull-down menu, select CMS key database file. 6. Enter the File name and Location of the source key database that contains the certificate you would like to import. You can also use the Browse button. Tivoli SecureWay Policy Director WebSEAL Administration Guide 261 C. Managing Certificates with ikeyman

282 Figure 47. Export/Import Key 7. Click OK. The Password Prompt window displays. 8. Enter the password and click OK. The Select From Key Label List window appears. 9. Select the certificate you want to import and click OK. The certificate now appears in the list of the target database. Export Certificate Directly to a Database To export a certificate from the (source) key database to a (target) key database follow these steps: 1. Open the source key database. 2. From the IBM Key Management window pull-down menu, select the type of certificate you want to export: Personal or Signer. 3. Select (highlight) the certificate you want to export. 4. Click the Export/Import button. The Export/Import Key window displays. 5. Select Export from the Choose Action Type. 6. From the Key file type pull-down menu, select CMS key database file. 7. Enter the File name and Location of the target key database where you want to send the certificate. You can also use the Browse button. 262 Version 3.8

283 Note: A disturbing message appears about replacing this database file. Click Yes. The exported certificate will only be added to the target database. Nothing will be lost. Figure 48. Export/Import Key 8. Click OK. The Password Prompt window displays. 9. Enter the password for the target database and click OK. 10. When you open the target database, the exported certificate will appear in the list of certificates. Requesting a Server Certificate WebSEAL requires a CA-signed certificate to authenticate itself to SSL clients. WebSEAL may need different certificates to serve other authentication requirements (such as responding to a application server junctioned with junctioncp K). The ikeyman utility allows you to generate a certificate request that you can send to the appropriate CA. To generate a certificate request, follow these steps: 1. In the IBM Key Management window, select Personal Certificate Requests from the pull-down list. 2. Click New. Tivoli SecureWay Policy Director WebSEAL Administration Guide 263 C. Managing Certificates with ikeyman

284 The Create New Key and Certificate Request dialog box appears. Figure 49. Create New Key and Certificate Request 3. Enter a Key Label for the certificate request. 4. Enter a Common Name and Organization and select a Country. For the remaining fields, either accept the default values, or type or select new values. 5. At the bottom of the window, enter a name and location for the file. You can also use the Browse button. 6. Click OK. A confirmation window appears and verifies that you have successfully created a request for a new digital certificate. 7. Click OK. The Personal Certificate Requests field shows the key label of the new digital certificate request you created. 8. Send the file to the appropriate CA to request a new digital certificate, or cut and paste the request into the request forms from the CA s Web site. 264 Version 3.8