CA SOA Security Manager Implementation Guide

Implementation Guide r12

CA™ SOA Security Manager

This documentation and any related computer software help programs (hereinafter referred to as the “Documentation”) is for the end user’s informational purposes only and is subject to change or withdrawal by CA at any time.

This Documentation may not be copied, transferred, reproduced, disclosed, modified or duplicated, in whole or in part, without the prior written consent of CA. This Documentation is confidential and proprietary information of CA and protected by the copyright laws of the United States and international treaties.

Notwithstanding the foregoing, licensed users may print a reasonable number of copies of the Documentation for their own internal use, and may make one copy of the related software as reasonably required for back-up and disaster recovery purposes, provided that all CA copyright notices and legends are affixed to each reproduced copy. Only authorized employees, consultants, or agents of the user who are bound by the provisions of the license for the Product are permitted to have access to such copies.

The right to print copies of the Documentation and to make a copy of the related software is limited to the period during which the applicable license for the Product remains in full force and effect. Should the license terminate for any reason, it shall be the user’s responsibility to certify in writing to CA that all copies and partial copies of the Documentation have been returned to CA or destroyed.

EXCEPT AS OTHERWISE STATED IN THE APPLICABLE LICENSE AGREEMENT, TO THE EXTENT PERMITTED BY APPLICABLE LAW, CA PROVIDES THIS DOCUMENTATION “AS IS” WITHOUT WARRANTY OF ANY KIND, INCLUDING WITHOUT LIMITATION, ANY IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NONINFRINGEMENT. IN NO EVENT WILL CA BE LIABLE TO THE END USER OR ANY THIRD PARTY FOR ANY LOSS OR DAMAGE, DIRECT OR INDIRECT, FROM THE USE OF THIS DOCUMENTATION, INCLUDING WITHOUT LIMITATION, LOST PROFITS, BUSINESS INTERRUPTION, GOODWILL, OR LOST DATA, EVEN IF CA IS EXPRESSLY ADVISED OF SUCH LOSS OR DAMAGE.

The use of any product referenced in the Documentation is governed by the end user’s applicable license agreement.

The manufacturer of this Documentation is CA.

Provided with “Restricted Rights.” Use, duplication or disclosure by the United States Government is subject to the restrictions set forth in FAR Sections 12.212, 52.227-14, and 52.227-19(c)(1) - (2) and DFARS Section 252.227-7014(b)(3), as applicable, or their successors.

All trademarks, trade names, service marks, and logos referenced herein belong to their respective companies.

Copyright © 2007 CA. All rights reserved.

CA, Inc. Product References This document references the following CA, Inc. products:

CA™ SOA Security Manager

CA™ SiteMinder®

Contact Technical Support For online technical assistance and a complete list of locations, primary service hours, and telephone numbers, contact Technical Support at http://ca.com/support.

http://www.ca.com/support

http://www.ca.com/support

Contents 5

Contents

Chapter 1: CA SOA Security Manager Introduction 11 CA SOA Security Manager Overview ........................................................... 11

CA SOA Security Manager Features ........................................................ 12 CA SOA Security Manager Benefits ......................................................... 13 CA SOA Security Manager Architecture and Components .................................... 13

Authentication Methods ....................................................................... 19 Develop and Deploy CA SOA Security Manager Protected Web Services .......................... 20 Authentication Service Models ................................................................. 21

Single-Step Authentication Model .......................................................... 22 Multistep Authentication Model............................................................. 23 Chain Authentication Service Model ........................................................ 25

Sample Deployment Scenario ................................................................. 28 Use Cases.................................................................................... 28

SSO From SiteMinder-protected Portal to Web Service Use Case ............................. 29 Chained Web Service Request Use Case .................................................... 29 Multitep Web Service Request Use Case .................................................... 30

Chapter 2: Prepare for Your Install 31 Policy Server Install Preparation ............................................................... 31

Prepare to Install a Policy Server on Windows .............................................. 31 Prepare to Install a Policy Server on UNIX .................................................. 35

SOA Agent for Web Servers Install Preparation ................................................. 42 Supported Operating Systems and Web Servers ............................................ 42 Ensure the Policy Server is Installed and Configured ........................................ 43 Gather information Needed to Complete the Agent Installation............................... 45 Install the Correct Agent for a Web Server.................................................. 45 How to Use a Non-Default IIS website...................................................... 46 Miscellaneous Web Server Preparations .................................................... 46 Required Linux Libraries................................................................... 48 General Preparations for All Web Agents.................................................... 48 Set the DISPLAY For Web Agent Installations on UNIX....................................... 49 Modify the Apache 2.0 httpd.conf File for Agents on IBM HTTP Servers ....................... 49 Enable Write Permissions for IBM HTTP Server Logs......................................... 49 Add a Logs Subdirectory for Apache Web Agents............................................ 50 Compile an Apache Web Server on a Linux System.......................................... 50 Set Up DNS on AIX Platforms for Agent Operation .......................................... 50 Prepare for Cryptographic Hardware Support (Optional) ..................................... 51

6 Implementation Guide

Preserve Changes in the WebAgentTrace.conf File........................................... 52 SOA Agent for IBM WebSphere Install Preparation .............................................. 52

Software Requirements ................................................................... 53 Required JVM Patch for SOA Agent for IBM WebSphere...................................... 53 Installation Checklist ...................................................................... 53 Setting a PATH Variable to the JVM on UNIX Systems ....................................... 54

SOA Security Gateway Install Preparation ...................................................... 54 Scripting Interface for Perl .................................................................... 56 Preconfiguring Policy Objects for SOA Agents ................................................... 56

Policy Object Preconfiguration Overview .................................................... 56 Preconfiguring the Policy Objects .......................................................... 58

Chapter 3: Install the CA SOA Security Manager Software 59 Information Required During Installation ....................................................... 59

Installation Selections..................................................................... 60 Information Required for Policy Server Installation Elements................................. 60 Information Required for SOA Agent for IBM WebSphere .................................... 64

Run the CA SOA Security Manager Installer in GUI or Console Mode ............................. 65 Run the Unattended CA SOA Security Manager Installer......................................... 66 Upgrade CA SOA Security Manager ............................................................ 68 Reinstall CA SOA Security Manager ............................................................ 68 Uninstall CA SOA Security Manager ............................................................ 69

Chapter 4: Post-installation, Policy Server 71 Run the Policy Server Configuration Wizard..................................................... 72 Additional SNMP Step ......................................................................... 74

Configure SNMP Event Trapping ........................................................... 74 Configuring LDAP Directory Servers as a Policy or Key Store..................................... 75

LDAP Directory Servers as a Policy or Key Store ............................................ 75 Important Considerations ................................................................. 75 Create a Policy Store in an LDAP Directory.................................................. 76 SiteMinder Key Store Overview ............................................................ 99 Migrate an Existing Policy Store into an LDAP Directory..................................... 101 Point the Policy Server at the Policy Store ................................................. 103

Configure CA SOA Security Manager Data in a Relational Database ............................. 104 Relational Databases as a Policy or Key Store.............................................. 104 Important Considerations ................................................................ 105 How to Configure a SiteMinder Data Store in a SQL Server Database ........................ 105 How to Configure a SiteMinder Data Store in an Oracle Database ........................... 112 Configure Policy, Key, Logging, Session or Token Data Stores .............................. 128 Import Default SiteMinder Objects into the Policy Store .................................... 138

Contents 7

Migrate an Existing Policy Store into a Relational Database ................................. 140 Create a Sample User Directory for Oracle or SQL Server................................... 143

Policy Server Tools .......................................................................... 145 Requirement When Using the Policy Server Tools on Linux Red Hat ......................... 146 Export Policy Data Using smobjexport ..................................................... 147 Import Policy Data Using smobjimport .................................................... 151 Migrate 6.x Policy Stores With Different Environments...................................... 155 Manage an LDAP Policy Store Using smldapsetup .......................................... 159 Hardware Key Storage with an nCipher Cryptographic Module .............................. 169 Delete SiteMinder Data in ODBC Databases................................................ 170 Check Solaris Patches with smpatchcheck ................................................. 171 Read RADIUS Log Files With Smreadclog .................................................. 173 Import Tokens Using the SiteMinder Token Tool ........................................... 174 SiteMinder Test Tool ..................................................................... 175 Change the SiteMinder Super User Password Using smreg .................................. 175

Configure the OneView Monitor ............................................................... 176 System Requirements for OneView Monitor GUI............................................ 176 Oneview Monitor GUI Configuration During Policy Server Installation ........................ 176 How to Configure the OneView Monitor GUI on Windows/IIS ................................ 177 How to Configure the OneView Monitor GUI on UNIX/Sun Java System ...................... 180 Monitor a Policy Server Cluster ........................................................... 183

Prerequisites for Running Reports Using Crystal Reports........................................ 183 Crystal Reports in a Policy Server Environment ............................................ 184 How to Configure the Policy Server for Crystal Reports ..................................... 186 Next Steps .............................................................................. 191 Modify SiteMinder Reports to Use the Crystal Reports Data Source .......................... 199

Secure Keys with a Hardware Module ......................................................... 200 Hardware Keys Overview ................................................................. 200 Install Cryptographic Modules and Creating Security Worlds ................................ 202 Create Operator Card Sets and Initializing Operator Cards .................................. 203 Generate and Load Host Keys............................................................. 203 Configure Unattended Failover for nCipher Hardware Modules............................... 203

SNMP Support............................................................................... 204 Prerequisites for Windows and UNIX Systems.............................................. 205 Configure the SNMP Agent on Windows.................................................... 206 Configure the SNMP Agent on UNIX Systems .............................................. 208

Troubleshooting ............................................................................. 210 Database may be corrupt message........................................................ 211 SiteMinder Administration Server Error: Could not log in. (Error 3) .......................... 212 Policy Server User Interface Does Not Appear on Windows.................................. 213 Unable to proceed. No response from SiteMinder Message .................................. 214 Policy Server Fails to Start After Installation ............................................... 214


AE failed to load library 'smjavaapi’. System error ......................................... 214 PDF Files Do Not Open From the Online Manuals Index HTML Page .......................... 215 Locate Logging Messages if Smobjimport Fails During Import ............................... 215 Missing Icons on the System and Domains tab of the Policy Server UI ....................... 216 Cannot launch Regedit Tool on UNIX Systems ............................................. 216 Cannot Access Online Manuals from Policy Server User Interface............................ 217 Adobe Acrobat Reader Won’t Install ....................................................... 217 Windows/IIS Virtual Path to /sitemindermonitor Does Not Exist ............................. 217 Policy Stores with Large Numbers of Objects............................................... 218 SSL initialization failed: error -8174 (security library: bad database.) ....................... 219 Winsock error 10054 message ............................................................ 219 Extra Shortcuts in the Windows Start Menu................................................ 220 Problem With Using Active Directory as a User Store ....................................... 221 Manually Create the netegrity_docs Virtual Directory on IIS 5.0/6.0......................... 221 Fix Modified UNIX/Sun Java System Web Server Configuration Files ......................... 222 NETE_PS_ALT_CONF_FILE Environment Variable on Solaris................................. 223 Manually Configure the OneView Monitor GUI on UNIX/Sun Java System 6.0................. 224 Set JRE in PATH Variable Before Uninstalling Any SiteMinder Component .................... 226

Chapter 5: Post-installation, SOA Agent for Web Servers 227 Configure an IIS Web Agent.................................................................. 227

How to Configure an IIS Web Agent....................................................... 227 Configuration Notes for Web Agents on IIS 6.0 Servers..................................... 230

Configure a Sun Java System Web Agent...................................................... 235 Configuration Methods for Sun Java System Web Agents on Windows Systems............... 235 Configuration Methods for Sun Java System Web Agents on UNIX Systems .................. 240 Apply Changes to Sun Java System Web Server Files....................................... 244

Configure a SOA Agent for Apache Web Servers ............................................... 244 Configure an Apache Web Agent on Windows Systems ..................................... 245 Configuration Methods for Apache Web Agents on UNIX Systems ........................... 248 Add Entries to the httpd.conf File to Improve Server Performance........................... 252 Set the LD_PRELOAD Variable for Apache Agent Operation ................................. 253 Set the LD_ASSUME_KERNEL for Apache Agent on SuSE Linux 9 for zSeries ................. 255 Enabling SHLIB Path for an Agent on Apache 2.0/HP-UX 11................................. 256 Modify the http.conf File for Apache Reverse Proxy Server .................................. 256

Configure a SOA Agent for Domino Web Servers............................................... 257 Configure a Domino Web Agent on Windows Systems ...................................... 258 Configuration Methods for Domino Web Agents on UNIX Systems ........................... 260

How to Configure Any Web Agent in Unattended Mode ......................................... 264 Prepare an Unattended Configuration ..................................................... 264 Run an Unattended Configuration ......................................................... 265

Reconfigure a Web Agent .................................................................... 266

Contents 9

How to Tune the Solaris 10 Resource Controls ................................................. 267 How to Set Up Additional Agent Components .................................................. 268 Troubleshooting a SOA Agent for Web Servers................................................. 269

Agent Start-Up/Shutdown Issues (Framework Agents Only) ................................ 269 Web Agent Start Up and Shut Down Issues (IBM HTTP Server) ............................. 270 Connectivity and Trusted Host Registration Issues ......................................... 270 Trusted Host Registration Fails............................................................ 271 No Connection From Trusted Host to Policy Server ......................................... 271 Host Registered, but the SMHost.conf file has been Deleted ................................ 272 General Installation Issues ............................................................... 272 One Installation Hangs During Multiple Installations on the Same System ................... 272 Installation Failure Log ................................................................... 273 Attempt to Access DMS Page Returns Error ................................................ 273 Configuration of Encryption Key for the Cryptographic Hardware Failed...................... 273 Web Agent Not Shown in Add/Remove Programs Control Panel ............................. 274 Netscape Browser Won't Open PDFs....................................................... 275 Adobe Acrobat Reader Won't Install on a Windows System ................................. 275 Error Message During Upgrade............................................................ 276 Web Server Starts but Web Agent Not Enabled ............................................ 276 smget Error Message When Web Server Starts............................................. 276 Reconfigured Web Agent Won't Operate ................................................... 277 Sun Java System Web Server Fails at Runtime............................................. 277 Apache Web Agent Issues ................................................................ 277 Domino Web Agent Not Enabled but the Web Server has Started............................ 278 Domino Agent Cannot Initialize When Local Configuration Mode is Used ..................... 278

Appendix A: Configuring the Policy Server for an International Environment 279 Policy Servers in an International Environment ................................................ 279 Important Planning Considerations Before Installing the Policy Server........................... 279

Policy Server User Interface Fields Supporting Multi-byte Characters ........................ 280 Policy Server Components Supporting Multi-byte Characters ................................ 281

Configure SiteMinder Data Stores Supporting International Characters .......................... 282 Configure an International SiteMinder Data Store in SQL Server ............................ 282 Configure an International SiteMinder Data Store in Oracle ................................. 282 Configure a Japanese User Store in SQL Server ............................................ 284 Configure a Japanese User Store in Oracle................................................. 285

Appendix B: Modified Environment Variables 287 Modified Windows Environment Variables ..................................................... 287 Modified UNIX Environment Variables ......................................................... 288


Appendix C: Settings Added to the Sun Java System Server Configuration 289 Additions for Sun Java System Server 6.0..................................................... 289 magnus.conf File Additions for Windows Platforms ............................................. 290 Code Added to the magnus.conf File on UNIX Platforms ........................................ 290 obj.conf File Additions for Windows Platforms.................................................. 291 obj.conf File Additions for UNIX Platforms ..................................................... 293 mime.types File Additions for Windows and UNIX Platforms .................................... 295 Check Agent Start-up with LLAWP ............................................................ 295

Appendix D: Configuration Changes to Web Servers with Apache Web Agent297 Library Path for the Web Server is Set for UNIX Systems....................................... 297 Set Library Path and Path for Oracle 10g Web Server Running in Apache 2.x Mode............... 298 Changes to the httpd.conf File................................................................ 299

Entries Added to DSO Support Section .................................................... 299 SmInitFile Entry Added................................................................... 301 Alias Entries Added ...................................................................... 302 AddHandler Entries Added for Traditional Agents ........................................... 304 Certificate Authentication Entries Added ................................................... 306

Agent Parameter Added for SSL Connections Using Apache 1.x Based Servers ................... 306

Appendix E: Environment Variables Added or Modified by the Web Agent Installation 307 Added or Modified Environment Variables ..................................................... 307

CA SOA Security Manager Introduction 11

Chapter 1: CA SOA Security Manager Introduction

This section contains the following topics:

CA SOA Security Manager Overview (see page 11) Authentication Methods (see page 19) Develop and Deploy CA SOA Security Manager Protected Web Services (see page 20) Authentication Service Models (see page 21) Sample Deployment Scenario (see page 28) Use Cases (see page 28)

CA SOA Security Manager Overview CA SOA Security Manager is a policy-based access management system for Service Oriented Architecture (SOA) environments. With CA SOA Security Manager, you can protect XML transaction-processing web services that are exposed to web service consumers through a URL.

For example, you can protect web services that are:

Implemented as a servlet or active server page (ASP) and exposed by a web server or an application server.

Implemented using the JAX-RPC binding and deployed on an IBM WebSphere Application Server

Exposed using the XML Firewall and web services proxy capabilities of the optional SOA Security Gateway

CA SOA Security Manager protects XML resources in much the same way as CA SiteMinder protects HTML resources, allowing entitlement data to be obtained from any layer of the XML message, depending upon the authentication and authorization needs of the back-end applications.

Note: CA SOA Security Manager is based on the CA SiteMinder access control platform, utilizing XML-enabled versions of the CA Policy Server and CA SiteMinder Web Agents. Therefore, this guide assumes familiarity with CA SiteMinder administration and policy design.

CA SOA Security Manager Overview


CA SOA Security Manager Features

The following CA SOA Security Manager features enable you to flexibly implement secure web services:

Support for several leading web and application servers.

Optional SOA Security Gateway filters XML traffic according to a set of configurable security rules and can be deployed in the network DMZ (De-Militarized Zone) to provide XML Firewall functionality.

Transport-level and content-level authentication schemes for message authentication without user intervention.

Fine-grained access control model that allows authorization policies to be based on information at any layer of the XML message (transport, envelope, or payload—body of the message).

Full support for generation and consumption of WS-Security (Web Services Security) SOAP headers containing Security Assertion Markup Language (SAML) assertion, X.509v3 certificate, or password digest security tokens, allowing authentication and authorization information to be passed securely between multiple Web services.

Support for generation and consumption of SAML Session Ticket assertions (which contain an encrypted session ticket and a public key for synchronized sessioning), allowing authentication and authorization information to be passed securely between multiple Web services within a Policy Server domain.

CA SOA Security Manager SDK provides two APIs:

– Web Service Client API—A Java API that greatly simplifies the task of creating Web service consumer applications.

– SOA Agent Content Helper API—Java and C++ APIs that allow you to create XML-enabled custom agents.



CA SOA Security Manager Benefits

CA SOA Security Manager provides numerous benefits.

Shared security services and policy management

Centralized, policy-based authentication and authorization, profile management, and auditing services. CA SOA Security Manager leverages SiteMinder infrastructure, so the same policy server can manage policies for web applications and web services.

Integration of Web services frameworks and environments

Single platform to securely manage a wide variety of web services environments. Support for market-leading web servers, application servers, and SOA Access Points as well as custom and federated environments.

Secure document-based federation

WS-Security support allows business partners to securely communicate through XML documents used to request and obtain Web services.

Industry-standard content-level authentication schemes

Support for user credentials embedded in the body and headers of XML documents (raw or SOAP-wrapped), XML Digital Signatures, and SAML assertions.

Fine-grained access control

Allows for authorization policies based on information provided at any layer of the XML message (transport, envelope, or payload).

Seamless integration with existing CA SiteMinder enabled sites

Provides single sign-on between web sites and web services through a common agent framework.

CA SOA Security Manager Architecture and Components

CA SOA Security Manager is built on the CA SiteMinder infrastructure, using SOA Agents, the SOA Security Gateway, and the CA SiteMinder Policy Server to protect web service resources hosted on web and application servers.



The following illustration shows a simple CA SOA Security Manager environment in which a SOA Agent is deployed into a web or application server that is hosting web services.

SOA Security Manager Policy

Server

Web Services

Web or App. Server

SOA Agent

Server Process

Web Service Consumer

Request

The following illustration shows a simple CA SOA Security Manager environment in which a SOA Security Gateway is deployed in front of web or application servers hosting web services.

Web or App. Server

User Credentials


Request

SOA Security Manager Policy

Server

SOA Security Gateway

Web Services

Web or App. Server

Web Services

Web or App. Server

Web Services



More complex architectures can also be configured to support multiple web service implementations or SOA Security Gateway implementations where SOA Agents are optionally deployed on web service endpoints to provide an additional layer of security.

CA SOA Security Manager Policy Server

The CA SOA Security Manager Policy Server provides a centralized, policy-based management platform. CA SOA Security Manager uses the same Policy Server as CA SiteMinder, with a set of extensions designed to support CA SOA Security Manager functionality. The Policy Server integrates with CA SOA Security Manager SOA Agents (including the SOA Security Gateway) as well as other CA Minder products and Agent types to provide a single platform for securely managing every aspect of a company’s business.

The Policy Server hosts the set of shared services delivered as part of the CA SOA Security Manager solution. Its extensible and scalable architecture allows services to be added and enhanced as the security and management needs for Web services evolve.

The Policy Server integrates with industry-standard Lightweight Directory Access Protocol (LDAP) implementations as well as relational database systems for centralized management of user identity and entitlement information. This information is used by the Policy Server for authentication and authorization.

SOA Agents

CA SOA Security Manager provides SOA Agents to protect web services deployed on web servers and application servers.



SOA Agent for Web Servers

The CA SOA Security Manager SOA Agent for Web Servers is an XML-enabled version of the CA SiteMinder Web Agent. It can integrate with the following components:

A web server to authenticate and authorize requests for access to web services bound to URLs served by that web server.

A proxy server that handles requests for an application server to authenticate and authorize requests for access to web services hosted by the application server but associated with URLs served by the proxy server.

Note: This approach is recommended only for basic proxy scenarios requiring authentication and authorization and to support for upgraded TransactionMinder deployments that use it. For more advanced use cases requiring XML firewall and routing capabilities, CA recommends that you use the CA SOA Security Gateway, which works as a web services proxy and also provides advance routing and XML firewall capabilities

The SOA Agent recognizes requests that meet the following criteria as web service requests to be handled by CA SOA Security Manager:

Agent action—POST; all XML message requests are POSTed. However, CA SOA Security Manager also provides two other agent actions, ProcessSOAP and ProcessXML, that allow you to create rules that fire for POSTed requests according to the XML message format.

Message MIME type—text/xml by default; configurable using the XMLSDKMimeTypes Agent parameter.

All other requests are handled using the core Web Agent functionality of the SOA Agent, allowing you to also to protect other resources on a web server, if you have purchased CA SiteMinder.

Note: For more information about protecting web resources using CA SiteMinder, see the CA SiteMinder Agent Guide.

SOA Agent for Application Servers

The CA SOA Security Manager SOA Agent for Applications Servers is a container-native for J2EE application servers that can be used to authenticate and authorize requests for JAX-RPC resources hosted on the IBM WebSphere Application Server.



The SOA Agent recognizes requests that meet the following criteria as web service requests to be handled by CA SOA Security Manager:

Agent action—POST; all XML message requests are POSTed. However, CA SOA Security Manager also provides two other agent actions, ProcessSOAP and ProcessXML, that allow you to create rules that fire for POSTed requests according to the XML message format.

Message MIME type—text/xml by default; configurable using the XMLSDKMimeTypes Agent parameter.


The CA SOA Security Gateway is an XML gateway that manages XML traffic, protecting XML applications from malicious attack and from unauthorized access. Its XML Security Acceleration engine offloads security processing from web services applications and ensures optimum performance and throughput.

A SOA Security Gateway deployment includes the following components:


SOA Security Gateway Management Console

SOA Security Gateway Configuration Manager

The SOA Security Gateway Configuration Manager provides a web service interface to its back-end policy storage. The polices themselves can be stored in an XML file, a directory server, a relational database, or an XML database. The SOA Security Gateway Configuration Manager acts as the sole interface to the underlying policy storage system.

Both the SOA Security Gateway and the SOA Security Gateway Management Console communicate with the SOA Security Gateway Configuration Manager (to update and retrieve polices) using SOAP over an authenticated HTTP(S) connection.

The SOA Security Gateway also provides SOA Agent functionality, allowing it to authenticate and authorize XML requests against the CA SOA Security Manager Policy Server.

Note: When planning and implementing CA SOA Security Manager security policies, consider the SOA Security Gateway as being the functional equivalent of a SOA Agent. Unless otherwise noted, diagrams and descriptions in this guide that refer to a SOA Agent also apply to the SOA Security Gateway.



CA SOA Security Manager SDK

CA SOA Security Manager includes a software development kit to enable the extension of SOA Agent capabilities and to facilitate easier development of Web service consumer applications. The SDK includes two packages

Web Service Client Toolkit

A Java API to help develop client applications to generate and post XML messages to Web services. Provides methods for:

Generating and adding digital signatures

Wrapping with a Simple Object Access Protocol (SOAP) envelope

Posting messages over HTTP and HTTPS.

The Web Service Client Toolkit also includes a sample Java application that can help test the Web service implementation.

SOA Agent Content Helper API

Enables development of custom SOA Agents.

Note: For more information about the CA SOA Security Manager SDK, see the CA CA SOA Security Manager Developer’s Guide.

CA SOA Security Manager Web Service Request Processing

CA SOA Security Manager supports content-level, XML-based security. The following illustration illustrates the flow of data in a simple, single web service implementation secured with CA SOA Security Manager.

Protected Web

Service

Policy Server

Web or App. Server

SOA Agent


(1)

(2)

(3)

(4)

(5)

Internet

Server

Authentication Methods


The data in the previous illustration flows as follows:

1. A web service consumer (client) application creates a web service request in the form of an XML document and sends it to the web service provider site. An example document could be a purchase order. Credentials and authorization entitlements can be inserted in the message envelope or message body.

2. At the web service provider’s site, the SOA Agent intercepts the request, based on its action and content type in the HTTP header, as shown in the following XML sample:

POST /CreditRating HTTP/1.1

Content-Type: text/xml

Content-Length: nnnn

SOAPAction:“someURI:CreditRating#GetCreditRating"

<SOAP-ENV:Envelope>



</SOAP-ENV:Envelope>

3. The SOA Agent gathers the sender’s credentials from the XML message and passes this information to the CA Policy Server for authentication and authorization.

4. The authorized message is passed on to the back-end business application for processing.

5. The back-end application optionally returns a response to the web service requester with the status of the payload (for example, indicating that the purchase order has been accepted and is being processed).

Authentication Methods Authentication schemes that require user intervention are generally not appropriate for securing web services. CA SOA Security Manager provides four transport-level and message-level authentication schemes that do not require user intervention.

XML Document Credential Collector

Validates XML messages using credentials gathered from the message itself by mapping fields within the document to fields within a user directory.

XML Digital Signature

Validates XML documents digitally signed with valid X.509 certificates.

Develop and Deploy CA SOA Security Manager Protected Web Services


WS-Security

Validates XML messages using credentials gathered from WS-Security headers in a message’s SOAP envelope.

CA SOA Security Manager can produce and consume WS-Security tokens. This enables you to use the WS-Security authentication scheme to deploy a multiple-web service implementation across federated sites.

SAML Session Ticket

Validates XML messages using credentials obtained from CA SOA Security Manager synchronized-sessioning SAML assertions (which contain an encrypted combination of a CA SOA Security Manager session ticket and a CA SOA Security Manager user’s public key) placed in a message’s HTTP header, SOAP envelope, or a cookie.

CA SOA Security Manager can generate and consume SAML Session Ticket assertions. This enables you to use the SAML Session Ticket authentication scheme to deploy a multiple-web service implementation within a single Policy Server domain.

Deciding which authentication scheme or schemes you intend to use to secure your web services is integral to how you design and implement your web services and is best made as part of the broader context of choosing an authentication service model.

More information:

Authentication Service Models (see page 21)

Develop and Deploy CA SOA Security Manager Protected Web Services

To develop a web service implementation protected with CA SOA Security Manager you need to:

1. Determine how many web services, locally or at federated sites, will be used to perform the required functionality.

2. Choose an authentication service model by determining:

How security information is to be obtained from a request and, in a multiple-web service environment, how that information is to be passed between web services.

In a multiple-web service environment, the flow of data between web services.

Authentication Service Models


3. For each web service in your web service implementation:

a. Define the service interface. The simplest form of interface for a web service can be specified as a set of XML schemas. These schemas dictate the type of XML document to be sent to the web service and what type of document the sender can expect in return.

b. Build the web service implementation to accommodate an incoming XML document of the type specified in the interface and turn that XML document into a meaningful set of calls to the integrated back-end systems the web service exposes.

c. Deploy your web service implementation on a web or application server using a supported SOAP binding:

Document literal (web servers)—XML Payload is sent to directly to a web service bound to a URL. The interface in this case is defined by XML Schema. For example, a purchase order XML payload is sent to a purchasing web service.

RPC-based (application servers)—Interface is defined by WSDL and the SOAP request message contains the operation name and input parameters. For example, a balance transfer request is sent to a banking web service with operation name and input parameters (account details and amount to transfer).

d. Configure CA SOA Security Manager policies from the web service WSDL file to determine how the SOA Agent should authenticate, authorize, and process the XML message before it passes it onto the web service implementation for handling.

Once it receives a message from the SOA Agent, the web service should return an applicable XML response to the calling web service consumer application or the next.

Authentication Service Models The ability of CA SOA Security Manager to obtain security information from XML documents without user interaction and produce WS-Security headers, SAML Session Ticket assertions, and SiteMinder session cookies enables you to securely deploy web services using a number of service models.

Single-step Authentication Service Model

All requests are authenticated and handled by a single web service.

Multistep Authentication Service Model

All requests are sent to a web service responsible for authentication, which then returns the message and authentication data back to the web service consumer. The web service consumer application can then send requests containing this authentication data to other related web services within or across domains.



Chain Authentication Service Model

All requests are received by a web service responsible for authentication and then passed, with authentication data, on to one or more other web services for handling. That is, message and authentication data always flows from the authentication web service directly to the next required web service, and from there to the next web service and so on, without further interaction from the web service consumer.

Choosing the appropriate authentication service model is the first, and probably most significant, decision you must make when designing a web service implementation. Your choice of service model also plays a significant role in determining the most appropriate CA SOA Security Manager authentication schemes to use.

Single-Step Authentication Model

The single-step service model is the simplest possible model for web services—requests from a web service consumer are authenticated and handled by a single web service.


Policy Server

Web or App. Server

SOA Agent

Web ServiceRequest

Authentication

Appropriate authentication schemes for use in the single-step authentication model are:

XML Document Collector Authentication Scheme

XML Digital Signature Authentication Scheme



Multistep Authentication Model

The Multistep authentication model is like the CA SiteMinder cookie-based single sign-on implementation, in which WS-Security headers or SAML Session Ticket assertions take the place of the cookie.

In the multistep authentication model, a single web service is responsible for authenticating all incoming web service requests. This authentication service verifies a web service consumer’s identity and returns an XML message with authentication data in the form of WS-Security headers or a SAML Session Ticket assertion. The web service consumer can then use this to add to subsequent requests to facilitate authentication by other associated web services.

The process that the web service consumer goes through when making a request has two phases:

Obtaining the authentication data

Using the authentication data to access other web services

The following illustration shows the multistep authentication service model.

Policy Server

3

1

XML message +authentication data

2

Server

Server

SOA Agent

Web Service

SOA Agent

Web Service

4

Web Service Consumer Authentication

Server

SOA Agent

Web Service

5Further requests authenticated

using authentication data provided by original Policy

Server

XML message request

New request +authentication data

New request +authentication data

...



1. The web service consumer sends a request for access to a protected web Service in the form of an XML document.

2. The SOA Agent receives the request, extracts credentials and passes them to the Policy Server, which authenticates the Web service request with an appropriate authentication scheme.

After authentication, the request goes through the authorization process. A response attribute associated with the authorizing policy causes the Policy Server to generate a response which it sends to the SOA Agent, instructing it to return authentication data to the Web service

3. The Web service returns the authentication data back to the Web service consumer (typically in an XML document, but synchronized sessioning SAML assertions can also be returned in HTTP headers or a cookie).

4. For subsequent requests, the Web service consumer passes XML messages that include the authentication data it received from the authentication service to other associated Web Services.

5. The requests are allowed access without having to reauthenticate because of the authentication data supplied with the request message (in effect, providing single sign-on).

Appropriate authentication schemes for initial authentication by the authentication web service in the multistep authentication model are:



The authorizing policy for the authentication web service should trigger one of the following response types:

WS-Security Responses (appropriate for web services protected by more than one policy store, or at multiple sites)

SAML Session Ticket Responses (appropriate for web services protected by the same policy store)



These responses instruct the SOA Agent to pass authentication data in the form of WS-Security headers or SAML Session Ticket assertions (as appropriate) back to the web service consumer for use in requests to associated web services. The associated web services should be protected using the corresponding authentication scheme:

WS-Security Authentication Scheme

SAML Session Ticket Authentication Scheme

Note: SOA Agents can be configured to accept information from a SiteMinder session (SMSESSION) cookie in the HTTP header of a request as a means of authenticating a client and always add such cookies to request headers upon successful authentication and authorization. SiteMinder session cookies can therefore be used to implement multistep authentication within all-SiteMinder/SOA Security Manager environments.

Chain Authentication Service Model

The chain authentication model is appropriate for solutions that require XML messages to flow between multiple web services without further intervention from the requesting web service consumer.

In the chain web service model, a single web service is responsible for authenticating all incoming web service requests. This authentication service verifies a web service consumer’s identity, then adds authentication data in the form of WS-Security headers or a SAML Session Ticket assertion to the XML message. It then passes the document to downstream web services for processing.



The following illustration shows the flow of data in the chain authentication model.

Policy Server

51

32

4

XML message request

response

Web/App. Server Web/App. Server

SOA Agent

Web Service

SOA Agent

Web Service


XML message +authentication

data

XML message +authentication

data

...

1. The web service consumer sends a request for access to a protected web Service in the form of an XML document.

2. The SOA Agent receives the request, extracts credentials and passes them to the Policy Server, which authenticates the web service request with an appropriate authentication scheme.

3. After authentication, the request goes through the authorization process. A response attribute associated with the authorizing policy causes the Policy Server to generate a response which it sends to the SOA Agent, instructing it to return authentication data to the authentication web service.

4. The authentication web service sends the XML message and authentication data to the next web service downstream.

5. Downstream web services are configured so that each passes the XML message and authentication data to the next web service in the chain. The requests are allowed access without having to re-authenticate because of the authentication data supplied with the request message.

The most appropriate authentication schemes for initial authentication of requests from the web service consumer by the authentication web service in the chain authentication model are:





The authorizing policy for the authentication web service should trigger either:

WS-Security Responses (appropriate for web services protected by more than one policy store, or at multiple sites)

SAML Session Ticket Responses (appropriate for web services protected by the same policy store)

These responses instruct the SOA Agent to add either WS-Security headers or SAML Session Ticket assertions (as appropriate) to the XML request passed to the next downstream web service in the chain, which should then be protected using the corresponding authentication scheme:

WS-Security Authentication Scheme

SAML Session Ticket Authentication Scheme

Note: SOA Agents can be configured to accept information from a SiteMinder session (SMSESSION) cookie sent in the HTTP header of a request as a means of authenticating a client and always add such cookies to request headers upon successful authentication and authorization. SiteMinder session cookies can therefore be used to implement chain authentication within all-SiteMinder/SOA Security Manager environments.

Sample Deployment Scenario


Sample Deployment Scenario The following diagram shows a sample deployment scenario for CA SOA Security Manager.

Use Cases This section contains sample CA SOA Security Manager protection use cases.

Use Cases


SSO From SiteMinder-protected Portal to Web Service Use Case

The following diagram shows an example of how SOA Security Manager could be deployed in conjunction with a SiteMinder-protected portal to protect resources using web single sign-on.

Chained Web Service Request Use Case

The following diagram shows an example of how SOA Security Manager could be deployed to protect a chain web service request.

Use Cases


Multitep Web Service Request Use Case

The following diagram shows an example of how SOA Security Manager could be deployed to protect a multistep web service request

Prepare for Your Install 31

Chapter 2: Prepare for Your Install


Policy Server Install Preparation (see page 31) SOA Agent for Web Servers Install Preparation (see page 42) SOA Agent for IBM WebSphere Install Preparation (see page 52) SOA Security Gateway Install Preparation (see page 54) Scripting Interface for Perl (see page 56) Preconfiguring Policy Objects for SOA Agents (see page 56)

Policy Server Install Preparation Before you install a CA SOA Security Manager Policy Server, there are a number of pieces of information you will need and requirements that must be met.

For a list of supported operating systems, Java environments, and prerequisite CA product versions, see the CA SOA Security Manager Platform Matrix at https://support.netegrity.com.

Note: If you are upgrading an existing CA Policy Server installation, see also the CA eTrust SiteMinder Upgrade Guide.

Note: Topics relating to the CA SOA Security Manager Policy Server throughout this book extensively refer to SiteMinder and the SiteMinder Policy Server. This is because CA SOA Security Manager uses the same Policy Server as CA SiteMinder, with a set of extensions designed to support CA SOA Security Manager functionality and many of the topics within this document

Prepare to Install a Policy Server on Windows

The following topics describe things you should be aware of and system requirements that must be met before installing a CA SOA Security Manager Policy Server.

https://support.netegrity.com/


Policy Server Install Preparation


Before You Begin

Be aware of the following before installing the Policy Server:

To install the Policy Server, you must log into a Windows account with local administrator privileges.

(IBM Directory Server only) If you are using IBM Directory Servers in your SiteMinder environment, edit the V3.matchingrules file by adding the following line:

MatchingRules=(2.5.13.15 NAME ‘integerOrderingMatch’ SYNTAX

1.3.6.1.4.1.1466.115.121.1.27

The Directory store will not be configured correctly and the necessary SiteMinder objects will not be created if the V3.matchingrules file does not contain the change.

Install the documentation.

System Path Length - The Policy Server installation fails if the system path length exceeds 1024 characters (including or excluding the SiteMinder added directories). For best results, trim the pre-SiteMinder system path to approximately 700 characters.

The 6.x Policy Server does not configure Microsoft Access as the default policy store as with previous SiteMinder releases. Access is not supported as a policy store.

Make sure that the Sun Java System or IIS Web server instance is stopped to allow the installation program to configure the Policy Server User Interface.

To avoid possible policy store corruption, ensure that the server on which the policy store will reside is configured to store objects in UTF-8 form. For more information on configuring your server to store objects in UTF-8 form, see the documentation for that server.

The Policy Server and Documentation installations each modify environment variables.

More Information:

Modified Windows Environment Variables (see page 287)



System Requirements

The Policy Server on Windows requires an Intel Pentium III or better.

Before you install the Policy Server, make sure you are using a supported operating system and third-party software. For a list of supported operating systems, Web Servers, databases, Web browsers, LDAP Directory Servers, and servlet engines, go to the Technical Support site and search for the CA SOA Security Manager Platform Matrix for r12.

Note: For Internet Explorer 5.5, make sure you have SP2 since SP1 cannot post data greater than 4072 bytes.

In addition, make sure you have the following components installed on your computer:

Memory: 128 MB system RAM (minimum).

Hard disk space: 250 MB free disk space in the install location, and 180 MB of free space in the system’s temporary file location. These requirements are based on a medium size policy database (about 1,000 policies).

Screen resolution: 800 x 600 or higher resolution with 256 colors or better to properly view the Policy Server User Interface. Netscape browsers running on a display with less than 256 colors cannot properly display the Policy Server User Interface.

JRE: Make sure you have the required JRE version. For the required version, search for the CA SOA Security Manager Platform Matrix for r12 on the Technical Support site. You can download the latest version at the Sun Developer Network (SDN).

Note: To run the OneView Monitor user interface, make sure you have the required Java SDK and Servlet Exec/ISAPI for Windows. For the required versions, search for the SiteMinder Platform Matrix for 6.0 on the Technical Support site. You also need ServletExec for JSP Password and Registration Services.



http://java.sun.com/





Install the Policy Server Documentation

You install the documentation separately using nete-sm-doc-6.0-sp5-cr008-win32.exe because it is not installed by default with the Policy Server. We recommend that you install the documentation before the Policy Server.

To install the Policy Server documentation

1. Exit all applications that are running.

2. Insert the CA SOA Security Manager DVD into the drive or download the software archive (soasm-r12.0-win32.zip) from the Technical Support site and then extract it.

3. Run the Documentation setup program:

a. Navigate to the PolicyServer folder.

b. Double-click nete-sm-doc-6.0-sp5-cr008-win32.exe.

4. In the Introduction dialog box, read the welcome message and click Next.

5. Read the Software License Agreement, accept the terms if you agree, and click Next.

6. Read the Installation Notes, then click Next.

7. In the Choose Install Folder dialog, select the location where you want the documentation installed. The default is C:\Program Files\Netegrity\netegrity_documents.

8. In the Choose Shortcut Folder dialog, select one of the following to create product icons.

In a new Program Group

The install program configures a SiteMinder program group in the Start, Programs menu.

In an existing Program Group

The install program configures a SiteMinder program group in an existing group.

Example: Start, Programs, Accessories.

In the Start Menu

The install program configures a program icon in the Windows Start menu.

On the Desktop

The install program configures a SiteMinder program icon on the Windows desktop.

In the Quick Launch Bar

The install program configures a SiteMinder program icon in the Quick Launch bar.





Other

The install program configures a SiteMinder installation directory in the specified directory.

Don’t create icons

The install program does not configure SiteMinder icons.

9. Review the settings in the Pre-Installation Summary dialog box, then click Install.

The installation program begins copying files to your system. This may take a few minutes.

10. After the installation is complete, click Done.

If you have installed the documentation after installing the Policy Server, you must create the netegrity_docs virtual directory on the Web server. This directory lets you view the documentation using the Policy Server User Interface. You can run the Policy Server Configuration Wizard to create the directory, or you can manually create it for IIS 5.0/6.0.

Prepare to Install a Policy Server on UNIX

The following topics describe things you should be aware of and system requirements that must be met before installing a CA SOA Security Manager Policy Server.

When you install the Policy Server on a UNIX system, you can choose to install the SiteMinder policy store (a repository of policy information) in a Sun Java System (formerly Sun One/iPlanet) LDAP Directory Server or Active Directory Application Mode. For other LDAP versions--CA eTrust Directory, Novell, Microsoft Active Directory, Oracle Internet Directory, IBM Directory Server--or for relational database such as SQL Server and Oracle, you need to manually configure them as a policy store after installation. These manual steps are outlined in this guide.

Audit logs can be stored in either an ODBC database (SQL Server or Oracle) or a text file. After you install the Policy Server, audit logging is set to a text file and not to ODBC by default.



System Requirements

Before you install the Policy Server, make sure you are using a supported operating system and third-party software. For a list of supported operating systems, Web Servers, databases, Web browsers, LDAP Directory Servers, and servlet engines, go to the Technical Support site and search for the SiteMinder Platform Matrix for 6.0.

Make sure you have the following components installed on your machine:

Memory: 128 MB RAM

Free disk space: 300 MB free disk space, and 200 MB free disk space in /tmp.

Note: Typically, 10 MB or less free disk space in /tmp is required for the daily operation of the Policy Server. The Policy Server creates files and named pipes under /tmp. The path to which these files and pipes are created cannot be changed.

Screen resolution: 800 x 600 or higher resolution with 256 colors or better to properly view the Policy Server User Interface. Web browsers running on a display with less than 256 colors cannot properly display the Policy Server User Interface.

JRE: Make sure you have the required JRE version installed. For the required version, search for the SiteMinder Platform Matrix for 6.0 on the Technical Support site. You can download the latest JRE version at the Sun Developer Network (SDN).

Note: To run the OneView Monitor user interface, you need the required version of Java SDK and ServletExec/AS for UNIX installed. For the required versions, search for the SiteMinder Platform Matrix for 6.0 on the Technical Support site. You also need ServletExec for Password and Registration Services.








Support Considerations for Solaris 10

Consider the following when planning to run one or more Policy Server instances in a Solaris 10 environment:

Running a Policy Server in either the global zone, the sparse-root non-global zone, or the whole-root non-global zone is supported.

Running multiple parallel Policy Server instances in their respective non-global zones is supported.

Note: Running multiple parallel instances in both the global and non-global zones is not supported.

Sparse-root zones optimize physical memory and disk space usage by sharing configuration files and the binaries in the /usr and /lib directories. Sparse-root zones also have private file areas for directories, such as /etc and /var.

Whole-root zones increase configuration flexibility, but increase resource usage because they do not share directories.



Before You Begin

Before you install the Policy Server, complete the following procedures, if applicable:

Create a new UNIX account (see page 39).

Modify the UNIX system parameters (see page 39), if necessary.

Unset the localization variables (see page 40), if necessary.

Install the documentation.

(IBM Directory Server only) If you are using IBM Directory Servers in your SiteMinder environment, edit the V3.matchingrules file by adding the following line:


1.3.6.1.4.1.1466.115.121.1.27

The Directory store will not be configured correctly and the necessary SiteMinder objects will not be created if the V3.matchingrules file does not contain the change.

Stop the Sun Java System Web server instance to allow the installation program to configure the Policy Server User Interface.

Trim the pre-SiteMinder system path to approximately 700 characters. The Policy Server installation fails if the system path length exceeds 1024 characters, including or excluding the directories SiteMinder adds.

Note: The Policy Server and Documentation installations each modify environment variables.

More information:

Modified UNIX Environment Variables (see page 288)



Create a New UNIX Account

Create a new UNIX account named smuser with the default shell as ksh. You may also need to modify the profile for the smuser account, as indicated later in this chapter.

You should install the Policy Server using the smuser UNIX account, but do not configure the Sun Java System or Apache on Linux Web Server for the Policy Server User Interface or the OneView Monitor GUI because the installer modifies the Web server's configuration files and smuser does not have the appropriate root privileges. Thus, when you run the policy server installer, do not select to modify the Web server.

After the Policy Server installation is complete, run the Policy Server Configuration Wizard (located in <siteminder_installation>\install_config_info\nete-ps-config.bin) as root to configure the Policy Server User Interface or the OneView Monitor GUI.

UNIX System Parameters

When the Policy Server is placed under load, it opens a large number of sockets and files. This can become a problem if the default limit parameters are not appropriate for the load.

To view the default limit parameters, type ulimit -a. The system displays a message similar to the following:

$ ulimit -a

time(seconds) unlimited

file(blocks) unlimited

data(kbytes 2097148

stack(kbytes) 8192

coredump(blocks) unlimited

nofiles(descriptors) 256

vmemory(kbytes) unlimited



The nofiles parameter is set to 256 in this example. This is the total number of files (sockets + files descriptors) that this shell and its descendants have been allocated. If this parameter is not set high enough, the Policy Server returns numerous socket errors. The most common socket error is 10024, or too many open files. You must increase this parameter value for proper Policy Server operation under load. You can change this value by running the ulimit -n command. For example, to set nofiles to 1024, place the ulimit -n 1024 command in the .profile or smprofile.ksh of the smuser account. The Policy Server is bound by the nofiles parameter within smuser's ulimit for the number of connections to it.

Note: On HP-UX systems, prior to the Policy Server installation, check your .profile file for a set +u option. If it has a set -u option, do a set +u to nullify it. A setting of set -u will cause a problem when the installation sets a SHLIB_PATH for smuser.

Localization Requirement

Use of the LC_* environment variables for localization is not permitted.

If the LC_* variables are set by default, they must be unset in the .profile or smprofile.ksh files of the smuser account.

The LANG environment variable should also be unset. To unset the variable, add the unset LANG command to the smprofile.ksh file.



Install the Policy Server Documentation

For 6.x, you must install the documentation separately using the documentation installation program because it is not installed by default with the Policy Server. We recommend that you install the documentation before the Policy Server.

To install the Policy Server documentation

1. Log in as smuser or as the user who installed the Policy Server.

Note: This UNIX user should have sufficient privileges to modify the Web server’s and ServletExec’s configuration files since the installer modifies these files to configure the Policy Server User Interface and the OneView Monitor.

2. Insert the CA SOA Security Manager DVD into the drive or download the software archive (soasm-r12.0-sol.zip) from the Technical Support site and then extract it.

3. Run the Policy Server documentation installer in GUI or console as described in the following sections.

Note: Depending on your permissions, you may need to add executable permissions to the install file by running the following command:

chmod +x nete-sm-doc-6.0-sp5-cr008-sol.bin

To use the GUI mode

1. Open a command window and navigate to where the install program is located (/PolicyServer).

2. Enter:

sh ./nete-sm-doc-6.0-sp5-cr008-sol.bin

To use the console mode

1. Open a command window and navigate to where the install program is located (/PolicyServer).

2. Enter the following command:

sh ./nete-sm-doc-6.0-sp5-cr008-sol.bin -i console

Note: The -i console part of the command lets you run the installation in a console instead of a GUI.

3. To view the Introduction/License Agreement, press ENTER when prompted.

The installation script displays the License Agreement.

4. Enter y to agree to agree with the terms and continue the installation.

5. Read the Installation/Release Notes and press ENTER.



SOA Agent for Web Servers Install Preparation


6. Enter the installation directory.

7. Review the Pre-Installation Summary and press ENTER to install the documentation.

The installation program installs the 6.x documentation in the directory you specified.

8. Press ENTER to exit the installer.

Also, you will need to run the Policy Server Configuration Wizard or manually edit the netegrity_docs virtual directory. The Policy Server Configuration Wizard can create this virtual directory.

SOA Agent for Web Servers Install Preparation The following topics describe things you should be aware of and system requirements that must be met before installing a SOA Agent for Web Servers.

Note: Topics relating to the SOA Agent for Web Server throughout this book extensively refer to the CA SiteMinder Web Agent. This is because the SOA Agent for Web Servers is an XML-enabled version of the SiteMinder Web Agent and therefore shares all its features and requirements.

Supported Operating Systems and Web Servers

Before you install a Web Agent, make sure you are using a supported operating system and web server configuration. For a list of SiteMinder Web Agents and supported web server platforms, go to Technical Support, and search for the SiteMinder 6.0 Platform Matrix.

Note: After you install the Web Agent, you can configure multiple Web Agent instances for each Sun Java System and Apache web server installed on your system.

http://support.netegrity.com/




Ensure the Policy Server is Installed and Configured

Before you install the Web Agent, the Policy Server must be installed and be able to communicate with the system where you plan to install the Web Agent.

Note: For instructions about configuring Agents at the Policy Server, see CA eTrust Policy Design. For Agent parameter descriptions, see the CA eTrust SiteMinder Web Agent Guide.

To centrally manage Agents, you must configure Policy Server with the following:

A SiteMinder Administrator that has the right to register trusted hosts.

A trusted host is a client computer where one or more SiteMinder Web Agents are installed. The term trusted host refers to the physical system. There must be an administrator with the privilege to register trusted hosts.

Note: To configure an administrator, see the CA eTrust Policy Design.

Agent identity

An Agent identity establishes a mapping between the name and the IP address of the Web Server instance hosting a Web Agent. You define an Agent identity from the Agents object in the Administrative UI. You assign it a name and specify the Agent type as a Web Agent.

The name you assign for the Agent is the same name you specify in the DefaultAgentName parameter for the Agent Configuration Object that you must also define to centrally manage an Agent.

Host Configuration Object

This object defines the communication between the trusted host and the Policy Server after the initial connection between the two is made.

A trusted host is a client computer where one or more SiteMinder Web Agents can be installed. The term trusted host refers to the physical system.

Do not confuse this object with the trusted host’s configuration file, SmHost.conf, which is installed at the trusted host after a successful host registration. The settings in the SmHost.conf file enable the host to connect to a Policy Server for the first connection only. Subsequent connections are governed by the Host Configuration Object.

Note: To read more about this object, see CA eTrust Policy Design.



Agent Configuration Object

This object includes the parameters that define the Web Agent configuration. There are a few required parameters you must set for basic operation described below.

Note: To read more about this object, see CA eTrust Policy Design.

For all Agents—the Agent Configuration Object must include a value for the DefaultAgentName. This entry should match an entry you defined in the Agents object.

The DefaultAgentName identifies the Agent identity that the Web Agent uses when it detects an IP address on its web server that does not have an Agent identity assigned to it.

For Domino Web Agents—the Agent Configuration Object must include values for the following parameters:

DominoDefaultUser—if the user is not in the Domino Directory, and they have been authenticated by SiteMinder against another user directory, this is the name by which the Domino Web Agent identifies that user to the Domino server. This value can be encrypted.

DominoSuperUser—ensures that all users successfully logged into SiteMinder will be logged into Domino as the Domino SuperUser. This value can be encrypted.

For IIS Web Agents—the Agent Configuration Object may need to include values for the DefaultUserName and DefaultPassword parameters.

The DefaultUserName and DefaultPassword identify an existing NT user account that has sufficient privileges to access resources on an IIS web server protected by SiteMinder. When users want to access resources on an IIS web server protected by SiteMinder, they may not have the necessary server access privileges. The Web Agent must use this NT user account, which is assigned by an NT administrator, to act as a proxy user account for users granted access by SiteMinder.

Note: If you plan to use the NTLM authentication scheme, or enable the Windows User Security Context feature, do not specify values for these IIS Web Agent parameters.



Gather information Needed to Complete the Agent Installation

You must have the following information before installing the Web Agent:

Name of the SiteMinder Administrator allowed to install Agents

Name of the Host Configuration Object. This defines the trusted host configuration.

Name of the Agent Configuration Object, which contains the Agent configuration settings. A single Agent Configuration Object can be referenced by many Agents.

Install the Correct Agent for a Web Server

Install the following Web Agents with the corresponding web servers:

Web Agent Web Server

IIS Microsoft IIS

Domino IBM Lotus Domino

Sun Java System Sun Java System

Apache Apache, Covalent FastStart, Covalent Enterprise Ready Server, HP-based Apache, IBM HTTP, Oracle HTTP Server, Stronghold

Most of the information for the Apache web server applies to these web servers.

For details on web server and operating system versions, go to Technical Support, and search for the SiteMinder Platform Matrix for 6.0.

Install an Apache Web Server on Windows as a Service for All Users

The Web Agent Configuration Wizard will not detect a valid Apache installation if the Apache web server is installed for an individual user.

When you install an Apache web server, select the option to "install as a service, available for all users " so during configuration, the SiteMinder Web Agent can detect the existing web server on a user’s system.

Installing the Apache Web Server with the option "manual start, for current user only" allows the Web Agent to be installed; however, because the Configuration Wizard cannot detect the Apache web server, the Web Agent cannot be configured for the server.






How to Use a Non-Default IIS website

SiteMinder requires IIS to have a default website for proper installation. By default, this site exists when you install an IIS web server.

If you install the Agent on IIS and for some reason the default website does not exist (check the Internet Services Manager), or you wish to install the SiteMinder virtual directories on a different IIS website, you need to edit the Metabase.

Use the following process to edit the metabase:

Go to Technical Support and search for a technical note that describes the needed changes. To find the note:

1. Go to the main Support page.

2. Search for the document titled METABASE -3 Error.

The documents are listed in alphabetical order.

Note: The Default website must be the original one that was installed with IIS. You cannot rename it without risk of the Metabase -3 Error.

Miscellaneous Web Server Preparations

The following sections discuss installation preparations for various web servers.

Required AIX Patches

Before installing a Web Agent on an AIX machine with an IBM HTTP server, you must install the patches listed in the following table:

AIX Release Patch

5.2 libc version 5.2.0.50 or greater

You can check the patch list by logging in as root and executing the instfix -i command.

Note: Before installing a Web Agent on an Apache 1.x Web Server/AIX system, be sure to apply IBM HTTP Server patch PQ87084.





Required HP-UX Patches

Before installing a Web Agent on an HP-UX 11i machine, you must install the patches listed in the table that follows. You can check the patch list by logging in as root and executing the swlist command.

HP-UX Release Patch

HP-UX 11i v1 PHCO_29029 is recommended for SiteMinder 6.0.4 and SiteMinder 6.0.5.

HP-UX 11i v1 PHSS_26560 ld and linker cumulative patch

IBM HTTP Server patch IBM PQ 71734 for IBM HTTP Server 1.3.19.4 and 1.3.19.5

Required Linux Patches

The following Linux patch is required.

Linux Release Patch

Linux 2.1 glibc-2.4.2-32.20 for Linux Application Server 2.1

Required Solaris Patches

The following Solaris patch is required.

Solaris Release Patch

Solaris 10 Daylight Savings fix for JVM 1.4.10 or above and 1.5.06 and above.



Required Linux Libraries

When installing a Red Hat Enterprise Linux version of a Web Agent, the following are required libraries:

On Red Hat Enterprise Linux 2.1, if using the "linux" kit (the kit built with GCC 2.96), there are no libraries required that are not part of a basic installation.

On Red Hat Enterprise Linux 3.0, use the "rhel30" kit (the kit built with GCC 3.2), and there are no libraries required that are not part of a basic installation.

On Red Hat Enterprise Linux 4.0, use the "rhel30" kit (the kit built with GCC 3.2). The following is required:

compat-libstdc++-33-3.2.3-<patch_version>.i386.rpm

General Preparations for All Web Agents

The following sections describe general preparations for all Web Agents.

IBM Hot Fixes for Domino 6.0.2 CF1 and CF2

The following are required for a Web Agent to run on Domino 6.0.2 CF1 or CF2:

Windows:

SPR# GFLY5NCKSM, KSPR5LDMLT, DMEA5MRKJH, PCHE5SBKGW, and SSAA5T7MXB, PCHE5UQRPJ

UNIX:

SPR# GFLY5NCKSM, KSPR5LDMLT, KGAI5RBKU6, DMEA5MRKJH, PCHE5SBKGW, and SSAA5T7MXB, PCHE5UQRPJ

IBM Hot Fix Required for Domino 6.5.2

IBM hot fix SPR #NORK632KQA is required for a Web Agent to run on a Domino 6.5.2 server.

This hotfix applies to Windows and UNIX platforms.



Set the DISPLAY For Web Agent Installations on UNIX

If you are installing the Web Agent on a UNIX system from a remote terminal, such as a Telnet or Exceed terminal, be sure the DISPLAY variable is set for the local system. For example, if your machine is 111.11.1.12, set the variable as follows:

DISPLAY=111.11.1.12:0.0

export DISPLAY

Note: You can also install the Web Agent using the console mode installation, which does not require the X window display mode.

Modify the Apache 2.0 httpd.conf File for Agents on IBM HTTP Servers

If an Apache 2.0 Web Agent is installed on an IBM HTTP Server 2.0.47 on Windows, the server does not load if the ibm_afpa_module is also loaded in the httpd.conf file.

To avoid this problem, comment out the following lines from the httpd.conf file: #LoadModule ibm_afpa_module modules/mod_afpa_cache.so

#AfpaEnable

#AfpaCache on

#AfpaPort 9080

#AfpaLogFile "D:/Program Files/IBM HTTP Server 2.0/logs/afpalog" V-ECLF

Enable Write Permissions for IBM HTTP Server Logs

If you install the Web Agent on an IBM HTTP Server v2.0.x, this web server gets installed as root and its subdirectories do not give all users in all groups Write permissions.

For the Low Level Agent Worker Process (LLAWP) to write Web Agent initialization messages to the web server logs, the user running the web server needs permission to write to the web server’s log directory. Ensure that you allow write permissions for this user.



Add a Logs Subdirectory for Apache Web Agents

For Apache Web Agents, a logs subdirectory must exist under the Apache server’s root directory so that the Web Agent can operate properly. This subdirectory must have Read and Write permissions for the user identity under which the Apache child process will be running.

If the logs subdirectory does not exist, create it with the required permissions.

Note: This configuration requirement applies to any Apache-based server that writes log files outside the Apache root directory.

Compile an Apache Web Server on a Linux System

For the Web Agent to operate with an Apache web server running Linux, you have to compile the server. Compiling is required because the Agent code uses pthreads (a library of POSIX-compliant thread routines), but the Apache server on the Linux platform does not, by default.

If you do not compile with the lpthread option, the Apache server starts up, but then hangs and does not handle any requests. The Apache server on Linux cannot initialize a module which uses pthreads due to issues with Linux's dynamic loader.

To compile Apache on Linux for the Web Agent

1. Enter the following:

LIBS=-lpthread

export LIBS

2. Configure Apache as usual by entering the folloiwng:

configure --enable-module=so --prefix=<your install target dir>

make

make install

Set Up DNS on AIX Platforms for Agent Operation

You can use nCipher cryptographic hardware with the Web Agent to encrypt the shared secret, which is an encryption key that secures traffic between the Agent and the Policy Server.



Prepare for Cryptographic Hardware Support (Optional)

You can use nCipher cryptographic hardware with the Web Agent to encrypt the shared secret, which is an encryption key that secures traffic between the Agent and the Policy Server.

Decide Whether to Implement Cryptographic Hardware

Before using nCipher cryptographic hardware, note the following:

Once SiteMinder has been configured to use cryptographic hardware modules, you cannot remove, disable, or reconfigure SiteMinder’s use of hardware encryption.

Use of hardware cryptography in your SiteMinder environment prevents unattended system failover — a passphrase must be supplied by an operator each time a cryptographic hardware-enabled Policy Server or Agent restarts.

Install nCipher on an Agent Web Server

Prior to registering you system as a Trusted Host, be sure the nCipher cryptographic hardware module and runtime software, including the PKCS11 library, is already installed on the same Web Server as the Agent. Read the nCipher installation documentation before attempting to install it in the SiteMinder environment.

Add a SiteMinder Agent User to nCipher UNIX Group (UNIX Only)

Before it can access the nCipher hardware the operating system user account must be a member of the nCipher UNIX group (typically nfast). Add the UNIX user account that you will use to install the Agent, to the nCipher UNIX group. See your nCipher documentation for more information on this UNIX group.

Collect nCipher Information

Have the following information prior to installing the Web Agent:

full path to the PKCS11 DLL

token label, if applicable

token passphrase

SOA Agent for IBM WebSphere Install Preparation


Fix Display Errors on Sun Java System with Cryptographic Hardware

If you install a Web Agent with cryptographic hardware support on an Sun Java System web server running Solaris or HP-UX, you may receive a display error when attempting to start the Web Server using the ./start command. This problem indicates that the DISPLAY environment variable is not set to direct the display to the desired machine.

To fix this problem, set and export DISPLAY in the shell before executing the ./start command. If the httpd server is not started manually from a shell, then the DISPLAY variable must be added to the start script or to an appropriate configuration file.

If DISPLAY is set correctly, the prompt for the pass phrase should display properly.

Note: The httpd process on the target machine must be able to access the DISPLAY. Run xhost + as the logged in user on the target machine to ensure it can.

Preserve Changes in the WebAgentTrace.conf File

If you have modified the WebAgentTrace.conf file and you are installing a new Web Agent over an existing Web Agent, the WebAgentTrace.conf file is overwritten. Therefore, you should rename or back up the WebAgentTrace.conf file before the installation.

After the installation, you can integrate your changes into the new file.

SOA Agent for IBM WebSphere Install Preparation Before you install a SOA Agent for IBM WebSphere, there are a number of pieces of information you will need and requirements that must be met.

SOA Agent for IBM WebSphere Install Preparation


Software Requirements

Before installing the SOA Agent for IBM WebSphere, install the following software:

Note: Be sure to install the prerequisite software in the correct order.

IBM WebSphere Application Server, Version 6.1 and any cumulative fixes for this application server. For WebSphere hardware and software requirements, see the WebSphere documentation.


Note: The SiteMinder Policy Server can be installed on a different systems than the WebSphere Application Server.

For a list of supported operating systems, Java environments, and prerequisite CA product versions, see the CA SOA Security Manager r12 Platform Matrix.

Required JVM Patch for SOA Agent for IBM WebSphere

The Java Runtime Environment (JRE) required for use by the SOA Agent for IBM WebSphere must be patched to support unlimited key strength in the Java Cryptography Extension (JCE) package. If you are installing the SOA Agent for IBM WebSphere, the WebSphere JRE must also be patched to support unlimited key strength.

WebSphere's 1.4.x IBM JRE is based on Sun's JRE on the Solaris platform; this patch is available at Sun's website. The patch for the Windows platform is available at IBM's website. See the IBM documentation for more details.

If the JRE is not patched to support unlimited key strength, WebSphere will fail to start once the SOA Agent has been configured on WebSphere.

Installation Checklist

Before you install the SOA Agent for IBM WebSphere on the WebSphere server, complete the steps in the following table. To ensure proper configuration, follow the steps in order. You can place a check in the first column as you complete each step.

Completed? Steps For information, see...

Install and configure the CA SOA Security Manager Policy Server.

Install the CA SOA Security Manager Software (see page 59)


SOA Security Gateway Install Preparation


Completed? Steps For information, see...

Install the IBM WebSphere Application Server.

The IBM WebSphere Application Server Documentation

Patch JVMs for unlimited cryptography with the Java Cryptography Extension (JCE) package.

Required JVM Patch (see page 53)

Configure the Policy Server for the SOA Agent for IBM WebSphere.

Preconfiguring Policy Objects for SOA Agents (see page 56)

Install the SOA Agent on the WebSphere Application Server.

Note: For WebSphere clusters, install the SOA Agent on each node in the cluster.

Install the CA SOA Security Manager Software (see page 59)

Setting a PATH Variable to the JVM on UNIX Systems

On UNIX systems, if your Java Virtual Machine (JVM) is not in the PATH variable, run these two commands:

PATH=$PATH:JRE

export PATH

JRE

Defines the location of your Java Runtime Environment bin directory. For example:

/opt/WebSphere/AppServer/java/jre/bin

SOA Security Gateway Install Preparation The Java Runtime Environment (JRE) used by the SOA Security Gateway must be patched to support unlimited key strength in the Java Cryptography Extension (JCE) package. You must apply the patch to the JRE used by each SOA Security Gateway component:

SOA Security Gateway Configuration Manager


SOA Security Gateway Management Console

The files that need to be patched are:

local_policy.jar

US_export_policy.jar

Scripting Interface for Perl


The jars that need to be patched are in the following locations:

UNIX

– soasm_installation/SOASecurityGateway/SunOS.sun4u-32/jre/lib/security

– soasm_installation/SOASecurityGatewayCM/SunOS.sun4u-32/jre/lib/security

– soasm_installation/SOASecurityGatewayMMC/SunOS.sun4u-32/jre/lib/security

Windows

– soasm_installation\SOASecurityGateway\win32\jre\lib\security

– soasm_installation\SOASecurityGatewayCM\win32\jre\lib\security

– soasm_installation\SOASecurityGatewayMMC\win32\jre\lib\security

soasm_installation

Specifies the SOA Security Manager installation location. By default, this is:

Windows: C:\Program Files\CA\SOA Security Manager

Solaris: ~/CA/SOA_Security_Manager

The patches for all supported platforms are available from Sun's website.

Scripting Interface for Perl The Scripting Interface lets you write Perl scripts to configure and manage policy stores. Using the Scripting Interface, you can write Perl scripts to import and export particular objects rather than all the Policy Store objects. The installation program installs a full version of Perl and puts the interface files in the CA SOA Security Manager_installation\CLI directory.

CA SOA Security Manager_installation

Specifies the installed location of CA SOA Security Manager

To use the Scripting Interface, make sure the CA SOA Security Manager_installation\CLI directory is in your system’s Path environment variable before any other Perl bin directories on your machine.

Note: For more information on this interface, see the CA eTrust SiteMinder Scripting Guide for Perl.

Preconfiguring Policy Objects for SOA Agents


Preconfiguring Policy Objects for SOA Agents This section describes how to preconfigure policy objects for SOA Agents on the Policy Server.

Policy Object Preconfiguration Overview

Before you install any SOA Agent (including the SOA Security Gateway), the CA SOA Security Manager Policy Server must be installed and be able to communicate with the system where you plan to install the SOA Agent. Additionally, you must configure the Policy Server with the following:

An administrator that has the right to register trusted hosts

A trusted host is a client computer where one or more SOA Agents are installed. The term trusted host refers to the physical system. There must be an administrator with the privilege to register trusted hosts with the Policy Server.

To configure an administrator, see the Administrators chapter of CA Policy Design.

Agent object/Agent identity

An Agent object creates an Agent identity by assigning the Agent a name. You define an Agent identity from the Agents object in the Administrative UI. You assign the Agent identity a name and specify the Agent type as a Web Agent.

The name you assign for the Agent is the same name you specify in the DefaultAgentName parameter for the Agent Configuration Object that you must also define to centrally manage an Agent.

Host Configuration Object

This object defines the communication between the trusted host and the Policy Server after the initial connection between the two is made.

A trusted host is a client computer where one or more SOA Agents can be installed. The term trusted host refers to the physical system, in this case the WebSphere Application Server host.

Do not confuse this object with the trusted host's configuration file, SmHost.conf, which is installed at the trusted host after a successful host registration. The settings in the SmHost.conf file enable the host to connect to a Policy Server for the first connection only. Subsequent connections are governed by the Host Configuration Object.

For more information, see CA SiteMinder Policy Design.

Preconfiguring Policy Objects for SOA Agents


Agent Configuration Object

This object includes the parameters that define the SiteMinder Agent configuration. There are a few required parameters you must set for basic operation.

The Agent Configuration Object must include a value for the DefaultAgentName parameter. This entry should match an entry you defined in the Agent object.

For more information, see CA SiteMinder Policy Design.

For detailed information about how to configure SOA Agent-related objects, see CA SiteMinder Policy Design, CA SOA Security Manager SOA Agent Guide.

Preconfiguring the Policy Objects

The following is an overview of the configuration procedures you must perform on the Policy Server prior to installing the Agent software:

1. Duplicate or create a new Host Configuration Object, which holds initialization parameters for a Trusted Host. (If upgrading from an earlier Agent install, you can use the existing Host Configuration object).

The Trusted Host is a server that hosts one or more Agents and handles their connection to the Policy Server.

2. As necessary, add or edit Trusted Host parameters in the Host Configuration Object that you just created.

3. Create an Agent identity for the SOA Agent for WebSphere. You must select Web Agent as the Agent type for the SOA Agent for IBM WebSphere.

4. Duplicate an existing or create a new Agent Configuration Object, which holds Agent configuration parameters and can be used to centrally configure a group of Agents.

5. In the Agent Configuration Object you just created, ensure that the DefaultAgentName parameter is set to specify the Agent identity defined in Step 3.

Install the CA SOA Security Manager Software 59

Chapter 3: Install the CA SOA Security Manager Software


Information Required During Installation (see page 59) Run the CA SOA Security Manager Installer in GUI or Console Mode (see page 65) Run the Unattended CA SOA Security Manager Installer (see page 66) Upgrade CA SOA Security Manager (see page 68) Reinstall CA SOA Security Manager (see page 68) Uninstall CA SOA Security Manager (see page 69)

Information Required During Installation The CA SOA Security Manager installer prompts you for information based on the installation choices you make.

Information Required During Installation


Installation Selections

The CA SOA Security Manager installer allows you to choose which components to install.


Choose this option to install any of:


CA SOA Security Gateway Configuration Manager

CA SOA Security Manager Agents

Choose this option to install any of:

CA SOA Security Gateway

CA SOA Agent for Web Servers

CA SOA and SiteMinder Agents for IBM WebSphere

Select this option to install the SOA Agent for IBM WebSphere and, optionally, a binary-compatible version of the SiteMinder Agent for IBM WebSphere to coexist with the SOA Agent in the IBM WebSphere container. (SiteMinder Agent for IBM WebSphere requires a separate license; it is not included as part of CA SOA Security Manager.)

CA SOA Security Manager UI

Choose this option to install the SOA Security Gateway Management Console.

CA SOA Security Manager SDK

Choose this option to install the CA SOA Security Manager SDK.

CA SOA Security Manager Documentation

Choose this option to install the CA SOA Security Manager documentation.

Information Required for Policy Server Installation Elements

If you choose to install the SOA Agent for IBM WebSphere, the installation program prompts you for the following information:

If the installer cannot locate the JRE (or finds multiple versions), the location of the JRE to use.

Whether you want the installer to configure an ADAM or Sun Java System LDAP Directory Server as a Policy Store.



Note: You can use the Policy Server installer to install the policy store in a Sun Java System LDAP Directory Server or Active Directory Application Mode (ADAM). For other supported LDAP versions or for relational databases such as SQL Server and Oracle, you need to manually configure them as a policy store after installation.

The install program configures an LDAP Directory Server as a policy store. You can choose to install the policy store in a Sun Java System LDAP Directory Server or Active Directory Application Mode (ADAM). For other LDAP versions--CA eTrust Directory, Novell, Microsoft Active Directory, Oracle Internet Directory, IBM Directory Server--or for relational database such as SQL Server and Oracle, you need to manually configure them as a policy store after installation.

Note: If there is a problem with configuring the policy store, you can run the Policy Server Configuration Wizard (located in C:\Program Files\CA\SOA Security Manager\install_config_info\ca-ps-config.exe) to fix the issue.

If you want the installer to configure an ADAM Policy Store:

– IP Address of the machine where the ADAM server is installed.

– Port number for the ADAM server instance.

Example: 389

– Existing root DN location of the application partition in the ADAM server where you want to put the policy store schema data under.

Example: dc=netegrity,dc=com

– Full domain name, including the guid value, of the ADAM administrator.

Example: CN=user1,CN=People,CN=Configuration,CN={guid}

– Password for the administrator DN.

– Whether or not you want to specify a different LDAP user account to be used to update SiteMinder data.

Normally, CA SOA Security Manager uses the LDAP Administrator account to communicate to the LDAP server. You have the option to have the SiteMinder policy store administered through a different LDAP user account. You must know the complete DN for the user to configure SiteMinder this way.

Note: This user should have all of the necessary privileges to modify attributes and change passwords.

– If you choose to use a different LDAP account:

– DN of the LDAP user

– Password of the LDAP user

Example: uid=SMAdmin, ou=people, o=security.com.



– Whether you want to initialize a new LDAP instance. The installation program can configure Active Directory Application Mode automatically, but you need to configure other LDAP versions--CA eTrust Directory, Novell eDirectory, Microsoft Active Directory, Oracle Internet Directory, and IBM Directory Server--manually.

– SiteMinder Super User password. The pre-defined SiteMinder Super User account has maximum SiteMinder privileges. The password can be from 6 to 24 characters in length.

Note: The password is case-insensitive, except in cases where the password is stored in an Oracle policy store.

Important: Take note of this password for future reference.

Note: We recommend that this account not be used in day-to-day operations. Instead, only use this account to access the Administrative UI for the first time and for creating an administrator with system configuration privileges.

If you want the installer to configure a Sun Java System LDAP directory as a policy store:

– IP Address where the LDAP directory is installed.

– Port number of the LDAP directory server instance that you want to configure as a policy store or accept the default number (389).

– Root DN as follows

For Sun Java System LDAP, specify the root DN as follows:

o=example.com

– User name (Bind DN) for the LDAP administrator account

Example: cn=Directory Manager

– Password for the administrator DN account.

– Whether or not you want to specify a different LDAP user account to be used to update SiteMinder data.

Normally, CA SOA Security Manager uses the LDAP Administrator account to communicate with the LDAP server. You have the option to have the SiteMinder policy store administered through a different LDAP user account. You must know the complete DN for the user to configure SiteMinder this way.

Note: This user should have all of the necessary privileges to modify attributes and change passwords.

– If you choose to use a different LDAP account:

– DN of the LDAP user

– Password of the LDAP user

Example: uid=SMAdmin, ou=people, o=security.com.



– Whether you want to initialize a new LDAP instance. The installation program can configure Active Directory Application Mode automatically, but you need to configure other LDAP versions--CA eTrust Directory, Novell eDirectory, Microsoft Active Directory, Oracle Internet Directory, and IBM Directory Server--manually.

– SiteMinder Super User password. The pre-defined SiteMinder Super User account has maximum SiteMinder privileges. The password can be from 6 to 24 characters in length.

Note: The password is case-insensitive, except in cases where the password is stored in an Oracle policy store.


Note: We recommend that this account not be used in day-to-day operations. Instead, only use this account to access the Administrative UI for the first time and for creating an administrator with system configuration privileges.

An encryption key to use for the Policy Store. This must be a case-sensitive, alphanumeric value. The encryption key is a key that secures data sent between the Policy Server and the policy store. The key can be from 6 to 24 characters in length. All Policy Servers that share a SiteMinder policy store (a database containing policy information) must be configured using the same encryption key. For stronger protection, define a long Encryption Key.

Important: Take note of this key for future reference.

Whether you want to import affiliate data:

For new installations, select the option to Import affiliate data during install. If you deselect the check box, you will have to import this data later using the smobjimport command.

For an upgrade, do not select the Import affiliate data during install option if you have made any changes or additions to affiliate-related policy store objects. Importing affiliate data overwrites these policy store objects.

Whether you want the installer to configure an XML Key Database (required for a private key and certificates required to sign and validate WS-Security tokens in XML messages):

Note: When upgrading or reinstalling CA SOA Security Manager the installer will detect any existing XML Key Database and will not attempt to reconfigure it even if you choose the Yes option.



Note: If you choose not to configure the XML Key Database at this time, you can create one manually later. See the section on the WS-Security authentication scheme in the CA SOA Security Manager Policy Configuration Guide.

A password for the XML Key Database. The specified password is encrypted using the policy store key and then used by CA SOA Security Manager to gain access to the database.


Information Required for SOA Agent for IBM WebSphere

If you choose to install the SOA Agent for IBM WebSphere, the installation program prompts you for the following information:

Location where WebSphere Application Server is installed. The default is:

Windows: c:\Program Files\WebSphere\AppServer

UNIX: /opt/Websphere/AppServer

Policy Server IP Address

IBM WebSphere Administrator account name and password

Run the CA SOA Security Manager Installer in GUI or Console Mode


Run the CA SOA Security Manager Installer in GUI or Console Mode

The installation instructions that follow reflect the GUI mode prompts. For UNIX systems, you can install the Policy Server Option Pack using Console mode by executing the Option Pack binary file with the -i console command argument. The command line installation prompts are similar to the GUI mode prompts; hit Enter when instructed to click Next or Done.

Note: Before you run the installer, be sure that the system meets all requirements for the components that you plan to install on it and that you have all the information that you need.

To run the CA SOA Security Manager installer

1. Exit all applications that are running.

2. Insert the CA SOA Security Manager DVD into the drive or download the zip archive of the software from the Technical Support site and then extract it:

Windows: soasm-r12.0-win32.zip

Solaris: soasm-r12.0-sol.zip

3. Navigate to where the install program in located and run the installation program as follows:

Windows: Double-click ca-soasm-12.0-win32.exe

UNIX: At the command prompt, enter:

GUI mode: ./ca-soasm-12.0-sol.bin

Console mode: ./ca-soasm-12.0-sol.bin -i console

For example, to run the installation in GUI mode on Solaris enter:

./ca-soasm-12.0-sol.bin

The installation program prepares the files and verifies the following prerequisites:

You are logged into an account with local administrator privileges.

You have the appropriate operating system and prerequisites for the components you plan to install listed on the CA SOA Security Manager Platform Matrix for r12. To access this matrix, go to the Technical Support site and search for the CA SOA Security Manager Platform Matrix for r12.

The computer has necessary free disk space and the required JDK or JRE installed. For the required versions, search for the CA SOA Security Manager Platform Matrix for r12 on the Technical Support site.





Run the Unattended CA SOA Security Manager Installer


4. Read the Introduction and click Next.

5. Read the Software License Agreement (you must scroll through it to the end to proceed), accept the terms if you agree, and click Next.

6. On the Install Set screen, choose the type of installation you would like and click Next. Install set options are:

Typical Installation—Installs everything except the SOA SDK and the documentation (best for evaluation installations)

Custom Installation—Allows you to choose which components you want to install.

7. If you chose the Custom Installation option, select the CA SOA Security Manager components you want to install and click Next.

8. Accept the default top-level CA SOA Security Manager installation location or select a different one and click Next. If necessary, click Choose to browse to the appropriate location.

Note: If you cut and paste a path into this screen, you must also type in a character before the Next button is enabled. If you manually type in a path, the Next button is enabled automatically.

9. Type a generic username and password (and confirm the password) for use by CA SOA Security Manager embedded components and click Next.

10. Complete the instructions in the screens presented relating to the components selected for installation.

11. Check the pre-installation summary and click Install to proceed. If you are not satisfied with your selections, click Previous to change them.

12. When the installation is complete, click Done to exit the installer.

Run the Unattended CA SOA Security Manager Installer After you have installed CA SOA Security Manager on one machine, you can reinstall it on the same machine or install it with the same options on another machine using an unattended installation mode. An unattended installation lets you install or uninstall CA SOA Security Manager components without any user interaction

The unattended installation uses the ca-soasmr12-installer.properties file generated during the initial install from the information you specified to define the necessary installation parameters, passwords, paths, and so on.

Run the Unattended CA SOA Security Manager Installer


The ca-soasmr12-installer.properties file is located in: soasm_installation\install_config_info

soasm_installation

Specifies the SOA Security Manager installation location. By default, this is:

Windows: C:\Program Files\CA\SOA Security Manager

Solaris: ~/CA/SOA_Security_Manager

To run the installer in the unattended installation mode

1. From a system where CA SOA Security Manager is already installed, copy the ca-soasmr12-installer.properties to a local directory on your system.

2. Download the zip archive to a temporary location from the Technical Support site and then extract it:

Windows: soasm-r12.0-win32.zip

Solaris: soasm-r12.0-sol.zip

3. Extract the Zip archive into the same local directory as the ca-soasmr12-installer.properties file.

4. Open a console window and navigate to the location where you copied the files.

5. Run the following command:

ca-soasm-12.0-win32.exe -f ca-soasmr12-installer.properties

-i silent

When running this command, if the ca-soasmr12-installer.properties file is not in the same directory as the installation program, make sure you use double quotes if the argument contains spaces.

For example:

ca-soasm-12.0-win32.exe -f "C:\Program Files\CA\SOA Security

Manager\install_config_info\ca-soasmr12-installer.properties" -i silent

The -i silent setting instructs the installer to run in the unattended installation mode.

An InstallAnywhere status bar appears, which shows that the unattended CA SOA Security Manager installer has begun. The installer uses the parameters specified in the ca-soasmr12-installer.properties file.



Upgrade CA SOA Security Manager


To stop the installation manually, follow the instructions for your platform:

Windows: Open the Windows Task Manager and stop the ca-soasm-12.0-win32.exe process.

UNIX: Type Ctrl+C.

To check if the unattended installation completed successfully, see the ca-soasmr12_InstallLog.log file in the soasm_installation/install_config_info directory. This log file contains the results of the installation.

Upgrade CA SOA Security Manager To upgrade CA SOA Security Manager on Windows or UNIX systems, follow the same procedure as described for a first time installation.

Note: If you are upgrading a system with an existing Policy Server or Web/XML Agent installation, the installer will upgrade the those components in their existing location. In this case, any upgraded product components will be located in the sm_install_dir rather than the soasm_install_dir directory

sm_installation

Specifies the installation location of an existing CA Policy Server or Web/XML Agent. For example:

C:\Program Files\CA\SiteMinder

or

C:\Program Files\Netegrity\SiteMinder

soasm_install_dir

Specifies the SOA Security Manager installation location. For example:

C:\Program Files\CA\SOA Security Manager

Reinstall CA SOA Security Manager To reinstall CA SOA Security Manager on Windows or UNIX systems, follow the same procedure as for installing it.

Uninstall CA SOA Security Manager


Uninstall CA SOA Security Manager To fully uninstall CA SOA Security Manager, you must remove all CA SOA Security Manager software components and subcomponents.

To uninstall CA SOA Security Manager on Windows or UNIX systems

1. Navigate to the soasm_installation\install_config_info directory and run the CA SOA Security Manager uninstaller to remove core CA SOA Security Manager components:

Windows: soa-uninstall.cmd

UNIX: soa-uninstall.sh

soasm_installation

Specifies the SOA Security Manager installation location.

2. Remove remaining subcomponents (Policy Server, Web Agent, and documentation) by running their individual uninstallers.

3. If you have deployed the SOA Agent for IBM WebSphere, clean up the CA SOA Security Manager-specific configuration in WebSphere.

Post-installation, Policy Server 71

Chapter 4: Post-installation, Policy Server


Run the Policy Server Configuration Wizard (see page 72) Additional SNMP Step (see page 74) Configuring LDAP Directory Servers as a Policy or Key Store (see page 75) Configure CA SOA Security Manager Data in a Relational Database (see page 104) Policy Server Tools (see page 145) Configure the OneView Monitor (see page 176) Prerequisites for Running Reports Using Crystal Reports (see page 183) Secure Keys with a Hardware Module (see page 200) SNMP Support (see page 204) Troubleshooting (see page 210)

Run the Policy Server Configuration Wizard


Run the Policy Server Configuration Wizard The Policy Server Configuration Wizard (ca-ps-config.exe) lets you configure the OneView Monitor GUI, the Policy Server User Interface, and the netegrity_docs virtual directory on a Web server; SNMP support; Hardware Key Storage; and a policy store.

When configuring a policy store on Windows, the wizard can automatically configure Sun Java System Directory Server or Active Directory Application Mode as a policy store. For other LDAP versions (CA eTrust Directory, Novell eDirectory, Active Directory, IBM Directory Server, and Oracle Internet Directory), you need to manually configure them using smldapsetup and by importing the smpolicy.smdif file after installation.

Additionally, the wizard does not let you configure an Oracle or other SQL Server database as a policy store during installation and, as a result, must manually configure the database after installation.

If you install the documentation after installing the Policy Server, you need to run the Policy Server Configuration Wizard to create the netegrity_docs virtual directory on the Web server. This virtual directory allows you to view the documentation using the Policy Server User Interface.

To run the Policy Server Configuration Wizard

1. Close all programs.

2. Start the Policy Server Configuration Wizard script, located in the soasm_installation\install_config_info directory, by running the following command: ca-ps-config.exe (Windows) or double-click this executable file from Windows Explorer.

The wizard verifies that the following prerequisites:

You are logged into an account with local administrator privileges.

You have the appropriate Policy Server environment variables set.

3. In the Choose Features dialog box, select which Policy Server features you want. The OneView Monitor GUI, Web Server(s), and Policy Store are selected by default:

OneView Monitor GUI

The install program configures the OneView Monitor GUI to work on the Web server you choose before completing this procedure.

Note: To use the OneView Monitor, you must have the required Java SDK and ServletExec ISAPI for Windows/IIS installed. For the required versions, search for the SiteMinder Platform Matrix for 6.0 on the Technical Support site.

Web Server(s)



Run the Policy Server Configuration Wizard


The install program configures the Policy Server User Interface and the OneView Monitor (if you specified it previously) to work on this Web server.

SNMP

The install program configures SNMP to work with the Policy Server.

Note: Make sure you have an SNMP Service (Master OS Agent) installed with your Windows operating system. For instructions on installing the SNMP service, refer to the Windows Help system.

Hardware Key Storage

The install program configures Hardware Key storage to work with the Policy Server.

LDAP Policy Store

The install program configures an LDAP Directory Server as a policy store.

4. In the Web Server dialog box, select the Web server(s) to configure for the Policy Server and click Next. Make sure that the Web server is stopped to allow the installation program to configure the Policy Server User Interface.

Note: If you are configuring the Policy Server User Interface on multiple Web servers, the Policy Server User Interface shortcut’s URL is configured to the port number of the first Web server you specify. For example, if the first Web Server in the list is IIS (at port 80) and the second one is Sun Java System (at port 81), the Policy Server User Interface shortcut's URL is configured for port 80. Later, if you want to run the Policy Server User Interface configured on the Sun Java System Web Server, you need to edit the shortcut URL or the policy server user interface will not appear.

5. (Optional) In the Hardware Key dialog box, if you want the Policy Server installer to configure Hardware Key storage, be aware that:

You must have an nCipher cryptographic module with a smart card reader installed and configured. Further, ensure the PKCS 11 Library is installed.

Once SiteMinder has been configured to use cryptographic hardware modules, you cannot remove, disable, or reconfigure SiteMinder’s use of hardware encryption.

Hardware cryptography in your SiteMinder environment prevents unattended system failover -- a passphrase must be supplied by an operator each time a cryptographic hardware-enabled Policy Server or Agent restarts.

Note: If you do not want to configure Hardware Keys, return to the Choose Features dialog box, and deselect Hardware Key Storage.

Additional SNMP Step


a. Enter the absolute path to the PKCS 11 Library that came with your NCipher installation. If necessary, click Choose to browse to the appropriate location.

b. Enter an optional token (operator card) label.

c. Re-enter your token password.

6. In the first Policy Store dialog box, select whether you want to configure a new policy store or update an existing one.

7. (Optional) In the next Policy Store dialog box, click Next to configure an ADAM or Sun Java System LDAP Directory Server as a policy store.

Note: You can use the configuration wizard to configure the policy store in a Sun Java System LDAP Directory Server or Active Directory Application Mode (ADAM). For other supported LDAP versions or for relational databases such as SQL Server and Oracle, you need to manually configure them.

Additional SNMP Step After the installation is complete, if you chose to have SNMP configured, the installer prompts you to configure SNMP event trapping.

Note: Before running this step, you must have an SNMP Service installed with your Windows operating system.

Configure SNMP Event Trapping

To enable SNMP event trapping

1. Launch the Policy Server Management Console.

2. Click the Advanced tab.

3. In the Event Handlers field at the bottom, enter the full path to the eventsnmp.dll.

4. Click OK.

After enabling SNMP event trapping, configure the snmptrap.config file.

More Information:

Configure the SNMP Agent on Windows (see page 206)

Configuring LDAP Directory Servers as a Policy or Key Store


Configuring LDAP Directory Servers as a Policy or Key Store This section describes how to configure LDAP directory servers as a Policy or Key Store.

LDAP Directory Servers as a Policy or Key Store

The SiteMinder policy store is the repository for all policy related information. All Policy Servers in a SiteMinder installation must share the same policy store data, either directly or via replication. SiteMinder is installed with tools that allow administrators to move policy store data from one storage facility to another.

When you install the Policy Server, the default policy store is a Sun Java System (formerly Sun One/iPlanet) LDAP Directory Server or Microsoft Active Directory Application Mode. You can configure the Policy Server to use another LDAP directory, a SQL Server database, or an Oracle database as a policy store after you have completed the Policy Server installation. Also, after installation, you can use the Policy Server Management Console's Data tab to have the Policy Server point to another policy store.

The Policy Server supports the following LDAP Directory Servers as policy stores:

CA eTrust Directory

Sun Java System LDAP Directory

Microsoft Active Directory

Microsoft Active Directory Application Mode

Novell eDirectory

Oracle Internet Directory

IBM Directory Server

To see which operating systems, Web Servers, databases, Web browsers, and LDAP Directory Server versions that SiteMinder supports, see the SiteMinder Platform Matrix for 6.0. To access this matrix, go to Technical Support site and search for the SiteMinder Platform Matrix for 6.0.

Important Considerations






Create a Policy Store in an LDAP Directory

The LDAP directory server can be the same directory server SiteMinder uses for user authentication and authorization, which simplifies the task of administering SiteMinder.

By default, the policy store is stored in an LDAP directory. The following lists the specific items that will be required in the process of creating an LDAP policy store or moving an existing policy store from a non-LDAP database or from an existing LDAP directory to another:

Secured Sockets Layer (SSL) Certificate Database - If the targeted LDAP directory service communicates with a Policy Server over SSL, specifies the LDAP database where Certificates are located.

LDAP Server IP Address - Specifies the targeted LDAP server IP address.

LDAP Port Number - Specifies the port number on which the targeted LDAP service is listening on.

Distinguished Name (DN) - Specifies the DN of an LDAP user with sufficient privileges for tasks such as i.e. the ability to creating, reading, modifying, and deleting objects in the LDAP tree underneath the policy store root object

Example: cn=Directory Manager for Sun Java System Directory Server.

DN’s Password - Specifies the password of the Administrator DN.

Policy store Root DN - Specifies the DN under which the policy store objects are defined.

Example: o=test.com.



What To Do First

Depending on the directory for which you want to configure as a policy store, complete one of the following procedures:

To configure a CA eTrust Directory as a policy store, refer to Configure the Policy Server to Use CA eTrust Directory as a Policy Store (see page 77).

To configure a Sun Java System LDAP Directory as a policy store, refer to Configure a Policy Store in a Sun Java System LDAP Directory (see page 83).

To configure a Microsoft Active Directory as a policy store, refer to Configure the Policy Server to Use Active Directory as a Policy Store (see page 89).

To configure Microsoft ADAM as a policy store, refer to Configure the Policy Server to Use Microsoft ADAM as a Policy Store (see page 90).

To configure a Novell eDirectory as a policy store, refer to Configure the Policy Server to Use Novell eDirectory as a Policy Store (see page 93).

To configure an Oracle Internet Directory as a policy store, refer to Configure the Policy Server to Use OID as a Policy Store (see page 97).

To configure an IBM Directory Server as a policy store, refer to Configure the Policy Server to Use IBM Directory Server as Policy Store (see page 98).

How to Configure the Policy Server to Use CA eTrust Directory as a Policy Store

Configuring the Policy Server to use a CA eTrust Directory as a policy store requires you to:

1. Create a database and a DSA for the policy store in a CA eTrust directory.

2. Configure the CA eTrust directory as a policy store.

3. Configure caching for the eTrust policy store.

4. Verify the eTrust cache configuration.



Create a Database and DSA for the Policy Store in CA eTrust Directory

To create a database and DSA for the policy store in CA eTrust Directory

1. Create the DSA by running the following command.

dxnewdsa eTrustDSA <eTrustDatabase> <12380> <c AU o eTrustDSA>

Note: The command creates the eTrust database if it does not exist.

eTrustDSA

Specifies the DSA name.

eTrustDatabase

Specifies the name of the new or existing database.

12380

Specifies the port number of the DSA.

c AU o eTrustDSA

Specifies the DSA prefix.

2. Run the following command to ensure that your new DSA starts:

dxserver start eTrustDSA



Configure CA eTrust Directory as a Policy Store

To configure CA eTrust Directory as a policy store

1. Copy the netegrity.dxc file installed with the Policy Server into the CA eTrust DXHOME\config\schema directory.

The netegrity.dxc file is installed in: <policy_server_installation>\eTrust

2. Create a new SiteMinder schema file by copying the default schema file from DXHOME\config\schema\default.dxg.

Example: create DXHOME\config\schema\eTrustDsa.dxg

3. Edit the DXHOME\config\schema\eTrustDsa.dxg SiteMinder schema file by adding the following lines to the bottom if they are not currently present:

# Netegrity Schema

source "netegrity.dxc";

4. Edit the DSA’s DXI file by changing the schema from default.dxg to the newly created SiteMinder schema file, eTrustDsa.dxg.

Example: DXHOME\config\servers\eTrustDsa.dxi

5. Edit the DSA’s DXI file and add the following to the end of the file:

set ignore-name-bindings = true;

Note: If this step is omitted, an error occurs when you try to add variables to domains.

6. As the DSA user, stop and restart the eTrustDSA to make the schema changes take effect:

dxserver stop eTrustDSA

dxserver start eTrustDSA

7. Launch the JXplorer GUI and do the following:

a. Select the connect icon.

b. Enter:

Host Name: <host name or the IP address where eTrust Directory Server is running>

Port number: 12380 <DSA port number>

Base DN: o=eTrustDsa,c=AU <DSA prefix>

Level: anonymous

8. In the eTrust Directory, create the base tree structure to hold the policy store data. Use the JXplorer GUI to create the following organizational units:

a. Select the root element of your DSA:

Example: eTrustDSA



b. Under the root element, create an organizational unit called:

Netegrity

c. Under Netegrity, create an organizational unit (root element) called:

SiteMinder

d. Under SiteMinder, create an organizational unit (root element) called:

PolicySvr4

9. In the eTrust Directory, create a SiteMinder Super User administrator that has rights to create, delete, or modify the dsa. This user will point the Policy Server at the policy store residing in eTrust Directory.

Example: dn: cn=admin,o=yourcompany,c=in

10. On the server where the Policy Server is installed, open the Policy Server Management Console and select the Data tab to bring it to the front.

11. Point the Policy Server at the directory by doing the following:

a. In the Database drop-down menu, select Policy Store.

b. In the Storage drop-down menu, select LDAP.

c. In the LDAP Policy Store box, configure the fields for the LDAP policy store.

The following lists sample values for the fields:

LDAP IP Address: 123.123.12.12:3500

Root DN: o=eTrustDSA,c=AU

Admin Username: cn=admin,o=yourcompany,c=in.

Password: <masked password>

Note: Refer to the Policy Server Management guide for a complete description of the LDAP settings.

d. Click Apply after you have modified the LDAP fields.

e. Click the Test LDAP Connection button to test the connection.

If the connection is successful, SiteMinder returns a confirmation. If it is not successful, SiteMinder returns an error message. If you receive an error message, verify that the values you entered are correct and that the directory is running.

12. Set the SiteMinder Super User password by completing the following steps:

a. Copy smreg from either \win32\tools or solaris/tools on the SiteMinder DVD to <siteminder_installation>\bin.

b. Execute the following command:

smreg -su <superuserpassword>



superuserpassword

Specifies the password for the SiteMinder Super User account.

Note: Ensure there is a space between -su and the superuserpassword.

a. Delete smreg.exe.

Deleting smreg.exe prevents anyone from changing the Super User password without knowing the previous one.

13. From <siteminder_installation>/bin, import the basic SiteMinder objects required to set up a policy store by running:

smobjimport -i<siteminder_installation>\db\smdif

\smpolicy.smdif -d<SM_Super_User_Name>

w<superuserpassword> -v

siteminder_install

Specifies the installed location of SiteMinder.

SM_Super_User_Name

Specifies the Super User name of the SiteMinder administrator.

superuserpassword

Specifies is the password for the SiteMinder Super User.

Note: If an argument contains spaces, use double quotes around the entire argument.

Windows example: smobjimport -i“C:\Program Files\Netegrity\siteminder\db\smdif\smpolicy.smdif” -d"SM Admin" -wPassword -v

UNIX:smobjimport -i$NETE_PS_ROOT/db/smdif/smpolicy.smdif -d"SM Admin" -wPassword -v

-v

Outputs error, warning, and comment messages in verbose format so you can monitor the status of the import.

Be aware of the following:

This step creates default objects required by SiteMinder. The objects are automatically saved in their appropriate locations in the policy store.

If you do not complete this step, required SiteMinder objects will not be added to your policy store, and you will not be able to use the Policy Server User Interface to properly configure policies.

The policy store is configured and you can now log into the Policy Server User Interface.



Configure Caching for the eTrust Policy Store

Enabling caching helps to improve policy store load times for large policy stores.

To enable the eTrust Directory DXcache feature

1. As the dsa user, edit the policy store DSA’s DXI file (for example, <dxserver_install>\config\servers\eTrustDsa.dxi) and add the following lines to the end of the file:

# cache configuration

set max-cache-size = 100;

set cache-index = smPropertyOID5, objectclass;

set cache-attrs = all-attributes;

set cache-load-all = true;

set lookup-cache = true;

Note: The max-cache-size entry is the total cache size in MB. Adjust this value based on the total memory available on the eTrust Directory server and overall size of the policy store.

2. As the dsa user, stop and restart the policy DSA to allow the DXcache configuration changes to take effect:

dxserver stop eTrustDsa

dxserver start eTrustDsa



Verify the eTrust Directory Cache Configuration

You can verify that the DXcache settings are enabled using the DXconsole.

To verify that the cache is enabled

1. From a command prompt, enter the following to Telenet to the eTrust Directory DSA DXConsole port:

telenet <DSA_Host> <DXconsole_Port>

DSA Host

Specifies eTrust Directory DSA server host name or IP address.

DXConsole Port

Specifies the port on which the DXconsole is listening.

Default: The DXconsole port is set to the value of the DSA port +1.

Example: If the DSA is running on port 19389, the DXconsole port is 19390.

The DSA Management Console appears.


get cache;

The DXconsole displays the current DSA DXcache settings and specifies is directory caching is enabled.

How to Configure a Policy Store in a Sun Java System LDAP Directory

Configuring a policy store in a Sun Java System LDAP Directory requires you to either:

Automatically configure the policy store data using the Configuration Wizard through a GUI or console window.

Manually configure (see page 86) the policy store data.



smldapsetup and the 5.x SunOne Directory Server

In a 5.x SunOne (iPlanet) Directory Server, smldapsetup creates the ou=Netegrity,<root> sub suffix and PolicySvr4 database, where <root> is the directory root you specified in the Root DN field on the Data tab of the Policy Server Management Console. The <root> variable has to be either an existing root suffix or sub suffix. For example, if your root suffix is dc=netegrity,dc=com then running smldapsetup produces the following in the 5.x SunOne Directory Server:

A root suffix, dc=netegrity,dc=com, with the corresponding userRoot database.

A sub suffix, ou=Netegrity,dc=netegrity,dc=com, with the corresponding PolicySvr4 database.

For another example, if you want to place the policy store under ou=apps,dc=netegrity,dc=com, then ou=apps,dc=netegrity,dc=com has to be either a root or sub suffix of the root suffix dc=netegrity,dc=com. If it is a sub suffix, then running smldapsetup produces the following:


A sub suffix, ou=apps,dc=netegrity,dc=com, with the corresponding Apps database.

A sub suffix, ou=Netegrity,ou=apps,dc=netegrity,dc=com, with the corresponding PolicySvr4 database.

Note: More information on root and sub suffixes is available at http://docs.sun.com http://docs.sun.com.

http://docs.sun.com/

http://docs.sun.com/



Replicate the Policy Store on a SunOne 5.x Directory Server

For a SunOne 5.x Directory Server, SiteMinder 6.x creates a UserRoot and a PolicySvr4 database. The PolicySvr4 database has suffix mappings pointing to it. To replicate this policy store, you need to set up a replication agreement for the PolicySvr4 database directory.

Note: More information exists in Sun's documentation.

Further, after creating a replication agreement, you need to replicate the SiteMinder indexes.

To replicate SiteMinder indexes

1. Generate the SiteMinder indexes:

smldapsetup ldgen -x -findexes.ldif

2. Set up the indexes on a replica server:

smldapsetup ldmod -x -findexes.ldif -h<host> -p<replicaport>

-d<AdminDN> -w<AdminPW>

host

Specifies the replica host.

replicaport

Specifies the replica port number.

AdminDN

Specifies the replica administrator DN.

Example: cn=directory manager

AdminPW

Specifies the replica administrator password

More Information:

Manage an LDAP Policy Store Using smldapsetup (see page 159)

http://docs.sun.com/app/docs



Manually Configure Policy Store Data in an LDAP Directory

To manually configure policy store data in an LDAP Directory

1. Use the LDAP vendor software to create an LDAP Directory Server instance, if applicable.

2. On the machine where the Policy Server is installed, navigate to <siteminder_installation>/bin

3. Point the Policy Server at the LDAP directory by running the following commands:

smldapsetup status -h<host> -p<portnumber> -d<AdminDN>

-w<AdminPW> -r<rootDN> -ssl<1/0> -c<cert>

smldapsetup reg -h<host> -pCA Portal -d<AdminDN>

-w<AdminPW> -r<rootDN> -ssl<1/0> -c<cert>

host

Specifies the name or IP Address of the LDAP server.

portnumber

Specifies the LDAP server’s port number.

AdminDN

Specifies is the name of an LDAP user with privileges to create a new LDAP schema in the LDAP Directory Server. After running this smldapsetup command, this user appears in the Admin Username field on the Data tab of the Policy Server Management Console.

For ADAM: Specifies the full domain name, including the guid value, of the ADAM administrator.

Example: CN=user1,CN=People,CN=Configuration,CN,{guid})

AdminPW

Specifies the password for the administrator DN, which is specified by -d.

rootDN

Specifies the DN location of the SiteMinder data in the LDAP directory.

For ADAM: Specifies the Existing root DN location of the application partition in the ADAM server where you want to put the policy store schema data under.

1/0

If you are connecting to the LDAP directory over SSL, specify -ssl1 and -c<cert>

cert

Specifies the path of the directory where the SSL client certificate database file, cert7.db, exists.



Note: If cert7.db exists in /app/siteminder/ssl, specify -capp/siteminder/ssl.

This smldapsetup command tests the connection to the specified LDAP server, and if successful, configures the Policy Server to use this LDAP directory as the policy store.

4. Create the policy store schema by running:

smldapsetup ldgen -f<filename>

smldapsetup ldmod -f<filename>

filename

Specifies the name of the LDIF file you are creating.

Example: smldapsetup ldmod -fpstoreschema.ldif

5. Change the SiteMinder Super User password by completing the following steps:




superuserpassword







\smpolicy.smdif -d<SM_Super_User_Name> -w<superuserpassword> -v

siteminder_installation


SM_Super_User


superuserpassword






UNIX example: smobjimport -i$NETE_PS_ROOT/db/smdif/smpolicy.smdif -d"SM Admin" -wPassword -v

-v





7. Stop and start the Policy Server service by doing the following:

a. Start the Policy Server Management Console.

b. Under the Status tab, stop the service by clicking the Stop button in the Policy Server group box.

The stoplight icon changes from green to red.

c. Click the Start button in the Policy Server group box to restart the service.

d. Click OK to exit the Policy Server Management Console.

(UNIX systems) Enter the commands stop-all followed by start-all.


More Information:

Manage an LDAP Policy Store Using smldapsetup (see page 159) Import Policy Data Using smobjimport (see page 151) Change the SiteMinder Super User Password Using smreg (see page 175)



Configure the Policy Server to Use Active Directory as a Policy Store

Microsoft Active Directory is the native LDAP-compatible directory for Windows. Policy Servers installed on either Windows or UNIX systems can use Active Directory as a policy store. Moreover, the Policy Server and policy store can be installed on separate machines. For example, a Policy Server installed on a UNIX machine can use an Active Directory policy store on a Windows system.

Note: If Active Directory is to communicate with the Policy Server over SSL, ensure that the SSL client certificate contains the CN of the SubjectDN. The Policy Server crashes if the SSL client certificate does not contain this information.

You manually configure the Policy Server to use Active Directory as a policy store.

More Information:

Manually Configure Policy Store Data in an LDAP Directory (see page 86)

Support for Active Directory ObjectCategory Indexing Attribute

Unlike other LDAP-compatible directories, Active Directory does not index policy store objects using the objectClass attribute by default. Instead, the objects are indexed by the objectCategory attribute. To enhance searches, you can either configure objectClass as an indexable attribute (see the Active Directory documentation) or enable objectCategory support in the Policy Server.

Enable or Disable ObjectCategory Attribute Support

On Windows Systems:

To enable or disable ObjectCategory attribute support

1. Launch the Windows Registry Editor.

2. Locate the key HKLM\Software\Netegrity\SiteMinder\CurrentVersion\DS\LDAPProvider.

a. To enable support, set the EnableObjectCategory value to 1.

b. To disable support, set the EnableObjectCategory value to 0.

Note: The default value is 0.



On UNIX systems:

To enable or disable ObjectCategory attribute support

1. In a text editor, open the SiteMinder sm.registry file, located in <siteminder_installation>/registry.

2. Locate the key

HKEY_LOCAL_MACHINE\SOFTWARE\Netegrity\SiteMinder\CurrentVersion\Ds\LDAPProvider.

a. To enable support, set the EnableObjectCategory value to 1.

b. To disable support, set the EnableObjectCategory value to 0.

Note: The default value is 0.

How to Configure the Policy Server to Use Microsoft ADAM as a Policy Store

Configuring the Policy Server to use Microsoft ADAM as a policy store requires you to:

1. Complete the prerequisites for configuring ADAM (see page 91) as a policy store.

2. Either:

Automatically configure the policy store data by running the Configuration Wizard using a GUI or console window.

Manually configure (see page 86) the policy store data in the LDAP directory.



Prerequisites to Configure ADAM as a Policy Store

Prerequisite 1: Install Microsoft Patch to the ADAM Server

Before configuring an ADAM Directory Server as a policy store, you must apply the Microsoft patch Q840991 to the ADAM server. This patch enables you to create users in the configuration partition, as only users with administrative rights in this partition can import the schema. You can download the patch at www.microsoft.com or by contacting Microsoft Product Support.

Prerequisite 2: Understand ADAM Server Partitions

Make sure that you are familiar with configuration, application, and schema partitions in the ADAM server. For more information, see:

http://www.c-sharpcorner.com/Code/2004/Aug/DirectoryServices.asp

Prerequisite 3: Prepare ADAM Server for the Policy Store Configuration

1. On the machine where the ADAM Directory Server is located, install an ADAM instance on an available port number.

2. Open the ADAM ADSI Edit utility by going to Start, Program Files, ADAM, ADAM ADSI Edit.

3. In ADAM ADSI Edit, create a policy store partition.

4. Create a user in the configuration partition, reset the user’s password, and give this user administrative rights over the configuration partition and all of the application partitions, including the policy store partition, by doing the following:

a. In the configuration partition, navigate to:

cn=directory service, cn=windows nt, cn=services,cn=configuration,cn={guid}

b. On that object, locate the msDS-Other-Settings attribute.

c. Add a new value to that attribute with the following as the text of that value:

ADAMAllowADAMSecurityPrincipalsInConfigPartition=1

In the configuration and policy store application partitions:

i. Navigate to CN=Administrators, CN=Roles.

ii. Open the properties of CN=Administrators.

iii. Edit the member attribute.

iv. Click Add ADAM Account, and paste the full DN of the user you created in the configuration partition.

v. Go to the properties of the user created and check the value set for the object "msDS-UserAccountDisabled". It should be set to false.



Once you have met the prerequisites, either:

Automatically configure the policy store data by running the Configuration Wizard using a GUI or console window.

Manually configure the policy store data in the LDAP directory.

More Information:




Configure the Policy Server to Use Novell eDirectory as a Policy Store

In SiteMinder 6.x, you can configure the Policy Server to use a Novell eDirectory residing on a UNIX, Windows, or NetWare machine as a policy store or user directory. To use eDirectory as a policy store or user directory, the Novell eDirectory schema must be extended to include SiteMinder 6.x objects.

Before you begin, make sure that you have the following installed:

Novell eDirectory

Novell Windows Login Client

Novell ConsoleOne for Windows, UNIX, and Netware systems

To configure Policy Store Data in a Novell eDirectory

1. From the Novell Client, navigate to the Novell directory where SiteMinder is installed:

On Windows: <siteminder_installation>\novell



On UNIX: <siteminder_installation>/novell



The Novell directory contains the following files:

Novell_Add_SM60.ldif

Novell_Delete_SM60.ldif

Novell_Upgrade_SM50_To_SM60.ldif

Novell_Upgrade_SM55_To_SM60.ldif

Readme_60.txt

2. Find the DN of the NCPServer for your Novell Server by entering the following information in a command window on the machine where you installed the Policy Server:

ldapsearch -h <host> -p <portnumber> -b <container> -s sub -D <admin_login> -

w <password>objectClass=ncpServer dn

Example: ldapsearch -h 192.168.1.47 -p 389 -b "o=nwqa47container" -s sub -D "cn=admin,o=nwqa47container" -w password objectclass=ncpServer dn

3. Manually edit the Novell_Add_SM60.ldif file by replacing every <NCPServer> variable with the value you found in the previous step.



Example: if your sample DN value is cn=servername,o=servercontainer, you would replace every instance of <NCPServer> with cn=servername,o=servercontainer.







LDAP IP Address: 123.123.12.12:3500

Root DN: o=test

Note: Novell eDirectory has a 256 character limit in the DN. The longest root DN that the SiteMinder policy store can have is 256 characters.

Admin Username: cn=admin,ou=people,o=test


Refer to the Policy Server Management guide for a complete description of the LDAP settings.




Note: Once you have a successful connection, you can modify the Novell eDirectory policy store from the machine on which the Policy Server is installed.

6. Update the LDAP Directory Server with the Novell_Add_SM60.ldif file by doing the following:

a. Open up a command prompt window.

b. Navigate to the /siteminder/novell directory.

c. Enter the command:

smldapsetup ldmod -v -fNovell_Add_SM60.ldif

Important! For Novell, you do not need to run smldapsetup ldgen as you do for other LDAP Directory Servers such as Sun Java System and Active Directory.







superuserpassword








siteminder_install


SM_Super_User_Name


superuserpassword

Specifies the password for the SiteMinder Super User.




-v







9. Refresh the LDAP server to update Novell eDirectory by completing the following:

a. From the Novell Client, open ConsoleOne.

b. Double click LDAP server from the directory tree.

c. Click the Refresh NLDAP Server Now button.




c. The stoplight icon changes from green to red.

d. Click the Start button in the Policy Server group box to restart the service.

e. Click OK to exit the Policy Server Management Console.

For UNIX systems, enter the commands stop-all followed by start-all.


More Information:

Manage an LDAP Policy Store Using smldapsetup (see page 159) Import Policy Data Using smobjimport (see page 151) Change the SiteMinder Super User Password Using smreg (see page 175)

Limitations of Policy Store Objects in Novell eDirectory

Consider the following when working with Policy Store objects in a Novell eDirectory:

When the policy store resides in Novell eDirectory, policy store objects cannot have names longer than 64 characters since eDirectory does not allow an attribute to be set to a value longer than 64. This affects Certificate Maps particularly since they routinely have long names by design.

The Policy Server does not support LDAP referrals for policy stores residing in Novell eDirectory.



Configure the Policy Server to Use OID as a Policy Store

To configure the Policy Server to use OID as a Policy Store

1. Create a domain in OID using the ODM by right-clicking Entry Management and selecting Create.

2. In the Distinguished Name dialog:

a. Click Add.

b. Select the domain.

3. Enter:

a. dc=dcbok for the Distinguished Name value.

b. dc for the dc value.

4. Do the following:

a. Create an organizational unit.

b. Select the organizational unit.

c. Enter ou=bok,dc=dcbok for Distinguished Name value and bok for the ou value.

5. Manually configure the Policy Store data.


More Information:




Configure the Policy Server to Use IBM Directory Server as Policy Store

To configure the Policy Server to use an IBM directory server as a Policy Store

1. Edit the V3.matchingrules file by adding the following line:


1.3.6.1.4.1.1466.115.121.1.27

2. Using the IBM Directory Server Configuration Tool, create/load a server suffix if one does not already exist.

3. Using the IBM Directory Server Web Administration Tool:

a. Create a new directory entry (for example, ou=Nete) for the Root DN of the policy server data.

b. Create the root nodes (ou=PolicySvr4, ou=SiteMinder, ou=Netegrity) under ou=Nete.

4. Using the IBM Directory Server Configuration Tool, add the supplied schema file V3.siteminder60, which is located in <policy_server_installation>\IBMDirectoryServer, to the Manage Schema Files section of the schema configuration.

Note: If you are upgrading from SiteMinder 4.x or 5.x, remove the old SiteMinder schema file before adding the new V3.siteminder60 file. For more information, see the Upgrade Guide.

5. Restart the IBM Directory Server.







LDAP IP Address: 123.123.12.12:3500

Root DN: o=test









8. Complete steps 5-7 in Manually Configure Policy Store Data in an LDAP Directory (see page 86).

Note: IBM Directory Server referrals are incompatible with SiteMinder.


SiteMinder Key Store Overview

Web Agents use Agent keys to encrypt and decrypt SiteMinder cookies so the data they contain can be read. The Agent uses the key to encrypt cookies before sending them to a user's browser and to decrypt cookies received from other Web Agents. When a Web Agent starts up and makes a management call request, the Policy Server supplies the current set of keys. Each time that the Web Agent polls the Policy Server, the Agent again makes the management call. The Web Agent receives the updated keys. These keys are stored in either the policy store or in a separate store.

Configure a Key Store in an Existing Policy Store

To configure a key store in an existing policy store

1. Start the Policy Server Management Console.

2. Select the Data tab to move it to the front.

3. In the Database drop-down list, select Key Store.

4. Select Use Policy Store database check box.

5. Click Apply to save the settings.

6. On the Data tab, click Test LDAP Connection to verify connectivity to the policy store in the LDAP directory.



Configure a Separate Key Store

To configure a separate key store




4. In the Storage drop-down list, select LDAP.

5. (Optional) If applicable, deselect the Use Policy Store database check box.

6. In the LDAP Key Store group box, enter the following:

a. In the LDAP IP Address field, enter the IP address (or host name) and port number of the LDAP directory, separated by a colon (:).

Example, enter 123.123.12.12:321. If the port is not specified, SiteMinder uses port 389 as the default.

b. In the Root DN field, enter the LDAP branch under which the SiteMinder policy store is located.

Example, o=airius.com.

c. In the Admin Username field, enter the DN of the LDAP directory administrator for the Policy Server being configured.

d. Example, cn=Directory Manager.

e. In the Password field, enter the LDAP directory administrator password.

f. In the Confirm Password field, re-enter the LDAP directory administrator password.

g. (Optional)If your system is communicating with the LDAP directory over SSL, select the Use SSL check box.

h. Click Apply.

7. (Optional) If you are using SSL, enter the name of the certificate database in the Netscape Certificate Database File field on the Settings tab.


9. On the Data tab, click Test LDAP Connection to verify connectivity to the LDAP directory server.

10. Click OK to save the settings and close the Console.



Migrate an Existing Policy Store into an LDAP Directory

Using the smobjexport and smobjimport tools, you can migrate policy store data from other types of databases into LDAP policy stores or move policy stores in one LDAP directory to another.

The following list identifies the supported migrations:

Oracle/SQL Server to LDAP

LDAP to LDAP

LDAP to Oracle/SQL Server

Note: The following procedure assumes you have configured a new LDAP directory as a policy store to which you will import your existing policy store.

To migrate data from one policy store to another LDAP Directory

1. Export your existing policy store into an .smdif file by doing the following:

a. Navigate to <siteminder_installation>/bin

b. Run:

smobjexport -o<filename> -d<SM_Super_User_Name>

-w<superuserpassword> -v

filename

Specifies the name of the output file to which you are exporting the data.

SM_Super_User_Name


superuserpassword


Example: smobjexport -opstore.smdif -d"SM Admin" -wPassword -v

Note: If the key store exists in the policy store, use the -k option too. By default, keys are not included in the export.

2. Run the import utility to import your old policy store into the new one:

smobjimport -i<filename> -d<SM_Super_User_Name> -w<superuserpassword> -v

filename

Specifies the name of the file to which you exported the policy store.

SM_Super_User_Name


superuserpassword




Example: smobjimport -ipstore.smdif -d"SM Admin" -wPassword -v

Note: If the key store exists in the policy store, use the -k option.


a. Verify that the Policy Server is pointing to the policy store.

b. Make sure that the key store is configured correctly.


More Information:

Manage an LDAP Policy Store Using smldapsetup (see page 159) Import Policy Data Using smobjimport (see page 151) Point the Policy Server at the Policy Store (see page 103) SiteMinder Key Store Overview (see page 99)



Point the Policy Server at the Policy Store

Once you have created a new policy store or key store, or migrated or moved an LDAP policy store, you must configure the Policy Server to use the LDAP directory. You can also use the Policy Server Management Console to configure additional Policy Servers to leverage an existing policy store in an LDAP directory.

When you use the Policy Server Management Console to change the Policy Store from ODBC to LDAP, the key store does not automatically switch to LDAP, even when it is set to use the same store as the policy store. You must manually change both to LDAP for the key store to be accepted by the Policy Server Management Console.

Note: Refer to the Policy Server Management guide for detailed information about using the Policy Server Management Console.

To point the Policy Server at the policy store







LDAP IP Address: 123.123.12.12:3500

Root DN: o=test



Note: Refer to the Policy Server Management guide for a complete description of the LDAP settings.

d. If the Policy Server is communicating with the LDAP directory over SSL, select the Use SSL check box.

e. Click Apply after you have modified the LDAP fields.

f. Click the Test LDAP Connection button to test the connection.


Configure CA SOA Security Manager Data in a Relational Database



This section describes how to configure CA SOA Security Manager data in relational database.

Relational Databases as a Policy or Key Store

The SiteMinder policy store is the repository for all policy related information. All Policy Servers in a SiteMinder installation must share the same policy store data, either directly or via replication. SiteMinder is installed with tools that allow administrators to move policy store data from one storage facility to another.

When you install the Policy Server, the default policy store is a Sun Java System (formerly Sun One/iPlanet) LDAP Directory Server or Microsoft Active Directory Application Mode. You can configure the Policy Server to use another LDAP directory or relational database as a policy store after you have completed the Policy Server installation. Also, after installation, you can use the Policy Server Management Console's Data tab to have the Policy Server point to another policy store.

The Policy Server supports the following relational databases as policy stores:

Microsoft SQL Server

Oracle

Oracle RAC 9.2.0.6

Oracle RAC 10.1.0.4

You can use either of these databases to store SiteMinder policy store data. SiteMinder keys, audit logs, token data, and session data can be stored in the policy store or in a separate database.

Storing keys in a separate database may be required to implement single sign-on functionality.

Note: For more information on key management, refer to the Policy Server Management guide.

To see which operating systems, Web Servers, databases, Web browsers, and and LDAP Directory Servers versions that SiteMinder supports, see the SiteMinder Platform Matrix for 6.0. To access this matrix, go to Technical Support site and search for the SiteMinder Platform Matrix for 6.0.







How to Configure a SiteMinder Data Store in a SQL Server Database

Configuring a SiteMinder data store in a SQL server database requires you to:

1. Create a SQL server database with a SiteMinder schema (see page 106).

2. Configure a SQL server data source (see page 108) for SiteMinder.

3. Configure policy, key, logging, session, or token data stores (see page 128).

4. Import default SiteMinder objects (see page 138) into the policy store.



Create a SQL Server Database With SiteMinder Schema

SiteMinder provides schema files to create the individual schema for storing policies, keys, logs, session data, token data (such as Encotone TeleID data), and sample users. The following schema files are provided in the <siteminder_installation>\db\SQL directory:

sm_mssql_ps.sql

Creates the SiteMinder policy store or key store (if you are storing keys in a different database) in a SQL Server database.

sm_mssql_logs.sql

Creates the schema for SiteMinder audit logs in a SQL Server database.

sm_mssql_token.sql

Creates the schema for storing token data, such as Encotone TeleID data, in a SQL Server database.

sm_mssql_ss.sql

Creates the schema for the Session Server in a SQL Server database.

smsampleusers_sqlserver.sql

(Optional) Creates the schema for SiteMinder sample users in a SQL Server database and populates the database with sample users. For example, if you look in the script, you can see a sample user named GeorgeC with a password of siteminder.

Create the database objects by running the appropriate SQL script using the SQL Server Enterprise Manager and SQL Server Query Analyzer.

Note: For information about running SQL scripts, refer to your database documentation.

You can store SiteMinder data in a single SQL Server database or run each script on its own to create a separate:

policy store

key store

logging database

token store

session store

sample users database

More Information:

Delete SiteMinder Data in ODBC Databases (see page 170)



Create the SQL Server Database for the Policy, Key, Logging, Session or Token Data Stores

If the Policy Server is installed on a UNIX machine, you need to copy the following SQL Server files from the <siteminder_installation>/db/SQL directory a temporary directory (C:\temp) on a Windows machine:

sm_mssql_ps.sql

sm_mssql_ss.sql

sm_mssql_token.sql

sm_mssql_logs.sql


In addition, make sure the SQL Server database server is installed on the Windows machine. If the Policy Server is on a Windows machine, you can run these .sql files from the <siteminder_installation>/db/SQL directory.

For a SQL Server database, run the sm_mssql_ps.sql, sm_mssql_logs.sql, sm_mssql_token.sql, and sm_mssql_ss.sql scripts to create the following SiteMinder data in a single SQL Server database:

policy store

key store

logging database

token store

session store

To run the scripts

1. Make sure the SQL Server database instance that will contain the SiteMinder data is accessible from the Policy Server machine.

2. Using the SQL Server Enterprise Manager, create the database instance for the SiteMinder data store.

Example: smdatastore.

3. Create the SiteMinder schema in a single SQL Server database:

a. Open sm_mssql_ps.sql in a text editor and copy the contents of the entire file.

b. Start the Query Analyzer and log in as the user who administers the Policy Server database information.

c. In the Query Analyzer, select the database instance you created using the SQL Server Enterprise Manager from the database drop down list at the top-middle of the screen.

d. Paste the schema from sm_mssql.sql into the query.

e. Execute the query.



4. Import the sm_mssql_logs.sql, sm_mssql_token.sql, or sm_mssql_ss.sql scripts into the same database instance by following the same procedure you used for the sm_mssql_ps.sql script.

You can also store SiteMinder data in a separate SQL Server database by running each script on its own to create a separate:

policy store

key store

logging database

token store

session store


When running the sm_mssql.sql or sm_mssql_logs.sql scripts to create SQL Server-based policy or logging stores, the following warnings are displayed:

Warning: The table 'smvariable5' has been created but its maximum row size (8746) exceeds the maximum number of bytes per row (8060). INSERT or UPDATE of a row in this table will fail if the resulting row length exceeds 8060 bytes.

Warning: The table 'smodbcquery4' has been created but its maximum row size (64635) exceeds the maximum number of bytes per row (8060). INSERT or UPDATE of a row in this table will fail if the resulting row length exceeds 8060 bytes.

Warning: The table 'smaccesslog4' has been created but its maximum row size (9668) exceeds the maximum number of bytes per row (8060). INSERT or UPDATE of a row in this table will fail if the resulting row length exceeds 8060 bytes.

These warnings are expected and do not cause any problems with the policy store or logging database.

More Information:

Create the SQL Server Database Schema For Logging (see page 188)

Configure a SQL Server Data Source for SiteMinder

If you are using ODBC, you need to configure a data source for the SQL Server wire protocol driver.



Create a SQL Server Data Source on Windows Systems

To create a SQL Server data source on Windows systems

1. Select Programs, Administrative Tools, Data Sources (ODBC) to access the ODBC Data Source Administrator.

2. Click the System DSN tab to move it to the front.

3. Click Add.

The Create New Data Source dialog box appears

4. Scroll down and select SiteMinder SQL Server Wire Protocol, and click Finish.

The ODBC SQL Server Wire Protocol Driver Setup dialog box appears.

5. In this dialog, do the following:

a. In the Data Source Name field, enter the Data Source name.

Example: SM SQL Server Wire DS.

Note: Take note of your data source name, as you will need it when configuring your ODBC database as a policy store.

b. (Optional) In the Description field, enter a description of the data source.

c. In the Server Name field, enter the name of an existing SQL server.

d. In the Database name field, enter the name of an existing database instance.

e. Click Test Connect to make sure to make sure the connection works.

f. Click OK.

The configuration is complete. Now, point the Policy Server to use the data source you just created by configuring your ODBC database as a policy store.

More Information:

Configure an ODBC Database as a Policy Store (see page 129)



Create a SQL Server Data Sources on UNIX Systems

The SiteMinder ODBC data sources are configured using a system_odbc.ini file, which you create by renaming sqlserverwire.ini, located in <policy_server_installation>/db, to system_odbc.ini. This system_odbc.ini file contains all of the names of the available ODBC data sources as well as the attributes that are associated with these data sources. This file must be customized to work for each site. Also, you can add additional data sources to this file, such as defining additional ODBC user directories for SiteMinder.

The first section of the system_odbc.ini file, [ODBC Data Sources], contains a list of all of the currently available data sources. The name before the “=” refers to a subsequent section of the file describing each individual data source. After the “=” is a comment field.

Note: If you modify of the first line of data source entry, which is [SiteMinder Data Source], take note of the change because you will need this value when configure your ODBC database as a policy store.

Each data source has a section in the system_odbc.ini file describing its attributes. The first attribute is the ODBC driver to be loaded when this data source is used by SiteMinder. The remaining attributes are specific to the driver.

Adding a SQL Server Data source involves adding a new data source name in the [ODBC Data Sources] section of the file, and adding a section that describes the data source using the same name as the data source. You need to change the system_odbc.ini file if you create a new service name or want to use a different driver. You should have entries for the Oracle or SQL drivers under [SiteMinder Data Source].

Again, to configure a SQL Server data source, you must first create a system_odbc.ini file in the <policy_server_installation>/db directory. To do this, you need to rename sqlserverwire.ini, located in <policy_server_installation>/db, to system_odbc.ini.



Configure the SQL Server Wire Protocol Driver

No client is required for the wire protocol driver.

To configure the SQL Server wire protocol driver

1. Edit the $NETE_PS_ROOT/db/system_odbc.ini file by making the following entries under [ODBC Data Sources] and [SiteMinder Data Source].

[ODBC Data Sources]

Siteminder Data Source=DataDirect 5.0 SQL Server Wire Protocol

[SiteMinder Data Source]

Driver=nete_ps_root/odbc/lib/NSmsss20.so

Description=DataDirect 5.0 SQL Server Wire Protocol

Database=SiteMinder Data

Address=myhost, 1433

QuotedId=No

AnsiNPW=No

nete_ps_root

Specifies an explicit path, rather than one with an environment variable

Example: export/smuser/siteminder.

SiteMinder Data

Specifies the SQL Server database instance name.

myhost

Specifies the SQL Server database’s IP Address.

1433

Represents the default listening port for SQL Server.

Note: If no system_odbc.ini file exists, copy and rename sqlserverwire.ini to system_odbc.ini. The sqlserverwire.ini file is located in the $NETE_PS_ROOT/db directory. You can edit these sections in the same manner to configure data sources for separate tokens, logs, keys, session, and sample users databases:

[SiteMinder Tokens Data Source]

[SiteMinder Logs Data Source]

[SiteMinder Keys Data Source]

[SiteMinder Session Data Source]

[SmSampleUsers Data Source]

2. Configure your policy, key, logging, session, or token data stores.



More Information:

Configure Policy, Key, Logging, Session or Token Data Stores (see page 128)

How to Configure a SiteMinder Data Store in an Oracle Database

Configuring a SiteMinder data store in an Oracle database requires you to:

1. Create an Oracle database with SiteMinder schema (see page 115).

2. Configure an Oracle data source (see page 118) for SiteMinder.

3. Configure policy, key, logging, session or token data stores (see page 128).

4. Import default SiteMinder objects (see page 138) into the policy store.

Note: If you are configuring an Oracle 10g database, ensure that you have met the prerequisites for Oracle 10g databases.

Prerequisites for an Oracle 10g Database

These prerequisites are applicable to an Oracle 10g database only and not to 8i or 9i. If you are using Oracle 8i or 9i, you can create an Oracle database with SiteMinder schema without having to satisfy the following prerequisites.

After installing the Oracle 10g database, you need to:

Create a table space for the policy store.

Create a user with appropriate privileges to manage this table space in the database.

More Information:

Create an Oracle Database With SiteMinder Schema (see page 115)



Create an Oracle 10g Table Space for the Policy Store

Creating a table space for the policy store is a prerequisite for an Oracle 10g database only.

To create an Oracle 10g table space for the policy store

1. In the Oracle Enterprise Manager 10g Database Control, log in as the SYSDBA user with appropriate privileges to manage the Oracle database.

2. On the Oracle global database’s configuration screen, select Administration, Tablespaces.

3. On the Tablespaces screen, click Create.

4. On the Create Tablespaces screen, enter a table space name, and click ADD.

Example: NETE_TB

5. On the Create Tablespaces: Add Datafile screen:

a. Enter a file name.

Example: NETE_TB

b. Specify the file size.

Example: 100 MB

c. Click Continue.

Oracle creates the table space and displays it on the Tablespaces screen.

Complete the prerequisites by creating a user to manage the table space for the policy store.

More Information:

Create an Oracle 10g User to Manage the Policy Store’s Table Space (see page 114)



Create an Oracle 10g User to Manage the Policy Store’s Table Space

Creating a user to manage table space for the policy store is a prerequisite for an Oracle 10g database only.

To create a user to manage table space for the policy store

1. On the Oracle global database’s configuration screen, select Administration, Users.

2. On the Create Tablespaces screen, click Create.

3. On the Create User screen, enter the:

Name for the user.

Example: NETE

Password for the user.

Default Tablespace that you created.

Temporary tablespace.

Example: TEMP

4. Click Roles.

5. Select Modify.

6. On the Modify Roles screen:

a. Select CONNECT and RESOURCE as a roles for this user.

b. Click Apply.

7. Start sqlplus in a command window, by entering:

a. sqlplus

b. the credentials for the policy store user created on the Create User screen.

8. You have complete the prerequisites for an Oracle 10g database, and can now configure a SiteMinder data store for the database.

More Information:




Create an Oracle Database With SiteMinder Schema

SiteMinder provides schema files to create the individual schema for storing policies, keys, logs, session data, token data (such as Encotone TeleID data), and sample users. The following schema files are provided in the <siteminder_installation>\db\SQL directory:

sm_oracle_ps.sql

Creates the SiteMinder policy store or key store (if you are storing keys in a different database) in an Oracle database.

sm_oracle_logs.sql

Creates the schema for SiteMinder audit logs in an Oracle database.

sm_oracle_token.sql

Creates the schema for storing token data, such as Encotone TeleID data, in an Oracle database.

sm_oracle_ss.sql

Creates the schema for the Session Server in an Oracle database.

smsampleusers_oracle.sql

(Optional) Creates the schema for SiteMinder sample users in an Oracle database and populates the database with sample users. For example, if you look in the script, you can see a sample user named GeorgeC with a password of siteminder.

Create the database objects by running the appropriate SQL script using SQL Plus for Oracle.


Note: If you are creating a schema for an Oracle database, be sure to create an Oracle user, such as SMOWNER, and run scripts as that user. This associates SiteMinder data files with the new user. It is not recommended that you create a schema with the SYS or SYSTEM users.

You can store SiteMinder data in a single Oracle database or run each script on its own to create a separate:

policy store

key store

logging database

token store

session store




More Information:




Create the Oracle Database For the Policy, Key, Logging, Session or Token Data Stores

If you are using an Oracle database, run the sm_oracle_ps.sql, sm_oracle_logs.sql, sm_oracle_token.sql, and sm_oracle_ss.sql scripts to create the following SiteMinder data in a single Oracle database:

policy store

key store

logging database

token store

session store

To run the scripts

1. Make sure the Oracle database instance that will contain the SiteMinder data is accessible from the Policy Server machine. Test the communication using tnsping or sqlplus.

2. Create the SiteMinder schema in the Oracle database:

a. Log in to Oracle with sqlplus (or some other Oracle utility) as the user who administers the Policy Server database information.

b. Import the scripts to create the SiteMinder schema:

$NETE_PS_ROOT/db/sql/sm_oracle_ps.sql

$NETE_PS_ROOT/db/sql/sm_oracle_logs.sql

$NETE_PS_ROOT/db/sql/sm_oracle_token.sql

$NETE_PS_ROOT/db/sql/sm_oracle_ss.sql

If you are using sqlplus, run the schema using an @ sign.

Example: @$NETE_PS_ROOT/db/sql/sm_oracle_ps.sql

Note: Environment variables may not function in Oracle's SQL utility. If you encounter problems when using the utility, specify an explicit path for $NETE_PS_ROOT, rather than one with an environment variable.

You can also store SiteMinder data in a separate Oracle database by running each script on its own to create a separate:

policy store

key store

logging database

token store

session store




For example, you can run the sm_oracle_logs.sql script to create a separate logging database.

More Information:

Configure an Oracle Data Source for SiteMinder (see page 118)

Configure an Oracle Data Source for SiteMinder

If you are using ODBC, you need to configure a data source for the Oracle wire protocol driver.

Note: For Windows, the Policy Server uses DataDirect 4.2 Oracle (NSora19.dll) and SQL Server (NSmsss19.dll) wire protocol drivers to connect to a policy store residing in an Oracle or SQL Server database.



Create an Oracle Data Source on Windows Systems

To create an Oracle data source on a Windows system


2. Click the System DSN tab and click Add.

The Create New Data Source dialog box appears.

3. Scroll down and select SiteMinder Oracle Wire Protocol and click Finish.

The ODBC Oracle Wire Protocol Driver Setup dialog appears.

4. Under the General tab, do the following:

a. In the Data Source Name field, enter any name you want.

Example: SM Oracle Wire DS

Note: Take note of the data source name, as you will need it when configuring your ODBC database as a policy store.

b. (Optional) In the Description field, enter a description of the Oracle wire protocol data source.

c. In the Host field, enter the machine name where the Oracle database is installed.

d. In the Port Number field, enter the port number where Oracle is listening on the machine.

e. In the SID field, enter the service name of the Oracle instance that you want to connect, which you specified in the tnsnames.ora file. The SID is the system identifier for the database instance.

Note: Due to a limitation of the Oracle wire protocol driver (NSORA19.dll), you can only enter 10 characters or less in the SID field.

The tnsnames.ora file contains service names and details that Oracle uses to identify and connect to Oracle instances. For example, if the tnsnames.ora file contains the following entry for an Oracle instance, enter instance1 in the SID field.

instance1 = (DESCRIPTION = (ADDRESS = (PROTOCOL = TCP)(Host = myhost)(Port =1521)) (CONNECT_DATA = (SID = SIDofinstance1)) )

f. Test the connection with the database by clicking Test Connect.

5. Click OK to save the selections and exit the ODBC Oracle Wire Protocol Driver Setup.

The configuration is complete. Now, configure SiteMinder to use the data source you just created.



More Information:




Create an Oracle RAC Data Source on Windows Systems

Oracle RAC 9.2.0.6 and 10.1.0.4 instances can be configured with the Policy Server as a single data source name similar to that of a single instance Oracle database. However, the data source name for Oracle RAC is different than a regular ODBC data source.

In an Oracle RAC system, in addition to the SID or ServiceName for each Oracle instance, there is also a ServiceName for the entire Oracle RAC system. When configuring a data source, configure the data source name to use this ServiceName when connecting to an Oracle RAC.

To configure an Oracle RAC data source


2. Click the System DSN tab, and then click Add.


3. Scroll down and select SiteMinder Oracle Wire Protocol and click Finish.

The ODBC Oracle Wire Protocol Driver Setup dialog appears.


a. In the Data Source Name field, enter any name for the data source.

Note: Take note of the data source name, as you will need it when configuring your ODBC database as a policy store.

b. In the Host field, enter the IP address of the first node in the Oracle RAC system. For Oracle RAC 10g, specify the virtual IP address.

c. In the Service Name field, enter the service name for the entire Oracle RAC system. For example, in the following tnsnames.ora file, the value SMDB is the service name for the entire Oracle RAC system (consisting of 3 nodes).

SMDB =

(DESCRIPTION =

(ADDRESS = (PROTOCOL = TCP)(HOST = nete_servername1)(PORT = 1521))



(LOAD_BALANCE = yes)

(CONNECT_DATA =

(SERVER = DEDICATED)



(SERVICE_NAME = SMDB)

)

5. Under the Failover Tab, do the following:

a. In the Alternate Servers field, specify the host name (virtual IP address), port number, and service name for all the remaining Oracle RAC nodes in the environment. The ServiceName is service name for the entire Oracle RAC system.

b. Specify the AlternateServers to provide connection failover to the other Oracle nodes if the primary server is not accepting connections. The entry should have the following format:

(HostName=nete_servername2:PortNumber=1521:ServiceName=nete_servicename[, . . . ])

c. Check the LoadBalancing option. This turns on the client load balancing to help distribute new connections to keep RAC nodes from being overwhelmed with connection requests. When client load balancing is enabled, the order in which primary and alternate database servers are accessed is random.


The configuration is complete. Now, configure SiteMinder to use the data source you created.

More Information:




Create an Oracle Data Source on UNIX Systems

The SiteMinder ODBC data sources are configured using a system_odbc.ini file, which you create by renaming oraclewire.ini, located in <policy_server_installation>/db, to system_odbc.ini. This system_odbc.ini file contains all of the names of the available ODBC data sources as well as the attributes that are associated with these data sources. This file must be customized to work for each site. Also, you can add additional data sources to this file, such as defining additional ODBC user directories for SiteMinder.

The first section of the system_odbc.ini file, [ODBC Data Sources], contains a list of all of the currently available data sources. The name before the “=” refers to a subsequent section of the file describing each individual data source. After the “=” is a comment field.

Note: If you modify of the first line of data source entry, which is [SiteMinder Data Source], take note of the change because you will need this value when configure your ODBC database as a policy store.

Each data source has a section in the system_odbc.ini file describing its attributes. The first attribute is the ODBC driver to be loaded when this data source is used by SiteMinder. The remaining attributes are specific to the driver.

Adding an Oracle Data source involves adding a new data source name in the [ODBC Data Sources] section of the file, and adding a section that describes the data source using the same name as the data source. You need to change the system_odbc.ini file if you create a new service name or want to use a different driver. You should have entries for the SQL Server or Oracle drivers under [SiteMinder Data Source].

Again, to configure an Oracle data source, you must first create a system_odbc.ini file in the <policy_server_installation>/db directory. To do this, you need to rename oraclewire.ini, located in <policy_server_installation>/db, to system_odbc.ini.

Note: For UNIX systems, the Policy Server uses DataDirect 5.0 Oracle wire protocol drivers to connect to a policy store residing in an Oracle database.



Configure the Oracle Wire Protocol Driver

To configure the Oracle wire protocol driver

1. Edit the $NETE_PS_ROOT/db/system_odbc.ini file by replacing the nete_serverid value for SID with the value that is appropriate for your Oracle instance. If no system_odbc.ini file exists, copy and rename oraclewire.ini to system_odbc.ini. The SID is the system identifier for the database instance. In the following tnsnames.ora file, the value instance1 is the SID.

instance1 = (DESCRIPTION = (ADDRESS = (PROTOCOL = TCP)(Host = myhost)(Port =1521)) (CONNECT_DATA = (SID = instance1)) )

The modified text for the policy store’s data source should appear as follows:

[SiteMinder Data Source]

Driver=nete_ps_root/odbc/lib/NSora21.so

Description=DataDirect 5.0 Oracle Wire Protocol

LogonID=uid

Password=pwd

HostName=nete_servername

PortNumber=1521

SID=nete_serverid

CatalogOptions=0

ProcedureRetResults=0

EnableDescribeParam=0

EnableStaticCursorsForLongData=0

ApplicationUsingThreads=1

nete_ps_root

Specifies the explicit path rather than one with an environment variable.

uid

Specifies the user name of the database account that has full access rights to the database.

pwd

Specifies the password for the user.

nete_servername

Specifies the machine name where the Oracle database is installed.

nete_serverid

Specifies the SID.



Note: You should only enter 10 characters or less for the SID value due to a limitation of the Oracle wire protocol driver.

You can edit these sections in the same manner to configure data sources for separate tokens, logs, keys, session, and sample users databases:

[SiteMinder Tokens Data Source]

[SiteMinder Logs Data Source]

[SiteMinder Keys Data Source]

[SiteMinder Session Data Source]

[SmSampleUsers Data Source]

2. Configure your policy, key, logging, session, or token data stores.

More Information:

Configure Policy, Key, Logging, Session or Token Data Stores (see page 128)



Create an Oracle RAC Data Source on UNIX Systems

Oracle RAC 9.2.0.6 and 10.1.0.4 instances can be configured with the Policy Server as a single data source name similar to that of a single instance Oracle database. However, the data source name for Oracle RAC is different than a regular ODBC data source. In an Oracle RAC system, in addition to the SID or ServiceName for each Oracle instance, there is also a ServiceName for the entire Oracle RAC system. When configuring a data source, configure the data source name to use this ServiceName when connecting to an Oracle RAC.

To configure an Oracle RAC data source

1. Go to NETE_PS_ROOT/db

NETE_PS_ROOT

Specifies the SiteMinder installation directory.

2. Create a copy of the existing system_odbc.ini file.

3. Create a new system_odbc.ini file by copying the oraclewire.ini file to system_odbc.ini.

4. Modify the system_odbc.ini file as follows:

a. Insert the ServiceName field.

b. Insert the AlternateServers field.

c. Insert the LoadBalancing field.

d. Remove or comment the SID field.

5. In the ServiceName field, enter the ServiceName for the entire Oracle RAC system. For example, in the following tnsnames.ora file, the value SMDB is the ServiceName for the entire Oracle RAC system (consisting of 3 nodes).

SMDB =

(DESCRIPTION =




(LOAD_BALANCE = yes)

(CONNECT_DATA =

(SERVER = DEDICATED)

(SERVICE_NAME = SMDB)

)



)

The modified text for a data source should appear as follows:

[Data Source Name]

Driver=nete_ps_root/odbc/lib/NSora21.so

Description=DataDirect 5.0 Oracle Wire Protocol

LogonID=uid

Password=pwd

HostName=nete_servername1

PortNumber=1521

ServiceName=nete_servicename

CatalogOptions=0

ProcedureRetResults=0

EnableDescribeParam=0

EnableStaticCursorsForLongData=0

ApplicationUsingThreads=1

AlternateServers=(HostName=nete_servername2:PortNumber=1521:ServiceName=nete_

servicename[, . . . ])

LoadBalancing=1

nete_ps_root

Specifies an explicit path to the directory where SiteMinder is installed.

uid

Specifies is the username of the database account

pwd

Specifies the password for the user.

nete_servername1

Specifies the IP address of the first Oracle RAC node. For Oracle RAC 10g, it specifies the virtual IP address.

nete_servicename

Specifies the ServiceName for the entire Oracle RAC system.

AlternateServers

Specifies the Hostname (virtual IP address), PortNumber, and ServiceName for the remaining Oracle RAC nodes in the environment.

ServiceName

Specifies service name for the entire Oracle RAC system. Specifying the AlternateServers provides connection failover to the other Oracle nodes, if the primary server is not accepting connections.

LoadBalancing=1

Turns on client load balancing, which helps distribute new connections to keep RAC nodes from being overwhelmed with connection requests.



When enabled, the order in which primary and alternate database servers are accessed is random.

The configuration is complete. Now, configure SiteMinder to use the data source you just created.

More Information:


Configure Policy, Key, Logging, Session or Token Data Stores

You can use an Oracle or SQL Server database to store SiteMinder policy store data. SiteMinder keys, audit logs, token data, and session data, can be stored in the policy store or in a separate database.



Configure an ODBC Database as a Policy Store

To configure an ODBC database as a policy store



3. In the Storage drop-down list, select ODBC.

4. In the Database drop-down list, select Policy Store.

5. In the Data Source Information field, enter the name of the data source.

For Windows systems, this name must correspond to the name you entered in the Data Source field of the ODBC Oracle Wire Protocol Driver Setup dialog box, when you created your Oracle data source or to the name you entered in the Data Source field of the ODBC SQL Server Wire Protocol Driver Setup dialog box when you created your SQL data source.

For UNIX systems, the value you enter must match the first line of the data source entry in the system_odbc.ini file when you created your SQL server data sources or your Oracle data sources. This file is located in $NETE_PS_ROOT/db. For example, the first line of the default entry in the system_odbc.ini file is [SiteMinder Data Source], so you would enter SiteMinder Data Source in the Data Source Name field. If you modified the entry in the system_odbc.ini file, you would enter that value in the Data Source Information field.

Note: When entering the data source name, do not include the brackets.

6. In the User Name and Password fields, enter the username and password of the database account that has full access rights to the Oracle or SQL Server database instance.

7. In the Confirm Password field, re-enter the password.

8. Specify the maximum number of database connections allocated to SiteMinder. For best performance, retain the default of 25 connections.

9. (Optional) Click Test Connection to make sure the connection works.


11. Click the Status tab.

12. Stop and restart the Policy Server.

More Information:

Create an Oracle Data Source on Windows Systems (see page 119) Create an Oracle Data Source on UNIX Systems (see page 123) Create a SQL Server Data Source on Windows Systems (see page 109) Create a SQL Server Data Sources on UNIX Systems (see page 110)



Store Keys, Logging, Token, and Session Data in the Policy Store

You can store keys, logging, token, and session information in the policy store to simplify administration tasks.

Note: The following procedures assume you are working with an Oracle or SQL Server database for which you have imported sm_oracle_ps.sql or sm_mssql_ps.sql, respectively. Each of these files hold key store and policy data. If you have not, create an Oracle or SQL Server database for policy, key, logging, session, and token data stores.

More Information:

Create the SQL Server Database for the Policy, Key, Logging, Session or Token Data Stores (see page 107) Create the Oracle Database For the Policy, Key, Logging, Session or Token Data Stores (see page 117)



Store Key, Logging, Token, and Session Information in an Oracle Database

To store keys, logging, token, and session information in an Oracle database

1. Make sure the Oracle database instance that will contain the SiteMinder data is accessible from the Policy Server machine. Test the communication using tnsping or sqlplus.

2. Create the SiteMinder schema in the Oracle database

a. Log in to Oracle with sqlplus or another Oracle utility as the user who administers the Policy Server database information.

b. Import one or more of the following scripts to create the respective SiteMinder schema:

$NETE_PS_ROOT/db/sql/sm_oracle_ps.sql Creates the SiteMinder policy store; or if you are storing keys in different database, creates a key store.

$NETE_PS_ROOT/db/sql/sm_oracle_logs.sql Creates the schema for SiteMinder audit logs in an Oracle database.

$NETE_PS_ROOT/db/sql/sm_oracle_token.sql Creates the schema for storing token data, such as Encotone TeleID data, in an Oracle database.

$NETE_PS_ROOT/db/sql/sm_oracle_ss.sql Creates the schema for the Session Server in an Oracle database.


Example: @$NETE_PS_ROOT/db/sql/sm_oracle_ps.sql

Note: Environment variables may not function in Oracle's SQL utility. If you encounter problems when using the utility, specify an explicit path for $NETE_PS_ROOT, rather than one with an environment variable.

3. In the Policy Server Management Console, click the Data tab to move it to the front.


5. Select the Use the policy store database check box and click Apply.

6. In the Database drop-down list, select Audit Logs.


8. In the Database drop-down list, select Token Data.


10. Click Test Connection to verify connectivity to the database server.

If it returns a success message, click OK to save the settings and exit.



If it returns a failure message, go back and recheck your data source settings.



Store Key, Logging, Token, and Session Information in a SQL Server Database

To store keys, logging, token, and session information in a SQL Server database

1. Make sure the SQL Server database instance that will contain the SiteMinder data is accessible from the Policy Server machine.

2. Using the SQL Server Enterprise Manager, create the database instance for the information type you want.

3. Create the SiteMinder schema in the database:

a. Open one schema file in a text editor and copy the contents of the entire file. The schema files include:

sm_mssql_ps.sql Creates the SiteMinder policy store; or, if you are storing keys in a different database, creates a key store.

sm_mssql_logs.sql Creates the schema for SiteMinder audit logs.

sm_mssql_tokens.sql Creates the schema for storing token data, such as Encotone TeleID data.

sm_mssql_ss.sql Creates the schema for the Session Server.


c. In the Query Analyzer, select the desired database instance from the database drop down list at the top-middle of the screen.

d. Paste the copied schema into the query.


Note: Running sm_mssql_logs.sql causes warnings to display. These warnings are expected and do not cause problems with the policy store or logging database.

4. Repeat steps 2-3 for the remaining files.






10. In the Database drop-down list, select Token Data.





If it returns a success message, click OK to save the settings and exit.

If it returns a failure message, go back a recheck your data source settings.



Configure a Database to Store Keys, Audit Logs or Token Data

SiteMinder keys, audit logs, and token information can all be stored in separate databases.

Before configuring a SQL Server or Oracle database to store keys, audit logs or token data, make sure you have created and configured a separate database using all of the steps described in this chapter for configuring a relational database as a policy store.

Note: Storing keys in a separate database may be required to implement single sign-on functionality. Refer to the Policy Server Management guide for detailed information on key management. Audit Logs and Token Data databases require that you import different .sql files when importing initial data into your policy store.

The following procedure assumes that you have imported sm_mssql_logs.sql and sm_mssql_tokens.sql if you are working with a SQL Server database or $NETE_PS_ROOT/db/sql/sm_oracle_logs.sql and $NETE_PS_ROOT/db/sql/sm_oracle_token.sql if you are working with an Oracle database.

To point SiteMinder to store keys, audit logs and token data in different databases:


2. In the Database drop-down list, select Key Store, Audit Logs, or Token Data.

3. Deselect the Use the policy store database check box and click Apply.

The fields in the Data Source Information group box become active.


For Windows Systems:

This name must correspond to the name you entered in the Data Source field of the ODBC Driver Setup dialog box.

For UNIX Systems:

The value you enter must match the first line of the data source entry in the system_odbc.ini file. This file is located in $NETE_PS_ROOT/db. For example, the first line of the default entry in the system_odbc.ini file is [SiteMinder Data Source] so you would enter SiteMinder Data Source in the Data Source Name field. If you modify the entry in the system_odbc.ini file, you would enter that value in the Data Source Information field.

Note: When entering the data source name, do not include the brackets.



5. In the User Name and Password fields, enter the username and password of the database account that has full access rights to the database.







Configure a Database as a Session Store

Before configuring a relational database to store session data, make sure you have:

Created a separate session server database using sm_oracle_ss.sql or sm_mssql_ss.sql.

Create a SQL Server Database With SiteMinder Schema (see page 106)


Configured a SiteMinder Session Server Data Source for your respective database.

Configure a SQL Server Data Source for SiteMinder (see page 108)

Configure an Oracle Data Source for SiteMinder (see page 118)

To point SiteMinder to store session data in a relational database:


2. In the Database drop-down list, select Session Server.


4. Select the Session Server enabled check box and click Apply.


Example: SiteMinder Session Data Source.

Note: This name must correspond to the name you entered in the Data Source field of the ODBC Driver Setup dialog box.

6. In the User Name and Password fields, enter the username and password of the database account that has full access rights to the database.







Import Default SiteMinder Objects into the Policy Store

You can import data into a policy store to import required SiteMinder objects stored in smpolicy.smdif. When creating a new policy store, you must import the default SiteMinder objects into the policy store. If you do not, SiteMinder will not work.

To import the required policy store objects

1. On the machine where the Policy Server is installed, navigate to <siteminder_installation>/bin





superuserpassword

Specifies the password for the SiteMinder Super User account. The password in case-insensitive, except in cases where the password is stored in an Oracle policy store. The default administrator name is SiteMinder. Once the Oracle policy store is setup, administrator user names for the Policy Server User Interface become case sensitive.









SM_Super_User_Name


superuserpassword


If an argument contains spaces, use double quotes around the entire argument.



Windows example: smobjimport -i “C:\Program Files\Netegrity\siteminder\db\smdif\smpolicy.smdif” -d"SM Admin" -wPassword -v


-v








The stoplight icon changes from green to red.

c. Click the Start button in the Policy Server group box to restart the service.

d. Click OK to exit the Policy Server Management Console.

For UNIX systems, enter the commands stop-all followed by start-all.


More Information:

Import Policy Data Using smobjimport (see page 151) Change the SiteMinder Super User Password Using smreg (see page 175)



Migrate an Existing Policy Store into a Relational Database

Using the smobjexport and smobjimport tools, you can migrate policy store data from other types of LDAP into database policy stores or move policy stores in one database to another.

The following list identifies the supported migrations:

Oracle/SQL Servers to LDAP

Oracle/SQL Server to Oracle/SQL Severs

LDAP to Oracle/SQL Server

The following procedure assumes you have created a SiteMinder data store in either an Oracle database or a SQL Server database to which you will export your data. Details exist in How to Configure a SiteMinder Data Store in a SQL Server Database (see page 105) and How to Configure a SiteMinder Data Store in an Oracle Database (see page 112).

To migrate data from one policy store to a Database

1. Export your existing policy store into an .smdif file by doing the following:

a. Navigate to <siteminder_installation>/bin

b. Run:

smobjexport -o<filename> -d<SM_Super_User_Name>

-w<superuserpassword> -v

filename

Specifies the name of the output file to which you are exporting the data.

SM_Super_User_Name


superuserpassword


Example:smobjexport -opstore.smdif -d"SM Admin" -wPassword -v

Note: If the key store exists in the policy store, use the -k option. By default, keys are not included in the export.

2. Run the import utility to import your old policy store into the new one:

smobjimport -i<filename> -d<SM_Super_User_Name> -w<superuserpassword> -v

filename

Specifies the name of the file to which you exported the policy store.

SM_Super_User_Name




superuserpassword


Example: smobjimport -ipstore.smdif -d"SM Admin" -wPassword -v

Note: If the key store exists in the policy store, use the -k option.

3. Verify that the Policy Server is pointing to the policy store.


More Information:

Point the Policy Server at the Policy Store (see page 142) Import Policy Data Using smobjimport (see page 151)



Point the Policy Server at the Policy Store

Once you have created a new policy store or key store, or migrated or moved an ODBC policy store, you must configure the Policy Server to use the ODBC database. You can also use the Policy Server Management Console to configure additional Policy Servers to leverage an existing policy store in an ODBC database.

When you use the Policy Server Management Console to change the Policy Store from LDAP to ODBC, the key store does not automatically switch to ODBC, even when it is set to use the same store as the policy store. You must manually change both to ODBC for the key store to be accepted by the Policy Server Management Console.

Note: Refer to the Policy Server Management guide for detailed information about using the Policy Server Management Console.

To point the Policy Server at the policy store







LDAP IP Address: 123.123.12.12:3500

Root DN: o=test




d. (Optional) If the Policy Server is communicating with the LDAP directory over SSL, select the Use SSL check box.

e. Click Apply after you have modified the LDAP fields.

f. Click the Test LDAP Connection button to test the connection.

If the connection is successful, SiteMinder returns a confirmation. If it is not successful, SiteMinder returns an error message. If you receive an error message, verify that the values you entered are correct and that the database is running.



Create a Sample User Directory for Oracle or SQL Server

SiteMinder provides schema files to create sample users to populate a user directory for the Policy Server. The following schema files are provided in the \siteminder\db\Sql directory:

smsampleusers_oracle.sql

Creates the schema for SiteMinder sample users in an Oracle database and populates the database with sample users. For example, if you look in the script, you can see a sample user named GeorgeC with a password of siteminder.


Creates the schema for SiteMinder sample users in a SQL Server database and populates the database with sample users. For example, if you look in the script, you can see a sample user named GeorgeC with a password of siteminder.

Note: These user directories are optional since your environment will have different ones.

Create the database objects by running the appropriate SQL script(s) using SQL Plus for Oracle or the SQL Server Enterprise Manager and SQL Server Query Analyzer.


More Information:




Create a Sample User Directory for Oracle

If you are using an Oracle database as a user directory, run the smsampleusers_oracle.sql script to create a schema for it.

To create a sample Oracle user directory

1. Make sure the Oracle database instance that will contain the SiteMinder sample user data is accessible from the Policy Server machine. Test the communication using tnsping or sqlplus.

2. Create the sample user directory schema in the Oracle database:


b. Import the script to create the sample users schema:

$NETE_PS_ROOT/db/sql/smsampleusers_oracle.sql


Example: @$NETE_PS_ROOT/db/sql/smsampleusers_oracle.sql

Note: Environment variables may not function in Oracle's SQL utility. If you encounter problems when using the utility, specify an explicit path for $NETE_PS_ROOT rather than one with an environment variable.

Policy Server Tools


Create a Sample User Directory for SQL Server

If you are using a SQL Server database as a user directory, run the smsampleusers_sqlserver.sql script to create a schema for it.

To create a sample SQL Server user directory

1. Make sure the SQL Server database instance that will contain the SiteMinder sample user data is accessible from the Policy Server machine.

2. Using the SQL Server Enterprise Manager, create the database instance for the sample user directory.

Example: smuserstore.

3. Create the SiteMinder schema in the SQL Server database:

a. Open smsampleusers_sqlserver.sql in a text editor and copy the contents of the entire file.


c. In the Query Analyzer, select the smuserstore database instance from the database drop down list at the top middle of the screen.

d. Paste the sample users schema from smsampleusers_sqlserver.sql into the query.


Policy Server Tools SiteMinder provides a number of administrative tools to help manage the SiteMinder environment. The following list describes the function of each tool:

XPSImport and XPSExport

Imports and exports policy store data in XML format.

smobjexport

Contains arguments that let you export an entire policy store; a specified policy domain; the specified policy domain and all system objects used by the policy domain, such as administrators, Agents, authentication schemes and user directories; Agent keys stored in the policy store along with the rest of the policy store data. By default, keys are not included in the export; only the Agent keys stored in the policy store; variables only.

smobjimport

Imports policy data into the SiteMinder policy store.

smldapsetup

Manages the SiteMinder policy store in an LDAP directory.

Policy Server Tools


ODBC database SQL scripts

Removes SiteMinder policy store, token data, and log schema from ODBC databases.

smpatchcheck

Checks to make sure all of the required/recommended patches are installed on your Solaris machine.

smreadclog

Reads RADIUS log files generated by the Policy Server.

SiteMinder Token Tool

Preloads information about hardware tokens.

smreg

Changes the SiteMinder Super User password.

Requirement When Using the Policy Server Tools on Linux Red Hat

For the Policy Server tools (smreg, smobjimport, smobjexport) to work correctly on a Linux Red Hat operating system, you must define the Policy Server host name in /etc/hosts. The host name must be defined in this location because these utilities generate adminoids and OIDs. The operating system uses the gethostid() and gettimeofday() Linux functions when generating these OIDs.

Policy Server Tools


Export Policy Data Using smobjexport

The smobjexport tool exports the entire policy store or a single policy domain by creating two files: an .smdif (SiteMinder Data Interchange Format) and .cfg (environment configuration) file. The .smdif file standardizes SiteMinder data so you can import it to a different type of policy store. For example, you can export an .smdif file from an ODBC database and import it to an LDAP directory. The environment configuration (.cfg) file contains environment-specific properties for the policy store such as IP Addresses, redirection URLs, shared secrets, agent names, logging settings, and .com extensions. Only the 5.0, 5.5, and 6.x versions of smobjexport create an environment configuration file, as this feature is not available for previous versions. The text in the .cfg file is separated by tabs and you can edit it as a tab-delimited file in any text editor or Microsoft Excel.

Note: Using the Scripting Interface, you can write Perl scripts to import and export particular objects rather than all the Policy Store objects. For more information, see the CA eTrust SiteMinder Scripting Guide for Perl.

The following table describes the four fields of a sample registration scheme entry from the .cfg file.

Object OID Object Class Property Type Value

<reg scheme OID> SelfReg RegistrationURL http://your.url.com

Policy Server Tools


The Object OID column is represented only by the <OID> variable since OIDs such as the following are too long to fit:

<reg scheme OID> = 0d-6dc75be0-1935-11d3-95cc-00c04f7468ef

Each entry's fields--Object OID, Object Class, Property Type, Value--can be edited in a text editor or Excel.

Note: For backward compatibility purposes, the smobjexport command line only references the .smdif file. As a result, the corresponding environment configuration file is created according to the following naming convention: if the output file you specify with the smobjexport command has an .smdif extension (for example, <filename>.smdif), then the extension is replaced with .cfg (such as <filename>.cfg) for the configuration file. However, if the output file you specify does not have an .smdif extension (for example, <filename>.txt), then .cfg is appended to file name and extension (such as <filename>.txt.cfg).

smobjexport uses the following arguments to supply information required to export the data:

-o<file-name>

Specifies the path and filename of the output .smdif file. If this argument is not specified, the default output file names are stdout.smdif and stdout.cfg. This filename should be a name other than the one used for smldapsetup ldgen -f<filename>, otherwise the export will be overwritten.

-f

Overwrites an existing output file.

-s<domain-name>

Exports only the specified policy domain.

-e<domain-name>

Exports the specified policy domain as well as all system objects used by the policy domain, such as administrators, Agents, authentication schemes, and user directories.

Note: The -e option does not support exporting Affiliate domains.

-c

Exports sensitive data as clear-text. Exporting data as clear-text allows you to migrate policy data from a SiteMinder deployment that uses one encryption key to another SiteMinder deployment that uses a different encryption key. To use -c, you must enter the credentials of a SiteMinder administrator who can manage all SiteMinder domain objects. Enter credentials using the -d and -w arguments.

-d<admin-name>

Policy Server Tools


Specifies the login name of a SiteMinder Administrator that can manage all SiteMinder objects in the policy store being exported.

-w<admin-pw>

Specifies the password of the SiteMinder Administrator specified using -d.

-k

Exports Agent keys stored in the policy store along with the rest of the policy store data. By default, keys are not included in the export.

-x

Exports only the Agent keys stored in the policy store.

-v

Enables verbose mode.

-t

Enables low level tracing mode. This mode can be used to troubleshoot the export process.

-u

Export variables only.

-l

Creates a log file. Make sure the <filename>.smdif file ends with an .smdif and not a .txt or other extension. If the <filename>.smdif file ends with an .smdif extension, smobjexport creates a log file with a .log extension. However, if the <filename>.smdif file ends with a .txt extension, smobjexport creates a <filename>.txt.log file, which is incorrect since the log file must be in the <filename>.log format.

-m

Exports IdentityMinder objects only.

-i

Exports specific IdentityMinder objects and all relevant system objects.

-j

Exports a specific IdentityMinder directory and all relevant system objects.

-?

Displays the help message.

Note: If the arguments contain spaces, use double quotes around the entire argument. For example, if the name of the SiteMinder administrator is SiteMinder Admin, the argument for smobjexport would be -d" SiteMinder Admin"

To export data using smobjexport

Policy Server Tools


1. Navigate to one of the following locations:

On Windows, policy_server_installation\bin



Note: For a complete listing of the smobjexport parameters, enter smobjexport -? at a command prompt.

On UNIX, <siteminder installation>/bin




smobjexport -o<file-name>.smdif -c -d<admin-name> -w<admin-pw> -v -t

file-name

Specifies the name of the .smdif output file that will contain the exported policy store data

admin-name

Specifies the name of a SiteMinder administrator that can manage all SiteMinder objects

admin-password

Specifies the password for the specified SiteMinder administrator.

Note: Ensure the <filename>.smdif file ends with a .smdif and not a .txt extension.

Example: smobjexport -opstore.smdif -c -dSiteMinder -wpassword -v -t

Note: The -o<file-name> argument should use a filename other than the one used for smldapsetup ldgen -f<file-name>, otherwise the export may be overwritten.

Policy Server Tools


Export Policy Store Objects With Dependencies

When exporting policy store objects with dependencies by either running smobjexport with the –e option or by using the migration methods in the Command Line Interface:

If any of the object’s dependencies is a Host Configuration Object, then all Host Configuration Objects are exported.

If any of the object’s dependencies is an Agent Configuration Object, then all Agent Configuration Objects are exported.

If any of the object’s dependencies is an affiliate (when Policy Server Option Pack is installed), then the entire affiliate domain to which the affiliate belongs is exported.

Note: The -e option does not support exporting Affiliate domains.

Import Policy Data Using smobjimport

The smobjimport tool imports the entire policy store or a single policy domain using two files--an .smdif (SiteMinder Data Interchange Format) and a .cfg (environment configuration) file--created by smobjexport. The .smdif file standardizes SiteMinder data so you can import it into an ODBC or LDAP directory. For example, you can export an .smdif file from an ODBC database and import it to an LDAP directory. The environment configuration (.cfg) file contains environment specific properties for the policy store such as the IP Addresses, redirection URLs, shared secrets, and logging settings. The text in the .cfg file is separated by tabs and you can read it in an Excel spreadsheet.

Using the Command Line Interface, you can write Perl scripts to import and export particular objects rather than all the Policy Store objects.

Note: The naming convention for smobjimport is the same as smobjexport in that it supports an .smdif file and .cfg file. Using smobjexport as an example, if the output file you specified with the smobjexport command has an .smdif extension (that is, <filename>.smdif), then the extension is replaced with .cfg (such as <filename>.cfg) for the configuration file. However, if the output file you specify does not have an .smdif extension (that is, <filename>.txt), then .cfg is appended to file name and extension (such as <filename>.txt.cfg).

smobjimport uses the following arguments to supply information required to import data:

-4

Allows you to import policy store data from SiteMinder 4.51/4.61.

-i<file-name>

Specifies the path and filename of the input .smdif file.

Policy Server Tools


-f

Indicates that duplicate information should be overwritten. Be careful using this argument as it enables you to overwrite default SiteMinder objects that may have been imported into a new policy store by using smpolicy.smdif.

-c

Indicates that the input file contains sensitive data in clear-text. This argument allows to you import policy data from a SiteMinder deployment that uses one encryption key to another SiteMinder deployment that uses a different encryption key. This option requires the credentials of a SiteMinder administrator who can manage all SiteMinder domain objects. Enter credentials using the -d and -w arguments.

-d<admin-name>

Specifies the login name of a SiteMinder Administrator that can manage all SiteMinder objects.

-w<admin-pw>

Specifies the password of the SiteMinder Administrator specified in -d.

-k

Imports Agent keys stored in the policy store. If you import using this argument, and the policy store to which you are importing already contains keys, single sign-on for existing users may be interrupted. Note that keys are created each time you start the Policy Server.

-v

Enables verbose mode.

-t

Enables low level tracing mode. This can be used to troubleshoot the import process.

-l

Creates a log file. Make sure the <filename>.smdif file ends with an .smdif and not a .txt or other extension. If the <filename>.smdif file ends with an .smdif extension, smobjimport creates a log file with a .log extension. However, if the <filename>.smdif file ends with a .txt extension, smobjimport creates a <filename>.txt.log file, which is incorrect since the log file must be in the <filename>.log format.

Policy Server Tools


-r

Turns off automatic renaming of objects. By default, when smobjimport attempts to import an object with a name that already exists in the target policy store, it creates a duplicate object with a name of <name><oid>, where <name> is the name of the object, and <oid> is the object ID of the new duplicate object. If you use this flag to turn off the automatic renaming feature, smobjimport returns errors messages for any objects that could not be created because of naming conflicts.

-u

Import variables only.

-m

Import IdentityMinder objects only.

+m

Import SiteMinder objects only.

-?


-a1

Disables object store validation and helps increase the speed at which objects are imported.

Important! This parameter should only be used when importing data into a new policy store and when the imported .smdif file is consistent with regards to policy store objects.

-a2

Disables object store auditing and helps increase the speed at which objects are imported.

-a3

Disables object store cache updates and helps increase the speed at which objects are imported.

Important! Do no use this parameter when importing data into an existing policy store with more than one policy store pointing at it. Using this parameter disables cache synchronization between the Policy Servers.

-a

Same as setting -a1, -a2, and -a3 together.

Important! This should only be used on a new policy store. Do not use this parameter when importing data into an existing policy store since it could corrupt the policy store.

Policy Server Tools


Note: If any of the arguments contain spaces, use double quotes around the entire argument. For example, if the name of the SiteMinder administrator is SiteMinder Admin, the argument for smobjimport would be -d"SiteMinder Admin". If the description of a SiteMinder object specified in the Policy Server User Interface is more than one line long, smobjimport will only import the first line of the description.

To import Policy data using smobjimport


On Windows, <siteminder_installation>\bin



On Unix, <siteminder installation>/bin




smobjimport -i<filename> -d<admin-name> -w<admin-pw> -v -t

Example: smobjimport -ipstore.smdif -dSiteMinder -wpassword -v -t

Note: You only need to enter the .smdif file with the smobjimport command, since it automatically imports both the .smdif and .cfg files together if they are in the same directory. The environment properties stored in the .cfg file take precedence over the ones in the .smdif file. Thus, you can overwrite an environment’s data by pairing the .smdif file with a different .cfg file when running smobjimport.

Import 4.51/4.61 Policy Data Using smobjimport

The smobjimport tool allows you to import 4.51/4.61 .smdif files into a 6.x policy store using the -4 argument. You can do this by entering the following command: smobjimport -i<filename> -d<admin-name> -w<admin-pw> -v -4 -t

Example: smobjimport -ipstore.smdif -dSiteMinder -wpassword -v -4 -t

The 4.51/4.61 version of smobjexport does not create an environment configuration file so you only need to import the <filename>.smdif file.

Policy Server Tools


Migrate 6.x Policy Stores With Different Environments

The following sections detail migrating 6.x policy stores with in different environments.

Example 1 Policy Stores with Different Objects and Environments

In this example, there are two policy stores--one for test.com and another for production.com--containing different objects and environments. The goal is to migrate and override existing policy store data objects in production.com with those from test.com but keep production.com’s environment settings by following the steps listed in the following figure.

Policy Data (Test.com)Environment Data

(Test.com)

Test.com Policy Store

test.smdif test.cfg

Policy Data (Test.com)Environment Data(Production.com)

Production.comPolicy Store

(after migration)

1

3

2 Change values toproduction.com

Policy Server Tools


1. Export the Test.com policy store into test.smdif, which backs up the policy data, and test.cfg, which preserves the environment settings.

Note: The text in the .cfg file is separated by tabs and you can read it in any text editor or as a tab-delimited file in Microsoft Excel.

2. To change test.com’s environment to match the settings in production.com, do the following:

a. Using Microsoft Excel or a text editor, open test.cfg.

b. Replace the test.com values with those from production.com. For illustrative purposes only, replace values such as IP Addresses, registration URLs, shared secrets, and agent names listed in the following table with those from production.com listed in the second table.

Note: These are just four sample values and you will need to edit other values based on your own environment.

Important! Make sure you only edit the Value entries and not the ones for Object OID, Object Class, Property Type.

Object OID Object Class Property Type Value

<Trusted Host OID>

TrustedHost IPAddr 192.216.167.23

<reg scheme OID>

SelfReg RegistrationURL http://test.url .com

<auth scheme OID>

Scheme Secret testpassword

<agent OID> Agent Name testagent

The Object OID column is represented only by the <OID> variable since OIDs such as the following are too long to fit in the above table:

<Trusted Host OID> = 0d-6dc75be0-1935-11d3-95cc-00c04f7468ef

Object OID Object Class

Property Type

Value

<Trusted Host OID>

TrustedHost

IPAddr 192.216.167.24

<reg scheme OID> SelfReg RegistrationURL

http://production.url.com

<auth scheme OID>

Scheme Secret productionpassword

Policy Server Tools


Object OID Object Class

Property Type

Value

<agent OID> Agent Name productionagent

3. Import test.smdif and test.cfg, which you edited to include the values from production.com, into the Production.com policy store:

smobjimport -itest.smdif -dSiteMinder -wpassword -v -f -t

Note: To override existing data and matching objects in the Production.com policy store with that of Test.com, use the -f argument.

smobjexport and smobjimport allow you to export or import an entire policy store or an individual domain.

Note: For more information on exporting or importing individual objects on a smaller scale, see the API Reference Guide for Perl.

Policy Server Tools


Example 2 Policy Stores with Same Objects But Different Environments

In this example, there are two synchronized 6.x policy stores--A and B--containing the same objects with the same object IDs (OIDs) but different environments. The goal is to migrate 6.x policy data from A into B and keep the original B environment settings by doing the steps listed in the following figure using the .smdif and .cfg files. The .smdif files (A.smdif and B.smdif) back up the policy data. The configuration files (A.cfg and B.cfg) expedite incremental updates between the stores and preserve environment-specific properties such as Agent IP Addresses, redirection URLs, shared secrets, Agent names, logging settings, and .com extensions.

Policy Data AEnvironment Data A

Policy Store A

Policy Data BEnvironment Data B

Policy Store B

A.smdif A.cfg

Policy Data AEnvironment Data B

Policy Store B(after migration)

1 2

3

B.smdif B.cfg

To migrate 6.x policy data from A into B and keep the original B environment settings:

1. Export policy store A into A.smdif, which backs up the policy data, and A.cfg, which preserves the environment settings.

smobjexport -oA.smdif -c -dSiteMinder -wpassword -v -t

2. Export policy store B into B.smdif, which backs up the policy data, and B.cfg, which preserves the environment settings.

Policy Server Tools


smobjexport -oB.smdif -c -dSiteMinder -wpassword -v -t

3. Import policy data from A into B and preserve B’s environment settings by:

a. Renaming B.smdif to B.smdif.bak.

b. Renaming A.smdif to B.smdif.

c. Ensuring that B.smdif and B.cfg are in the same directory.

d. Importing B.smdif (which used to be A.smdif) and B.cfg into policy store B.

smobjimport -iB.smdif -dSiteMinder -wpassword -v -f -t

To override existing data in policy store B with that of A, use the -f argument. You can override matching objects with this argument since you already backed up policy store B into B.smdif and B.cfg during the export.

Note: You can also migrate policy store data and the environment using the Scripting Interface for Perl. For more information, see the API Reference Guide for Perl.

smobjimport imports B.smdif and B.cfg into policy store B. The policy data in B.smdif, which contains policy data from A, overrides matching data in policy store B. The B environment settings stored in B.cfg overrides the settings stored in A.smdif. Thus, policy store B contains policy data from A, but the environment settings from B.

Note: If there are objects in A.smdif that do not have counterparts in B, then B.cfg will not override environment settings for non-matching objects.

Manage an LDAP Policy Store Using smldapsetup

The smldapsetup utility allows you to manage an LDAP policy store from the command line. Using smldapsetup, you can configure an LDAP policy store, generate an LDIF file, and remove policy store data and schema.

To use smldapsetup, specify a mode, which determines the action that smldapsetup will perform, and arguments, which contain the values that are used to configure the LDAP server.

Policy Server Tools


The following table contains the modes you can use with smldapsetup and the arguments each mode uses:

Modes Arguments

reg -h<host>, -p<portnumber>, -d<userdn>, -w<userpw>, -r<root>, -ssl<1|0>, -c<certdb>, -k1

ldgen -h<host>, -p<portnumber>, -d<userdn>, -w<userpw>, -r<root>, -m<n>, -ssl<1|0>, -c<certdb> -f<ldif>, -t<tool>, -s<suffix>, -e, -k

ldmod -h<host>, -p<portnumber>, -d<userdn>, -w<userpw>, -r<root>, -ssl<1|0>, -c<certdb>, -f<ldif>, -s<suffix>, -e, -k, -i

remove -h<host>, -p<portnumber>, -d<userdn>, -w<userpw>, -r<root>, -ssl<1|0>, -c<certdb>, -k

switch none

revert -v

status -v

Policy Server Tools


To use smldapsetup





On Unix, <siteminder installation>/bin




smldapsetup <mode> <arguments>

Example: smldapsetup reg -hldapserver.mycompany.com -d”LDAP User” -wMyPassword123 -ro=security.com

Note: When running smldapsetup, make sure that the LDAP user you specify has the appropriate administrator privileges to modify schema in the LDAP Directory Server. If this user does not have the proper privileges, then the LDAP server will not allow you to generate the policy store schema. After running the smldapsetup command, this user appears in the Admin Username field on the Data tab of the Policy Server Management Console.

More Information:

Modes for smldapsetup (see page 162) Arguments for smldapsetup (see page 163)

Policy Server Tools


Modes for smldapsetup

The mode indicates the action that smldapsetup performs. You can specify a mode to connect to the LDAP server, generate an LDIF file, configure an LDAP policy store and remove policy data.

The modes for smldapsetup include:

reg

Tests the connection to the LDAP server. If the connection succeeds, smldapsetup configures the SiteMinder LDAP server as its policy store using the -h<host>, -p<portnumber>, -d<userdn>, -w<userpw>, -r<root>, -ssl<1/0> and -c<certdb> arguments.

ldgen

Automatically detects supported LDAP servers and generates an LDIF file with the SiteMinder schema. The generated file is used by smldapsetup ldmod to create the SiteMinder schema. If the -e argument is specified, smldapsetup ldgen creates an LDIF file that can be used with ldmod to delete the SiteMinder schema. Use the -m switch to skip automatic detection of LDAP servers. The ldgen mode requires the -f switch unless previously configured in reg mode.

ldmod

Connects to the LDAP server and the SiteMinder schema without populating the policy store with any data. It requires the LDAP modify program and the LDIF file, specified with the -f<ldif> argument. If you specify the -h<host>, -p<portnumber>, -d<userdn>,-w<userpw>, -r<root>, -ssl<1/0> and -c<certdb> arguments, smldapsetup ldmod will modify the LDAP directory specified using these arguments. If you do not specify -h<host>, -p<portnumber>, -d<userdn>, -w<userpw>, -r<root>, -ssl<1/0> and -c<certdb>, smldapsetup ldmod uses the LDAP directory previously defined using smldapsetup reg or the Policy Server Management Console.

remove

Connects to the LDAP server, then removes all policy data stored under the SiteMinder LDAP node that corresponds to the current version of smldapsetup. If you specify the -h<host>, -p<portnumber>, -d<userdn>,-w<userpw>, -r<root>, -ssl<1/0> and -c<certdb> arguments, smldapsetup remove will remove policy data from the LDAP directory specified by these arguments. If you do not specify -h<host>, -pCA Portal, -d<userdn>, -w<userpw>, -r<root>, -ssl<1/0> and -c<certdb>, smldapsetup remove will remove the policy data from the LDAP directory previously defined using smldapsetup reg or the Policy Server Management Console.

Policy Server Tools


switch

Reconfigures the Policy Server to use LDAP rather than ODBC. It does not prepare the LDAP store or the LDAP connection parameters before making the change.

revert

Reverts to ODBC policy store from LDAP. The only argument used with this mode is -v.

status

Verifies that the LDAP policy store connection parameters are configured correctly. It requires the -v argument. If you specify the -h<host>, -p<portnumber>, -d<userdn>, -w<userpw>, -r<root>, -ssl<1/0> and -c<certdb> arguments, smldapsetup status tests the connection to the LDAP directory specified using these arguments. If you do not specify -h<host>, -p<portnumber>, -d<userdn>, -w<userpw>, -r<root>, -ssl<1/0> and -c<certdb>, smldapsetup status verifies the connection to the LDAP directory previously defined using smldapsetup reg or the Policy Server Management Console.

From the Data tab in the Policy Server Management Console, you can view or change the settings you configured with the reg, switch and revert functions using a GUI interface. You must use smldapsetup to perform the ldgen, ldmod, remove, and status functions.

Arguments for smldapsetup

Arguments allow you to specify the information used by the modes to manage the LDAP policy store. If you do not specify arguments, smldapsetup uses the values configured in the Policy Server Management Console.

Note: smldapsetup does not allow spaces between an argument and its value. For example, the -h argument should be specified as follows: smldapsetup ldmod -hldapserver.mycompany.com

Policy Server Tools


The arguments you can specify in an smldapsetup call are listed below:

-h<host>

Specifies the fully qualified name of the LDAP server; the relative name, if the machines are in the same domain (-hldapserver); or the IP address (-h123.12.12.12). If you do not specify a host, smldapsetup uses the previously configured value as the default.

Example: -hldapserver.mycompany.com

-p<portnumber>

Specifies a non-standard LDAP port. The LDAP port must be specified if the LDAP server is using a non-standard port or if you are moving a server to a new server that uses a different port, such as moving from a server using SSL to one that is not. If a port is not specified, the previous configuration values are used. If no previous port configuration has been specified, smldapsetup uses the default ports 389, if SSL is not being used, or 636, if SSL is being used.

-d<userdn>

Specifies the LDAP user name of a user with the power to create new LDAP directory schema and entries. This is not necessarily the user name of the LDAP server administrator. If you do not specify a user name, smldapsetup uses the previously configured name as the default.

-w<userpw>

Specifies the password for the user identified in the -d argument. If you do not specify a password, smldapsetup uses the previously configuration value.

Example: -wMyPassword123

-r<root>

Specifies the distinguished name of the node in the LDAP tree where SiteMinder will search for the policy store schema. If you do not specify a root, smldapsetup uses the previously configured root.

Example: -ro=security.com

-e

When specified with smldapsetup ldgen, generates an LDIF file that can delete the SiteMinder schema. The generated file must be used with smldapsetup ldmod to remove the schema.

Policy Server Tools


-m<n>

Skips automatic detection of LDAP servers and specify type of LDAP policy store where <n> is one of the following:

2

iPlanet v4 LDAP servers.

3

Active Directory LDAP servers.

4

Oracle Internet Directory.

5

SunOne (iPlanet) v5 LDAP servers.

9

Active Directory Application Mode.

-f<ldif>

Specifies the absolute or relative path to an LDIF file from the directory in which smldapsetup is being executed.

Example: -f../siteminder/db/smldap.ldif

Default: if you do not specify a path, smldapsetup uses the current directory as the default.

-t<tool>

Specifies the absolute or relative path, including filename and extension, of the ldapmodify command line utility. Ldapmodify is used to configure the server schema using the LDIF format commands. LDAP servers and SiteMinder provide a copy of ldapmodify. If the utility is not in the default location, use this argument to specify its location.

-ssl<1 or 0>

Specify -ssl1 to use an SSL-encrypted connection to the LDAP server, and -ssl0 to use a non-SSL connection. If you do not specify a value for -ssl, smldapsetup uses the previously configured value. If the LDAP connection has not been configured before, the initial default value is 0.

Policy Server Tools


-c<cert>

This argument must be specified when using an SSL encrypted (-ssl1) LDAP connection. Specifies the path of the directory where the SSL client certificate database file, which is usually called cert7.db for the Netscape Navigator Web browser, exists.

Example: If cert7.db exists in /app/siteminder/ssl, specify -c/app /siteminder/ssl when running smldapsetup ldmod -f/app/siteminder/pstore.ldif -p81 -ssl1 -c/app/siteminder/ssl.

Note: For policy stores using an SSL-encrypted connection to Sun Java System LDAP, make sure the key3.db file exists in the same directory as cert7.db.

-k-k1

Enables you to use smldapsetup to set up or modify a key store if you are storing key information in a different LDAP directory. If you specify -k, smldapsetup checks to see if the Policy Server is pointing to the key store before performing any functions. If the Policy Server is not pointing to the key store, smldapsetup issues a warning. If you specify -k1, in conjunction with smldapsetup ldgen and the other arguments for a new policy store, smldapsetup creates a separate key store in the location you specify. If you do not specify -k or -k1, smldapsetup will modify the policy store.

-v

Enables verbose mode for troubleshooting. With -v, smldapsetup logs its command-line arguments and configuration entries as it performs each step in the LDAP migration.

-i<user DN>

Specifies the distinguished name of an account that should be used by SiteMinder to make modifications to the policy store. This argument allows an administrator account to retain control of the SiteMinder schema while enabling another account that will be used for day-to-day modifications of SiteMinder data. When a change is made using the Administrative UI, the account specified by this argument is used. Be sure to enter the entire DN of an account when using this argument.

-q

Enables quiet mode for no questions to be asked.

-u

Creates a 6.x upgrade .ldif file to bring a 5.0 or 5.5 policy store to 6.x.

-x

Use the -x argument with ldmod to generate replication indexes for another 4.x or 5.x Sun Java System LDAP Directory Server database.

Policy Server Tools


-s<suffix>

This option allows you to specify a suffix other than the default parent suffix when configuring the 6.x Policy Server's schema in a 5.x Sun Java System LDAP Directory Server.

Example: assume the following:

ou=Apps,o=test.com is the Policy Store root.

o=test.com is the root suffix.

ou=netegrity,ou=Apps,o=test.com is the sub suffix.

If you do not use the -s parameter with smldapsetup, the Policy Server assigns ou=Apps,o=test.com as a parent suffix of ou=netegrity,ou=Apps,o=test.com. To change this and have the appropriate parent suffix set, run smldapsetup using the -s parameter while specifying o=test.com.

-?


Note: If the arguments contain spaces, you must enter double quotes around the entire argument. For example, if the name of the SiteMinder administrator is LDAP user, the argument for smldapsetup would be: -d”LDAP user".

smldapsetup and the 5.x SunOne Directory Server

In a 5.x SunOne (iPlanet) Directory Server, smldapsetup creates the ou=netegrity,<root> sub suffix and PolicySvr4 database, where <root> is the directory root you specified in the Root DN field on the Data tab of the Policy Server Management Console. The <root> variable has to be either an existing root suffix or sub suffix. As an example, if your root suffix is dc=netegrity,dc=com then running smldapsetup produces the following in the 5.x SunOne (iPlanet) Directory Server:


A sub suffix, ou=netegrity,dc=netegrity,dc=com, with the corresponding PolicySvr4 database.

Policy Server Tools


For another example, if you want to place the policy store under ou=apps,dc=netegrity,dc=com, then ou=apps,dc=netegrity,dc=com has to be either a root or sub suffix of the root suffix dc=netegrity,dc=com. If it is a sub suffix, then running smldapsetup produces the following:


A sub suffix, ou=apps,dc=netegrity,dc=com, with the corresponding Apps database.

A sub suffix, ou=netegrity,ou=apps,dc=netegrity,dc=com, with the corresponding PolicySvr4 database.

Note: More information on root and sub suffixes exists in Sun's documentation.

Remove the SiteMinder Policy Store using smldapsetup

To remove the SiteMinder policy store data and schema from an LDAP directory, you must first delete the data, then remove the schema.

Important! Before removing the SiteMinder policy store data, make sure that the Policy Server is pointing to the policy store that contains the data you want to delete. smldapsetup will remove the data from the policy store to which the Policy Server is pointing. Additionally, export the policy store data to an output file and create a backup of the file before removing the data.

To remove the policy store using smldapsetup

1. Navigate to the following location:







2. Remove the policy store data by entering the following command:

smldapsetup remove -h<LDAP_IP_Address> -p<LDAP_Port>

-d <LDAP_Admin> -w<LDAP_Admin_Password> -r<LDAP_Base_DN>

-v

Example: smldapsetup remove -h192.169.125.32 -p552 -d"cn=directory manager" -wfirewall -rdc=ad,dc=test,dc=com -v

Note: Removing the policy store data may take a few moments.



Policy Server Tools


3. Generate the LDIF file you will use to delete the schema by entering the following:

smldapsetup ldgen -e -f<ldif>

ldif

Specifies the name of the LDIF file you are generating.

Example: smldapsetup ldgen -e -fdelete.ldif

4. Remove the SiteMinder schema by executing the following command:

smldapsetup ldmod -f<ldif>

ldif

Specifies the name of the LDIF file you generated using smldapsetup ldgen -e.

Example: smldapsetup ldmod -fdelete.ldif

Hardware Key Storage with an nCipher Cryptographic Module

If you are using Hardware Key storage with an nCipher cryptographic module, smldapsetup, smobjimport, and smobjexport all prompt for the token passphrase. For all three tools, make sure you enter the correct hardware cryptography token passphrase.

For example, after running:

smldapsetup reg -h192.168.7.126 -d"cn=Directory Manager"

-wdirmanager -ro=NetscapeRoot

smldapsetup prompts:

Enter Token Passphrase: <token_passphrase>

After running: smobjimport -i/export/smuser/siteminder/db/smdif/smpolicy.smdif -v

smobjimport prompts:

Enter Token Passphrase: <token_passphrase>

More Information:

Hardware Keys Overview (see page 200)

Policy Server Tools


Delete SiteMinder Data in ODBC Databases

SiteMinder provides a number of SQL scripts that delete the SiteMinder schema from ODBC databases. The following list describes each SQL script:

sm_oracle_ps_delete.sql

Removes the SiteMinder 6.x policy store and data from an Oracle database.

sm_oracle_logs_delete.sql

Removes SiteMinder 6.x logs stored in an Oracle database if the database was created using sm_oracle_logs.sql.

sm_oracle_token_delete.sql

Removes the SiteMinder 6.x token data, such as Encotone Encrypta card data, and schema from an Oracle database if the database was created using sm_oracle_token.sql.

sm_oracle_ss_delete.sql

Removes the SiteMinder 6.x Session Server tables and data from an Oracle database.

sm_mssql_ps_delete.sql

Removes the SiteMinder 6.x policy store and data from an SQL database.

sm_mssql_logs_delete.sql

Removes SiteMinder 6.x logs stored in an SQL database if the database was created using sm_mssql_logs.sql.

sm_mssql_token_delete.sql

Removes the SiteMinder 6.x token data, such as Encotone TeleID card data, and schema from an SQL database if the database was created using sm_mssql_token.sql.

sm_mssql_ss_delete.sql

Removes the SiteMinder 6.x Session Server tables and data from a SQL database.

sm_db2_ps_delete.sql

Removes the SiteMinder 6.x policy store and data from a DB2 database.

sm_db2_logs_delete.sql

Removes SiteMinder 6.x logs stored in a DB2 database if the database was created using sm_db2_logs.sql.

Policy Server Tools


sm_db2_token_delete.sql

Removes the SiteMinder 6.x token data, such as Encotone TeleID card data, and schema from a DB2 database if the database was created using sm_db2_token.sql.

sm_db2_ss_delete.sql

Removes the SiteMinder 6.x Session Server tables and data from a DB2 database.

The ODBC database SQL scripts are in the following location:

For Windows, <siteminder_installation>\db



For UNIX, <siteminder_installation>/db



Delete the database objects by running the appropriate SQL script(s) using DB2, SQL Plus for Oracle, or SQL Server Query Analyzer.


Check Solaris Patches with smpatchcheck

SiteMinder provides a utility, called smpatchcheck, that checks whether or not you have the Solaris patches required for the Policy Server and Web Agent installed on your system. Smpatchcheck can be run on the Solaris versions listed on the SiteMinder Platform Matrix. To access this matrix, go to Technical Support site and search for the SiteMinder Platform Matrix.

To use smpatchcheck

1. Navigate <siteminder installation>/bin





Policy Server Tools


2. Enter smpatchcheck.

Smpatchcheck looks for each required/recommended patch and then displays its status.

For example:

Testing for Required Patches:

Testing for Patch: 106327-09 ... NOT Installed

Testing for Recommended Patches:

Testing for Patch: 106541-08 ... Installed

Testing for Patch: 106980-00 ... Installed

SiteMinder Patch Check: Failed

Smpatchcheck returns one of the following messages:

Failed

One or more of the required patches is not installed.

Partially Failed

One or more of the recommended patches is not installed.

Success

All of the required and recommended patches are installed.

Policy Server Tools


Read RADIUS Log Files With Smreadclog

This tool is used to read RADIUS log files generated by the Policy Server. It is useful for troubleshooting the Policy Server when used as a RADIUS authentication server. Options are provided to display individual RADIUS attributes that are exchanged between NAS and SiteMinder.

Smreadclog uses the following arguments to supply information required to read RADIUS log files:

-i<input-file>

Specifies the filename of the log file.

-o<output-file>

Specifies the filename of the output file.

-s<secret>

Specifies the shared secret that can be used to decode RADIUS passwords.

-r

Indicates that a hex dump of an entire RADIUS packet be displayed.

-a

Indicates that RADIUS attributes should be displayed individually.

-d

Indicates that RADIUS attributes should be displayed according to their definition in the policy store. This option displays actual attribute names as well as attribute values formatted based on their attribute type. Without this option, only the attribute name and value are displayed as a hex string.

-p<radius-server>

Records and replays RADIUS activity of the Policy Server service against your RADIUS server.

-m<authentication port>

Specifies the port used for RADIUS authentication if that port is not the default port, 1645.

-n<accounting port>

Specifies the port used for RADIUS accounting if that port is not the default port, 1646.

Note: For information about deploying the Policy Server as a RADIUS authentication server, see the Policy Design guide.

To use smreadclog


Policy Server Tools









smreadclog -i<input-file> -o<output-file>

-s<secret> -r -a -d -p<radius-server> -m<portnumber>

-n<portnumber>

Example:smreadclog -iradiuslog.txt -oradiuslog2.txt -ssecret -r -a -d -p123.123.12.12

Import Tokens Using the SiteMinder Token Tool

SiteMinder supports hardware-based security cards or tokens. Tokens use a dynamically generated password to provide an additional level of security.

All tokens require a data file provided by the vendor. Some tokens, such as ACE, access the token data file remotely on the vendor’s server. Most tokens access the token database locally, through the SiteMinder Token Tool.

SiteMinder supports the following types of tokens:

Encotone TeleID

CryptoCard RB-1

Before assigning tokens to users, the administrator must import a token data file. This file, provided by the token vendor, contains the identification or serial number for each token you are licensed to install.

To import the token data file

1. Before using this tool, ensure your Policy Server is running and pointing at a configured policy store.

2. From the Windows Start menu, select Programs, SiteMinder, SiteMinder Token Tool.

3. Select the Overwrite duplicate tokens check box if you want to overwrite existing tokens.

4. Specify the type of token in the Pick field and click the Import button.

The Token Tool displays the Open dialog.

Policy Server Tools


5. Select the location from which to import the token data file and click the Open button.

You can either import this file from your hard drive or directly from your install disk. The Token Tool displays a list of all of the serial numbers installed in the database.

6. Click Exit to close and exit the token utility.

SiteMinder Test Tool

The SiteMinder Test Tool is a utility that simulates the interaction between Agents and Policy Servers. It tests the functionality of the Policy Server. During testing, the Test Tool acts as the Agent, making the same requests to the Policy Server as a real Agent. This allows you to test your SiteMinder configuration before deploying it.

Note: For further information about this tool, see the Policy Server Configuration Guide.

Change the SiteMinder Super User Password Using smreg

To change the Super User Password

1. Before using this tool, ensure your Policy Server is running and pointing at a configured policy store.


a. Copy smreg from the folder corresponding to the operating system (\win32\tools or solaris/tools) on the SiteMinder DVD to policy_server_installation\bin




c. Delete smreg.

Deleting smreg prevents anyone from changing the Super User password.

Configure the OneView Monitor


Configure the OneView Monitor The OneView Monitoring infrastructure consists of a number of modules that enable the monitoring of SiteMinder components. Included is the Monitor process that runs in the context of a Java Runtime Environment (JRE). The Monitor GUI’s HTML pages are generated by Java Server Pages (JSPs) and servlets hosted on a ServletExec servlet engine running on the same machine as the Policy Server.

The OneView Monitor utility monitors the following SiteMinder components:

Policy Server

Web Agents

System Requirements for OneView Monitor GUI

The following requirements exist for the OneView Monitor GUI:

JDK: Make sure you have the required Java SDK. For the required version, search for the SiteMinder Platform Matrix for 6.0 on the Technical Support site. You can download the latest Java SDK at the Sun Developer Network (SDN).

Servlet Engine: Make sure you have the required ServletExec/ISAPI for Windows or ServletExec/AS for UNIX. For the required versions, search for the SiteMinder Platform Matrix for 6.0 on the Technical Support site.

For a list of supported Web Servers for Windows and UNIX systems, search for the SiteMinder Platform Matrix for 6.0 on the Technical Support site.

Oneview Monitor GUI Configuration During Policy Server Installation

During the Policy Server installation, you can have the install program automatically configure the OneView Monitor GUI.

If you did not have the OneView Monitor GUI automatically configured by the Policy Server installer, you can set it up using the Policy Server Configuration Wizard (nete-ps-config.exe or nete-ps-config.bin, which is located in the <siteminder_installation>/install_config_info directory).








How to Configure the OneView Monitor GUI on Windows/IIS

Configuring the OneView Monitor GUI on Windows/IIS requires you to:

1. Read the prerequisites (see page 177) to installing ServletExec on Windows.

2. Install ServletExec/ISAPI 4.2 on Windows 2000/IIS (see page 178) or Windows 2003/IIS (see page 179).

Note: The Monitor GUI’s HTML pages are generated by Java Server Pages (JSPs) and servlets hosted on a ServletExec servlet engine running on the same machine as the Policy Server.

3. Assign modify permissions to the Internet guest account for the <siteminderinstallation>\monitor\settings folder.

4. Set permissions for the IIS Users (see page 179).

5. If you did not have the Policy Server installation program auto-configure the OneView Monitor GUI, configure it by running the Policy Server Configuration Wizard.

Note: Details on auto-configuring the OneView Monitor GUI exist in Run the Policy Server Configuration Wizard.

6. Start the OneView Monitor service (see page 182).

7. Access the OneView Monitor GUI (see page 183).

Prerequisites to Installing ServletExec on Windows

CA recommends that you read the ServletExec documentation before installing ServletExec. If ServletExec is not running properly, then the OneView Monitor GUI does not work since it relies on ServletExec’s servlet engine.

You can access the ServletExec documentation at:

http://www.newatlanta.com/products/servletexec/self_help/docs/index.jsp



As mentioned in the ServletExec documentation, before installing ServletExec, do the following:

1. In Windows Explorer, create a scripts directory under C:\Inetpub.

ServletExec installs the ISAPI filter (ServletExec_ISAPI.dll) in the scripts directory.

2. In the Internet Information Services (IIS) Manager, under Default Web Site, create a scripts virtual directory that points to C:\Inetpub\scripts with the following permissions:

Read

Run scripts

Execute

3. Install ServletExec.

Note: For more information, see the ServletExec documentation at:

http://www.newatlanta.com/biz/c/products/servletexec/self_help/faq/detail?faqId=7

Install ServletExec/ISAPI 4.2 on Windows 2000/IIS

To install ServletExec/ISAPI 4.2 on Windows 2000/IIS

1. If you have an earlier version of ServletExec:

a. Back up the ServletExec Data and Servlets sub-directories, if desired.

b. Remove the earlier version.

2. Run ServletExec_ISAPI_42.exe.

3. In the Welcome dialog box, click Next.

4. Read the Software License Agreement and click Yes.

5. Read the Information dialog box and click Next.

6. In the Choose Destination Location dialog box, select the location where you want ServletExec installed and click Next.

ServletExec installs on your machine.

7. Click Finish to complete the installation.

8. Stop and restart the IIS Admin Web service and IIS Web server.



Install ServletExec/ISAPI 4.2 on Windows 2003/IIS

To install ServletExec/ISAPI 4.2 on Windows 2003/IIS

1. If you have an earlier version of ServletExec:

a. Back up the ServletExec Data and Servlets sub-directories, if desired.

b. Remove the earlier version.

2. Run ServletExec_ISAPI_42.exe.

3. In the Welcome dialog box, click Next.

4. Read the Software License Agreement and click Yes.

5. Read the Information dialog box and click Next.

6. In the first Choose Destination Location dialog box, select the location where you want ServletExec installed and click Next.

7. In the second Choose Destination Location dialog box, enter the destination folder of the scripts directory you created and click Next.

ServletExec installs on your machine.

8. Click Finish to complete the installation.

9. Stop and restart the IIS Admin Web service and IIS Web server.

Set Permissions for IIS Users After Installing ServletExec

Since ServletExec/ISAPI runs as part of the IIS process, it runs as different users at different times. As a result, you must set the following permissions for the ServletExec installation directory and subdirectories.

To set permissions for IIS users after installing ServletExec

For Windows 2000

Make sure that the SYSTEM and Authenticated Users have read and write access to the entire directory tree under C:\Program Files\New Atlanta.

For Windows 2003

Make sure the user that runs IIS (for example, Network Services) has read and write access to the entire directory tree under C:\Program Files\New Atlanta.

More Information:

Start the OneView Monitor Service (see page 182)



Limitation of OneView Monitor GUI/IIS Web Agent on Same Machine

CA does not support the configuration of the IIS-based OneView Monitor GUI and the IIS Web Agent on the same machine if the Agent has Registration Services enabled. With this configuration, there is a conflict with the same instance of ServletExec.

How to Configure the OneView Monitor GUI on UNIX/Sun Java System

Configuring the OneView Monitor GUI on a UNIX/Sun Java System requires you to:

1. Read the prerequisites (see page 180) to installing ServletExec.

2. Disable servlets (see page 180) in Sun Java System (Sun One/iPlanet) 6.0.

3. Install ServletExec/AS 4.2 (see page 181) on UNIX/Sun Java System.

4. If you did not have the Policy Server installation program auto-configure the OneView Monitor GUI.

Note: Details on auto-configuring exist in Run the Configuration Wizard Using a GUI or Console Window. Details on manually configuring exist in Manually Configure the OneView Monitor GUI on UNIX/Sun Java System 6.0 (see page 224).

5. Start the OneView Monitor Service (see page 182).

6. Access the OneView Monitor GUI (see page 183).

Prerequisites to Installing ServletExec

CA recommends that you read the ServletExec documentation before installing ServletExec. If ServletExec is not running properly, then the OneView Monitor GUI does not work since it relies on ServletExec’s servlet engine.

You can access the ServletExec documentation at:

http://www.newatlanta.com/products/servletexec/self_help/docs/index.jsp

Disable Servlets in Sun Java System 6.0

Ensure you follow the steps in this section before installing ServletExec.



To disable servlets in Sun Java System 6.0

1. Open the Sun Java System Enterprise Administration Server home page by entering the following URL in a browser: http://<yourserver.com>:<portnumber>

yourserver.com

Specifies the domain name of the Enterprise Administration Server

port

Specifies the port number

2. In the Select a Server drop-down menu, select the target server, and then click Manage.

3. Select the Java tab.

4. Deselect Enable Java for class defaultclass and Enable Java Globally and click OK.

5. Stop and restart the Web server so the settings can take effect.

Install ServletExec/AS 4.2 on UNIX/Sun Java System

The Monitor GUI’s HTML pages are generated by Java Server Pages (JSPs) and servlets hosted on a ServletExec servlet engine running on the same machine as the Policy Server.

To install ServletExec

1. Log in to the UNIX account where you want to install the Policy Server.

Note: You must log in as the same user who installed the Sun Java System Web server.

2. Enter the following command to run the ServletExec Application Server 4.2 installation:

$ ./ServletExec_AS_42.sh

3. Read the Welcome screen and press ENTER.

4. Enter the full path to where you want ServletExec installed.

Example: /usr/local/NewAtlanta.

Note: Make sure you have permission to create a new file in /tmp.

New Atlanta recommends installing ServletExec 4.2 in /usr/local/NewAtlanta. Installing ServletExec in /usr/local/NewAtlanta may change the permissions for the obj.conf file and the Sun Java System start script. After the installation, be sure the owner of obj.conf and the start script is the same user who owns the Web server.

5. If the directory you specified does not exist, enter Y to create the specified path.



6. Read the license agreement, and enter Y if you accept the terms.

7. Read the README.

8. Select the type of Web server on which you are installing ServletExec and enter the number that corresponds to the target server.

9. Install a Web server adaptor and an instance of ServletExec by selecting 1.

10. Enter the Web server instance where you want to install ServletExec AS.

11. Enter a unique name for this instance of ServletExec AS.

12. Enter the java installation directory. For example, usr/java.

13. Enter N to keep the installation program from updating the Web server’s configuration files.

Important! Make sure you choose N to keep ServletExec from modifying the Web server’s configuration files. If you allow ServletExec to modify the Web server’s obj.conf and magnus.conf configuration files, the Web server instance fails to run after you configure the OneView Monitor GUI on this instance.

14. After the installation program completes, restart the Web server.

More Information:

Start the OneView Monitor Service (see page 182)

Start the OneView Monitor Service

To start the OneView Monitor service

1. Make sure the IPC port numbers are available.

The OneView Monitor uses the following port numbers to communicate with the Policy Server processes:

Monitoring Agent: 44449

Monitor: 44450

To see which port numbers are unavailable, open a Command Window and enter:

netstat -an

Note: For more information on changing the port numbers, see the Policy Server Management guide.

2. Using the Status tab of the Policy Server Management Console, start the Monitor service.

Prerequisites for Running Reports Using Crystal Reports


Access the OneView Monitor GUI

To access the OneView Monitor GUI

Enter the following URL in a browser:

http://server:<portnumber>/sitemindermonitor

server

Specifies the Web Server’s IP Address

portnumber

Specifies the port number.

Monitor a Policy Server Cluster

The OneView Monitor can be configured to monitor a Policy Server cluster when one Policy Server is set up as a centralized monitor for other Policy Servers in a cluster.

Prerequisites for Running Reports Using Crystal Reports This section describes prerequisites for running reports using Crystal Reports.



Crystal Reports in a Policy Server Environment

In SiteMinder 6.0, the Policy Server does not install a Crystal Reports Server as with previous SiteMinder 5.x and 4.x versions. However, the Policy Server still generates audit logs and stores the necessary reporting information in a SQL Server or Oracle database. The Policy Server 6.0 installation program installs sample reports files (.rpt) that are compatible with Crystal Reports 9.0.

Note: These sample files are provided so that customers can continue to use Crystal Reports to read reporting data from the Policy Server's audit logging database. However, CA does not provide support for using the sample files.

The following figure shows a sample Crystal Reports 9.0 and Policy Server environment:

Stored Proceduressmaccesslog4

smobjlog4

ODBCAuditLogs

Database

2

3

4

CrystalReports

PolicyServer

5

1



In the above figure, the Policy Server resides on either a UNIX or Windows platform, with a database for audit logs. Crystal Reports resides on a Windows platform, and is configured to communicate with the audit logs database.

The following steps describe the events that occur in a Crystal Reports and Policy Server environment when a user requests a report:

1. The Policy Server generates audit logs and stores the information in an ODBC (SQL Server or Oracle) database. The Policy Server writes reporting information to the database using the SiteMinder logs data source.

2. A user requests a report using Crystal Reports.

3. When the user selects a report to run, Crystal Reports creates a SQL select statement based on the user’s filter criteria and retrieves the information required by the report from the database. Report information is located in the smaccesslog4 and smobjlog4 tables of audit logs database. Crystal Reports reads the reporting information from the audit logs database using the ODBC Crystal Reports data source.

4. The result set of the SQL select statement is passed to Crystal Reports.

5. Crystal Reports passes the formatted report information to the user.

Before You Begin

Verify that the following requirements are met:

You have Crystal Reports 9.0 Developer and Crystal Reports 9.0 Application Server installed, as you will need this software to modify and run the SiteMinder reports.

For Crystal Reports, apply the latest Crystal Enterprise 9 Database and Export Drivers Monthly Hot Fix (MHF) update, CE90DBEXWIN_EN.ZIP or later, available at the BusinessObjects site.

You will need an Oracle or SQL Server client installed on the Crystal Reports’ machine if you do not use the Oracle or SQL Server wire protocol drivers when configuring a Crystal Reports data source.

For a list of supported operating systems, Web Servers, databases, Web browsers, see the SiteMinder Platform Matrix for 6.0. To access this matrix, go to the Technical Support site and search for the SiteMinder Platform Matrix for 6.0.

http://support.businessobjects.com/





How to Configure the Policy Server for Crystal Reports

To configure Crystal Reports to run SiteMinder reports:

1. Create a logging database schema. The Policy Server generates audit logs and stores the necessary reporting information in a SQL Server or Oracle database.

Create the Oracle Database Schema For Logging (see page 187).

Create the SQL Server Database Schema For Logging (see page 188).

2. Create the stored procedures database schema.

Create the Oracle Database Schema For Stored Procedures (see page 189).

Create the SQL Server Database Schema For Stored Procedures (see page 190).

3. Create an ODBC logs data source to write to the logging database.

Configure an Oracle ODBC Logs Data Source (see page 192).

Configure a SQL Server ODBC Logs Data Source (see page 193).

4. Create an ODBC Crystal Reports data source to read from the logging database.

Configure an Oracle ODBC Crystal Reports Data Source (see page 194).

Configure a SQL Server ODBC Crystal Reports Data Source (see page 196).

5. Configure a Database to Store Audit Logs (see page 198).

6. Modify SiteMinder Reports to Use the Crystal Reports Data Source (see page 199)



Create the Oracle Database Schema For Logging

You may have already created an Oracle logging database when you created the Oracle database with the SiteMinder schema. If you already created a logging database, do not run sm_oracle_logs.sql again, as it will overwrite the current database with a new one.

If you are using Oracle to store reports information, run the sm_oracle_logs.sql script to create a schema for logging. If there is no schema in the database to log data, reports will not work. This script is included in the <siteminder_installation>\db\SQL directory.



To create the Oracle database schema for logging

1. Make sure the Oracle database instance that will contain the SiteMinder logs data is accessible from the Policy Server machine. Test the communication using tnsping or sqlplus.

2. Create the SiteMinder schema in the Oracle database:


b. Import the script to create a schema for logging:

$NETE_PS_ROOT/db/sql/sm_oracle_logs.sql

Note: If you are using sqlplus, run the schema using an @ sign.

Example: @$NETE_PS_ROOT/db/sql/sm_oracle_logs.sql

Note: Environment variables may not function in Oracle's SQL utility. If you encounter problems when using the utility, specify an explicit path for $NETE_PS_ROOT rather than one with an environment variable.

3. Create the Oracle database schema for stored procedures.

Note: The 6.x Policy Server and OneView Monitor services still start even if they are unable to connect to the audit logs database.

More Information:

Create the Oracle Database Schema For Stored Procedures (see page 189)



Create the SQL Server Database Schema For Logging

You may have already created a SQL Server logging database when you created the SQL Server database with SiteMinder schema. If you already created a logging database, do not run sm_mssql_logs.sql again as it will overwrite the current database with a new one.

If you are using SQL Server to store reports information, run the sm_mssql_logs.sql script to create a schema for logging. If there is no schema in the database to log data, reports will not work. This script is included in the <siteminder_installation>\db\SQL directory.



To create the SQL Server database schema for logging

1. Make sure the SQL Server database that will contain the SiteMinder logs data is accessible from the Policy Server machine.

2. Using the SQL Server Enterprise Manager, create the logs database instance.

3. Create the SiteMinder schema in the SQL Server database:

a. Open sm_mssql_logs.sql in a text editor and copy the contents of the entire file.


c. In the Query Analyzer, select the logs database instance from the database drop down list at the top-middle of the screen.

d. Paste the schema for logging from sm_mssql_logs.sql into the query.


4. Create the SQL Server database schema for stored procedures.

Note: The 6.x Policy Server's services (Policy Server and OneView Monitor) start even if they are unable to connect to the audit logs database.

More Information:

Create the SQL Server Database Schema For Stored Procedures (see page 190)



Create the Oracle Database Schema For Stored Procedures

If you are using Oracle to store reporting information, run the SmReportStoredProcedures_Oracle.sql script to create a schema for stored procedures in the logging database. You need to create the stored procedures, which the report files need to extract results from the database. This script is included in the <siteminder_installation>\reports directory.



1. Make sure the Oracle logging database instance that will contain the stored procedures schema is accessible from the Policy Server machine. Test the communication using tnsping or sqlplus.

2. Create the stored procedures schema in the Oracle logging database:

a. Log in to Oracle with sqlplus (or some other Oracle utility) as the same Oracle user that you used to run the sm_oracle_logs.sql script.

b. Import the script to create a schema for stored procedures:

$NETE_PS_ROOT/reports/SmReportStoredProcedures_Oracle.sql

Note: If you are using sqlplus, run the schema using an @ sign.

Example: @$NETE_PS_ROOT/reports/ SmReportStoredProcedures_Oracle.sql

3. Configure the Oracle ODBC logs data source.

More Information:

Configure an Oracle ODBC Logs Data Source (see page 192)



Create the SQL Server Database Schema For Stored Procedures

If you are using SQL Server to store reporting information, run the SmReportStoredProcedures_SqlServer.sql script to create a schema for stored procedures in the logging database. You need to create the stored procedures, which the report files need to extract results from the database. This script is included in the <siteminder_installation>\reports directory.



To create the SQL Server database schema for stored procedures

1. Make sure the SQL Server logging database instance that will contain the stored procedures schema is accessible from the Policy Server machine.

2. Create the stored procedures schema in the SQL Server logging database:

a. Open SmReportStoredProcedures_SqlServer.sql in a text editor and copy the contents of the entire file.

b. Start the Query Analyzer and log in to SQL Server as the same user who ran the sm_mssql_logs.sql script.

c. In the Query Analyzer, select the logs database instance from the database drop down list at the top-middle of the screen.

d. Paste the schema for stored procedures from SmReportStoredProcedures_SqlServer.sql into the query.


3. Configure the SQL Server ODBC logs data source.

More Information:

Configure a SQL Server ODBC Logs Data Source (see page 193)



Next Steps

After creating the logging database schema and stored procedures, you need to:

1. Create an ODBC logs data source to write to the Policy Server’s logging database:

Configure an Oracle ODBC Logs Data Source (see page 192).

Configure a SQL Server ODBC Logs Data Source (see page 193).

2. Create an ODBC Crystal Reports data source to read from to the Policy Server’s logging database:

Configure an Oracle ODBC Crystal Reports Data Source (see page 194).

Configure a SQL Server ODBC Crystal Reports Data Source (see page 196).

3. Configure a Database to Store Audit Logs (see page 198).

4. Modify SiteMinder Reports to Use the Crystal Reports Data Source (see page 199).



Configure an Oracle ODBC Logs Data Source

The SiteMinder Logs Data Source allows the Policy Server to write logging messages to an Oracle database. Crystal Reports reads messages from this database to create reports.

To create and configure the SiteMinder Logs Data Source


2. Click the System DSN tab and click Add. The Create New Data Source dialog box appears.

3. Scroll down and select SiteMinder Oracle Wire Protocol and click Finish. The ODBC Oracle Wire Protocol Driver Setup dialog appears.


a. In the Data Source Name field, enter any name you want.

Example: SiteMinder Logs Data Source.

Note: Take note of this name, as you will need it when you configure the database to store audit logs.

b. (Optional) In the Description field, enter a description of the Oracle wire protocol logs data source.

c. In the Host field, enter the machine name where the Oracle database is installed.

d. In the Port Number field, enter the port number where Oracle is listening on the machine.

e. In the SID field, enter the service name of the Oracle instance that you want to connect, which you specified in the tnsnames.ora file. The SID is the system identifier for the database instance.

Note: Due to a limitation of the Oracle wire protocol driver (NSORA19.dll), you can only enter 10 characters or less in the SID field.

The tnsnames.ora file contains service names and details that Oracle uses to identify and connect to Oracle instances. For example, if the tnsnames.ora file contains the following entry for an Oracle instance, enter instance1 in the SID field.

f. instance1 =

(DESCRIPTION = (ADDRESS = (PROTOCOL = TCP)(Host = myhost)(Port =1521)) (CONNECT_DATA = (SID = SIDofinstance1)) )

g. Test the connection with the database by clicking Test Connect.




6. Configure the database to store audit logs.

More Information:

Configure a Database to Store Audit Logs (see page 198)

Configure a SQL Server ODBC Logs Data Source

The SiteMinder Logs Data Source allows the Policy Server to write logging messages to a SQL Server database. Crystal Reports reads messages from this database to create reports.

To create and configure the SiteMinder Logs Data Source



3. Click Add.


4. Scroll down and select SiteMinder SQL Server Wire Protocol and click Finish.

The ODBC SQL Server Wire Protocol Driver Setup dialog box appears.


a. In the Data Source Name field, enter the Data Source name

b. Example: SiteMinder Logs Data Source.

Note: Take note of this name, as you will need it when you configure the database to store audit logs.

c. (Optional) In the Description field, enter a description of the data source.

d. In the Server Name field, enter the name of an existing SQL server.

e. In the Database name field, enter the name of an existing database instance.

f. Click Test Connect to make sure to make sure the connection works.

g. Click OK.

6. Configure the database to store audit logs.

More Information:

Configure a Database to Store Audit Logs (see page 198)



Configure an Oracle ODBC Crystal Reports Data Source

The Crystal Reports Data Source allows Crystal Reports to read messages from the Policy Server’s Oracle logging database.

Note: You will need an Oracle client installed on the Crystal Reports’ machine to use the Oracle client driver in this section.

To create and configure the Crystal Reports Data Source



3. Click Add.


4. Scroll down and select the CR Oracle ODBC Driver 4.10 driver and click Finish.

The ODBC Oracle Driver Setup dialog box appears.


a. In the Data Source Name field, enter Crystal Reports Oracle Data Source.


c. In the Server Name field, enter the Oracle service name. Do not use blank spaces in the name.

This is the Oracle client connection string (TNS) referenced in the Oracle Easy Configuration dialog box. Your version of Oracle may cause this dialog box to appear differently.

The service name is the name assigned to an Oracle instance specified in the tnsnames.ora file. This file contains service names and details that Oracle uses to identify and connect to Oracle instances. For example, if the tnsnames.ora file contains the following entry for an Oracle instance, enter instance1 in the Server Name field.

instance1 = (DESCRIPTION = (ADDRESS = (PROTOCOL = TCP)(Host = myhost)(Port =1521)) (CONNECT_DATA = (SID = SIDofinstance1)) )

6. (Optional) Test the connection with the database by clicking Test Connect.

7. Click the Advanced tab

8. Check Procedure Returns Results and click Apply and OK.

9. Click OK to save the selections and exit the ODBC Oracle Driver Setup.



The configuration is complete.

10. Edit the SiteMinder reports files to use this Crystal Reports data source.

More Information:

Modify SiteMinder Reports to Use the Crystal Reports Data Source (see page 199)



Configure a SQL Server ODBC Crystal Reports Data Source

The Crystal Reports Data Source allows Crystal Reports to read messages from the Policy Server’s SQL Server logging database.

Note: You will need a SQL Server client installed on the Crystal Reports’ machine to use the SQL Server client driver in this section.

To create and configure the Crystal Reports Data Source



3. Click Add.


4. Scroll down and select SQL Server and click Finish.

The Create New Data Source to SQL Server dialog box appears.


a. In the Name field, enter SQL Serv CR Reports Data Source.

Note: You must enter this name exactly as shown for the reports to work properly.


c. In the Server field, enter the name of an existing SQL server.

d. Click Next.

e. The second Create New Data Source to SQL Server dialog box appears.

6. In this second dialog, do the following:

a. Select the With SQL Server authentication using a login ID and password entered by the user radio button.

b. Enter the login name and password of the SQL Server user who administers the Policy Server’s logging database and click Next.

7. In the third dialog, do the following:

a. If you do not want to connect to the default database, check Change the default database to, and select the database instance from the drop-down menu.

Example: logs.

b. Click Next.

8. In the fourth dialog, click Finish.



9. (Optional) In the ODBC Microsoft SQL Server Setup dialog, click Test Data Source to make sure the connection works and click OK.

The configuration is complete.

You can now edit the SiteMinder reports files to use this Crystal Reports data source.

More Information:

Modify SiteMinder Reports to Use the Crystal Reports Data Source (see page 199)



Configure a Database to Store Audit Logs

Before configuring an Oracle or SQL Server database to store audit logs, ensure you have created the database for schema logging and configured an ODBC logs data source.

Details on creating a database for schema logging exist in:

Create the Oracle Database Schema For Logging (see page 187)

Create the SQL Server Database Schema For Logging (see page 188)

Details on configuring an ODBC logs data source exist in

Configure an Oracle ODBC Logs Data Source (see page 192)

Configure a SQL Server ODBC Logs Data Source (see page 193)

To point the Policy Server to store audit logs in a database

1. In the Policy Server Management Console, click the Data tab to move it to the front



4. (If necessary) Deselect the Use Policy Store database check box and click Apply.

The fields in the Data Source Information group box become active.

5. In the Data Source Information field, enter the name of the data source, which should be SiteMinder Logs Data Source.

Note: This name must correspond to the SiteMinder Logs Data Source name you entered in the Data Source Name field when you configured your ODBC logs data source.

6. In the User Name and Password fields, enter the user name and password of the user who administers the Policy Server’s logging database.







Modify SiteMinder Reports to Use the Crystal Reports Data Source

By default, all of the SiteMinder reports .rpt files installed in the <siteminder_installation>\reports directory are configured to use the SiteMinder Reports Data Source, which is the data source that allows Crystal Reports to read from the logging database. If your Crystal Reports data source name does not match SiteMinder Reports Data Source, then you will have trouble running reports. You modify each reports file so that it uses the Crystal Reports data source name you created when you configured your ODBC Crystal reports data source.

To modify SiteMinder reports to user the Crystal Reports data source

1. Go to Start, Programs, Crystal Reports.

2. Open one of the SiteMinder Activity, Intrusion, Administrative, or Time Series reports (.rpt) files in Crystal Reports.

3. Select Database, Set Datasource Location.

4. Under Replace with, in the Set DataSource Location dialog, expand Create New Connection, ODBC (RDO).

5. Under Data Source name, in the ODBC (RDO) dialog, select the Crystal Reports data source name you created and click Next.

6. In the next ODBC (RDO) dialog:

a. Enter the user name and password of the user who administers the Policy Server’s logging database.

b. Make sure the correct name of the Policy Server’s logging database appears in the Database drop down menu.

c. Click Finish.

7. Under Replace with, in the Set DataSource Location dialog:

a. Expand <logging_database> -> dbo -> Stored Procedures.

logging_database

Specifies the name of the Policy Server’s logging database.

Example: 60logs.

a. Highlight the report name under Stored Procedures and under Current Data Source at the top of the dialog.

Example: SmGetIntrusionAll;1

b. Click Update.

8. In the Enter Parameter Values dialog, enter the appropriate parameters you want.

Note: Oracle supports dates in the mm/dd/yyyy format. SQL database supports dd/mm/yyyy.

Secure Keys with a Hardware Module


9. Click Close and save the report.

10. To preview the report, select Report, Refresh Report Data.

Note: To view SiteMinder reports using Crystal Reports, see the Policy Server Management guide.

More Information:

Configure an Oracle ODBC Crystal Reports Data Source (see page 194) Configure a SQL Server ODBC Crystal Reports Data Source (see page 196)

Secure Keys with a Hardware Module This section describes how to secure keys with a hardware module.

Hardware Keys Overview

Installation of nCipher cryptographic modules into a SiteMinder environment provides enhanced security by using a hardware-generated and hardware-resident key to encrypt SiteMinder's master key. SiteMinder will also use the cryptographic hardware for all key generation and random number generation. SiteMinder uses the PKCS #11 standard for communication with the nCipher hardware.

Note: This chapter assumes that you are already familiar with nCipher cryptographic module hardware concepts and terminology. You should read the documentation provided with your nCipher hardware before attempting to install it in the SiteMinder environment using these directions.

This chapter discusses how to integrate nCipher cryptographic hardware into your SiteMinder environment.




Before you decide to implement nCipher cryptographic hardware into your SiteMinder environment, you should consider the following:

Once SiteMinder has been configured to use cryptographic hardware modules, you cannot remove, disable, or reconfigure SiteMinder’s use of hardware encryption without reinstalling and reconfiguring SiteMinder.

Hardware cryptography in your SiteMinder environment prevents secure unattended failover, because, if an operator is not present to supply the passphrase, it must be provided in an insecure manner or failover does not occur.

For UNIX systems, to access the nCipher hardware, your UNIX user account (for example, smuser) must be a member of the nCipher UNIX group (typically 'nfast'). See your nCipher documentation for more information on this UNIX group.

SiteMinder Encryption Keys and Cryptographic Hardware

SiteMinder uses several different encryption keys and shared secrets to encrypt cookie and session data and to establish secure connections between Agents and Policy Servers. Except for the shared secrets, all of these keys are stored on Policy Servers and distributed to Agents at runtime. The shared secrets are used to establish secure connections, and must therefore be available locally to both Agents and Policy Servers.

On a Policy Server, keys and shared secrets are kept in the Policy Server’s Key Store. By default, the key store is part of the Policy Store, but a separate key store database can be created if desired. Keys are stored in encrypted form, using either the policy store key or, if a separate key store is configured, a key store key. If configured, the key store key is stored in the registry (or Unix equivalent), encrypted using the policy store key. The policy store key, then, is the most critical key on a Policy Server, and the one most important to protect. On the Agent side, the shared secret must also be stored securely.

If you install and configure supported nCipher cryptographic modules on Policy Servers and/or Agents in your SiteMinder environment, the on-disk copy of the policy store key, which is called the encryption key during the Policy Server installation, or shared secret is by default protected using a standard encryption technique. However, the policy store key is encrypted using a secure key on a cryptographic token if you have the cryptographic hardware enabled.



Choose a Host Key Management Model

Before implementing cryptographic hardware support in your SiteMinder environment, you must decide on a host key usage/management model that meets your needs. You can choose to use a single host key for all your SiteMinder systems (Policy Server and Agents), or to assign different host keys to individual system or groups of systems. This decision has implications for the level of security provided, and for the management of Operator Card Sets (OCSs) and security worlds.

The level of security may be the least important of these considerations. Using different host keys for each individual system limits the vulnerability if any one host key is compromised. On the other hand, compromise of a single Policy Server can still lead, effectively, to the compromise of the entire system. Because compromising a hardware token is difficult regardless of the number of different keys in use, ease-of-management considerations may take precedence over level of security when deciding how many host keys to use.

The number of host keys used also affects the management of operator card sets. Each host key is kept on a different logical token – that is, a different operator card set. If all systems use the same host key then there is only one operator card set, then replacing that operator card set will require you to generate it from the others. If each server has its own host key (and therefore its own operator card set), then replacing that host key (operator card set) will affect only that server.

Lastly, it is important to note that each operator card set belongs to a particular security world, and that the security world’s data must be accessible from every machine where the operator card set will be used. Since Agents and Policy Servers are typically located on opposite sides of a site’s firewall, with no shared file systems visible to both sides, sharing a security world between them may be difficult.

If a host key (operator card set) must be shared among systems that do not have a shared file system in common, separate copies of the security world data must be maintained. Changes made to one copy of the security world – for example, when a new module or operator card set is added – must be propagated to the other copies. This is a manual process – nCipher does not provide tools for copying or replicating security worlds, or for determining whether security worlds are consistent with each other.

Install Cryptographic Modules and Creating Security Worlds

Once you have decided how many host keys you want to implement and how to configure your security worlds, you should install the necessary cryptographic hardware modules and configure the security worlds using the appropriate nCipher tools and procedures.



Create Operator Card Sets and Initializing Operator Cards

The next step is to create operator card sets and initialize the individual operator cards belonging to each set. You should create one operator card set for each different host key that will be used. Each operator card set should include enough operator cards to accommodate the number of servers that will share the operator card set and the host key stored on it.

Creating an operator card set with more operator card set than needed will allow for future growth and lost or damaged operator card set. All operator cards that belong to an operator card set must be initialized when the operator card set is created.

Initialization of an operator card includes assigning a passphrase which cannot be set to a null value. The SiteMinder software (Policy Server or Agent) will prompt for this passphrase whenever it needs to log in to the token (that is, whenever it initializes). SiteMinder startup cannot continue until a valid passphrase is entered.

Note: Because the SiteMinder software requires that the token passphrase is supplied each time it initializes (that is, upon restart), use of cryptographic modules in your SiteMinder environment prevents unattended system failover.

You create operator card sets using the nCipher KeySafe application or createocs command.

Generate and Load Host Keys

The Policy Server installation program generates a host key if it is not found during installation.

Configure Unattended Failover for nCipher Hardware Modules

You can configure Policy Servers equipped with an nCipher cryptographic module to allow unattended failover by setting the NETE_CMN_PINFO environment variable to the value "rpw:passphrase".

passphrase

Specifies the token passphrase in the environment in which the Policy Server processes run.

Important! The values of environment variables are not encrypted in memory. Additionally, the environment variable must typically be read from an unencrypted command file at runtime. Configuring unattended failover may therefore reduce the level of additional security otherwise provided by the addition of a cryptographic module.

SNMP Support


Once NETE_CMN_PINFO is set, SiteMinder processes that require access to the cryptographic token will use passphrase without prompting the console operator.

If the passphrase supplied in NETE_CMN_PINFO is wrong, the SiteMinder process that tried to use it to access the token will attempt to obtain a correct passphrase by prompting for the console operator to supply it.

SNMP Support SNMP support includes a Management Information Base (MIB), an SNMP Agent, and the Event SNMP Trap library. You can configure the SNMP Agent and Event SNMP Trap library independently and enable one or disable the other or vice versa. The SNMP Agent enables monitoring applications to retrieve operational data from the OneView Monitor. The SNMP Agent sends data to the SNMP manager and supports SNMP request handling.

The following figure shows the architecture between the management application, OS Master Agent, SNMP Agent, and the OneView Monitor.

(M IB B ro w s e r)

M a n a g e m e n tA p p lic a tio n

O S M a s te rA g e n t

M o n ito rin gC lie n t A P I

S N M P A g e n t

S N M P R e q u e s t S N M P R e s p o n s e

S N M P R e q u e s t S N M P R e s p o n s e

O n e V ie wM o n ito r

SNMP Support


The OS Master Agent, such as the native Solaris SunSolstice Master Agent, invokes the SNMP Agent once you restart the Master Agent. Upon receiving an SNMP request from the management application the OS Master Agent forwards the SNMP request to the SNMP Agent. The SNMP Agent contacts the OneView Monitor, retrieves the required information using Monitor Client API, and then sends the response to the Master Agent. The Master Agent, in turn, forwards the response to the management application.

If you do not configure the SNMP Agent during the Policy Server installation, all the SNMP files are still installed in case you want to use the Agent later. However, to get the Agent running, you need to manually get the Agent started by configuring the SNMP Agent on a Windows or UNIX system.

The Event SNMP Trap library converts some SiteMinder events into SNMP traps before sending them to the management application as noted in the following figure. The trap library captures events sent by the Policy Server, decides if SNMP traps are to be generated on a given event, and generates a trap.

Aut

horiz

atio

n

Aut

hent

icat

ion

Adm

inis

trat

ion

Acc

ount

ing

Policy Server

ManagementApplication

Web Server

WebAgent

EventSNMP

EventSNMP

EventSNMP

EventSNMPSNMP Trap

Prerequisites for Windows and UNIX Systems

You need to have a Master Agent installed with your operating system before installing or using the SNMP Agent.

SNMP Support


Windows Prerequisites

For Windows NT/2000, you need the SNMP service. For instructions on installing the SNMP service, refer to the Windows Help system.

Type SNMP into the Windows NT help system index to locate the Microsoft TCP/IP Help system.

Type SNMP service into the Windows 2000 Help system to locate the SNMP Help system.

UNIX Systems Prerequisites

The following section details UNIX prerequisites for SNMP support:

Solaris

You need the native Solaris SunSolstice Master Agent, which comes with the operating system.

Linux

For the supported Master Agent on Red Hat Advanced Server 3.0, upgrade the net-snmp package to net-snmp-5.1-2.1 or greater.

To upgrade the net-snmp package to net-snmp-5.1-2.1 or greater, use the following setting in net-snmpd instead of-c public -v 1 -p 8001 localhost .1.3.6.1.4.1.2552: proxy -c public -v 1 localhost:8001 .1.3.6.1.4.1.2552

Configure the SNMP Agent on Windows

To configure the SNMP agent on Windows

1. Ensure the NETE_PS_ROOT environment variable is set to the SiteMinder installation directory. The Policy Server installation program should have already done this.

2. Open the <siteminder-install-dir>\config\snmp.conf file and edit the last row to contain the full path to <siteminder-install-dir>\log\snmp.log.

Note: You only need to do this if you did not specify the Policy Server installation program to automatically configure SNMP.

Correct example: LOG_FILE=C:\Program Files\Netegrity\siteminder\ log\snmp.LOG

Incorrect example: LOG_FILE=$NETE_PS_ROOT\log\snmp.log

SNMP Support


3. Edit <Windows_dir>/java_service.ini file.

Note: You only need to do this if you did not specify the Policy Server installation to automatically configure SNMP.

a. Set SERVICE_BINARY_NAME to the full path name of JavaService.exe.

Example: SERVICE_BINARY_NAME=c:\winnt\JavaService.exe

b. Set WORKING_DIR to the full path to directory <siteminder-install-dir>\bin:

Example: WORKING_DIR=C:\Program files\Netegrity\siteminder\bin

c. Set JRE_PATH to the full path of javaw.exe.

4. Run <siteminder-install-dir>\bin\thirdparty\proxyreg.exe to change the registry keys for the apadll.dll and snmp.conf:

proxyreg.exe <full path for apadll.dll> <full path for snmp.conf>

Example: proxyreg.exe "c:\program files\netegrity\siteminder\ bin\ thirdparty\apadll.dll" "c:\programfiles\netegrity\ siteminder\ config\ snmp.conf"

5. Run <WINNT dir>/JavaService.exe with the -install option, to register the Netegrity SNMP agent as a WINNT service.

6. Start the Netegrity SNMP agent by using the Windows Services dialog box.

7. Restart the SNMP service.

How to Configure SNMP Event Trapping on Windows

Configuring SNMP event trapping on Windows requires you to:

1. Enable SNMP event trapping (see page 207).

2. Configure snmptrap.config (see page 208).

Enable SNMP event trapping




3. In the Event Handler’s field at the bottom, enter the full path to the EventSNMP.dll.

4. Click OK.


More Information:

Configure snmptrap.config (see page 208)

SNMP Support


Configure snmptrap.config

To configure snmptrap.config

1. Edit snmptrap.config, which is located in C:\ProgramFiles\Netegrity\siteminder\ config.

2. For the specified trap(s) that you want to receive, uncomment out the appropriate line(s).

3. Specify the IP Address, port number, and community for where you want the trap to be sent.

4. Save the snmptrap.config file with the new changes.

5. Restart the Policy Server.

More Information:

Stop and Restart the Policy Server (see page 209)

Configure the SNMP Agent on UNIX Systems

To configure the SNMP Agent on UNIX systems

1. Ensure the NETE_PS_ROOT environment variable is set to the SiteMinder installation directory. The Policy Server installation program should have already done this.

Example: /home/smuser/siteminder

2. Edit the file /etc/snmp/conf/RunSubagent.sh:

a. Set the correct JRE path: JAVA_HOME=$INSTALL_HOME/bin/jdk/<required_version>/jre

b. Set the correct SiteMinder path:

Example: INSTALL_HOME=/home/smuser/siteminder

Note: The INSTALL_HOME variable should contain the full path for the SiteMinder installation directory.

3. Restart the SNMP daemon on Solaris

a. Become root.

b. Goto /etc/rc3.d.

c. Execute the S76snmpdx script twice, as follows:

sh S76snmpdx stop to stop the running Solaris master agent.

sh S76snmpdx start to start the Solaris master agent and Netegrity subagent.

SNMP Support


How to Configure SNMP Event Trapping on UNIX Systems

Configuring SNMP event trapping on UNIX systems requires you to:

1. Enable SNMP event trapping (see page 209).

2. Configure snmptrap.config (see page 209).

Enable SNMP event trapping




3. In the Event Handler’s field at the bottom, enter the full path to libeventsnmp.so.

Example: /home/smuser/siteminder/lib/libeventsnmp.so

4. Click OK.


More Information:

Configure snmptrap.config (see page 209)

Configure snmptrap.config

To configure snmptrap.config

1. Edit snmptrap.config, which is located in /home/smuser/siteminder/config.

2. For the specified trap(s) that you want to receive, uncomment out the appropriate line(s).

3. Specify the IP Address, port number, and community for where you want the trap to be sent.

4. Save the snmptrap.config file with the new changes.

5. Restart the Policy Server.

More Information:

Stop and Restart the Policy Server (see page 209)

Stop and Restart the Policy Server

In order for the SNMP configurations changes to take effect, you need to stop and restart the Policy Server using the Status tab of the Policy Server Management Console.

Troubleshooting


Test SNMP Gets for Red Hat Enterprise Linux Advanced Server

You should test SNMP Gets after configuring SNMP.

To test SNMP Gets

1. Start the native SNMP master agent. On Red Hat AS, the master agent is not started automatically on start up as is the case on Solaris and HP-UX. To start the master agent, go to the /etc/rc1.d directory and run the following command (run as root):

K50snmpd start

2. Start the Netegrity subagent using the following command (run as root):

sh /etc/init.d/NetegrityAgent

3. To stop the Netegrity subagent on Red Hat AS, run the following command as root:

sh $NETE_PS_ROOT/etc/snmp/conf/StopSubagent.sh

Test SNMP Gets for HP-UX

You should test SNMP Gets after configuring SNMP.

To test SNMP Gets

1. Start the Native Agent Adaptor with the script “/sbin/init.d/SnmpNaa” using the following command as root:

nohup sh /sbin/init.d/SnmpNaa start

2. Start the Netegrity subagent with the script “/sbin/init.d/SnmpNetegrity” using the following command (run as root):

nohup sh /sbin/init.d/SnmpNetegrity start

3. To stop the Netegrity subagent on HP-UX, run the following command as root: sh /sbin/init.d/SnmpNetegrity stop

Troubleshooting This section provides tips for troubleshooting the Policy Server.

Troubleshooting


Database may be corrupt message

Valid on Windows and UNIX Systems

Symptom:

When I try to migrate policy store data from one LDAP Directory Server or relational database to another, the Policy Server displays a message that the database may be corrupt.

Solution:

When migrating the policy store, you must import the smpolicy.smdif file before importing your exported policy store’s data even if you are migrating between the same version of SiteMinder. If you import your old policy store data before importing smpolicy.smdif, SiteMinder may issue the "Database may be corrupt" message. You can fix your corrupted policy store by importing smpolicy.smdif after importing your old policy store data. However, you should import the smpolicy.smdif file first.

More Information:

Migrate an Existing Policy Store into an LDAP Directory (see page 101) Migrate an Existing Policy Store into a Relational Database (see page 140)

Troubleshooting


SiteMinder Administration Server Error: Could not log in. (Error 3)

Valid on Windows

Symptom:

I have received the following SiteMinder Administration server error: Could not log in. (Error 3)

Solution:

Reset the Siteminder Super User password for the policy store by completing the following steps:

1. Copy smreg.exe from the \win32\tools directory on the SiteMinder DVD to <siteminder_installation>\bin

2. Execute the following command:


superuserpassword



3. Delete smreg.exe.

Deleting smreg.exe prevents anyone from changing the Super User password.

Troubleshooting


Policy Server User Interface Does Not Appear on Windows

Valid on Windows

Symptom:

I have installed the Policy Server, but it does not appear.

Solution:

If you installed an Internet Information Server (IIS) Web Server on a port other than 80, the Policy Server User Interface may not appear. Editing the Policy Server User Interface shortcut URL should fix the problem.

To edit the shortcut URL.

1. Right-click Start and select Open All Users.

2. Double-click Programs.

3. Double-click SiteMinder.

4. Highlight the Policy Server User Interface icon, right click, and select Properties.

5. Select the Web Document tab.

6. In the URL field on the Web Document tab, change the port number to the one you configured for the IIS Web Server.

Example: if your IIS Web Server is located on port 81, change:

http://<fully qualified domain name>:80/siteminder/index.htm

to http://<fully qualified domain name>:81/siteminder/index.htm

7. Click Apply and OK.

If you are still have difficulty getting the Policy Server User Interface to display, run the Policy Server User Interface Browser Compatibility Test at the following URL: http://www.netegrity.com/uitest

If the panel is a solid box, click Details for more troubleshooting information.

Troubleshooting


Unable to proceed. No response from SiteMinder Message


Symptom:

I have received the "Unable to proceed. No response from SiteMinder" message.

Solution:

Stop and restart the Policy Server using the Policy Server Management Console’s Status tab.

Policy Server Fails to Start After Installation


Symptom:

I have installed the Policy Server, but it is not starting.

Solution:

You may have the wrong JRE version installed. Make sure you have the correct JRE version.

AE failed to load library 'smjavaapi’. System error


Symptom:'

During Authorization, I receive the "AE failed to load library 'smjavaapi'. System error: The specified module could not be found." error message.

Solution:

Set the PATH variable to policy_server_installation\config\JVMOptions.txt for Windows or the LD_LIBRARY_PATH to policy_server_installation/config/JVMOptions.txt for UNIX systems.

Troubleshooting


PDF Files Do Not Open From the Online Manuals Index HTML Page

Valid on UNIX Systems

Symptom:

When I click a link on the doc_index.htm page, the .pdf file does not open.

Solution:

Set Acrobat Reader as a helper application within Netscape Navigator. When you set this option, Netscape automatically launches Acrobat Reader each time you request to view a .pdf file.

To set Acrobat Reader as a Helper Application

1. In Navigator, go to Go the Edit, Preferences.

2. In the Netscape Preferences dialog, select Navigator, Applications.

3. Under Applications Specify helper applications for different file types, select Portable Document Format and click Edit.

4. In the Netscape Applications dialog, select Applications and set it to:

<Acrobat_Reader_installation>/bin/acroread %s

Example: if you installed Acrobat Reader in the default location, set this value to /usr/local/Acrobat4/bin/acroread %s.

5. Click OK to close these dialogs.

After you set this option, Navigator launches Acrobat Reader and opens the .pdf file in /tmp each time you request one.

Locate Logging Messages if Smobjimport Fails During Import


Symptom:

The smobjimport fails when I attempt to import an .smdif file.

Solution:

Read the error and warning message logging information in the <importfilename>.log and <importfilename>.tmp files.

Troubleshooting


Missing Icons on the System and Domains tab of the Policy Server UI


Symptom:

The Policy Server user interface is missing icons on the System and Domain tabs.

Solution:

Clear the Web browser cache by deleting all of the temporary internet files.

Cannot launch Regedit Tool on UNIX Systems


Symptom:

When I trying to back up the 4.51 or 4.61 SiteMinder registry using the regedit tool located in <siteminder_installation>/windu/bin directory, I get the following error: "fatal: libcommdlg43.so: open failed: No such file or directory."

Solution:

Set the LD_LIBRARY_PATH by running smprofile.ksh.

Troubleshooting


Cannot Access Online Manuals from Policy Server User Interface

Valid on Windows

Symptom:

I am unable to access the online manuals from the Policy Server user interface

Solution:

If you get the following message using Internet Explorer: “Access to the specified device.path, or file is denied trying to access online manuals from UI”, you may need to install Acrobat Reader from www.adobe.com.

You may also need to manually edit the netegrity_docs Virtual Directory.

More Information:

Manually Create the netegrity_docs Virtual Directory on IIS 5.0/6.0 (see page 221)

Adobe Acrobat Reader Won’t Install

Valid on Windows

Symptom:

When I try to install Adobe Acrobat, the installation program hangs.

Solution:

If the Acrobat Reader installation program hangs while the Policy Server service is running, stop it using the Policy Server Management Console’s Status tab. After stopping the service, the installation program should start.

Windows/IIS Virtual Path to /sitemindermonitor Does Not Exist

Valid on Windows

Symptom:

The virtual path to the /sitemindermonitor does not exist under Default Web Site in the IIS Microsoft Management Console.

Troubleshooting


Solution:

Create the virtual path.

To create the virtual path

1. From the Start menu, go to:

Windows 2000: Programs, Administrative Tools, Internet Service Manager.

2. Select Default Web Site.

3. From the Action menu, select New, Virtual Directory.

The Virtual Directory Wizard opens.

4. Specify the name (alias) of the virtual directory. For example: sitemindermonitor

Note: You can specify any name for the alias as sitemindermonitor is an example

5. Click Next.

6. Specify the path to <siteminder_installation>\monitor\.

7. Click Next.

8. Select the Allow Execute Access permission.

9. Click Finish.

Policy Stores with Large Numbers of Objects


Symptom:

My Policy store has returned the exception java.lang.IndexOutOfBounds to the Policy Server User Interface.

Solution:

Policy Stores with large numbers of objects may return the exception java.lang.IndexOutOfBounds to the Policy Server User Interface.

Define the registry key \HKEY_LOCAL_MACHINE\SOFTWARE\Netegrity\SiteMinder\CurrentVersion\ObjectStore\MaxObjects to a value lower than 100 (such as 50).

Troubleshooting


SSL initialization failed: error -8174 (security library: bad database.)


Symptom:

When I run smldapsetup ldmod -fpstore -ssl1 -c/app/siteminder/ssl/cert7.db for policy stores that are using an SSL-encrypted connection to Sun Java System LDAP, I receive the following error message:

"SSL initialization failed: error -8174 (security library: bad database.)"

Solution:

1. Make sure the key3.db file exists in the same directory as cert7.db for the Netscape Web browser.

2. Rerun this smldapsetup command, and, for the -c option, specify the path of the directory where the SSL client certificate database file, cert7.db, exists.

Example: if cert7.db exists in /app/siteminder/ssl, specify -c/app/siteminder/ssl

More Information:

Manage an LDAP Policy Store Using smldapsetup (see page 159)

Winsock error 10054 message

Valid on Windows

Symptom:

When I try to log into the Policy Server, I receive the "Unable to proceed, winsock error 10054" message.

Troubleshooting


Solution:

One of the following could be the cause of the problem:

The policy store does not contain the proper SiteMinder schema. Make sure you imported the correct SiteMinder schema.

The Policy Server is not running. To start this server, use the Status tab on the Policy Server Management Console.

The Policy Server is not connected to the policy store properly. Using the Data tab on the Policy Server Management Console, click Test Connection to make sure the policy store connects successfully. If it does not, reenter the data source information values on the Data tab by pointing the the Policy Server at the policy store.

More Information:

LDAP Directory Servers as a Policy or Key Store (see page 75) Relational Databases as a Policy or Key Store (see page 104) Point the Policy Server at the Policy Store (see page 103)

Extra Shortcuts in the Windows Start Menu

Valid on Windows

Symptom:

During an upgrade from SiteMinder 4.51, 4.61 or 5.0, two extra shortcuts may appear in the SiteMinder Program group:

SiteMinder Policy Server User Interface

SiteMinder Policy Server Management Console

Solution:

You may use or disregard these shortcuts. They are duplicates, respectively, of the following:

Policy Server User Interface

Policy Server Management Console

To manually remove these extra shortcuts after the upgrade

1. Right-click the Start menu.

2. Go to ..\Documents and Settings\All Users\Start Menu\Programs\SiteMinder.

3. Delete the SiteMinder Policy Server User Interface or SiteMinder Policy Server Management Console shortcuts.

Troubleshooting


Problem With Using Active Directory as a User Store

Symptom:

When I use Active Directory as a user store, the Policy Server issues error messages that it cannot connect to this store.

Solution:

When creating an Active Directory-based user store, make sure you specify a fully qualified host name (for example, host.domain.com) in the Policy Server User Interface and do not use the machine's IP Address. Moreover, make sure you can ping host.domain.com and domain.com from the machine where the Policy Server is installed since Active Directory sends referrals to the Policy Server that are identified by the fully qualified host name. If the fully qualified host names are invalid and unreachable, the Policy Server issues error messages.

Manually Create the netegrity_docs Virtual Directory on IIS 5.0/6.0

Symptom:

I have installed the documentation, but it does not appear in the Policy Server user interface.

Solution:

If you installed the documentation after the Policy Server and the documentation does not appear from the Policy Server User Interface:

1. Start the Internet Information Services (IIS) Manager.

2. Under Default Web Site, create the netegrity_docs virtual directory and point it to C:\Program Files\Netegrity\netegrity_documents.

Note: The above example gives the absolute path to the default netegrity_documents installation location. If you installed the documentation in a different location, then specify the correct path.

The documentation should now appear from the Policy Server User Interface when you select Help, Online Manuals.

Troubleshooting


Fix Modified UNIX/Sun Java System Web Server Configuration Files

As mentioned in the procedure for installing the ServletExec/AS 4.2 on a UNIX/Sun Java System, we advise not allowing ServletExec to modify the Sun Java System Web server’s configuration files (obj.conf and magnus.conf). However, if ServletExec did modify these files during installation, the Web server instance fails after you configure the Policy Server User Interface and OneView Monitor GUI using the Policy Server installer/wizard. The ServletExec installer puts entries in these files that conflict with those from the Policy Server.

To keep the Web server instance from failing, remove the conflicting entries from the Sun Java System Web Server instance’s obj.conf and magnus.conf files.

1. Open /<sunjavasystem_home>/servers/https-<web_server_instance_name>.domain.com/config/magnus.conf, and remove the first line:

Init fn="ServletExecInit"

<ServExec_instance_name>.instances="<IP_address>:<portnumber> "

ServExec_instance_name

Specifies the name of your SerlvetExec instance.

IP_address

Specifies the IP Address of the machine where ServletExec is installed.

portnumber

Specifies the port number for the SerlvetExec instance.

Note: The Policy Server Configuration Wizard added the correct entry at the end of the file.

2. Open /<sunjavasystem_home>/servers/https-<web_server_instance_name>.domain.com/config/obj.conf, and remove lines four and five from the top of the file:

NameTrans fn="assign-name" from="/servlet/*" name="<ServExec_instance_name>"

NameTrans fn="assign-name" from="*.jsp*" name="<ServExec_instance_name>"

Important! Do not remove the name="se-<ServExec_instance_name>" entries in lines two and three since these were added by the Policy Server Configuration Wizard.

3. In the same obj.conf file, remove the second to the last <Object name="<ServExec_instance_name>"> section from the end of the file:

<Object name="<ServExec_instance_name>">

Service fn="ServletExecService" group="<ServExec_instance_name>"

</Object>

Troubleshooting


Important! Do not remove the <Object name="se-<ServExec_instance_name>"> entry since this one was added by the Policy Server Configuration Wizard.

4. After saving these files, you should be able to start the Web server instance from the Sun Java System Web Server Administration Server page.

NETE_PS_ALT_CONF_FILE Environment Variable on Solaris

After installing the Policy Server on Solaris, the nete_ps_env.ksh script may have the following entry: export NETE_PS_ALT_CONF_FILE=/export/siteminder/config/.siteminder.conf

The NETE_PS_ALT_CONF_FILE environment variable is used by the stop-all and start-all scripts, which stop and start the Policy Server’s service. The .siteminder.conf file is a temporary, run-time file created by these scripts and has no affect your SiteMinder configuration.

Do not modify the NETE_PS_ALT_CONF_FILE environment variable.

Troubleshooting


Manually Configure the OneView Monitor GUI on UNIX/Sun Java System 6.0

If you do not configure the OneView Monitor GUI using the Policy Server Configuration Wizard, you can configure it manually by modifying the Sun Java System Web Server’s obj.conf and magnus.conf files and ServletExec’s StartServletExec file. The Policy Server Configuration Wizard performs the following procedure automatically so these steps are provided as a reference to help you troubleshoot OneView Monitor GUI issues.

1. Open /usr/local/NewAtlanta/ServletExecAs/se-<instance_name>/StartServletExec in a text editor, and do the following modifications:

a. Find the PORT=8888 entry, and change the port of communication with Web server to any free port (for example, PORT=7777).

instance_name

Specifies the name of your ServletExec instance.

The following is a sample entry:

THISHOST="testmachine"

PORT=8888

SEINSTANCE="testmachine-servexecinstance"

a. Extend the CLASSPATH definition by adding the entries in boldface to the end of the CLASSPATH:

CLASSPATH=${NA_ROOT}/lib/ServletExec42.jar:${NA_ROOT}/lib/servlet.jar:${JL}/tools.jar:${NA_ROOT}/lib/activation.jar:${NA_ROOT}/lib/dom.jar:${NA_ROOT}/lib/jaxen-full.jar:${NA_ROOT}/lib/jaxp-api.jar:${NA_ROOT}/lib/jdbc2_0-stdext.jar:${NA_ROOT}/lib/jndi.jar:${NA_ROOT}/lib/jstl.jar:${NA_ROOT}/lib/mail.jar:${NA_ROOT}/lib/sax.jar:${NA_ROOT}/lib/saxpath.jar:${NA_ROOT}/lib/standard.jar:${NA_ROOT}/lib/xalan.jar:${NA_ROOT}/lib/xercesImpl.jar:${NA_ROOT}/lib/xsltc.jar:${NA_ROOT}/se-${SEINSTANCE}/classes:<siteminder_installation>/monitor/smmongui.jar:<siteminder_installation>/lib/smconapi.jar:<siteminder_installation>/lib/smmonclientapi.jar

where <siteminder_installation> is, for example: /export/netegrity/siteminder.

b. Extend the document directories definition by adding the entries in boldface to:

$SENAME $HOMEDIR $MIMEFILE $DOCROOTDIR-port $PORT $SEOPTS -addl "/sitemindermonitor= <siteminder_installation>/monitor""

where <siteminder_installation> is, for example: /export/netegrity/siteminder.

Note: There are two quotes at the end of the entry above.

Troubleshooting


2. For Sun Java System 6.0, open /<sunjavasystem_home>/servers/https-<instance_name>.domain.com/config/magnus.conf, and move the Init fn="load-modules" section to the end of the file between the following new Init fn="init-cgi" and Init fn="ServletExecInit" sections:

Init fn="init-cgi" SM_ADM_UDP_PORT="44444" SM_ADM_TCP_PORT="44444"

Init fn="load-modules" shlib="<ServletExec_installation>/bin/ServletExec_Adapter.so" funcs="ServletExecInit,ServletExecService"

Init fn="ServletExecInit" <instance_name>.instances="<IP_address>:<portnumber> "

ServletExec_installation

Specifies the path to the ServletExec installation.

Example: /export/NewAtlanta/ServletExecAS

instance_name


IP_address

Specifies the IP Address of the machine where ServletExec is installed.

portnumber

Specifies the port number that you entered in the StartServletExec file.

3. Open /<sunjavasystem_home>/servers/https-<instance_name>.domain.com/config/obj.conf, and do the following:

a. Add these lines exist, in this order, under <Object name="default">:

<Object name="default">

NameTrans fn="assign-name" from="*.jsp*" name="<instance_name>"

NameTrans fn="assign-name" from="/servlet/*" name="<instance_name>"

NameTrans fn="pfx2dir" from="/sitemindermonitor" dir="<siteminder_installation>/monitor"

where <instance_name> is the name of your SerlvetExec instance and <siteminder_installation> is the SiteMinder installation directory, for example, /export/netegrity/siteminder.

Important! The last entry must be after the other two to ensure proper configuration of the OneView Monitor GUI.

b. Add the following to the end of the file:

<Object name="<instance_name>">

Troubleshooting


Service fn="ServletExecService" group="<instance_name>"

</Object>

instance_name


4. Stop and restart the Web server and ServletExec.

Set JRE in PATH Variable Before Uninstalling Any SiteMinder Component

Symptom:

When I attempt to uninstall the Policy Server, Web Agent, Policy Server Option Pack, Web Agent Option Pack, SDK, or SAML Affiliate Agent, the uninstallation program stops and issues one of the following error messages:

“Could not find a valid Java virtual machine to load. You need to reinstall a supported Java virtual machine.”

"No Java virtual machine could be found from your PATH environment variable. You must install a VM prior to running this program."

Solution:

Make sure the JRE is in the PATH variable.

Set the JRE in the PATH Variable on Windows

To Set the JRE in the PATH variable

1. Go to the Control Panel.

2. Double-click System.

3. In the Environment Variables dialog, add the location of the JRE to the Path system variable.

Set the JRE in the PATH Variable on Solaris

To set the JRE in the PATH variable

Run the following commands:

a. PATH=$PATH:<JRE>/bin

JRE

Specifies the location of your JRE.

a. export PATH

Post-installation, SOA Agent for Web Servers 227

Chapter 5: Post-installation, SOA Agent for Web Servers


Configure an IIS Web Agent (see page 227) Configure a Sun Java System Web Agent (see page 235) Configure a SOA Agent for Apache Web Servers (see page 244) Configure a SOA Agent for Domino Web Servers (see page 257) How to Configure Any Web Agent in Unattended Mode (see page 264) Reconfigure a Web Agent (see page 266) How to Tune the Solaris 10 Resource Controls (see page 267) How to Set Up Additional Agent Components (see page 268) Troubleshooting a SOA Agent for Web Servers (see page 269)

Configure an IIS Web Agent Perform the following procedures to configure a SOA Agent for IIS web servers.

How to Configure an IIS Web Agent

The Web Agent can operate with an IIS 6.0 web server on Windows Server 2003. Before you configure the Web Agent on an IIS 6.0 web server, you will need to complete some prerequisites using the following process:

1. Assign read permissions to samples and error files directories.

2. Allow IIS to execute Web Agent ISAPI and CGI extensions.

3. (Optional) Increase the Web Agent's size limit for uploaded files.

4. Run the Configuration Wizard for an IIS Web Agent.

5. Put the Agent filter and extension before other third-party filters.

Configure an IIS Web Agent


Assign Read Permissions to Samples and Error Files Directories

The Network Service account must have Read permissions to any directory where the Web Agent reads forms credential collector (FCC) files and to any directory where the Web Agent reads Web Agent custom error files.

To Assign Read Permissions to the Samples and Error Files Directories

1. Open Windows Explorer and go to the appropriate directory:

samples: <web_agent_home>/samples

custom error file: the location or your custom error files. There is no default location.

2. Right-click the directory and select Sharing and Security.

3. Select the Security tab.

4. Click Add.

The Select Users, Computers, or Groups dialog box opens.

5. Do one of the following:

a. Accept the defaults for the Select this object type and From this Location fields.

b. In the Enter the object names to select field, enter Network Service and click OK.

You return to the Properties dialog box for the directory.

6. In the Permissions for Network Service scroll-box, allow Read permissions.

7. Click OK to finish.

8. Repeat this procedure for each directory.



Allow IIS to Execute the Agent ISAPI and CGI Extensions

You must add certain ISAPI and CGI extentions to the IIS 6.0 web server and grant the server permission to execute them before configuring the SiteMinder Web Agent. These extensions will execute the Web Agent ISAPI and CGI scripts and other files.

To add the extensions and permissions

1. Open the Internet Information Services (IIS) Manager, and then expand the web server you are configuring for the Agent.

2. Double-click Web Service Extensions

The Web Service extensions pane appears..

3. For each ISAPI Web Agent:

a. Click the Add a new Web service extension link.

The New Web Service Extension dialog box opens.

b. In the Extension name field, enter ISAPI6WebAgentDLL, and then click Add.

The Add File dialog box opens.

c. Click the Browse button, and then navigate to the ISAPI6WebAgent.dll file in the <web_agent_home>/bin directory. If the proper file does not appear, click the Files of type drop-down list and select either ISAPI dll files (for the .dll files) or CGI exe files (for .exe files).

d. Click Open

The path to the file appears in the Add File dialog box.

e. Click OK.

You return to the New Web Service Extension dialog box.

f. Select the Set extension status to allowed check box.

g. Click OK.

The New Web Service Extension dialog box closes.

4. Repeat Step 3 and add each of the following Web Agent files. Even though both files use the same name, you must add a separate extension for each because they are in different directories.

<web_agent_home>/pw/smpwservicescgi.exe (suggested extension name: Password Services CGI)

<web_agent_home>/pw_default/smpwservicescgi.exe (suggested extension name: PW Default CGI)



Configuration Notes for Web Agents on IIS 6.0 Servers

The following sections contain configuration notes for Web Agents on IIS 6.0 servers.

IIS 6.0 Web Agents and Third-Party Software on the Same Server

The IIS 6.0 Web Agent consists of an ISAPI filter and an ISAPI extension. The majority of Web Agent processing occurs in the extension, following Microsoft IIS development guidelines. These guidelines specify that for the IIS 6.0 web server, the ISAPI filters should be used for filtering requests and the ISAPI extensions should be used to process or redirect requests.

When the Web Agent is installed on an IIS 6.0 Web Server with other third-party software, such as WebSphere or ServletExec, the Agent has the following restrictions:

The Web Agent filter and Web Agent extension must be configured to run before other third-party filters installed on the web server.

The Web Agent must be configured as the first wildcard application map if it is going to protect applications running as or spawned by an ISAPI extension.

The IIS 6.0 web server does not enforce how third-party filters and extensions behave. IIS 6.0 processes ISAPI filters before calling ISAPI extensions, including the Web Agent extension. Therefore, the SiteMinder Web Agent for IIS 6.0 is unable to authenticate or authorize access to applications implemented as pure ISAPI filters. This limitation impacts Web Agent integration with other third-party offerings for the IIS 6.0 web server, if those offerings are implemented as ISAPI filters that process and/or redirect the request before ISAPI extensions are called.

Increase the Agent's Size Limit for Uploaded Files

The Web Agent installed on an IIS 6.0 web server has a size limit of 2.5 MB for uploading files.

To upload files that are larger than this limit

1. Create a new DWORD registry key in SOFTWARE\Netegrity\SiteMinder Web Agent\Microsoft IIS called MaxRequestAllowed.

2. Set this value to the desired file size limit.

The value of this key overrides the default limit. If the value of this key is less than or equal to 0, than the default of 2.5 MB will be used.

Note: The IIS 6.0 web server has its own size limit. Changing the Web Agent’s limit will not affect the IIS 6.0 limit. If you want to change the IIS 6.0 server’s limit, refer to Microsoft IIS 6.0 documentation.



Run the Configuration Wizard for an IIS Web Agent

Before you configure the Agent, you may want to register the system where the Agent is installed as a trusted host; however, you can do this at a later time.

To configure an IIS Web Agent

1. If necessary, start the Web Agent Configuration Wizard.

The default method is to select Start, Programs, SiteMinder, Web Agent Configuration Wizard. If you have placed the Wizard shortcut in a non-default location, the procedure will be different.

Note: If you chose to configure the Web Agent immediately after the installation, SiteMinder automatically starts the wizard automatically.

2. If you have registered the trusted host, skip to the next step. If not, select No in the Host Registration dialog box to skip registration, then click Next.

3. Select the web server instances that you want to configure with Web Agents.

If you have already configured a server with a Web Agent and you are running the Configuration Wizard to configure additional web servers instances, the Wizard displays the Select One or More Instances to Overwrite dialog box. This dialog box lists the web servers that you have previously configured.

a. Select one of the following:

Overwrite—to overwrite the server instance configuration.

Preserve—to preserve the web servers configuration.

Important! If you uncheck a previously configured server, the Web Agent will be removed from this server.

b. Click Next.

4. In the Agent Configuration Object field, enter the name of the Agent Configuration Object for this web server instance, then click Next.

This name must match an Agent Configuration Object already defined at the Policy Server. For example, enter IISDefaultSettings to use the default.



5. If you want to configure Registration Services for DMS2, select Yes. If not, select No.

A servlet engine is required to run Self Registration. If the Web Agent Configuration Wizard does not detect a servlet engine, the Select Servlet Engine for Registration dialog box is not displayed.

If you selected Yes to configure Registration Services:

a. Select a servlet engine to be configured for the web server. If you do not see your engine displayed, select Other Advanced server. Click Next.

b. In the Self Registration Services Admin Account dialog box, identify the the DMS Administrator by provide values for the Admin User Name, Admin Password and Admin Confirm Password fields and click Next.

The user name and password that you enter here must match the DMS Admin values you set at the Policy Server.

The DMS Administrator account secures DMS requests that are performed outside of the scope of a DMS administrator, such as self-registration. The user name and encrypted password for the account are stored in the dms.properties file on the Web Agent.

6. In the Web Server Configuration Summary dialog box, confirm that the configuration settings are correct, then click Install.

The Web Agent files are installed.

7. Click Done when the installation is complete.



8. If you enabled cryptographic hardware on an Agent, you need to allow the associated Web-server service to interact with the desktop. This allows the service to prompt for the hardware’s associated passphrase.

To configure the service to interact with the desktop:

a. Open the Services control panel.

On Windows 2000, you access Services by selecting Administrative Tools, Computer Management, Services and Applications.

b. Double click the World Wide Web Publishing Service.

The Service dialog box opens.

c. Select Allow Service to Interact with Desktop.

On Windows 2000, this checkbox is on the Log On tab for the World Wide Web Publishing Service.

d. Click OK.

e. Exit the Control Panel.

9. Enable the Web Agent:

a. Open the WebAgent.conf file located in <web_agent_home>\bin\IIS

Example: C:\Program Files\netegrity\webagent\bin\IIS

b. Set the EnableWebAgent parameter to Yes.

c. Save the file and restart the web server.

Note: You need to reboot the machine once the Agent is configured to ensure proper logging of Agent and trace messages.



Put the Agent Filter and Extension Before Other Third-Party Filters

The IIS 6.0 Web Agent consists of an ISAPI filter and an ISAPI extension. The majority of Web Agent processing occurs in the extension, following Microsoft IIS development guidelines. These guidelines specify that for the IIS 6.0 web server, the ISAPI filters should be used for filtering requests and the ISAPI extensions should be used to process or redirect requests.

When the Web Agent is installed on an IIS 6.0 Web Server with other third-party software, such as WebSphere or ServletExec, the Agent has the following restrictions:

The Web Agent filter and Web Agent extension must be configured to run before other third-party filters installed on the web server.

The Web Agent must be configured as the first wildcard application map if it is going to protect applications running as or spawned by an ISAPI extension.

The IIS 6.0 web server does not enforce how third-party filters and extensions behave. IIS 6.0 processes ISAPI filters before calling ISAPI extensions, including the Web Agent extension. Therefore, the SiteMinder Web Agent for IIS 6.0 is unable to authenticate or authorize access to applications implemented as pure ISAPI filters. This limitation impacts Web Agent integration with other third-party offerings for the IIS 6.0 web server, if those offerings are implemented as ISAPI filters that process and/or redirect the request before ISAPI extensions are called.

When you install the Web Agent on an IIS 6.0 web server, the Agent’s filter is automatically placed at the top of the ISAPI filters list. However, if you install any other third-party plugins after installing the Web Agent, those filters may take precedence.

After you install and configure an IIS 6.0 Web Agent, you must ensure that the siteminderagent ISAPI filter and extension is listed before any third-party filter or extension. This enables the Web Agent to process requests before a third-party.

To put the agent filter and extension before other third-party filters

1. Check the ISAPI filter by doing the following steps:

a. Open the IIS Manager.

b. Select Web Sites then right-click and select Properties.

c. Select the ISAPI Filters tab.

d. Check the list of filters and ensure that siteminderagent is the first entry in the list. If it is not, use the Move Up button to place it at the top of the list.

e. Click OK.

Configure a Sun Java System Web Agent


f. Exit the IIS Manager.

2. Check the ISAPI extensions by doing the following steps:

To ensure the ISAPI extension is listed first, open the IIS management console and access the properties for the web server top level or for the server’s default Web site. In the Home Directory tab, go to the application settings and display the Application Mappings list to see the list of extensions.

Configure a Sun Java System Web Agent Perform the following procedures to configure a SOA Agent for Sun Java System web servers.

Configuration Methods for Sun Java System Web Agents on Windows Systems

The following configuration methods are available for Web Agents on Windows systems:

GUI mode

Unattended mode

More Information

Run the Configuration Wizard on Windows (see page 235) How to Configure Any Web Agent in Unattended Mode (see page 264)

Run the Configuration Wizard on Windows

To configure the Web Agent on an Sun Java System web server


The default method is to select Start, Programs, SiteMinder, Web Agent Configuration Wizard. If you have placed the Wizard shortcut in a non-default location, the procedure will be different.

Note: If you chose to configure the Web Agent immediately after the installation, SiteMinder automatically starts the wizard automatically.

2. If you have already done host registration, skip to the next step. If not, select No in the Host Registration dialog box to skip registration, then click Next.

To register a trusted host, go to the installation chapter for your platform.









b. Click Next.

4. In the Agent Configuration Object field, enter the name of the Agent Configuration Object for this web server instance, then click Next.

This name must match an Agent Configuration Object already defined at the Policy Server. For example, to use the default enter iPlanetDefaultSettings.



5. If applicable, select one of the advanced SSL authentication schemes listed in the SSL Authentication dialog box. If the Agent is not providing advanced authentication, select No advanced authentication. Click Next.

The selections are:

HTTP Basic over SSL—identifies a user based on a user name and password. The credential delivery is always done over an encrypted Secure Sockets Layer (SSL) connection.

X509 Client Certificate—identifies a user based on X.509 V3 client certificates. Digital certificates act as a signature for a user. Certificate authentication uses SSL communication.

X509 Client Cert and HTTP Basic—combines X.509 Client Certificate and Basic authentication. The user’s X.509 client certificate must be verified and he or she must provide a valid user name and password.

X509 Client Cert or HTTP Basic—combines X.509 Client Certificate and Basic authentication. The user’s X.509 client certificate must be verified, or he or she must provide a valid user name and password.

X509 Client Cert or Form—The X.509 Client Certificate or HTML Forms authentication scheme combines the use of X.509 Client Certificates and the use of customized HTML forms to collect authentication information. Using this scheme, the user’s X.509 client certificate must be verified or the user must provide the credentials requested by an HTML form.

X509 Client Cert and Form—The X.509 Client Certificate and HTML Forms authentication scheme combines the use of X.509 Client Certificates and the use of customized HTML forms to collect authentication information. Using this scheme, the user’s X.509 client certificate must be verified and the user must provide the credentials requested by an HTML form.

Note: For additional information about advanced authentication schemes, refer to CA eTrust Policy Design.

If this Web Agent is installed on an SSL server to handle only credential collection requests for advanced authentication schemes, set the Agent’s EnforcePolicies setting to No to improve performance. To modify the Agent’s configuration, refer to CA eTrust Policy Design or, for local configuration, this guide.



6. If you want to configure Self Registration for DMS2, select Yes. If not, select No.


If you selected Yes to configure Self Registration:

a. Select a servlet engine to be set up for the web server. If you do not see your engine displayed, select Other Advanced server. Click Next.




7. In the Web Server Configuration Summary dialog box. Confirm that the configuration settings are correct, then click Install.

The Web Agent files are installed and the Configuration Complete dialog box displays.



8. Click Done to exit the Configuration Wizard.

9. If you enabled cryptographic hardware on an Agent, you also need to allow the associated Web-server service to interact with the desktop. This allows the service to prompt for the hardware’s associated passphrase.


a. Open the Services control panel.

On Windows 2000, select Administrative Tools, Computer Management, Services and Applications.

b. Double click the appropriate iWS or Netscape server entry.



d. Click OK.



a. Open the WebAgent.conf file, located in:

<Sun_Java_System_server_home>\servers\https-hostname\config


c. Save the file.

11. Apply changes to Sun Java System Web Server files. This is required for the Agent’s configuration to take effect.

More Information

Apply Changes to Sun Java System Web Server Files (see page 244)

Configuration Methods for Sun Java System Web Agents on UNIX Systems

The following configuration methods are available for Web Agents on UNIX systems:

GUI mode

Console mode

Unattended mode

More Information

Configure Sun Java System Web Agents Using GUI or Console Mode (see page 240) How to Configure Any Web Agent in Unattended Mode (see page 264)



More Information

Apply Changes to Sun Java System Web Server Files (see page 244)

Configure Sun Java System Web Agents Using GUI or Console Mode

These instructions are for GUI and Console Mode configuration. The steps for the two modes are the same, with these exceptions for Console Mode:

You may be instructed to select an option by entering a corresponding number. For example, to select the Sun Java System Web Server, you enter a 3, which corresponds to this server.

Press ENTER after each step to proceed through the process instead of "clicking Next," as stated in the following procedure.

All passwords that you enter are displayed in clear text. To workaround this issue, run the installation in GUI or unattended mode.

The prompts for each mode will help guide you through the process.

To configure the Web Agent on a Sun Java System Web Server

1. If necessary, start the Configuration Wizard.

a. Open a console window.

b. Navigate to <web_agent_home>/install_config_info

c. Enter one of the following commands:

GUI mode: ./nete-wa-config.bin

Console mode: ./nete-wa-config.bin -i console

2. If you have already done host registration, skip to the next step. Otherwise, select the option to skip host registration, then click Next.

To register the trusted host, go to the installation chapter for your platform.

3. In the Select Web Server(s) dialog box, select the option for the iPlanet or Sun ONE Web Server and click Next.

4. Specify the root path where the Sun Java System web server is installed and click Next. For example, /opt/iPlanet/servers.

You can click Choose to locate the root directory.









b. Click Next.

6. In the Agent Configuration Object field, enter the name of the Agent Configuration Object for this web server instance.

This name must match an Agent Configuration Object already defined at the Policy Server. For example, to use the default enter iPlanetDefaultSettings.



7. If applicable, select one of the advanced SSL authentication schemes listed in the SSL Authentication dialog box. If the Agent is not providing advanced authentication, select No advanced authentication. Click Next following your choice.

The selections are:

HTTP Basic over SSL—identifies a user based on a user name and password. The credential delivery is always done over an encrypted Secure Sockets Layer (SSL) connection.

X509 Client Certificate—identifies a user based on X.509 V3 client certificates. Digital certificates act as a signature for a user. Certificate authentication uses SSL communication.

X509 Client Cert and HTTP Basic—combines X.509 Client Certificate and Basic authentication. The user’s X.509 client certificate must be verified and he or she must provide a valid user name and password.

X509 Client Cert or HTTP Basic—combines X.509 Client Certificate and Basic authentication. The user’s X.509 client certificate must be verified, or he or she must provide a valid user name and password.

X509 Client Cert or Form—The X.509 Client Certificate or HTML Forms authentication scheme combines the use of X.509 Client Certificates and the use of customized HTML forms to collect authentication information. Using this scheme, the user’s X.509 client certificate must be verified or the user must provide the credentials requested by an HTML form.

X509 Client Cert and Form—The X.509 Client Certificate and HTML Forms authentication scheme combines the use of X.509 Client Certificates and the use of customized HTML forms to collect authentication information. Using this scheme, the user’s X.509 client certificate must be verified and the user must provide the credentials requested by an HTML form.

Note: For additional information about advanced authentication schemes, refer to CA eTrust Policy Design.

If this Web Agent is installed on an SSL server to handle only credential collection requests for advanced authentication schemes, set the Agent’s EnforcePolicies setting to No to improve performance. To modify the Agent’s configuration, refer to CA eTrust Policy Design or, for local configuration, this guide.











The Web Agent files are installed and the Configuration Complete message is displayed.



a. Open the WebAgent.conf file, located in

<Sun_Java_System_server>/servers/https-hostname/config


c. Save the file.

d. Restart the web server.

12. Apply changes to the Sun Java System Web Server files. This is required for the Agent’s configuration to take effect.

Configure a SOA Agent for Apache Web Servers


Apply Changes to Sun Java System Web Server Files

The Web Agent Configuration Wizard makes changes to the Sun Java System server’s magnus.conf, obj.conf, and mime.types files. If you plan to use the Sun Java System Administration console, you must apply the changes to these files before making any modifications with the console or the Web Agent configuration may be lost. If you lose your configuration, use the Configuration Wizard to reconfigure your Web Agent.

Note: The Web Agent adds settings to the Sun Java System’s obj.conf file when the Agent is configured to support an advanced authentication scheme. SiteMinder does not remove these settings later if the Agent is reconfigured to support a different advanced authentication scheme. Administrators must edit the obj.conf file manually to remove the settings that are no longer relevant.

To apply changes to the Sun Java System configuration files

1. Log on to the Sun Java System Administration Server console.

2. From the Servers tab, select the web server with the Web Agent installed and click Manage.

3. In the right corner of the dialog box, click Apply.

You will see a warning message about loading the modified configuration files.

4. Click Load Configuration Files.

5. Exit the console.

6. Restart the web server.

7. Optimize the Sun Java System Web Agent by tuning the shared memory segments.

You may be required reboot your machine once the Agent is configured.

More Information

Settings Added to the Sun Java System Server Configuration (see page 289)

Configure a SOA Agent for Apache Web Servers Perform the following procedures to configure a SOA Agent for Apache Web Servers.



Configure an Apache Web Agent on Windows Systems


Note: Apache Web Agents are only supported on Windows systems using Apache Web Server version 2.0.

In these procedures, <web_agent_home> refers to the installed location of the SiteMinder Web Agent.

To configure the Apache Web Agent


The default method is to select Start, Programs, SiteMinder, Web Agent Configuration Wizard. If you’ve placed the Wizard shortcut in a non-default location, the procedure will be different.



3. In the Select Web Server(s) dialog box, select the radio button for the Apache Web Server and click Next.

4. In the Apache Web Server Path dialog box, specify the Apache web server root.

If you installed the Agent on an Apache-based server, such as Covalent server, IBM HTTP Server, or Stronghold server, the Web Agent may not recognize the path. In this case, the Configuration Wizard displays the Apache Web Server Failure dialog box with the following options:

I would like to re-enter the Apache Server Root.

Select this option for an Apache web server and re-enter the root path.

I would like to enter a specific configuration path.

Select this option if you are using an Apache-based web server (Covalent, IBM HTTP, HP Apache-based, Oracle, Stronghold). You are prompted to enter the full configuration path to the web server root.

I don’t have an Apache web server.

Choose this option to skip Apache configuration and continue with the Agent configuration.

Click Next.



5. Following the server root path, specify the version of Apache you are using. Select from these two options:

Apache version 1.0

Apache version 2.0







b. Click Next.


This name must match an Agent Configuration Object already defined at the Policy Server. For example, to use the default enter ApacheDefaultSettings.



8. If you want to configure Self Registration for DMS2, select Yes. If not, select No and go to Step .










11. If you enabled cryptographic hardware on an Agent, you need to allow the associated Web-server service to interact with the desktop. This allows the service to prompt for the hardware’s associated passphrase.


a. Open the Services Control Panel.

On Windows 2000, from the control panel select Administrative Tools, Computer Management, Services and Applications.

b. Double click the appropriate Apache server entry.



d. Click OK.





a. Open the WebAgent.conf file, located as follows:

<Apache_home>\conf

where Apache_home is the installed location of the Apache web server.


c. Save and close the file.


When you run the Configuration Wizard for the Apache Web Agent, it makes changes to the Web Server’s httpd.conf file and to the library path.

For httpd.conf changes to take effect, you need to restart the web server.

More Information

Configuration Changes to Web Servers with Apache Web Agent (see page 297)

Configuration Methods for Apache Web Agents on UNIX Systems


GUI mode

Console mode

Unattended mode

Notes:

For Stronghold, IBM HTTP web server, HP Apache-based web server, Covalent FastStart, Covalent Enterprise Ready Server, and Oracle HTTP web server, the Apache Web Agent is the Agent you should have installed. All the information for the Apache web server applies to those web servers also.

Before you configure the Agent, you may want to register the system as a trusted host; however, you can do this at a later time.

For Apache Web Agents installed on Oracle 9.0.3 HTTP Servers, you need to follow other configuration instructions.

More Information

Configure an Apache Web Agent Using GUI or Console Mode (see page 249) How to Configure Any Web Agent in Unattended Mode (see page 264)



Configure an Apache Web Agent Using GUI or Console Mode


You may be instructed to select an option by entering a corresponding number. For example, to select the Apache Web Server, you enter a 1, which corresponds to this server.




To configure the Apache Web Agent









3. In the Select Web server(s) dialog box, select the option for the Apache Web Sever and click Next.



4. In the Apache Web Server Path dialog box, specify the Apache Web Server root, for example, /opt/apache2. Click Next.

If you installed the Agent on an Apache-based server, such as Covalent server, IBM HTTP Server, or Stronghold server, the Web Agent may not recognize the path. In this case, the Configuration Wizard displays the Apache Web Server Failure dialog box with the following options:

I would like to re-enter the Apache Server Root.

Select this option for an Apache web server and re-enter the root path.

I would like to enter a specific configuration path.

Select this option if you are using an Apache-based web server (Covalent, IBM HTTP, HP Apache-based, Oracle, Stronghold). You are prompted to enter the full configuration path to the web server root.

I don’t have an Apache web server.

Choose this option to skip Apache configuration and continue with the Agent configuration.

Click Next.

5. Following the server root path, specify the version of Apache you are using. Select from these two options:

Apache version 1.0

Apache version 2.0







b. Click Next.


This name must match an Agent Configuration Object already defined at the Policy Server. For example, to use the default enter ApacheDefaultSettings.














a. Open the WebAgent.conf file, located as follows:

<Apache_home>/conf

b. Set the EnableWebAgent parameter to yes.

c. Save and close the file.


When you run the Configuration Wizard for the Apache Web Agent, it makes changes to the Web Server’s httpd.conf file and to the library path.

For httpd.conf changes to take effect, you need to restart the web server.

13. For Apache on UNIX systems, optimize the Apache Web Agent by tuning the shared memory segments.

More Information

Configuration Changes to Web Servers with Apache Web Agent (see page 297)



Add Entries to the httpd.conf File to Improve Server Performance

Optionally, you can improve server performance by modifying the default configuration settings; however, these changes are not required:

For low-traffic Web sites, define the following directives:

Set MaxRequestsPerChild>1000 or Set MaxRequestsPerChild=0

MinSpareServers >5

MaxSpareServers>10

StartServers=MinSpareServers>5

For high-traffic Web sites, define the following directives:

Set MaxRequestsPerChild>3000 or Set MaxRequestsPerChild=0

MinSpareServers >10

MaxSpareServers>15

StartServers=MinSpareServers>10

Note: For all Web sites (low and high traffic), Apache20WebAgent.dll must be assigned a higher priority level than other auth or access modules installed on your Apache and Sun Java System configuration.

Set the LD_PRELOAD Variable for Apache Agent Operation

The LD_PRELOAD variable needs to be defined for the Apache Web Agent to operate on different platforms.

More Information

Set the LD_PRELOAD Variable for an Oracle 10G Web Server on Linux (see page 254) Set the LD_PRELOAD Variable for Apache Web Server on SUSE Linux 98 (see page 253) Set the LD_PRELOAD Variable for SSL Configuration on an IBM HTTP Server 2.0.47/Linux AS 3.0 System (see page 254)



Set the LD_PRELOAD Variable for Apache Web Server on SUSE Linux 98

After you install the Web Agent v6.x on an Apache web server running on SUSE 9, you must set the LD_PRELOAD environment variable as follows:

LD_PRELOAD=<web_agent_home>/bin/libbtunicode.so

Without this setting, two problems may occur:

The Apache web server may dump core upon shutdown.

When a SAML Affiliate Agent is running on an Apache Web Server, a load change may spawn multiple processes that eventually consume 100% of the CPU cycles.

Note: Setting this environment variable causes any application executed from that environment to bind with libbtunicode.so. Therefore, only set this variable when starting or stopping a web server that loads the SiteMinder Web Agent.

Set the LD_PRELOAD Variable for an Oracle 10G Web Server on Linux

After you install the Web Agent v6.x on an Oracle 10G web server running on a Linux platform, you must set the LD_PRELOAD environment variable in the apachectl script.

If the LD_PRELOAD variable is not included in the apachectl script, the Oracle 10G web server may dump core upon shutdown and fail to restart.

1. Open the apachectl file.

2. Add the LD_PRELOAD entry as follows:

LD_PRELOAD=<web_agent_home>/bin/libbtunicode.so

export LD_PRELOAD

3. Run the script to start the Apache server.

Note: Setting this environment variable causes any application executed from that environment to bind with libbtunicode.so. Therefore, set this variable only when starting or stopping a web server that loads the SiteMinder Web Agent.



Set the LD_PRELOAD Variable for SSL Configuration on an IBM HTTP Server 2.0.47/Linux AS 3.0 System

When configuring SSL on an IBM HTTP Server 2.0.47.1 running SUSE8, ikeyman, the graphical user interface for the IBM key management utility, crashes when it is used to create a key database.

To resolve this issue, set the following environment variable:

export LD_PRELOAD=/usr/lib/libstdc++-libc6.2-2.so.3

After setting this variable, the key database file, key.kdb, is created successfully.

Set LD_PRELOAD for Using X.509-based Auth Schemes with Domino 6.5.3/SuSe8 Linux System

When accessing resource protected with any X.590-based Authentication Schemes on Domino 6.5.3/SuSe8 Linux, the Domino Server Crashes and generates an NSD.

To resolve this issue, set the following environment variable before starting the Domino Web Server:

export LD_PRELOAD=/usr/lib/libstdc++-libc6.2-2.so.3

Set the LD_ASSUME_KERNEL for Apache Agent on SuSE Linux 9 for zSeries

After you install the Web Agent on an Apache web server running on SuSE Linux 9 for zSeries, set the LD_ASSUME_KERNEL environment variable as follows:

LD_ASSUME_KERNEL=2.4.21

export LD_ASSUME_KERNEL

Important! You must set this variable to 2.4.21 because it represents the kernel release upon which the Web Agent libraries are built.

Without this setting, the following problems occur:

The Apache web server will not start properly.

Host registration dumps core.



Enabling SHLIB Path for an Agent on Apache 2.0/HP-UX 11

For the Web Agent to operate on an Apache 2.0 web server running HP-UX 11, be sure the SHLIB_PATH is enabled in the Apache executable.

1. Check if the SHLIB PATH is already enabled by executing the command chatr httpd. A partial sample of the output is shown below. Notice that SHLIB_PATH is disabled. httpd:

shared executable

shared library dynamic path search:

SHLIB_PATH disabled second embedded path

enabled first /home/userx/apache2043hp/lib:

home/userx/apache2043hp//lib

2. If it is not enable, enter chatr +s enable httpd.

A partial sample of the output is shown below. First the current values are shown followed by the new values. httpd:

current values:

shared executable


SHLIB_PATH disabled second

embedded path enabled first /home/userx/apache2043hp/lib:/


.

.

.


SHLIB_PATH enabled second

embedded path enabled first /home/userx/apache2043hp/lib:


shared library list:

Modify the http.conf File for Apache Reverse Proxy Server

A reverse proxy server acts on behalf of incoming requests to a company’s internal network as opposed to outgoing requests from a private network to the Internet. When a request for a resource is received by a reverse proxy server, the request is directed to a server behind the firewall, as opposed to redirecting the request to a remote server over the Internet.

To successfully implement a reverse proxy solution, modify the http.conf file by adding ProxyPass and ProxyPassReverse directives.

Configure a SOA Agent for Domino Web Servers


The ProxyPass directive allows remote servers to be mapped to the space of the local server. The local server essentially mirrors the specified remote server.

The ProxyPass directive takes the following form:

ProxyPass <path> <URL>

The <path> is the name of the local virtual path, and the <URL> is a partial URL for the remote server. For example:

ProxyPass /realma/ http://server.myorg.org/realma/

The ProxyPassReverse directive allows Apache to adjust the Location header on the HTTP redirect responses. This directive takes the following form:

ProxyPassReverse <path> <URL>

The <path> is the name of the local virtual path, and the <URL> is a partial URL for the remote server. For example:

ProxyPassReverse /realma/ http://server.myorg.org/realma/

Note: For information about implementing a reverse proxy solution on Apache, refer to the CA eTrust SiteMinder Web Agent Guide.

Configure a SOA Agent for Domino Web Servers Perform the following procedures to configure a SOA Agent for Domino web servers.



Configure a Domino Web Agent on Windows Systems


Note: In these instructions, <web_agent_home> refers to the installed location of the Web Agent.

To configure a Domino Web Agent


The default method is to select Start, Programs, SiteMinder, Web Agent Configuration Wizard. If you’ve placed the Wizard shortcut in a non-default location, the procedure will be different.



3. In the Select the Web server(s) dialog box, select the radio button for the Domino Web Sever and click Next.

4. In the Domino Web Server Path dialog box, specify the location of the notes.ini file, such as C:\Lotus\Domino\notesdata, then click Next.

Note: The installation automatically writes the path to the WebAgent.conf in the notes.ini file.

5. Select the Web server instances that you want to configure with Web Agents.

If you have already configured a server with a Web Agent and you are running the Configuration Wizard to configure additional Web servers instances, the Wizard displays the Select One or More Instances to Overwrite dialog box. This dialog box lists the Web servers that you have previously configured.



Preserve—to preserve the Web servers configuration.


b. Click Next.



6. In the Agent Configuration Object field, enter the name of the Agent Configuration Object for this Web server instance, then click Next.

This name must match an Agent Configuration Object already defined at the Policy Server. For example, to use the default enter DominoDefaultSettings.

7. In the Web Server Configuration Summary dialog box, confirm that the configuration settings are correct, then click Install.




a. Open the WebAgent.conf file, located in where you installed the Domino Web server root directory.

b. Set the EnableWebAgent parameter to YES.

c. Save the file.

Add the Domino Web Agent DLL (Windows)

To make the Domino Web Agent operate properly, you must add the DOMINOWebAgent.dll file to the filter DLLs. The Web Agent DLL must be the first DLL in the list.

To add the Domino Web Agent DLL

1. Open Lotus Notes.

2. Select File, Database, Open.

3. In the Server field, select the Domino Server where you installed the Web Agent.

4. In the Database scroll box, select the server’s address book.

In the Filename field you should see names.nsf displayed.

5. Click Open.

The server’s address book opens.

6. In the left pane, expand the Server folder and double-click on the All Server Documents icon.

7. Select your server and click Edit Server.

The Domino server’s administration console opens.

8. Select the Internet Protocols tab.



9. In the DSAPI section of the window, find the DSAPI filter file names field and enter the full path to the Domino Web Agent DLL, for example:

C:\Program Files\netegrity\webagent\bin\ DOMINOWebAgent.dll

Note: This entry should be the first in the list of filters.

10. Click Save and Close.


You may be required to reboot your machine after the Agent is configured.

Configuration Methods for Domino Web Agents on UNIX Systems


GUI mode

Console mode

Unattended mode

More Information

Configure Domino Web Agents in GUI or Console Mode (see page 260) How to Configure Any Web Agent in Unattended Mode (see page 264)

Configure Domino Web Agents in GUI or Console Mode


You may be instructed to select an option by entering a corresponding number. For example, to select the Apache Web Server, you enter a 1, which corresponds to this server.












Note: If you chose to configure the Web Agent immediately after the installation, SiteMinder automatically starts the Configuration Wizard.



3. In the Select the Web server(s) dialog box, select the radio button for the Domino Web Sever and click Next.

4. In the Domino Web Server Path dialog box, specify the location of the notes.ini file, such as /local/notesdata, then click Next.

Note: The installation automatically writes the path to the WebAgent.conf in the notes.ini file.







b. Click Next.


This name must match an Agent Configuration Object already defined at the Policy Server. For example, to use the default enter DominoDefaultSettings.







a. Open the WebAgent.conf file, located in the Domino web server root directory.


c. Save the file.

Configure ServletExec 5.0 for JSP Password Services for an IIS Web Server

To properly configure ServletExec 5.0 for JSP-based Password Services

1. Start the ServletExec Administration page by entering the following in a browser:

http://localhost/servletexec/admin

2. Select Virtual Machine, Classpath and enter the following:

<Web_Agent_installation>\jpw\jpw.jar

<Web_Agent_installation>\java\jsafe.jar

3. Select Web Applications, Manage.

4. Under Manage Web Applications, select the top web.xml link.

5. On the servletexec: Set Display Options screen, select Servlets, Manage.

6. Under servletexec: Manage Servlets, click Add Servlet.

7. Under servletexec: Add Servlet, add the following and click submit:

Servlet Name: PSWDChangeServlet

Servlet Class: PSWDChangeServlet

ServletExec should verify that the PSWDChangeServlet has been added successfully.

8. Select Servlets, Mapping, and add the following:

URL pattern: /siteminderagent/pwservlet/PSWDChangeServlet

Servlet Name: PSWDChangeServlet

9. Go back to the main ServletExec Administration page.

10. Select Web Applications, Manage.



11. Under Manage Web Applications, select the next web.xml link.

12. Repeat steps 5 to 8, and then ServletExec is properly configured.

Add the Domino Web Agent DLL (UNIX)

For the Domino Web Agent to operate properly, you must add the dominowebagent.so library to the filter DLLs. This library must be first in the list.

To add the Domino Web Agent DLL

1. Open Lotus Notes.

2. Select File, Database, Open.

3. In the Server field, select the Domino Server where you installed the Web Agent.

4. In the Database scroll box, select the server’s address book.

In the Filename field you should see names.nsf displayed.

5. Click Open.

The server’s address book opens.

6. In the left pane, expand the Server folder and double-click on the All Server Documents icon.

7. Select your server and click Edit Server.

The Domino server’s administration console opens.

8. Select the Internet Protocols tab.

9. In the DSAPI section of the window, find the DSAPI filter file names field and enter the full path to the Domino Web Agent file, for example:

<web_agent_home>/bin/dominowebagent.so

Note: This entry should be the first in the list of filters.

10. Click Save and Close.


How to Configure Any Web Agent in Unattended Mode


How to Configure Any Web Agent in Unattended Mode After you have installed the Web Agent on one system, you can automate the Web Agent configuration on other web servers using the Agent’s unattended configuration feature. An unattended configuration lets you configure the Web Agent without any user interaction.

To configure any Web Agent in unattended mode, use the following process:

1. Prepare an unattended configuration.

2. Run an unattended configuration.

Prepare an Unattended Configuration

Unattended configuration uses the nete-wa-installer.properties file to propagate the Web Agent configuration set up across all Agents in your network. For configuration, you define configuration parameters in the properties file, then copy the file to any web server in your network to run an unattended configuration.

When you perform an initial Web Agent installation and configuration, the nete-wa-installer.properties file is installed in the following location:

<web_agent_home>/install_config_info

The default parameters and paths in the file reflect the information you entered during the initial Web Agent installation and configuration.

To make the nete-wa-installer.properties file available on your system

1. Run an initial installation of the Web Agent.

2. Open the nete-wa-installer.properties file and, if necessary, modify the configuration parameters.

3. Save the file.

How to Configure Any Web Agent in Unattended Mode


Run an Unattended Configuration

You should have completed:

an initial (attended) Web Agent installation

an initial (attended) Web Agent configuration

modification of the nete-wa-installer.properties file

You use this file to run subsequent unattended Web Agent configurations

an installation (attended or unattended) on the system where you want to run the unattended configuration. This installation makes the configuration executable available.

To run an unattended Web Agent configuration:

1. From a system where the Web Agent is already installed, copy the nete-wa-installer.properties file from <web_agent_home>/install_config_info to a local directory on the system where you want to run an unattended configuration.

2. Open a console window and navigate to <web_agent_home>/install_config_info.

Note: You must run the unattended configuration from the install_config_info directory because the configuration executable file must remain in this directory.

3. Run the following command:

<agent_config_executable> -f <properties_file> -i silent

For example, if you copied the properties file to the install_config_info directory, the command would be:

Windows:

nete-wa-config.exe -f nete-wa-installer.properties -i silent

UNIX:

nete-wa-config.bin -f nete-wa-installer.properties -i silent

If you do not copy the properties file to the install_config_info directory, specify the full path to this file in the command. If there are spaces in the directory path, enclose the entire path between quotation marks.

When the configuration is complete, you return to the command prompt.

4. Check to see if the configuration completed successfully by looking in the CA_SiteMinder_Web_Agent_v6QMR5_InstallLog.log file, located in the <web_agent_home>/install_config_info directory. This log file contains the results of the configuration.

Reconfigure a Web Agent


Check SmHost.conf File Permissions for Shared Secret Rollover

If you enable shared secret rollover, the user who owns the web server process must have permissions to write to the SmHost.conf file. If this file cannot be modified by this user, then the shared secret rollover cannot be updated.

For example, for Sun Java System and Apache web servers, the person specified by the User directive needs write permission to the SmHost.conf file. If the SmHost.conf file is owned by User1 and no other user has write permissions, the shared secret rollover cannot be updated if User2 owns the server process.

Reconfigure a Web Agent Reconfigure a Web Agent for the following reasons:

You have upgraded the Web Agent and now you need to update the configuration

You need to change the configuration settings previously defined for a Web Agent

You need to remove the configuration settings from the Web Agent without uninstalling the entire Web Agent (you would need to configure the Web Agent again at a later time)

You want to configure the Web Agent for a different Web Server installed on the same system as the configured server.

To reconfigure a Web Agent in any mode, re-run the Configuration Wizard. There are no additional steps or prompts for reconfiguring an Agent.

How to Tune the Solaris 10 Resource Controls


How to Tune the Solaris 10 Resource Controls You may want to tune the resource controls at the project level if you need to improve the performance of the Web Agent.

Note: See your Solaris documentation for more information.

Tuning the resource controls on Solaris 10 uses the following process:

1. Determine the project associated with the user account under which the Web Agent runs.

2. Increase the settings for any of the following resource controls of that project:

project.max-shm-ids

Specifies the maximum shared memory IDs for a project.

project.max-sem-ids

Specifies the maximum number of semaphore IDs for a project.

project.max-msg-ids

Specifies the maximum number of message queue IDs for a project.

project.max-shm-memory

Specifies the total amount of shared memory allowed for a project.

process.max-sem-nsems

Specifies the maximum number of semaphores allowed per semaphore set.

process.max-sem-ops

Specifies the maximum number of semaphore operations allowed per semop.

process.max-msg-messages

Specifies the maximum number of messages on a message queue.

process.max-msg-qbytes

Specifies the maximum number of bytes of messages on a message queue.

How to Set Up Additional Agent Components


How to Set Up Additional Agent Components The Web Agent Configuration Wizard guides you through basic Agent configuration. However, there are other Agent components that you can configure without the wizard.

All SiteMinder Web Agents can protect resources, act as forms credential collectors (FCC) and/or an SSL credential collectors (SCC), and serve as a cookie provider for single sign-on. The Web Agent can serve in one or more of these roles simultaneously.

At installation, some of these functions, such as acting as the forms credential collector, are set up automatically; however, other capabilities, such as the cookie provider require additional configuration.

You can set up any of the additional components as follows:

Configuring an Agent as a forms credential collector

The libraries and files for forms credential collection are set up automatically during installation.

Note: To configure forms authentication, which uses the FCC, refer to the chapter on authentication schemes in CA eTrust Policy Design.

Configuring an Agent as an SSL credential collector

You specify whether the Agent performs SSL credential collection during the initial Agent configuration with the Configuration Wizard.

Note: To read about advanced authentication schemes, see the CA eTrust Policy Design.

Configuring the Agent as a cookie provider for multiple cookie domain single sign-on

A cookie provider lets the Agent implement single sign-on in a multiple cookie domain environment. All Web Agents have the ability to be the cookie provider, but you must configure only one Web Agent in this role. The cookie provider URL setting in the Agent’s configuration dictates which Web Agent is the cookie provider. After you determine which Agent is the cookie provider, you configure all other Agents in the single sign-on environment to point to the cookie provider by entering that Agent’s URL.

Note: For information about single sign-on, refer to the CA eTrust SiteMinder Agent Guide.

Troubleshooting a SOA Agent for Web Servers



Agent Start-Up/Shutdown Issues (Framework Agents Only)

If the Web Agent does not start after installation or you cannot shut it down, check the following error logs:

On Windows, check the Event Viewer’s Application Log.

On UNIX, messages are processed by the server’s standard error handling. For the Apache 2.0, errors are written to the web server error log.

On Windows or UNIX, run the Low Level Agent Worker Process (LLAWP) to isolate the problem.

Troubleshoot Agent Start-Up/ShutDown with LLAWP

If the Agent is not starting or shutting down properly, you can run the Low Level Agent Worker Process (LLAWP) from the command line.

The LLAWP handles inter-process Agent management. For IIS 6.0, LLAWP starts up after the Web Agent receives the first request. For Apache 2.0, the LLAWP process automatically starts when the Apache web server starts.

By running LLAWP from the command line, you eliminate the web server from the diagnostic process, which isolates Web Agent issues. Error messages are written to the Event log for Windows or to the console on UNIX systems.

Shut Down LLAWP

If the LLAWP process does not shut down properly when shutting down the web server, shut down the LLAWP from the command line. This shuts down the running worker process associated with a WebAgent.conf file.

To shut down the LLAWP, use the command with this syntax:

LLAWP <path_to_WebAgent.conf> -<web_server_type> -shutdown

For example:

LLAWP /usr/apache/conf/WebAgent.conf -APACHE20 -shutdown

Note: Configuration file names and version strings that contain spaces should be surrounded by quotes, such as "value with spaces."

The LLAWP process will take a few seconds to shut down.

Use the command line to shut the LLAWP down instead of the kill -9 command, so that the process cleans up shared system resources used by the Web Agent.



Web Agent Start Up and Shut Down Issues (IBM HTTP Server)

If the Web Agent does not start after installation or you cannot shut it down, check the following error logs:

On Windows, check the Event Viewer’s Application Log.

On UNIX, messages are processed by the server’s standard error handling.

Stop LLAWP When Stopping IBM HTTP Server 2.0.47

The IBM HTTP Server 2.0.47 on Windows 2000 and 2003 crashes if the ibm_afpa_module and the Web Agent are enabled. If the ibm_afpa_module is loaded and a module registering an init function does not exit that function quickly, the apache.exe child process crashes with an access violation in LIBAPR.dll.

To solve this issue for versions of IBM HTTP Server v2.0.x, if there is an <IfModule mod_afpa_cache.c> line in the httpd.conf file associated with LoadModule ibm_afpa_module, comment out the following lines:

#LoadModule ibm_afpa_module modules/mod_afpa_cache.so

#<IfModule mod_afpa_cache.c>

# AfpaEnable

# AfpaCache on

# AfpaPort 8082

# AfpaLogFile "C:/Program Files/IBM HTTP Server 2.0/logs/afpalog"

V-ECLF #</IfModule>

#<IfModule !mod_afpa_cache.c>

# Listen @@Port@@

#</IfModule>

By disabling the AFPA module, the IBM HTTP Server 2.0.47 starts properly.

Note: More information about the IBM HTTP Server limitation may be found by reading the document titled "Hang or crash of Microsoft Windows when Running AFPA and When Antivirus Software is Active" on the IBM Support site.

Connectivity and Trusted Host Registration Issues

This section contains troubleshooting information related to trusted host registration.



Trusted Host Registration Fails

Symptom:

I cannot register a trusted host.

Solution:

Check the following:

Make sure that the Policy Server is installed and configured on the target server, that the IP address for the server is correct, and that the Policy Server is running.

Check the SiteMinder administrator name and password and make sure these are correct.

Make sure that the Host Configuration Object and Agent Configuration Object specified during the Agent installation and configuration are defined at the Policy Server.

You may be using a name for the trusted host that is already in use by an existing trusted host. Re-register using a unique name for the trusted host.

No Connection From Trusted Host to Policy Server

Symptom:

Trusted host cannot make a connection to the Policy Server.

Solution:

Do the following:

Check for the SmHost.conf file in <web_agent_home>/config. The presence of this file indicates a successful registration of the trusted host.

Ensure that the host where the Agent is installed has been registered as a trusted host.

Check that EnableWebAgent is set to yes in the WebAgent.conf file.

Make sure the Agent Configuration Object has a DefaultAgentName specified. Also, depending on the Web Server, ensure that the minimum required parameters are configured.

Make sure the Policy Server is running.



Host Registered, but the SMHost.conf file has been Deleted

Symptom:

A Trusted Host is registered but the SmHost.conf file has been deleted.

Solution:

In the Administrative UI, remove the Trusted Host Object corresponding to the host name for which the file was deleted. Re-register the host using the smreghost tool.

General Installation Issues

This section contains troubleshooting information related to installations.

One Installation Hangs During Multiple Installations on the Same System

Symptom:

You are running multiple installations on the same system at the same time and an installation hangs.

Solution:

Try the following tasks in the order listed:

1. Reboot the system and try the installation again.

2. Rename the ZeroG registry file, then retry the installation. The registry file is in the following locations:

Windows: C:\Program Files\ZeroG Registry\com.zerog.registry.xml

UNIX: $HOME/.com.zerog.registry.xml or /var/.com.zerog.registry.xml

The registry file is locked while an installation is taking place, so if multiple installations are running at the same time, they cannot write to this file, causing the installation to hang.



Installation Failure Log

Symptom:

I want to see what failed during the installation.

Solution:

See the nete-wa-details.log file, located in <web_agent_home>/install_config_info.

Attempt to Access DMS Page Returns Error

Valid on Windows

Symptom:

On Windows systems, you receive a servlet DMS not found error when you access a DMS page.

Solution:

Check the ServletExec CLASSPATH and modify it if necessary.

Configuration of Encryption Key for the Cryptographic Hardware Failed

Symptom:

I could not configure my enryption key. I saw the following error message:

Setting encryption key configuration failed (error code 1). Please re-enter parameters carefully.

Solution:

Ensure that the UNIX user for the Agent belongs to the nCipher UNIX group.

More Information

Add a SiteMinder Agent User to nCipher UNIX Group (UNIX Only) (see page 51)



Web Agent Not Shown in Add/Remove Programs Control Panel

Symptom:

I cannot uninstall the Web Agent from the Add/Remove Programs list control panel because the SiteMinder Web Agent is not listed.

Solution:

Remove the Agent as follows:

1. Open the registry editor.

2. Go to HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall\SiteMinder\WebAgent

3. Highlight the entire UninstallString entry and copy it.

4. Open a DOS window and paste the UninstallString into the window at a DOS prompt.

5. Press ENTER.

The Agent is uninstalled.



Netscape Browser Won't Open PDFs

Valid on UNIX

Symptom:

I cannot open PDF Files from the Online Manuals Index HTML page on a UNIX system using a Netscape browser.

Solution:

If a .pdf file does not open after you click a link on the doc_index.htm page, set Acrobat Reader as a helper application in Netscape Navigator. When you set this option, Netscape automatically launches Acrobat Reader each time you request to view a .pdf file.

To set Acrobat Reader as a helper application

1. In Navigator, go to Edit, Preferences.

2. In the Netscape Preferences dialog, select Navigator, Applications.

3. Under Applications, Specify helper applications for different file types, select Portable Document Format and click Edit.

4. In the Netscape Applications dialog, select Applications and set it to the following:

<Acrobat_Reader_home>/bin/acroread %s

For example, if you installed Acrobat Reader in the default location, set this value to:

/usr/local/Acrobat4/bin/acroread %s.

5. Click OK to close these dialogs.

After you set this option, Navigator launches Acrobat Reader and opens the .pdf file in the /tmp directory.

Adobe Acrobat Reader Won't Install on a Windows System

Valid on Windows

Symptom:

I cannot install Adobe Acrobat Reader on a Windows system.

Solution:

If the Acrobat Reader installation program hangs while the Policy Server is running, stop the server using the Policy Server Management Console, then the installation program should start.



Error Message During Upgrade

Valid on Windows, UNIX

Symptom:

You receive the following error during an upgrade:

ComponentMoveData Error -115

Solution:

Do the following:

1. Click OK to exit the error message.


3. From the console, stop the Policy Server.

4. Close the Management Console.

5. Run the upgrade or again and this error message should no longer appear.

Web Server Starts but Web Agent Not Enabled

Symptom:

The Web Agent is not enabled even though the web server has started.

Solution:

Open the WebAgent.conf file, and then set the EnableWebAgent parameter to yes.

smget Error Message When Web Server Starts

Valid on Sun Java System web servers

Symptom:

When starting the Web Server, you see the message:

shmget failed. You may be trying to make a cache that is too large.

Solution:

Make the recommended adjustments to the shared memory segments.

More information:

How to Tune the Solaris 10 Resource Controls (see page 267)



Reconfigured Web Agent Won't Operate

Valid on Sun Java System web servers

Symptom:

Web Agent configuration changes are not in the obj.conf file. The Web Agent cannot operate.

Solution:

The Sun Java System Administration console was used to make server modifications before the changes made by the Agent configuration to the obj.conf were applied. Re-configure the Web Agent.

Sun Java System Web Server Fails at Runtime

Symptom:

Sun Java System web server is failing at run time.

Solution:

Increase the StackSize setting in the Sun Java System server’s magnus.conf file to a value of 256 KB. The magnus.conf file is located in:

<Sun_Java_System_home>/<web_server_instance>/config

Apache Web Agent Issues

This section lists troubleshooting information for the Apache Web Agent.



Domino Web Agent Not Enabled but the Web Server has Started

Valid on Domino

Symptom:

The Domino Web Agent is not enabled even though the web server has started.

Solution:

Do the following:

In the WebAgent.conf file, set the EnableWebAgent parameter to yes.

Ensure that the DOMINOWebAgent.dll file has been added to the filter DLLs. The Web Agent DLL must be the first DLL in the list.

More Information

Add the Domino Web Agent DLL (Windows) (see page 259)

Domino Agent Cannot Initialize When Local Configuration Mode is Used

Valid on Domino

Symptom:

Domino Agent cannot initialize in local configuration mode.

Solution:

Check that the full path to the WebAgent.conf file is added to the notes.ini file.

Configuring the Policy Server for an International Environment 279

Appendix A: Configuring the Policy Server for an International Environment


Policy Servers in an International Environment (see page 279) Important Planning Considerations Before Installing the Policy Server (see page 279) Configure SiteMinder Data Stores Supporting International Characters (see page 282)

Policy Servers in an International Environment The Policy Server supports SiteMinder data stores residing in an Oracle or SQL Server database, and LDAP servers for an international environment.

Important Planning Considerations Before Installing the Policy Server

Consider the following before installing the Policy Server:

Use supported operating system and third-party software

For a list of supported operating systems, Web Servers, databases, Web browsers, LDAP Directory Servers, and servlet engines, go to the Technical Support site and search for the SiteMinder Platform Matrix for 6.0. This matrix lists the Policy Server components supported on a Japanese operating system.

Create supported databases

Before creating databases for storing policy, user, or session data, make sure they are formatted with UTF-8 encoding.

Understand which Policy Server User Interface fields that support multi-byte characters in an internationalized environment

Understand which Policy Server components support multi-byte and ASCII characters in an internationalized environment





Policy Server User Interface Fields Supporting Multi-byte Characters

The following dialog box fields from the Policy Server User Interface support multi-byte characters in an internationalized environment:

Field Name Dialog Where Field is Located

Access Dialog By Selecting:

All Description fields All dialogs Any dialog that has a Description field

All Name fields except dialogs listed in next column

All dialogs except Name fields in:

SiteMinder Agent Dialog

SiteMinder Agent Group Dialog

SiteMinder Agent Configuration Object Dialog

SiteMinder Host Configuration Object Dialog

SiteMinder Agent Type Dialog

Access Dialog by selecting:

Edit, Create Agent

Edit, System Configuration, Create Agent Group

Edit, System Configuration, Create Agent Conf Object

Edit, System Configuration, Create Host Conf Object

Edit, System Configuration, Create Type

DN field under the User Session Caches group

SiteMinder Cache Management Dialog

Tools, Manage Cache

Value and Enter Single Value fields

SiteMinder Host Configuration Object’s Edit Parameter Dialog

Edit, System Configuration, Create Host Conf Object, click Add

Root, Start, and End fields for the LDAP and AD namespaces

SiteMinder User Directory Dialog

Edit, System Configuration, Create User Directory

Username field SiteMinder User Directory Dialog’s Credentials and Collection tab

Edit, System Configuration, Create User Directory

Filter (binoculars) fields SiteMinder Policy Domain Dialog Edit, System Configuration, Create Domain

Manual Entry field in the Condition group

Value field in the Infix Notation group

SiteMinder Password Policy Dialog’s SiteMinder User Lookup screen

Edit, System Configuration, Create Password Policy

Function Parameter field of the SiteMinder Active Rule editor dialog

SiteMinder Rule and SiteMinder Global Rule dialogs

Click a realm and select Create Rule Under Realm



Variable Value field in the Static option.

DN Spec field in the DN Attribute option.

Parameters field in Active Response option.

SiteMinder Response and Global Response dialogs

Click a response and select Create Response

On the Users tab, the Manual Entry field in Condition group and the Value field in Infix Notation group.

On the Rules tab, the Filter fields (binoculars) of the Set Response and Set Global Response dialogs.

On the Advanced tab, the Function Parameter field in Active Policy group.

SiteMinder Policies and Global Policies dialogs

Click Policies and select Policy

Value field in Attribute-Value option.

Search Expression field in the LDAP Query option.

SiteMinder User Lookup screen In multiple dialogs

Policy Server Components Supporting Multi-byte Characters

The following Policy Server components support multi-byte and ASCII characters in an internationalized environment:

Policy Server User Interface

Policy Server Management Console

HTML Forms authentication schemes

Password Services

Note: Passwords are limited to ASCII characters only.

Registration Services

Responses

Post Preservation

SiteMinder Test Tool

Configure SiteMinder Data Stores Supporting International Characters


Audit logging to text files

Note: Audit logging multi-byte character information to a database is not supported even if you created the database for UTF-8 character encoding.

smobjexport and smobjimport

DMS Self Registration

Java Agent API


You can configure SiteMinder data stores in SQL Server or Oracle databases. When configuring these data stores, be aware that the Policy Server only supports UTF-8 encoding and, as a result, you must use databases that support this encoding type.

Note: This section applies to configuring SiteMinder data stores in relational databases. More information on configuring these stores in LDAP servers exists in LDAP Directory Servers as a Policy Store or Key Store.

Configure an International SiteMinder Data Store in SQL Server

To create policy, keys, session, token, or key stores, configure a SiteMinder data store in the SQL Server database.

Note: By default, SQL Server supports UTF-8 character encoding.

More Information:

How to Configure a SiteMinder Data Store in a SQL Server Database (see page 105)

Configure an International SiteMinder Data Store in Oracle

To configure an international SiteMinder data store in Oracle

1. On the machine where Oracle is installed, create a custom Oracle database that supports UTF-8 character encoding.

Note: For more information and instructions, see Oracle’s documentation.

To verify if an existing Oracle database supports UTF-8 character encoding, run the following query:



Select * from nls_database_parameters where parameter = ‘NLS_CHARACTERSET’

2. Create policy, keys, session, token, or key stores for the Policy Server, by configuring a SiteMinder data store in the Oracle database.

More Information:

How to Configure a SiteMinder Data Store in an Oracle Database (see page 112)

Solaris/LINUX Red Hat Policy Server Logging UTF-8 Characters to an Oracle Database

A Solaris/LINUX Red Hat Policy Server can log UTF-8 characters to an Oracle audit log database. To enable this configuration, you need to set the following environment variables:

For a simplified Chinese operating system

LANG=zh_CN.utf8

For a Japanese operating system

LANG=jp_JP.UTF-8

You set the LANG variable system-wide or just for the Policy server process.

Note: To avoid impacting any other applications, make sure that you set this variable for the Policy Server process only.

Database Driver Variable

IANAAppCodePage=utf-8

You set this variable in the appropriate data source definition section of the system_odbc.ini file, installed in <policy_server_installation>/db.

Oracle Client Settings

Since the Policy Server uses the Oracle wire protocol driver, an Oracle client is not necessary. However, if you need an Oracle SQLPLUS client in your environment to read data from the audit log database, you may have to set one or both of the following environment variables to correctly display the multi-bytes characters:

For a simplified Chinese operating system

LANG=zh_CN.utf8

For a Japanese operating system

LANG=jp_JP.UTF-8

For the Oracle SQLPlus Client

NLS_LANG (For example, NLS_LANG=Japanese_Japan.UTF8)



Note: For more information, see the operating system and database client configuration manual.

Configure a Japanese User Store in SQL Server

Using the smsampleusers_sqlserver.sql file installed with the Policy Server, you can configure a user store in a SQL Server database. This file is installed in the policy_server_installation\db\SQL directory.

To configure a Japanese user store in SQL Server

1. Edit the smsampleusers_sqlserver.sql file, by doing the following:

a. Replace every varchar instance with nvarchar.

b. Place an N before any insert statement with international strings.

Japanese example:

insert into SmUser ( UserID , Name, Password, LastName, FirstName, ...)

values (12, N' ', 'siteminder','guest','guest','[email protected]...)

2. Import the smsampleusers_sqlserver.sql file.

Note: More information on importing the smsampleusers_sqlserver.sql file exists in How to Configure a SiteMinder Data Store in a SQL Server Database (see page 105).

3. Open the Policy Server User Interface’s SiteMinder ODBC Query Scheme dialog and modify the policy store’s SQL query scheme by placing an N before every %s reference in any = %s statement.

Example: the following sample query scheme statements:

select Name, 'User' from SmUser where Name = '%s' Union select Name, 'Group' from SmGroup where Name = '%s'

should become:

select Name, 'User' from SmUser where Name = N'%s' Union select Name, 'Group' from SmGroup where Name = N'%s'

4. Stop and restart the Policy Server.

The user store configuration is complete and now supports multi-byte characters.



Configure a Japanese User Store in Oracle

Using the smsampleusers_oracle.sql file installed with the Policy Server, you can configure a user store in an Oracle database. This file is installed in the policy_server_installation\db\SQL directory.

To configure a Japanese user store in Oracle

1. Create a database for the user data that supports Oracle’s UTF-8 NLS_CHARACTERSET encoding.

2. Using Oracle’s SQL-Plus, import the smsampleusers_oracle.sql file.

Note: More information on importing the smssampleusers_oracle.sql file exists in How to Configure a SiteMinder Data Store in an Oracle Database (see page 112). Be aware that if you are inserting Japanese characters, import the file from a Japanese operating system.

The user store configuration is complete.

Modified Environment Variables 287

Appendix B: Modified Environment Variables


Modified Windows Environment Variables (see page 287) Modified UNIX Environment Variables (see page 288)

Modified Windows Environment Variables The Policy Server installation adds and modifies the following environment variables in a Windows environment:

NETE_PS_ROOT = $INSTALL_PATH$

NETE_PS_PATH = $INSTALL_PATH$$/$bin; $INSTALL_PATH$$/$bin$/$thirdparty;$INSTALL_PATH$$/$lib

NETEGRITY_LICENSE_FILE = %NETE_PS_ROOT%$/$license$/$license.dat

NETE_JVM_OPTION_FILE = %NETE_PS_ROOT%$/$config$/$JVMOptions.txt

NETE_DOC_ROOT=$INSTALL_PATH$$/$netegrity_documents

NETE_JRE_ROOT = HKEY_LOCAL_MACHINE\SOFTWARE\JavaSoft\Java Runtime Environment\1.5 in JAVAHOME value

NETE_JDK_ROOT = HKEY_LOCAL_MACHINE\SOFTWARE\JavaSoft\Java Development Kit\1.5 in JAVAHOME value

NETE_SHORTCUTS = C:\Documents and Settings\All Users\Start Menu\Programs\SiteMinder

Note: This is the default location.

Modified UNIX Environment Variables


Modified UNIX Environment Variables The Policy Server installation adds and modifies the following environment variables in a UNIX environment:

NETE_PS_ROOT = $INSTALL_PATH$

NETE_PS_PATH = $INSTALL_PATH$$/$bin; $INSTALL_PATH$$/$bin$/$thirdparty;$INSTALL_PATH$$/$lib

NETEGRITY_LICENSE_FILE = %NETE_PS_ROOT%$/$license$/$license.dat

NETE_JVM_OPTION_FILE = %NETE_PS_ROOT%$/$config$/$JVMOptions.txt

NETE_DOC_ROOT=$INSTALL_PATH$$/$netegrity_documents

NETE_JDK_ROOT = $JDK_PATH$

NETE_JRE_ROOT = $JRE_PATH$

Settings Added to the Sun Java System Server Configuration 289

Appendix C: Settings Added to the Sun Java System Server Configuration


Additions for Sun Java System Server 6.0 (see page 289) magnus.conf File Additions for Windows Platforms (see page 290) Code Added to the magnus.conf File on UNIX Platforms (see page 290) obj.conf File Additions for Windows Platforms (see page 291) obj.conf File Additions for UNIX Platforms (see page 293) mime.types File Additions for Windows and UNIX Platforms (see page 295) Check Agent Start-up with LLAWP (see page 295)

Additions for Sun Java System Server 6.0 When you install the Web Agent on an Sun Java System web server 6.0, configuration settings are automatically added to the following files:

magnus.conf

obj.conf file

mime.types

These files load automatically when the web server starts. The additional settings initialize the Web Agent. When the Web Agent installation program adds information to the web server’s configuration, it divides this information differently for different versions of the Sun Java System web server.

For Windows platforms, these files are in the <Sun_Java_System_install_location>\servers\https-hostname\config\ directory.

For UNIX platforms, these files are in the /usr/<Sun_Java_System_install_location>/servers/https-hostname/config/ directory.

Note: The Sun_Java_System_install_location is the directory where you installed the Sun Java System server on your computer, and hostname is the name of the server.

magnus.conf File Additions for Windows Platforms


magnus.conf File Additions for Windows Platforms The following lines are added to the magnus.conf file on Windows platforms:

Init fn="load-modules" shlib="C:/Program

Files/Netegrity/webagent/bin/SunOneWebAgent.dll"

funcs="SmInitAgent,SiteMinderAgent,SmRequireAuth,SmAdvancedAuth,SmLoginFcc,SmGetC

red,SmMakeCookie,SmSSLLoginFcc"

Init fn=SmInitAgent config="C:/iPlanet/Servers/https-

server1/config/WebAgent.conf" errortext="Error initializing Web Agent..."

Init fn="SmInitChild" LateInit="yes"

Note: Some entries in your file may differ slightly from the example shown.

The additional lines instruct the web server to load the SiteMinder Web Agent with the following NSAPI functions:

SmInitAgent

SiteMinderAgent

SmRequireAuth

SmAdvancedAuth

Code Added to the magnus.conf File on UNIX Platforms The following lines are added to the magnus.conf file for UNIX platforms: Init fn="load-modules"

shlib="/usr/netegrity/siteminder/agents/bin/libSunOneWebAgent.so"

funcs="SmInitAgent,SmInitChild,SiteMinderAgent,SmRequireAuth,SmAdvancedAuth,SmLog

inFcc,SmGetCred,SmMakeCookie,SmSSLLoginFcc"

Init fn=SmInitAgent config="/usr/iPlanet/servers/https-

yourserver/config/WebAgent.conf" errortext+"Error initializing Web Agent..."

Init fn="SmInitChild" LateInit=”yes”

These lines instruct the web server to load the SiteMinder Web Agent with the following NSAPI functions:

SmInitAgent

SmInitChild

SiteMinderAgent

SmRequireAuth.

SmAdvancedAuth

obj.conf File Additions for Windows Platforms


obj.conf File Additions for Windows Platforms When a Web Agent is configured to support an advanced authentication scheme, the Web Agent adds settings to the Sun Java System’s obj.conf file. SiteMinder does not remove these settings later if the Agent is reconfigured to support a different advanced authentication scheme. You must manually edit the obj.conf file to remove the settings that are no longer relevant.

Most of the additional lines in the file are added by the Web Agent installation program. Other lines (shown in bold) are added by the servlet engine that you configure for the JSP version of the SiteMinder Password Services.

The lines added by the servlet engine must come before the NameTrans fn functions added by the SiteMinder Web Agent.

In the following example of a modified obj.conf file, smhome represents the installed location of SiteMinder on your system:

Note: Some entries in your file may differ slightly from the example shown.

AuthTrans fn="SiteMinderAgent"

NameTrans fn="assign-name" from="*.jsp*" name="myservletengine"

NameTrans fn="assign-name" from="/servlet/*" name="myservletengine"

NameTrans fn="assign-name" from="/siteminderagent/pwservlet/*"

name="servletengine"

NameTrans fn="pfx2dir" from="/siteminderagent/pwcgi"

dir="/smhome/siteminder/webagent/pw" name="cgi"

NameTrans fn="pfx2dir" from="/siteminderagent/pw"

dir="/smhome/siteminder/webagent/pw"

NameTrans fn="pfx2dir" from="/siteminderagent/certoptional"

dir="/smhome/siteminder/webagent/samples"

NameTrans fn="pfx2dir" from="/siteminderagent/jpw"

dir="/smhome/siteminder/webagent/jpw"

NameTrans fn="pfx2dir" from="/siteminderagent"


PathCheck fn="SmRequireAuth"

PathCheck fn="get-client-cert" dorequest="1"

PathCheck fn="get-client-cert" require="0" dorequest="1"

Service method="(GET|HEAD)" type="magnus-internal/scc" fn="smGetCred"

Service method="(GET|POST|HEAD)" type="magnus-internal/fcc" fn="SmLoginFcc"

Service method="(GET|POST|HEAD)" type="magnus-internal/sfcc" fn="SmSSLLoginFcc"

Service fn="send-cgi" type="magnus-internal/cgi"

Service method="(GET|HEAD)" type="magnus-internal/ccc" fn="smMakeCookie"

The following items describe the content of the lines that are added to the obj.conf file:

obj.conf File Additions for Windows Platforms


The line that reads AuthTrans fn="SiteMinderAgent" is added to the default object (<Object name="default">). It sets up the SiteMinder Web Agent as the Authorization method, or AuthTrans function, for the Web server.

The line that reads NameTrans fn="assign-name" from= "/siteminderagent/pwservlet/*" name="myservletengine" is a filter added by the Web Agent that maps the JSP Password Services servlet to the instance of the servlet engine so that engine can process it.

Most of the lines that begin NameTrans fn="pfx2dir" add virtual directories and mappings for the Agent to support SiteMinder’s Password Services (CGI and JSP versions).

The line that begins NameTrans fn="pfx2dir" from="/siteminderagent/certoptional" is added if you chose to configure a certificate based authentication scheme.

The line that reads PathCheck fn="SmRequireAuth" is added to any existing PathCheck lines in the default object. It verifies that the user is authorized to perform the requested action on the requested resource.

The line that reads PathCheck fn="get-client-cert" dorequest="1" is added if, during configuration, you indicated that the Web Agent would support advanced authentication schemes. It supports the use of certificate, certificate plus basic, and certificate and forms authentication schemes.

The line that reads PathCheck fn="get-client-cert" require="0" dorequest="1" is added if, during configuration you indicated during installation that the Web Agent would support advanced authentication schemes. It supports the use of certificate or basic or the certificate or forms authentication schemes.

Note: Both PathCheck lines for advanced authentication should be commented out for "Basic Auth over SSL."

The lines that begin Service method are added to instruct the Web server what to do with the MIME types.

The lines that read NameTrans fn="assign-name" from="*.jsp*" name="myservletengine" and NameTrans fn="assign-name" from="/servlet/*" name="myservletengine"create mappings for the Agent to support SiteMinder’s Password Services.

obj.conf File Additions for UNIX Platforms


obj.conf File Additions for UNIX Platforms When a Web Agent is configured to support an advanced authentication scheme, the Web Agent adds settings to the Sun Java System’s obj.conf file. SiteMinder does not remove these settings later if the Agent is reconfigured to support a different advanced authentication scheme. You must manually edit the obj.conf file to remove the settings that are no longer relevant.

Most of the additional lines in the file are added by the Web Agent installation program. Other lines (shown in bold) are added by the servlet engine that you configure for the JSP version of the SiteMinder Password Services.

The lines added by the servlet engine must come before the NameTrans fn functions added by the SiteMinder Web Agent.

In the following example of a modified obj.conf file, smhome represents the installed location of SiteMinder on your system:

Note: Some entries in your file may differ slightly from the example shown. AuthTrans fn="SiteMinderAgent"

NameTrans fn="assign-name" from="*.jsp*" name="myservletengine"

NameTrans fn="assign-name" from="/servlet/*" name="myservletengine"

NameTrans fn="assign-name" from="/siteminderagent/pwservlet/*"

name="servletengine"

NameTrans fn="pfx2dir" from="/siteminderagent/pwcgi"

dir="/smhome/siteminder/webagent/pw" name="cgi"

NameTrans fn="pfx2dir" from="/siteminderagent/pw"

dir="/smhome/siteminder/webagent/pw"

NameTrans fn="pfx2dir" from="/siteminderagent/certoptional"


NameTrans fn="pfx2dir" from="/siteminderagent/jpw"

dir="/smhome/siteminder/webagent/jpw"

NameTrans fn="pfx2dir" from="/siteminderagent"


PathCheck fn="SmRequireAuth"

#SMSSL The line below should be uncommented for "cert" and "cert plus basic"

schemes

PathCheck fn="get-client-cert" dorequest="1"

#SMSSL The line below should be uncommented for "cert or basic" or "cert or form"

schemes

PathCheck fn="get-client-cert" require="0" dorequest="1"

#SMSSL Both of the above PathCheck lines should be commented out for "Basic Auth

over SSL"

Service method="(GET|HEAD)" type="magnus-internal/scc" fn="smGetCred"

Service method="(GET|POST|HEAD)" type="magnus-internal/fcc" fn="SmLoginFcc"

Service method="(GET|POST|HEAD)" type="magnus-internal/sfcc" fn="SmSSLLoginFcc"

obj.conf File Additions for UNIX Platforms


Service method="(GET|HEAD)" type="magnus-internal/ccc" fn="smMakeCookie"

The following items describe the content of the lines that are added to the obj.conf file:

The line that reads AuthTrans fn="SiteMinderAgent" is added to the default object (<Object name="default">). It sets up the SiteMinder Web Agent as the Authorization method, or AuthTrans function, for the Web server.

The line that reads NameTrans fn="assign-name" from= "/siteminderagent/pwservlet/*" name="myservletengine" is a filter added by the Web Agent that maps the JSP Password Services servlet to the instance of the servlet engine so that engine can process it.

Most of the lines that begin NameTrans fn="pfx2dir" add virtual directories and mappings for the Agent to support SiteMinder’s Password Services (CGI and JSP versions).

The line that begins NameTrans fn="pfx2dir" from="/siteminderagent/certoptional" is added if you chose to configure a certificate based authentication scheme.

The line that reads PathCheck fn="SmRequireAuth" is added to any existing PathCheck lines in the default object. It verifies that the user is authorized to perform the requested action on the requested resource.

The line that reads PathCheck fn="get-client-cert" dorequest="1" is added if, during configuration, you indicated that the Web Agent would support advanced authentication schemes. It supports the use of certificate, certificate plus basic, and certificate and forms authentication schemes.

The line that reads PathCheck fn="get-client-cert" require="0" dorequest="1" is added if, during configuration you indicated during installation that the Web Agent would support advanced authentication schemes. It supports the use of certificate or basic or the certificate or forms authentication schemes.

Note: Both PathCheck lines for advanced authentication should be commented out for "Basic Auth over SSL."

The lines that begin Service method are added to instruct the Web server what to do with the MIME types.

mime.types File Additions for Windows and UNIX Platforms


mime.types File Additions for Windows and UNIX Platforms The following lines are added to the mime.types file by the setup program:

type=magnus-internal/sfcc exts=sfcc

type=magnus-internal/fcc exts=fcc

type=magnus-internal/scc exts=scc

type=magnus-internal/ccc exts=ccc

These lines set up the mime types to support advanced SiteMinder features.

Check Agent Start-up with LLAWP You can see if the Web Agent is starting up properly by starting the LLAWP process.

To start the LLAWP process

1. Ensure you have configured the Web Agent with the Configuration Wizard.

2. Open a console window and enter the following command:

LLAWP <path_to_WebAgent.conf> -<web_server_type>

web_server_type can be ISAPI60 or APACHE20

path_to_WebAgent.conf can be a full path or a relative path from the location where you are running LLAWP. For example:

Windows:

LLAWP "C:\Program Files\Netegrity\Siteminder Web Agent\Bin\IIS\WebAgent.conf" -ISAPI60

UNIX:

LLAWP /usr/apache/conf/WebAgent.conf -APACHE20

Note: If you start the LLAWP from the command line, you must also shut it down from the command line.

Configuration Changes to Web Servers with Apache Web Agent 297

Appendix D: Configuration Changes to Web Servers with Apache Web Agent

This appendix lists changes made automatically by running the Web Agent Configuration Wizard to configure an Apache Web Agent. These changes apply to all web servers that support the Apache Web Agent, including Apache 1.x, Apache 2.0, Stronghold, Oracle 10G, IBM HTTP Server, Covalent Enterprise Web Server, and HP Apache.

Library Path for the Web Server is Set for UNIX Systems The library path for the Apache web server is required because it enables the Apache server to load libraries correctly on a UNIX system. For example:

export LD_LIBRARY_PATH <web_agent_home>/bin

The library path variable depends on the operating system—it should always point to <web_agent_home>/bin. The following table lists the variables.

Operating System Path Variable

Solaris LD_LIBRARY_PATH

HP-UX SHLIB_PATH

LINUX LD_LIBRARY_PATH

AIX LIBPATH

Set Library Path and Path for Oracle 10g Web Server Running in Apache 2.x Mode


The entries are as follows:

Oracle HTTP Server 9.0.2 on Solaris and Linux:

if [ -z "$LD_LIBRARY_PATH" ]

then

LD_LIBRARY_PATH=<OHS_home>/libexec:<web_agent_home>/bin;

export LD_LIBRARY_PATH

else

LD_LIBRARY_PATH=<OHS_home>/libexec:${LD_LIBRARY_PATH};

export LD_LIBRARY_PATH

Oracle HTTP Server 9.0.2 on HP-UX:

if [ -z "$SHLIB_PATH" ]

then

SHLIB_PATH=/<OHS_home>/libexec:<web_agent_home>/bin;

export SHLIB_PATH

else

SHLIB_PATH=<OHS_home>/libexec:${SHLIB_PATH};

export SHLIB_PATH

Set Library Path and Path for Oracle 10g Web Server Running in Apache 2.x Mode

For an Oracle 10g web server running in Apache 2.x mode, both the LD_LIBRARY_PATH and PATH variables need to be set in the apachectl script.

LD_LIBRARY_PATH is automatically added to the apachectl script, which is located in the directory <OHS_home>/Apache/Apache/bin/.

Add the following entry for PATH in the apachectl script:

PATH=<Path of webagent install>/bin:${PATH} ; export PATH

Changes to the httpd.conf File


Changes to the httpd.conf File The Configuration Wizard modifies the httpd.conf configuration file to enable the web server to operate with the Apache Web Agent.

Notes:

The examples in this procedure are for UNIX platforms; however the same changes are made to Windows platforms using the appropriate Windows syntax.

The <web_agent_home> variable represents the installed location of the Web Agent, such as:

UNIX: /opt/netegrity/webagent

Windows: C:\Program Files\netegrity\webagent

For most Apache-based web servers, this file is located in the conf directory:

<Apache_home>/conf

For the Oracle 9.0.2/9.0.3 HTTP Server (OHS), the httpd.conf file is located in:

<OHS_home>/Apache/Apache/conf

where <OHS_home> is the server root for Oracle HTTP Server.

Entries Added to DSO Support Section

The following line(s) are added to the Dynamic Shared Object (DSO) Support configuration section, which precedes the Main server configuration section of the file.



LoadModule Entries Added

One of these modules is required to load the SiteMinder Agent.

For Apache 1.x (servers except HP-UX 11i):

LoadModule sm_module <web_agent_home>/bin/mod_sm.so

For Apache 1.x running HP-UX 11i:

LoadModule hpaCCso_module <web_agent_home>/bin/mod_hpaCCso.sl

HPaCCLoadModule sm_module <web_agent_home>/bin/mod_sm.sl

For Apache 1.x running Windows:

LoadModule sm_module <web_agent_home>/bin/Apache20WebAgent.dll

For Apache 2.0 (excluding servers running HP-UX 11i):

LoadModule sm_module <web_agent_home>/bin/libmod_sm20.so

For Apache 2.0 running HP-UX 11i:

LoadModule sm_module <web_agent_home>/bin/libmod_sm20.sl

For Apache 2.0 running Windows:

LoadModule sm_module <web_agent_home>/bin/mod_sm20.dll

For IBM HTTP Server 2.0.47 running HP-UX 11i:

LoadModule ibm_ssl_module modules/mod_ibm_ssl.so

Note: If you are communicating across an SSL connection, the IBM HTTP Server 2.0.47 on HP-UX 11i requires that the IBM SSL module be last in the list of LoadModule directives. Therefore, the Web Agent and all other Apache LoadModule directives are placed above the IBM SSL library, mod_ibm_ssl.so.

For Oracle HTTP Server (excluding servers running HP-UX 11i), add:

LoadModule sm_module <web_agent_home>/bin/mod_sm.so

For Oracle HTTP Server running HP-UX 11i:

LoadModule hpaCCso_module <web_agent_home>/bin/mod_hpaCCso.sl

HPaCCLoadModule sm_module <web_agent_home>/bin/mod_sm.sl

Optionally, for UNIX systems, to enable certificate-based authentication, the following line is added to the DSO configuration section:

LoadModule sm_certenv <web_agent_home>/bin/mod_smcertenv.so



mod_smcertenv enables certificate-based authentication to work with Apache web servers without requests being redirected to the SSL credential collector. Note: This module is only for Apache 1.3.27 web servers. It is not supported for proprietary versions of the Apache 1.3.x web server, such as Stronghold, IBM HTTP Server, or Oracle HTTP Server.

The entry to load mod_smcertenv must come after the entry to load mod_sm.

Note: HP-UX uses the extension .sl to refer to a shared library. If the operating system for the Web Agent is HP-UX, the .sl extension is used.

mod_sm.c Entry Added to ClearModuleList

If the directive ClearModuleList exists in the DSO configuration section, the mod_sm.c entry is placed at the end of the AddModule section of the file, as shown in bold:

ClearModuleList

AddModule mod_env.c

.

.

.

AddModule mod_servletexec.c

#Siteminder

AddModule mod_sm.c

SmInitFile Entry Added

In the Main server section of the file, the SmInitFile entry is added:

SmInitFile <Apache_home>/conf/WebAgent.conf

This entry is placed after the LoadModule entry. A full path is used, not a relative path. For example:

SmInitFile "/export/Apache2/conf/WebAgent.conf"

For Oracle 9.0.2/9.0.3 HTTP Server, the entry is:

SmInitFile <OHS_home>/Apache/Apache/conf/WebAgent.conf



Alias Entries Added

In the Aliases section of the file, entries are added to enable SiteMinder features.

Note the following:

The Alias /siteminderagent/ “<web_agent_home>/samples/” entry must come after all other aliases in the Aliases section.

For SiteMinder to use Basic over SSL or X.509 certificate-based authentication schemes with an Apache Web Agent, SSL must be enabled by compiling the Apache server to include the mod_ssl module. To obtain this module, see www.modssl.org.

Each alias entry appears on its own line.



Password Services Alias /siteminderagent/pwcgi/ “<web_agent_home>/pw/”

<Directory "/export/webagent/pw/">

Options Indexes MultiViews ExecCGI

AllowOverride None

Order allow,deny

Allow from all

</Directory>

Alias /siteminderagent/pw/ “<web_agent_home>/pw/”

<Directory "/export/webagent/pw/">

Options Indexes MultiViews ExecCGI

AllowOverride None

Order allow,deny

Allow from all

</Directory>

Basic over SSL authentication AliasMatch /siteminderagent/nocert/[0-9]+/(.*)

"<web_agent_home>/$1"

<Directory "<web_agent_home>/$1">

Options Indexes MultiViews

AllowOverride None

Order allow,deny

Allow from all

</Directory>

X509 Client Cert or X509 Client Cert and Basic authentication AliasMatch /siteminderagent/cert/[0-9]+/(.*)

"<web_agent_home>/$1"

<Directory "<web_agent_home>/$1">

Options Indexes

AllowOverride None

Order allow,deny

Allow from all

</Directory>

X509 Client Cert or Basic authentication AliasMatch /siteminderagent/certoptional/[0-9]+/(.*) "<web_agent_home>/$1"

<Directory "<web_agent_home>/$1"

Options Indexes

AllowOverride None

Order allow,deny

Allow from all

</Directory>

X509 Certificate or Form or X509 Client Cert and Form authentication



Alias /siteminderagent/certoptional/"<web_agent_home>/

samples/"

<Directory "<web_agent_home>/samples/"

Options Indexes

AllowOverride None

Order allow,deny

Allow from all

</Directory>

Forms authentication or Agent is cookie provider for single sign-on Alias /siteminderagent/ “<web_agent_home>/samples/”

<Directory "/export/webagent/samples/">

Options Indexes MultiViews

AllowOverride None

Order allow,deny

Allow from all

</Directory>

Note: This is the alias that should be placed at the end of the section.

AddHandler Entries Added for Traditional Agents

For traditional Web Agents (versions before 5.x QMR 6, such as Agents installed on Apache 1.x web servers), the following entries are added to the AddHandler section of the file for SiteMinder features.

Note: These entries do not apply to Framework Web Agents (versions including v5.x QMR 6 and all subsequent versions, such as Agents installed on Apache 2.0 web servers). These functions are now part of the Web Agent Framework.

SiteMinder Feature AddHandler Entry

Password Services AddHandler cgi-script .exe

Forms authentication

Certificate and Forms authentication

AddHandler smformsauth-handler .fcc

Certificate or forms authentication

AddHandler smsslformsauth-handler .sfcc



SiteMinder Feature AddHandler Entry

SSL authentication, including:

Basic over SSL

Certificate

Certificate or basic

Certificate and basic

AddHandler smadvancedauth-handler .scc

Cookie provider for single sign-on

AddHandler smcookieprovider-handler .ccc

The modified section would appear as follows:

AddHandler cgi-script .exe

AddHandler smformsauth-handler .fcc

AddHandler smsslformsauth-handler .sfcc

AddHandler smadvancedauth-handler .scc

AddHandler smcookieprovider-handler .ccc

Agent Parameter Added for SSL Connections Using Apache 1.x Based Servers


Certificate Authentication Entries Added If you are using X509 Client Cert, X509 Client Cert and Basic, or X509

Client Cert or Basic authentication, the following SSL Engine Options entry in the Virtual Hosts section is uncommented for the appropriate virtual host (if multiple hosts are defined):

SSLOptions +ExportCertData +StdEnvVars

Note: If there is an existing SSL option in the Virtual Hosts section, then that existing entry is commented out and the new SSL entry is added.

If you are using X509 Client Cert or Forms authentication, the following SSL Engine Options entry in the Virtual Hosts section is uncomment for the appropriate virtual host (if multiple hosts are defined):

SSLOptions +StdEnvVars +CompatEnvVars

In the Virtual Hosts section of the file, the SSL Client Authentication type is set it to optional:

SSLVerifyClient optional

For Oracle 9.02/9.03 HTTP Server, if SSL has been configured, the SSLWallet and SSLWalletPassword entries are added to the Virtual Hosts section.

The entries should look similar to the following:

SSLWallet file:<OHS_home>/Apache/Apache/conf/ssl.wlt

SSLWalletPassword <your_wallet_password>

Agent Parameter Added for SSL Connections Using Apache 1.x Based Servers

If you are using SSL connections (HTTPS) to an Apache 1.x based server, the httpsports parameter is added to the WebAgent.conf file or the Agent Configuration Object configured at the Policy Server. This parameter specifies one or more (comma-separated) HTTPS port numbers the web server is listening on. For example, set httpsports to 80.

Note: If a server is behind an HTTPS accelerator, which converts HTTPS to HTTP, all requests are treated as SSL connections by your browser.

Environment Variables Added or Modified by the Web Agent Installation 307

Appendix E: Environment Variables Added or Modified by the Web Agent Installation


Added or Modified Environment Variables (see page 307)

Added or Modified Environment Variables The following environment variables are added or modified by the Web Agent installation:

NETE_WA_ROOT = $INSTALL_PATH$

NETE_WA_PATH = $INSTALL_PATH$$/$bin